Skip to content

Concepts

This page explains how FastMock is put together and what happens to a request. Feature pages go into detail; this one gives the model they share.

Data plane and control plane

FastMock listens on two ports.

Data plane Control plane
Default address 0.0.0.0:8080 (FASTMOCK_LISTEN) 0.0.0.0:9090 (FASTMOCK_ADMIN_LISTEN)
Serves mocks: stubs, plugins, gRPC, SSE, WebSocket /__admin/* API, /ui, OpenAPI document and Swagger UI, /metrics, /healthz, /readyz
Clients the system under test tests, CI pipelines, the operator, people, Prometheus
Authentication none (it imitates other services) bearer token with a role on every /__admin call
TLS optional, with mTLS (FASTMOCK_TLS_*) terminate at the Gateway or ingress

The two can never be the same port, and no admin route exists on the data port: a system under test cannot change its own mocks. Expose them separately (in Kubernetes the chart creates two Services) and restrict the control plane to the clients that need it (Security).

Stubs

A stub is a JSON document: a request pattern and what to do when a request matches it.

{
  "id": "7f1c4c1e-8a0a-4a43-9d1b-0d6c1d4a9f10",
  "name": "send sms",
  "priority": 5,
  "tags": ["billing"],
  "metadata": {"owner": "team-messaging"},
  "enabled": true,
  "request": {"method": "POST", "urlPath": "/sms"},
  "response": {"status": 202, "jsonBody": {"id": "{{uuid}}"}},
  "scenario": {"name": "sms-{{request.json.to}}", "newState": "SENT"},
  "callbacks": [{"url": "http://app.example.svc/hooks/sms", "jsonBody": {"status": "DELIVERED"}}],
  "messages": [{"topic": "sms.events", "jsonValue": {"to": "{{request.json.to}}"}}]
}
Part Purpose Reference
id UUID; generated when absent. PUT /__admin/stubs/{id} creates or replaces a stub with a known id. Stub lifecycle
name, tags, metadata Labels for people, cleanup (DELETE /__admin/stubs?tag=), import sets and metrics. Stub lifecycle
priority Lower numbers are tried first; default 5. Request matching
enabled Disabled stubs stay stored but never match. Stub lifecycle
request Method, path (exact, template, regex), query, headers, body matchers, GraphQL. Request matching
response Status, headers, body, delay, fault, proxy, SSE. Responses
scenario State machine condition and transition. Scenarios and state
callbacks Durable HTTP requests sent after the response. Callbacks
messages Kafka records published when the stub matches. Kafka

Stub JSON is strict: unknown fields are rejected with 400, so typos do not silently change behaviour. Stubs can be validated without saving them (POST /__admin/stubs/validate, fastmock validate file.json), imported in bulk, generated from OpenAPI, WireMock, MockServer, Postman, HAR and other formats (Importing), or recorded from a real service (Recording).

Matching order

All enabled stubs are kept in memory, compiled (regular expressions, JSONPath, schemas) and sorted once when they change. For each request FastMock walks the list and the first stub whose every condition holds answers:

  1. priority: lower first.
  2. order at equal priority: stubs that carry an order (set by the WireMock and MockServer importers to reproduce their tie-breaking) come first, lower order first.
  3. Specificity of the path for stubs without order: an exact path before a path template, templates with fewer parameters before templates with more, a trailing {rest...} template after those, then regular expressions, then stubs without a path condition.
  4. Recency: at equal priority and specificity, the most recently changed stub wins.

A stub with a scenario whose requiredState does not hold is skipped and the walk continues. When nothing matches, the data plane answers 404 {"error":"no stub matched","method":"GET","path":"/x"} and journals the request with matched=false; POST /__admin/requests/near-misses explains which stubs came closest and why (Verification).

Templates

Response bodies, headers, callback and message fields and scenario names are Handlebars templates rendered with the request as context: request.pathParams.id, request.json.orderId, request.headers.x-client-id, state.current, and helpers such as uuid, now, jsonPath, randomInt, hmac. Templates are a closed language: they cannot read files, environment variables, secrets or the network, and their size and output are bounded. Set "templated": false on a response to send text with {{ literally. See Templating.

Scenarios and key-value state

A scenario is a named state machine. Stubs require a state (requiredState) and move it (newState), so the same request can get different answers over time. Names are templates, so one set of stubs drives a separate machine per order or user. States start at Started, expire after ttlSeconds (7 days by default), and change atomically across replicas. A separate key-value store keeps strings with optional expiry. See Scenarios and state.

Request journal

Every data-plane request is recorded after the response is sent: method, path, query, headers, body, status, response body, matched stub, correlation id, duration and trace id. Secrets are masked before anything is stored (redaction). Tests query the journal to verify calls (GET /__admin/requests, /requests/count) and wait for them with the Java client's awaitRequests.

Because the journal is written asynchronously, an entry can appear a few milliseconds after the response; poll instead of reading once. When the write queue (FASTMOCK_JOURNAL_QUEUE) is full, entries are dropped and counted in fastmock_journal_dropped_total rather than slowing down mocks. Entries are kept for FASTMOCK_JOURNAL_RETENTION (24 h). See Verification.

Callbacks outbox

Callbacks are written to an outbox before the response is returned, then delivered by whichever replica claims them when they are due. Delivery is at-least-once with exponential backoff for network errors, 408, 429 and 5xx, up to maxAttempts. Every attempt carries the same x-fastmock-delivery-id (the idempotency key for receivers), the attempt number, a traceparent that continues the trace of the original request, and optionally an HMAC signature made with a server-side secret that stubs may use only if it is listed in FASTMOCK_STUB_SECRETS. Outgoing traffic passes the egress policy. See Callbacks.

Kafka messages

Stubs can publish Kafka records (text, JSON, or Avro registered in a Schema Registry) when they match. Publishing runs in the background and does not delay or fail the response. See Kafka.

Plugins

Some providers need more than declarative stubs: generated identifiers that later requests refer to, delivery reports that depend on earlier messages, provider-specific signatures. Such providers are implemented as plugins compiled into the binary. A plugin is mounted on the data port under /<name>, can add admin routes under /__admin/plugins/<name>/, uses the same stores, templates, callbacks outbox, journal and metrics (its traffic is labelled source="<name>" instead of source="stubs"), and reads settings from FASTMOCK_PLUGIN_<NAME>_<KEY>. GET /__admin/plugins and fastmock plugins list them; FASTMOCK_PLUGINS selects which are active. The release binary contains no plugins; Writing plugins shows how to build one that does.

Storage modes

What memory postgres (PostgreSQL + Valkey)
stubs process PostgreSQL fm_stubs, change notifications via LISTEN/NOTIFY
request journal process, latest 100,000 entries PostgreSQL fm_journal
callbacks outbox process PostgreSQL fm_outbox
audit log process PostgreSQL fm_audit (kept 90 days)
imported documents, gRPC descriptors, plugin data process PostgreSQL fm_data
scenario states, key-value entries, chaos rules, recording state, plugin counters process Valkey, keys under FASTMOCK_VALKEY_PREFIX
survives a restart no yes
replicas exactly one any number

memory needs nothing else and starts in milliseconds: use it on a laptop and in CI jobs that start their own FastMock. postgres is the default and the mode for shared environments. Migrations run at start-up (or separately with fastmock migrate). PostgreSQL 18 and Valkey 9 are the tested versions.

Running several replicas

In postgres mode replicas share everything, so you can scale horizontally and roll out without losing state:

  • Stubs change on all replicas within milliseconds (PostgreSQL notifications, with polling every FASTMOCK_STUB_POLL as a fallback).
  • Scenario transitions use compare-and-set in Valkey: concurrent requests on different replicas move a scenario exactly once.
  • Callbacks are claimed with row locks; any replica delivers, and a callback whose replica died is retried by another after its lease expires.
  • The journal is one table: a test can call replica A and verify through replica B.
  • Chaos rules are cached for up to 2 seconds per replica.
  • Shutdown is graceful: on SIGTERM a replica withdraws readiness, waits FASTMOCK_SHUTDOWN_DELAY, then finishes open requests (up to 20 s) and in-flight callbacks.

Several independent FastMock instances can share one PostgreSQL server if each uses its own database, and one Valkey if each uses its own FASTMOCK_VALKEY_PREFIX.

Life of a request

client ──► data port
            │ size and memory budget checks (413 / 503)
            │ server span, trace id (continues an incoming traceparent)
            │ chaos rules (may delay, fail or reset)
            │ plugin route?  ── yes ──► plugin handler
            │ gRPC?          ── yes ──► decode with descriptors, then match as JSON
            │ match stubs (priority, specificity, recency, scenario state)
            │   ├─ no match ─► 404, or proxy to the recording target while recording
            │   └─ match ───► scenario transition (compare-and-set)
            │                 render response, callbacks → outbox, messages → Kafka (background)
            │                 delay, then response / fault / proxy / SSE stream
            ▼
        response + x-fastmock-trace-id
            │ metrics (requests, latency, stub hits)
            └─► journal queue ─► background writer (redacted)