Skip to main content

MQTT Transport

Excalibur.Dispatch.Transport.Mqtt registers the transport primitives for MQTT: a keyed ITransportSender and ITransportReceiver that publish, subscribe, and acknowledge messages against an MQTT broker over the MQTTnet client. The transport pins MQTT 5.0 so it can use response topics, correlation data, and shared subscriptions.

Scope of this package

This package provides the low-level transport primitives only — the keyed sender and receiver you resolve by transport name to move bytes directly. High-level integration into the dispatch pipeline (a transport adapter that publishes and consumes typed dispatch messages end-to-end, participating in middleware, serialization, and routing) is not part of this package and is provided separately.

If you need full pipeline-integrated messaging today, use one of the pipeline-integrated transports (Kafka, RabbitMQ, Azure Service Bus, AWS SQS, Google Pub/Sub).

Before You Start​

Installation​

dotnet add package Excalibur.Dispatch.Transport.Mqtt

Dependencies: Excalibur.Dispatch.Abstractions, Excalibur.Dispatch.Transport.Abstractions, MQTTnet

Registration​

Register a named transport with AddMqttTransport. The name is used for multi-transport routing and to resolve the keyed sender/receiver.

using Microsoft.Extensions.DependencyInjection;

services.AddMqttTransport("events", mqtt =>
{
mqtt.Host = "mqtt.internal";
mqtt.Port = 8883;
mqtt.UseTls = true;
mqtt.ClientId = "order-service";
mqtt.Topic = "orders";
mqtt.QualityOfService = MqttQualityOfService.AtLeastOnce;
mqtt.UseSharedSubscription = true;
mqtt.SharedSubscriptionGroup = "order-processors";
});

AddMqttTransport requires an explicit transport name. Options are validated at startup (ValidateOnStart), so a missing Host, ClientId, or Topic fails fast with OptionsValidationException.

Transport security​

The broker can be reached in the clear, so an unencrypted connection is refused by default. The refusal happens when the transport is resolved -- while the host is starting -- rather than on the first message, and it raises TransportSecurityException.

MQTT over plain TCP carries the user name, password and every payload in the clear, so UseTls must be set (the TLS listener is normally port 8883). For a local broker with no TLS listener, opt out explicitly:

services.AddMqttTransport("local-dev", mqtt =>
{
mqtt.Host = "localhost";
mqtt.Port = 1883;
mqtt.ClientId = "order-service";
mqtt.Topic = "orders";
mqtt.RequireTls = false; // Local brokers only: credentials travel in the clear
});

Options​

PropertyTypeDefaultPurpose
Hoststring(required)The broker host name.
Portint1883The broker TCP port (1..65535); typically 8883 for TLS.
ClientIdstring(required)The client id presented to the broker. Must be unique per connected client.
Topicstring(required)The topic to publish to and subscribe from.
UseTlsboolfalseConnect over TLS.
RequireTlsbooltrueRefuse the connection unless UseTls is set.
QualityOfServiceMqttQualityOfServiceAtLeastOnceThe delivery guarantee (see below).
PersistentSessionbooltrueKeep this client's session on the broker across disconnects. This is what makes rejection with redelivery work; see below.
SessionExpiryIntervalTimeSpan1 hourHow long the broker keeps the session after the connection closes — the recovery window. Must be positive and a whole number of seconds.
UseTlsboolfalseConnect to the broker over TLS.
UseSharedSubscriptionboolfalseSubscribe using an MQTT-5 shared subscription so multiple consumers compete for messages. Requires an MQTT-5 broker that supports shared subscriptions.
SharedSubscriptionGroupstring"dispatch"The shared-subscription group applied when UseSharedSubscription is enabled. Must be a shared, stable name distinct from ClientId, or subscribers do not compete.
ResponseTopicstring?nullThe MQTT-5 response topic for the request/reply pattern, or null when unused.
Usernamestring?nullThe user name for broker authentication, or null for none.
Passwordstring?nullThe password for broker authentication, or null for none. Source from a secret manager; never commit a value.
MaxPayloadBytesint?4 MiBThe maximum accepted inbound payload size in bytes, or null to opt out of the limit (see below).

Quality of service​

MqttQualityOfService maps to the MQTT delivery levels and governs both publish and subscribe:

ValueSemantics
AtMostOnce (0)Fire-and-forget; no broker acknowledgement. Refused for a receiver — see below.
AtLeastOnce (1, default)Acknowledged delivery; messages may be redelivered (duplicates possible).
ExactlyOnce (2)Exactly-once delivery end-to-end.

Ordering is not guaranteed under QoS 0/1. Exactly-once end-to-end requires QoS 2.

QoS 0 is rejected at startup when a receiver is registered

At QoS 0 the protocol sends no acknowledgement packet, so the receiver's whole settlement surface is inoperable: AcknowledgeAsync settles a message the broker already stopped tracking, RejectAsync(…, requeue: true, …) cannot cause a redelivery — so it discards the message outright — and RejectAsync(…, requeue: false, …) suppresses a redelivery that was never going to happen. Rather than accept that configuration and report success for operations that do nothing, AddMqttTransport fails validation at startup. Publish-only hosts are unaffected.

Using the sender and receiver​

The sender and receiver are registered as keyed singletons under the transport name. Resolve them with GetRequiredKeyedService:

using Excalibur.Dispatch.Transport;

var sender = provider.GetRequiredKeyedService<ITransportSender>("events");
var receiver = provider.GetRequiredKeyedService<ITransportReceiver>("events");

