AsyncAPI and async mocks¶
FastMock imports AsyncAPI 2.x (2.0 to 2.6) and 3.0 documents, in JSON or YAML, and turns every operation that the described application publishes into a mock that keeps publishing example messages:
- Kafka operations become async mocks: stored definitions that a background publisher sends to a Kafka topic at a fixed frequency, round robin over their examples, as JSON or Confluent Avro.
- WebSocket operations become WebSocket stubs (ordinary stubs with
response.websocket) that stream the examples to every client that connects. See WebSocket mocks.
This is the event-driven counterpart of the OpenAPI import and covers the "async API mocking" feature of Microcks. To check that a real producer respects the same contract, see Contract testing.
- Importing a document
- What is imported
- Examples and generated payloads
- Avro
- The async mock document
- Managing async mocks
- Publishing and leader election
- Kafka topic allowlist
- Metrics, traces and logs
- Limits
- Errors
The examples use FASTMOCK_TOKEN for an editor or admin token and the admin API on localhost:9090. Kafka
publishing needs FASTMOCK_KAFKA_BOOTSTRAP (and FASTMOCK_KAFKA_SCHEMA_REGISTRY_URL for Avro), see
Kafka messages.
Importing a document¶
curl -X POST localhost:9090/__admin/import/asyncapi \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'content-type: application/json' \
-d "$(jq -n --rawfile spec streetlights.yaml '{spec: $spec, tag: "streetlights", frequencyMs: 5000}')"
| Field | Type | Default | Meaning |
|---|---|---|---|
spec |
string or object | required | The AsyncAPI document: a JSON object, or a JSON or YAML string. |
tag |
string | asyncapi-<title slug> |
Tag put on every async mock and WebSocket stub created by the import. Re-importing with the same tag replaces the async mocks and the stubs that carry it. 1..128 characters. |
dryRun |
boolean | false |
Parse and convert, return what would be created, store nothing. |
frequencyMs |
integer | 10000 |
Publishing interval for every created mock, 1000..86400000. |
pathPrefix |
string | none | Prefix for the paths of WebSocket stubs, for example /ws. Must start with /. |
topicNaming |
string | channel |
Kafka topic names: channel (below) or microcks (<service>-<version>-<channel>, as Microcks publishes; see Microcks topic names). |
The response is 201 Created (or 200 OK for a dry run):
{
"dryRun": false,
"tag": "streetlights",
"asyncMocks": [
{
"id": "0193a5c2-8f4e-7c1a-9d4e-2f6b1a7c9e01",
"name": "sendLightMeasured",
"protocol": "kafka",
"channel": "smartylighting.streetlights.1.0.event.s1.lighting.measured",
"operation": "sendLightMeasured",
"service": "Streetlights Kafka API:1.0.0",
"messages": [
{"name": "example-1", "key": "s1", "payload": {"lumens": 7, "sentAt": "{{now}}"}}
],
"frequencyMs": 5000,
"enabled": true,
"templated": true,
"contentType": "application/json",
"payloadSchema": {"type": "object", "properties": {"lumens": {"type": "integer", "minimum": 0}, "sentAt": {"type": "string", "format": "date-time"}}},
"tags": ["streetlights"],
"updatedAt": "2026-11-19T10:00:00Z"
}
],
"websocketStubs": [],
"warnings": [
"channel `smartylighting.streetlights.1.0.event.{streetlightId}.lighting.measured` was mapped to Kafka topic `smartylighting.streetlights.1.0.event.s1.lighting.measured`",
"turnOn: `receive` (the application consumes); nothing to mock"
]
}
Warnings never fail the import; read them. A document that yields no async mock and no WebSocket stub (for example
only publish operations) is answered 400 and the mocks of the tag are left as they were. They explain skipped operations, renamed topics, topics outside the
allowlist, examples that are not valid templates (they are then sent verbatim, templated: false) and a missing
Kafka configuration.
What is imported¶
FastMock mocks the side of the document that sends messages, because that is what a consumer under test needs:
| AsyncAPI | Mocked operation |
|---|---|
| 2.x | channels with a subscribe operation (the application publishes and clients subscribe) |
| 3.0 | operations with "action": "send" |
publish (2.x) and receive (3.0) operations are reported as warnings and skipped.
Protocol. An operation is mocked for Kafka when its operation, channel or message has a kafka binding, and for
WebSocket when it has a ws binding. Without bindings, the protocols of the servers decide: the servers listed by
the channel (servers in 2.2+ or 3.0), otherwise all servers of the document. kafka and kafka-secure mean Kafka,
ws and wss mean WebSocket. Operations with neither (for example MQTT or AMQP only) are skipped with a warning. An
operation that matches both protocols produces one mock for each.
Messages. Each message of an operation becomes its own mock, so a 2.x message.oneOf with three messages, or a
3.0 operation with three messages, gives three mocks named <operation> <message name>. An operation with a single
message is named after the operation (operationId in 2.x, the operation key in 3.0). A 3.0 operation without
messages uses every message of its channel.
Kafka topic. bindings.kafka.topic of the channel wins. Otherwise the channel name (2.x) or address (3.0) is
used; channel parameters such as {streetlightId} are replaced with the parameter's first examples value, its
default, its first enum value, an example generated from its schema, or else its name. Characters that Kafka
does not allow in topic names (anything but a-z A-Z 0-9 . _ -) become -, and the result is cut to 249
characters, so user/signedup becomes user-signedup. Each such change is reported as a warning.
Microcks topic names¶
Microcks publishes to <service name without spaces and dashes>-<version without spaces>-<operation part>, where the
operation part is the channel address with its parameters replaced and / turned into - (AsyncAPI 2.x and
parameterized 3.0 channels), or the operation key (other 3.0 operations); bindings.kafka.topic is not used.
Consumers configured for Microcks keep working when the import sets "topicNaming": "microcks":
curl -X POST localhost:9090/__admin/import/asyncapi \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'content-type: application/json' \
-d "$(jq -n --rawfile spec streetlights.yaml '{spec: $spec, tag: "streetlights", topicNaming: "microcks"}')"
For the document above the topic becomes
StreetlightsKafkaAPI-1.0.0-smartylighting.streetlights.1.0.event.s1.lighting.measured. Parameters take the value
described under Kafka topic (Microcks takes it from each example message, so use one example value per
parameter). Characters Kafka does not allow become -, with a warning.
WebSocket path. pathPrefix + the channel address. Parameters stay as path template parameters, so
/live/{city} matches /live/kyiv and {{request.pathParams.city}} is available in the examples.
Key, headers and content type. The Kafka key is an example of bindings.kafka.key of the message. Headers come
from each example's headers, or from an example generated from the message headers schema. The content type is
the message contentType or the document defaultContentType; when set it is sent as the Kafka header
content-type unless the example sets that header itself.
$ref pointers inside the document (#/components/..., #/channels/..., #/servers/...) are resolved with
the same budgets as the OpenAPI import: recursion is cut, at most 200,000 nodes are expanded per operation, and the
resolved document may not exceed 64 MiB (counted while references are expanded). References to other files or URLs are not fetched; they resolve to an
empty schema.
Examples and generated payloads¶
For every message, FastMock takes the first of these that exists:
- The message
examples(each item'spayload,headersandname); up to 100 per message. - The payload schema's
examplesarray, or itsexample. - A payload generated from the schema, as in the OpenAPI import:
enum,const,defaultandminimumvalues are used, formats get typical values (date-timegives2026-01-01T00:00:00Z,uuida fixed UUID,emailuser@example.com), objects get all their properties, arrays one item. Avro schemas get a value per field (see Avro).
Example payloads are templates: every string is rendered with the template engine before each publication, with no request (async mocks run on a timer, not in reply to a request). The context is:
| Variable | Value |
|---|---|
mock.id, mock.name, mock.channel |
the async mock |
sequence |
a counter per mock, shared by all replicas, starting at 1 |
example |
the name of the example being sent |
All helpers work (uuid, now, randomInt, randomDigits, pickRandom, ...; see Templating).
A string that is exactly "{{json expr}}" keeps the JSON type of the value:
{"id": "{{uuid}}", "sentAt": "{{now}}", "seq": "{{json sequence}}", "lumens": "{{json (randomInt 0 1000)}}"}
Avro¶
A message whose schemaFormat (2.x message, or 3.0 multi-format payload {"schemaFormat": ..., "schema": ...})
starts with application/vnd.apache.avro (for example application/vnd.apache.avro;version=1.9.0 or
application/vnd.apache.avro+json;version=1.9.0) is published as Confluent-framed Avro, exactly like a stub
message with avroSchema: the schema is registered under the subject <topic>-value in
FASTMOCK_KAFKA_SCHEMA_REGISTRY_URL, and each JSON example is converted to Avro with the same rules (unions, logical
types, defaults, named types). The schema may be inline JSON or a JSON string.
Generated Avro examples use the field default when there is one, 0 for numbers, "string" for strings, the
first enum symbol, one item for arrays, {"key": ...} for maps, the first non-null branch of unions,
"2026-01-01" for date, "2026-01-01T00:00:00Z" for timestamps and "0" for decimals. A named type that
refers to itself is expanded once; the inner reference becomes null. One generated example has at most 10,000
values and 1 MiB.
The async mock document¶
| Field | Type | Default | Meaning |
|---|---|---|---|
id |
UUID | generated | Taken from the URL on PUT. |
name |
string | required | 1..256 characters. Used in logs and traces. |
protocol |
kafka |
kafka |
Stored async mocks are Kafka mocks; WebSocket mocks are stubs. |
channel |
string | required | Kafka topic: a-z A-Z 0-9 . _ -, at most 249 characters. |
messages |
array | required | 1..100 examples: {"name", "key", "headers", "payload"}. payload is any JSON; a string is sent as raw text, other values as JSON. |
frequencyMs |
integer | 10000 |
Interval between publications, 1000..86400000. One example is sent per interval, round robin. |
enabled |
boolean | true |
Disabled mocks are kept but not published. |
templated |
boolean | true |
Render payload, key and header values as templates. |
contentType |
string | none | Sent as the content-type header unless an example sets it. |
avroSchema |
object | none | Publish as Confluent Avro with this schema. |
payloadSchema |
object | none | JSON Schema of the payload, kept for contract testing. |
operation, service |
string | none | Where the mock came from. |
tags |
array | none | At most 32 tags of up to 128 characters. |
Validation runs on import and on PUT: limits above, every template must compile, payloads at most 256 KiB, at most
64 headers per example (names up to 256 bytes, values up to 8 KiB), keys up to 4 KiB.
Managing async mocks¶
All routes are under /__admin and need a token: GET needs viewer, everything else editor. Changes are written
to the audit log.
| Route | Purpose |
|---|---|
POST /import/asyncapi |
import a document (above) |
GET /async-mocks?tag= |
list async mocks, optionally by tag |
GET /async-mocks/{id} |
one async mock |
PUT /async-mocks/{id} |
create or replace an async mock |
DELETE /async-mocks/{id} |
delete it (204, or 404) |
POST /async-mocks/{id}/trigger |
publish the next example now, on the replica that receives the call |
Create one by hand:
curl -X PUT localhost:9090/__admin/async-mocks/0193a5c2-8f4e-7c1a-9d4e-2f6b1a7c9e01 \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'content-type: application/json' -d '{
"name": "order events",
"channel": "orders.v1",
"frequencyMs": 2000,
"contentType": "application/json",
"messages": [
{"name": "created", "key": "order-{{sequence}}", "headers": {"x-event": "created"},
"payload": {"orderId": "order-{{sequence}}", "status": "CREATED", "at": "{{now}}"}},
{"name": "paid", "key": "order-{{sequence}}", "headers": {"x-event": "paid"},
"payload": {"orderId": "order-{{sequence}}", "status": "PAID", "at": "{{now}}"}}
]
}'
Pause it, then publish one message on demand:
curl -X PUT localhost:9090/__admin/async-mocks/0193a5c2-8f4e-7c1a-9d4e-2f6b1a7c9e01 \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'content-type: application/json' \
-d "$(curl -s localhost:9090/__admin/async-mocks/0193a5c2-8f4e-7c1a-9d4e-2f6b1a7c9e01 \
-H "Authorization: Bearer $FASTMOCK_TOKEN" | jq '.enabled = false')"
curl -X POST localhost:9090/__admin/async-mocks/0193a5c2-8f4e-7c1a-9d4e-2f6b1a7c9e01/trigger \
-H "Authorization: Bearer $FASTMOCK_TOKEN"
trigger works for disabled mocks too, and continues the same round robin as the background publisher.
Publishing and leader election¶
Every replica runs the publisher loop, but exactly one replica publishes at a time, so the number of replicas never multiplies the message rate. The replicas elect the publisher with a lease in Valkey:
- The lease is the key
asyncmock:leader(underFASTMOCK_VALKEY_PREFIX) holding the id of the leading replica, with a 15 second time-to-live. - A replica becomes leader by creating the key only if it does not exist (
SET NX PXsemantics, through the same atomic compare-and-set script that scenarios use). The leader renews it every 5 seconds by an atomic compare-and-set that succeeds only while the key still holds its own id; followers try to take it every second. - The leader publishes only while its local view of the lease is valid: it counts the 15 seconds from the moment before its last successful renewal, minus a 2 second safety margin. A leader that cannot reach Valkey therefore stops publishing before another replica can acquire the lease.
- On shutdown the leader releases the lease (it lets the key expire at once), so another replica takes over within about a second. If a replica dies without releasing, the lease expires within 15 seconds.
- The leader reloads the async mocks every 5 seconds; changes made through the admin API on any replica are
picked up within that time. Each enabled mock is published once per
frequencyMs, the first time right after the leader loads it. - The round-robin position is the
sequencecounter in Valkey (asyncmock:seq:<id>, kept 30 days), so a new leader continues where the previous one stopped.
With FASTMOCK_STORAGE=memory the single instance is always the leader. The gauge fastmock_async_leader is 1 on
the leading replica and 0 elsewhere; alert if the sum over all replicas stays 0.
Publishing is at-most-once per interval: a failed publication is logged and counted, not retried, and the next
example follows at the next interval. Up to 32 publications run at once per leader; when they are all busy (for
example Kafka is slow), due messages are skipped and counted as dropped.
Kafka topic allowlist¶
Async mocks publish through the same Kafka client as stub messages, so FASTMOCK_KAFKA_ALLOWED_TOPICS applies
(name or prefix*, comma-separated; unset allows every topic). On import, topics outside the list produce a
warning; at run time publishing to them fails and is counted as failed, and trigger answers 400. The topics
must exist; FastMock does not create them.
FASTMOCK_KAFKA_BOOTSTRAP=kafka-0.example.com:9092 \
FASTMOCK_KAFKA_SCHEMA_REGISTRY_URL=http://schema-registry.example.com:8081 \
FASTMOCK_KAFKA_ALLOWED_TOPICS='orders.v1,smartylighting.*' \
fastmock serve
Metrics, traces and logs¶
| Metric | Type | Labels | Meaning |
|---|---|---|---|
fastmock_async_messages_total |
counter | mock (async mock id), result = sent, failed, dropped |
Publications by async mocks, scheduled or triggered. Ids of stored mocks only, at most 1000. |
fastmock_async_leader |
gauge | none | 1 on the replica that holds the publisher lease. |
fastmock_async_mocks_active |
gauge | none | Enabled Kafka async mocks loaded by the leader. |
fastmock_store_errors_total |
counter | store = asyncmocks, asyncmock_lease |
Storage errors while loading mocks or renewing the lease. |
Every publication has a span fastmock.async_publish (otel.kind=producer, messaging.system=kafka,
messaging.destination.name, fastmock.async_mock). Leadership changes are logged at info, failed publications
at warn with the topic and the error.
Limits¶
| Limit | Value |
|---|---|
| Stored async mocks | 1000 |
| Examples per mock | 100 |
| Payload or Avro schema size | 256 KiB |
| Headers per example | 64 |
frequencyMs |
1000 .. 86,400,000 |
| Operations or channels per document | 2000 |
$ref expansion |
200,000 nodes per operation, 64 MiB in total |
| Generated Avro example | 10,000 values, 1 MiB |
| Concurrent publications per leader | 32 |
Errors¶
| Status | When |
|---|---|
400 |
The document is not AsyncAPI 2.x or 3.x, has no channels (2.x) or operations (3.0), exceeds a limit, is neither JSON nor YAML; invalid frequencyMs, tag or pathPrefix; an invalid async mock on PUT; storing would exceed 1000 mocks; trigger to a topic outside the allowlist or without FASTMOCK_KAFKA_BOOTSTRAP. The body is {"error": "..."}. |
401 / 403 |
Missing token, or a viewer token on a route that changes something. |
404 |
Unknown async mock id. |
502 |
trigger could not publish (Kafka unreachable, unknown topic, schema registry error); details are in the server log. |