MQTT and AMQP messages¶
A stub can publish MQTT messages and AMQP 0-9-1 messages (RabbitMQ, LavinMQ and other AMQP 0-9-1 brokers) when it
matches, in the same way as Kafka messages: the event a real service would emit after an HTTP call.
Async mocks publish to MQTT and AMQP too, on a timer, and the AsyncAPI import
creates them from mqtt and amqp bindings. To check what your application publishes to a broker, see
Message capture.
- Server settings
- Publishing from stubs
- MQTT messages
- AMQP messages
- Connections, reconnects and readiness
- Allow-lists
- TLS and authentication
- Observability
- Troubleshooting
Server settings¶
MQTT and AMQP are off until their broker URL is set. Each protocol has one broker; FastMock never needs credentials in the URL.
| Variable | Default | Meaning |
|---|---|---|
FASTMOCK_MQTT_URL |
none | mqtt://host:1883 or mqtts://host:8883 (also tcp://, ssl://, tls://). |
FASTMOCK_MQTT_VERSION |
5 |
5 or 3.1.1. With 3.1.1, user properties, content type, correlation data, response topic and expiry are not sent. |
FASTMOCK_MQTT_CLIENT_ID_PREFIX |
fastmock |
Client ids are <prefix>-pub-<8 hex digits> for publishing and <prefix>-cap-<8 hex digits> for capture, new for every connection, so replicas never take each other's session. Match it in broker ACLs that restrict client ids. |
FASTMOCK_MQTT_USERNAME, FASTMOCK_MQTT_PASSWORD |
none | Credentials (a user name alone is allowed for MQTT). |
FASTMOCK_MQTT_TLS_CA_FILE, _TLS_CERT_FILE, _TLS_KEY_FILE |
none | See TLS and authentication; only with mqtts://. |
FASTMOCK_MQTT_KEEP_ALIVE |
30s |
MQTT keep-alive (at least 5 s). |
FASTMOCK_MQTT_ALLOWED_TOPICS |
none (any) | Topics stubs and async mocks may publish to: exact names or prefixes ending in * (devices/*). |
FASTMOCK_AMQP_URL |
none | amqp://host:5672/vhost or amqps://host:5671/vhost. The virtual host is the URL-encoded path (/%2f or no path for /, /orders for orders). |
FASTMOCK_AMQP_USERNAME, FASTMOCK_AMQP_PASSWORD |
none (guest) |
Credentials for SASL PLAIN. Set both or neither. |
FASTMOCK_AMQP_SASL_MECHANISM |
PLAIN |
PLAIN or EXTERNAL (the broker takes the identity from the client certificate; needs amqps:// and a client certificate, no password). |
FASTMOCK_AMQP_TLS_CA_FILE, _TLS_CERT_FILE, _TLS_KEY_FILE |
none | Only with amqps://. |
FASTMOCK_AMQP_ALLOWED_EXCHANGES |
none (any) | Exchanges stubs and async mocks may publish to: names or prefix*. The default exchange routes to the queue named by the routing key, so it is allowed through amq.default/<queue> entries (amq.default/orders.*); amq.default alone allows no queue. |
FASTMOCK_AMQP_DECLARE_EXCHANGES |
false |
Declare a missing exchange before the first message to it, with the message's exchangeType (default topic), durable. Only exchange names written in the stub are declared, never names produced by a template. Existing exchanges are never redeclared. The user needs the configure permission. |
Settings are checked at start-up: a URL with credentials, a query or an unknown scheme, a password without a user
name (AMQP), a certificate without its key, TLS files with a plain mqtt:// or amqp:// URL, EXTERNAL without
a client certificate, or FASTMOCK_MQTT_*/FASTMOCK_AMQP_* settings without the URL stop the server with a message
naming the variable. Passwords never appear in logs, errors or /__admin/info. In Helm these are the mqtt.* and
amqp.* values (Helm).
FASTMOCK_MQTT_URL=mqtts://mqtt.example.com:8883
FASTMOCK_MQTT_USERNAME=fastmock
FASTMOCK_MQTT_PASSWORD=<from a Secret>
FASTMOCK_MQTT_ALLOWED_TOPICS='devices/*,alerts/*'
FASTMOCK_AMQP_URL=amqps://rabbit.example.com/orders
FASTMOCK_AMQP_USERNAME=fastmock
FASTMOCK_AMQP_PASSWORD=<from a Secret>
FASTMOCK_AMQP_TLS_CA_FILE=/etc/fastmock/amqp/ca.crt
FASTMOCK_AMQP_ALLOWED_EXCHANGES='orders,audit.*'
Publishing from stubs¶
The messages of a stub take protocol: kafka (the default, see Kafka messages), mqtt or amqp.
One stub can publish to several brokers. The template context is the same as for the response.
{
"name": "ship order",
"request": {"method": "POST", "urlPathTemplate": "/orders/{id}/ship"},
"response": {"status": 202, "jsonBody": {"id": "{{request.pathParams.id}}", "status": "SHIPPING"}},
"messages": [
{
"protocol": "mqtt",
"topic": "orders/{{request.pathParams.id}}/status",
"qos": 1,
"retain": true,
"contentType": "application/json",
"correlationData": "{{request.headers.x-request-id}}",
"headers": {"event-type": "OrderShipped"},
"jsonValue": {"orderId": "{{request.pathParams.id}}", "status": "SHIPPED", "at": "{{now}}"}
},
{
"protocol": "amqp",
"exchange": "orders",
"routingKey": "order.shipped",
"contentType": "application/json",
"messageId": "{{uuid}}",
"correlationId": "{{request.headers.x-request-id}}",
"persistent": true,
"headers": {"event-type": "OrderShipped"},
"jsonValue": {"orderId": "{{request.pathParams.id}}", "carrier": "{{request.json.carrier}}"},
"delayMs": 500
}
]
}
Fields for every protocol:
| Field | Type | Meaning |
|---|---|---|
protocol |
kafka, mqtt, amqp |
The broker; kafka when absent. |
jsonValue |
JSON with templates | JSON body. A string that is exactly "{{json expr}}" keeps the JSON type of the value. |
value |
template | Text body, used when jsonValue is not set. Without both, the body is empty. |
headers |
map of templates | Kafka headers, MQTT 5 user properties, AMQP headers (long strings). At most 100 per message. |
contentType |
template | MQTT 5 content type property, AMQP content_type; for Kafka the content-type header unless headers sets it. |
delayMs |
integer | Publish this long after the match, at most FASTMOCK_MAX_DELAY and one hour. Messages of a stub are sent in order of their delay; each delay counts from the match. |
A stub has at most 100 messages. All templated fields of all messages of one response render together within one
budget: 16 MiB of output and the time, step and memory limits of one template. A field a protocol limits stops
rendering as soon as it is too long and fails the message: AMQP exchange, routing key, messageId,
correlationId, replyTo, expiration, messageType, appId and contentType at 255 bytes, a Kafka topic at
249 bytes, MQTT topics, properties and user properties at 65535 bytes (messages[0].routingKey: the rendered value
exceeds 255 bytes). The response itself is not affected.
The HTTP response is not delayed by publishing and does not fail when publishing fails: publishing runs in the
background, the outcome is logged and counted. Messages are published at most once, never retried; a message whose
broker is unreachable is lost and counted as failed. Each replica publishes at most 256 messages at a time;
messages due now beyond that are dropped and counted as dropped. Delayed messages wait in a separate queue and
take a publication slot only when they are due: at most 4096 messages and 64 MiB wait per replica, at most 1024 of
them from one stub; messages beyond that are dropped and counted as dropped, and a due message that finds no free
slot within 10 seconds too. Messages that do not fit the protocol (an MQTT key, an AMQP
topic, qos for Kafka, avroSchema outside Kafka) are rejected when the stub is saved:
messages[0]: key not used with protocol mqtt.
MQTT messages¶
| Field | Type | Meaning |
|---|---|---|
topic |
template, required | Topic name; no + or #, no control characters. |
qos |
0, 1, 2 |
Quality of service, default 0. |
retain |
boolean | The broker keeps the message as the topic's retained message. |
correlationData |
template | MQTT 5 correlation data (UTF-8 bytes). |
responseTopic |
template | MQTT 5 response topic: a topic name like topic (no + or #). |
messageExpirySeconds |
integer | MQTT 5 message expiry interval. |
Before a message is handed to the connection, its topic, response topic, content type and user properties are
checked against what brokers accept (no NUL or other control characters, no non-characters, at most 65535 bytes;
correlation data at most 65535 bytes): a bad value fails that message only instead of making the broker close the
connection that every publication shares. A publication counts as sent when the broker acknowledged it: on the write for QoS 0, on PUBACK for QoS 1, on
PUBCOMP for QoS 2. An MQTT 5 acknowledgement with an error reason (NotAuthorized, TopicNameInvalid, ...) fails
the message; NoMatchingSubscribers counts as sent. A publication waits at most 10 seconds for its acknowledgement.
Example with Mosquitto (mosquitto_sub -V mqttv5 -t 'orders/#' -F '%t %p %P' shows the topic, payload and user
properties):
curl -s -X POST localhost:8080/orders/A-1/ship -H 'content-type: application/json' \
-H 'x-request-id: r-17' -d '{"carrier":"DHL"}'
orders/A-1/status {"at":"2026-11-22T02:09:16.401Z","orderId":"A-1","status":"SHIPPED"} event-type:OrderShipped
AMQP messages¶
| Field | Type | Meaning |
|---|---|---|
exchange |
template | Exchange; empty or amq.default is the default exchange, which routes to the queue named by the routing key. |
routingKey |
template | Routing key. A message needs exchange, routingKey or both. |
exchangeType |
topic, direct, fanout, headers |
Type used when FastMock declares a missing exchange (FASTMOCK_AMQP_DECLARE_EXCHANGES=true); default topic. |
messageId, correlationId, replyTo, messageType, appId |
template | The AMQP basic properties message_id, correlation_id, reply_to, type, app_id. |
expiration |
template | Per-message TTL in milliseconds, digits only ("60000"). |
persistent |
boolean | Delivery mode 2 (persistent) instead of 1. |
priority |
0..255 | Message priority. |
Every message also carries timestamp (seconds). FastMock publishes on one channel in confirm mode: a message
counts as sent when the broker confirms it, and fails on a negative confirm, when the exchange does not exist
(exchange orders does not exist (create it, or set FASTMOCK_AMQP_DECLARE_EXCHANGES=true ...)) or when no confirm
arrives within 10 seconds. Before the first message to an exchange FastMock checks on a separate channel that it
exists, so a missing exchange fails only the messages to it, never the confirms of other messages on the shared
channel. It remembers up to 256 exchanges as existing. A message routed to no queue is confirmed and dropped by the
broker, as for any AMQP producer.
Connections, reconnects and readiness¶
Each replica opens one MQTT connection and one AMQP connection for publishing, on the first message, and keeps
them. An unset or unreachable broker never affects readiness (/readyz): stubs answer, their messages fail.
- MQTT: the connection reconnects by itself after an error, with a pause that doubles from 200 ms to 30 s and resets only after a connection that lasted at least 10 seconds, so a broker that accepts and then closes every connection is not retried at the shortest pause. It uses a clean session; publications in flight when the connection breaks fail and are not resent.
- AMQP: after a failure the connection is rebuilt by the next message, at most once per pause (200 ms doubling
to 30 s); messages in between fail at once with
the AMQP broker is unavailable (...); the next connection attempt is in 1.6s. A closed channel (for example afterNOT_FOUND) is reopened on the next message.
TLS files are read again on every new connection; restart the pods after rotating a client certificate, as the publishing connections stay open.
Allow-lists¶
FASTMOCK_MQTT_ALLOWED_TOPICS and FASTMOCK_AMQP_ALLOWED_EXCHANGES work like FASTMOCK_KAFKA_ALLOWED_TOPICS:
unset allows everything; otherwise a message outside the list is not published and fails with
topic is not in FASTMOCK_MQTT_ALLOWED_TOPICS or exchange audit is not in FASTMOCK_AMQP_ALLOWED_EXCHANGES. The
stub still answers. For the AMQP default exchange (amq.default or an empty exchange) the routing key is the
destination queue, so the list needs amq.default/<queue> entries: amq.default/replies.* allows routing keys
starting with replies.; a plain amq.default entry allows none. The AsyncAPI import warns about async mocks outside the lists, and
POST /__admin/async-mocks/{id}/trigger answers 400. Use them in shared brokers.
TLS and authentication¶
TLS uses rustls (TLS 1.2 and 1.3) with the ring provider. The broker certificate is verified against the public
Mozilla roots compiled into the binary plus the certificates of the *_TLS_CA_FILE bundle; verification cannot be
switched off. The certificate must name the host of the URL. *_TLS_CERT_FILE (leaf first, then intermediates)
and *_TLS_KEY_FILE (unencrypted PEM) present a client certificate for mTLS; set both or neither. For mqtts://
the MQTT client talks to a Unix socket of the process and FastMock wraps that connection in TLS towards the broker.
On Linux the socket has a random name in the abstract namespace, so no file is written and a read-only root
filesystem needs no writable /tmp; the bridge accepts connections from the FastMock process only. On other Unix
systems the socket is a file in a private temporary directory (mode 0700, removed with the connection), so
TMPDIR (else /tmp) must be writable there.
| Broker setup | Settings |
|---|---|
| MQTT with user and password | FASTMOCK_MQTT_USERNAME, FASTMOCK_MQTT_PASSWORD (use mqtts:// outside test networks) |
| MQTT with a private CA | mqtts://..., FASTMOCK_MQTT_TLS_CA_FILE |
| MQTT with client certificates | plus FASTMOCK_MQTT_TLS_CERT_FILE, FASTMOCK_MQTT_TLS_KEY_FILE |
| RabbitMQ with user and password | FASTMOCK_AMQP_USERNAME, FASTMOCK_AMQP_PASSWORD |
| RabbitMQ over TLS | amqps://..., FASTMOCK_AMQP_TLS_CA_FILE |
RabbitMQ with rabbitmq_auth_mechanism_ssl |
amqps://..., the client certificate and FASTMOCK_AMQP_SASL_MECHANISM=EXTERNAL |
The same settings are used by message capture.
Observability¶
| Signal | Content |
|---|---|
fastmock_messages_total{protocol, result} |
Stub messages: protocol = kafka, mqtt, amqp; result = sent, failed (allow-list, broker or encoding errors), dropped (more than 256 publications of a replica in flight). |
fastmock_async_messages_total{mock, result} |
Async mock publications of every protocol. |
log message published |
protocol, topic (exchange/routing key for AMQP), for Kafka partition and offset. |
log message publishing failed |
protocol, topic, error. |
logs MQTT connected, MQTT connection lost; reconnecting, AMQP connected, AMQP connection failed |
Connection state, with the broker URL (never credentials). |
Errors returned through the admin API (POST /__admin/async-mocks/{id}/trigger, the lastError of capture sources)
name no broker address, virtual host, certificate detail or broker response: they say what failed, for example
publishing to AMQP failed: broker connection refused (details in the server log), TLS handshake failed or
schema registry returned 404. Errors FastMock raises itself (allow-lists, invalid values, missing settings or
exchanges) keep their text. The server log has the full error.
Troubleshooting¶
| Symptom | Cause |
|---|---|
FASTMOCK_MQTT_URL is not configured, FASTMOCK_AMQP_URL is not configured |
Set the broker URL. |
Connection refused, return code: NotAuthorized (MQTT) |
Wrong user or password, or the broker requires them. |
invalid peer certificate: UnknownIssuer |
The broker's CA is missing from *_TLS_CA_FILE. |
the MQTT broker did not acknowledge the message within 10s |
The broker is overloaded or dropped the connection; QoS 0 avoids waiting for acknowledgements. |
the broker refused the message: NotAuthorized |
The broker's ACL denies the topic to FastMock's user. |
exchange orders does not exist |
Create the exchange, or set FASTMOCK_AMQP_DECLARE_EXCHANGES=true (not for exchange names produced by a template). |
the default exchange with this routing key is not in FASTMOCK_AMQP_ALLOWED_EXCHANGES |
Add amq.default/<queue> (or a prefix*) for the queues stubs may publish to. |
responseTopic ... is not a valid MQTT topic name |
The rendered response topic contains +, # or a control character. |
ACCESS_REFUSED (AMQP) |
The user lacks write on the exchange (or configure for declarations), or the virtual host is wrong (/%2f is /). |
| MQTT 5 properties are missing at the consumer | FASTMOCK_MQTT_VERSION=3.1.1, or the consumer uses MQTT 3.1.1. |