// Send
await sender.SendAsync(
new TransportMessage
{
Body = JsonSerializer.SerializeToUtf8Bytes(order),
ContentType = "application/json",
MessageType = "OrderPlaced",
},
cancellationToken);

// Receive and acknowledge
var messages = await receiver.ReceiveAsync(maxMessages: 10, cancellationToken);
foreach (var message in messages)
{
Process(message);
await receiver.AcknowledgeAsync(message, cancellationToken);
}

The receiver uses manual acknowledgement: an inbound message is only PUBACK/PUBCOMP'd (QoS 1/2) when you call AcknowledgeAsync. The sender and receiver open separate connections and present distinct client ids derived from ClientId, so a single configured client id is safe for both.

Redelivery and rejection​

RejectAsync honours the requeue argument, and it uses a different mechanism for each outcome:

CallMechanismOutcome
RejectAsync(…, requeue: true, …)The acknowledgement is withheld.Redelivery depends on the broker retaining the session and the client resuming it.
RejectAsync(…, requeue: false, …)The acknowledgement is sent carrying a failure reason code.Requests completion of the delivery flow; callback completion does not prove durable broker acceptance.

The second row is the one to reach for in a poison-message handler. Under MQTT 5 a PUBACK completes the QoS 1 flow whatever its reason code, and at QoS 2 a PUBREC with a reason code of 0x80 or above terminates the flow before PUBREL — so acknowledging with a failure code is how a client says "I could not process this, and do not send it again." The transport always connects as MQTT 5, so this is available on every connection it opens.

requeue: false suppresses redelivery on a best-effort basis

Returning normally means the native acknowledgement callback completed without an observed failure. It does not prove durable broker acceptance. If the connection fails before the broker processes the packet, the message may remain outstanding and arrive again when the retained session resumes. Deduplicate in your dead-letter handler — but not on TransportReceivedMessage.Id, which is unique per delivery and so differs on every redelivery. It has to be: it keys the receiver's pending-settlement map, and deriving it from a content field a producer may legitimately repeat would let two in-flight messages settle against each other's handle. Set a deduplication id at the sender (UseDeduplication); it travels as an MQTT user property, the broker retransmits it with the message, and it is readable from TransportReceivedMessage.Properties. That is the key that survives a redelivery.

Native acknowledgement callback failures surface as TransportSettlementException, preserving the original exception in InnerException. Redelivery is Unspecified, while retrying the same settlement is Permanent because the local handle was consumed before the callback. An existing portable exception retains its identity. Cancellation remains a raw cancellation exception only when it carries the exact forwarded caller token and that token was requested; unrelated callback timeouts remain portable failures. Caller cancellation also leaves the handle consumed.

The requeue promise depends on the session outliving the disconnect, which is why PersistentSession defaults to true. The transport connects with a non-clean start and a one-hour session expiry so that a rejected message is still held by the broker when the client comes back.

Rejection needs a stable ClientId

A session is resumed by client id. If you generate ClientId per process — a GUID at start-up, a pod name, a random suffix — the broker cannot match the returning client to the old session, so every restart begins a fresh one and anything you rejected is gone. Configuration validation cannot catch this: a random id is a valid id. Use a name that is stable for the deployment.

Setting PersistentSession to false opts out. Clean sessions support acknowledgment and rejection without requeue. A requeue request is refused with TransportSettlementException (Mqtt, Unspecified, Permanent) before the receipt is claimed or the native callback is changed. You can still acknowledge that receipt or reject it without requeue. The receiver uses the connection settings captured for the delivery; changing the options object after connecting does not change that delivery's session configuration. These settings describe the requested connection, rather than proving that the broker retained a session.

Session-retention eligibility is fixed for the receiver's reused client. A reconnect request that changes that eligibility is refused before connecting; create a new receiver to change between clean and retained sessions. This keeps a delayed callback from an earlier connection from adopting a later connection's requeue policy. Reconnecting with unchanged eligibility remains supported.

SessionExpiryInterval is the recovery window, sized for reconnects and rolling restarts rather than for outages. A subscriber that returns inside the window resumes its session and receives what it left unacknowledged; one that returns after it gets a clean session. The window is encoded on the wire as whole seconds, so a fractional value is rejected at start-up rather than rounded — a silently-shortened recovery window is the defect this setting exists to prevent.

A persistent session is not free: the broker retains state for each client id, and brokers bound how much they will hold. If you run many short-lived clients, prefer a shorter window over disabling persistence.

Competing consumers (shared subscriptions)​

By default each subscriber receives every message (fan-out). Set UseSharedSubscription = true to have grouped consumers compete: the receiver subscribes to $share/{SharedSubscriptionGroup}/{Topic} and the broker load-balances across the group. This is an MQTT-5 feature — the transport pins protocol version 5.0 so the $share/… filter is honored rather than treated as a literal topic name.

Payload-size guard​

MaxPayloadBytes rejects oversized inbound payloads before they are buffered. The size is measured on receipt; an oversized message can never be processed, so it is acknowledged and dropped (rather than looped by broker redelivery).

The guard is on by default, at 4 MiB — the same default every other transport applies. Raise it for larger legitimate payloads, or set it to null to opt out of the limit entirely.

Changed: this option previously defaulted to null, so the guard was inert for every deployment that had not configured it. If you rely on inbound payloads larger than 4 MiB, set MaxPayloadBytes explicitly — otherwise they are now rejected.

What's Next​