Responses¶
The response object of a stub describes what FastMock sends back: status, reason phrase, headers, a body (inline,
JSON, base64 or a stored file), a delay, a slow "dribbled" body, a network fault, a proxy to a real service or a
stream of Server-Sent Events. A stub can also return a different response on every call with responses.
- Status, reason phrase and headers
- Bodies
- Body files
- Delays
- Dribbling the body
- Faults
- Response sequences
- Proxying
- Server-Sent Events
- Errors and metrics
Status, reason phrase and headers¶
{
"request": {"method": "GET", "urlPath": "/legacy/status"},
"response": {
"status": 299,
"statusMessage": "Mostly Fine",
"headers": {"content-type": "text/plain", "x-request-id": "{{uuid}}"},
"body": "partial"
}
}
| Field | Default | Meaning |
|---|---|---|
status |
200 | Any code from 200 to 599. |
statusMessage |
standard phrase | Custom reason phrase on HTTP/1.1 (HTTP/1.1 299 Mostly Fine). HTTP/2 has no reason phrase, so it is ignored there. At most 256 bytes, no control characters. |
headers |
none | Name to value, or to an array of values sent as separate header lines ("set-cookie": ["a=1", "b=2"]; the lines are never folded into one); values are templates. A rendered value that is not a valid header value is dropped and counted in fastmock_invalid_response_headers_total. |
templated |
true |
Render header values, bodies and bodyFileName as Handlebars templates (see Templating). |
Bodies¶
Use at most one of these fields:
| Field | Meaning |
|---|---|
body |
Text; a template when templated is true. |
jsonBody |
A JSON value; every string inside is a template, and "{{json expr}}" keeps the JSON type of the value. Adds content-type: application/json unless a header sets it. |
base64Body |
Binary content, base64-encoded; never templated. |
bodyFileName |
The name of a stored file, see below. |
Body files¶
Large or binary bodies, shared fixtures and bodies maintained outside the stub live in the file store and are
referenced by name. Upload them through the admin API (the request body is the file, Content-Type is stored with
it, files are limited to 10 MiB):
curl -X PUT http://localhost:9090/__admin/files/users/7.json \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'content-type: application/json' \
--data-binary '{"id": 7, "name": "Ann", "requestedPath": "{{request.path}}"}'
{
"request": {"method": "GET", "urlPathTemplate": "/users/{id}"},
"response": {"status": 200, "bodyFileName": "users/{{request.pathParams.id}}.json"}
}
bodyFileNameis a template whentemplatedis true, so one stub can serve many files.- The stored content type becomes the
content-typeheader unless the stub sets one. - With
templated: truethe file content is rendered as a template when it is text (text/*, JSON, XML, YAML, CSV, HTML, JavaScript, form data, or valid UTF-8 without a content type) and contains{{. Templates are limited to 256 KiB: set"templated": falsefor larger text files that only need to be served. Binary files are served byte for byte. - Files are stored in PostgreSQL (DataStore namespace
files), so every replica serves the same content. Each replica caches a file for up to 2 seconds (at most 256 files and 64 MiB; files over 16 MiB are not cached). - File names use
[A-Za-z0-9._-/], at most 512 bytes;GET /__admin/fileslists them.
When the file does not exist (or the rendered name is empty or longer than 512 bytes) the client gets
500 {"error": "response body file is not available", ...} without the file name, the name is logged on the
server, and fastmock_body_file_missing_total is incremented.
Delays¶
{"response": {"status": 200, "body": "slow", "delay": {"fixedMs": 1500}}}
{"response": {"status": 200, "body": "jittery", "delay": {"minMs": 100, "maxMs": 900}}}
{"response": {"status": 200, "body": "realistic", "delay": {"lognormal": {"medianMs": 120, "sigma": 0.4}}}}
delay field |
Meaning |
|---|---|
fixedMs |
Always this many milliseconds. |
minMs / maxMs |
Uniformly random in the range (either bound alone is allowed). |
lognormal |
{"medianMs", "sigma"}: a log-normal sample, medianMs * e^(sigma * N(0,1)). Half of the delays are below the median; a larger sigma gives a longer tail. Sigma 0.1 is tight, 0.5 is a typical network tail, 1 or more is very bursty. |
Use one kind per delay. Values are limited to 24 hours and sigma to 0..10 when the stub is saved, and every delay
is capped at FASTMOCK_MAX_DELAY (default 15 minutes) when it is applied.
The global settings add server-wide delays: fixedDelayMs is used for stubs
without their own delay, and delay (any kind above) is added to every stub response. Unmatched requests are not
delayed. The delay is applied before the response starts, also for proxy and SSE responses.
Dribbling the body¶
chunkedDribbleDelay sends the body in pieces spread over a duration, to test read timeouts and progress handling:
{
"request": {"urlPath": "/download/report.csv"},
"response": {
"headers": {"content-type": "text/csv"},
"body": "id,amount\n1,10\n2,20\n3,30\n",
"chunkedDribbleDelay": {"numberOfChunks": 5, "totalDurationMs": 2000}
}
}
The status and headers go out at once; the body is cut into numberOfChunks pieces of equal size (fewer when the
body is shorter than that) and each piece is sent after totalDurationMs / numberOfChunks. The response uses chunked
transfer encoding. numberOfChunks is 1 to 1000; the total duration is capped at FASTMOCK_MAX_DELAY. It cannot be
combined with sse, proxy or fault, and dribbled response bodies are not stored in the request journal.
Faults¶
fault breaks the response on purpose:
| Fault | What the client sees |
|---|---|
EMPTY_RESPONSE |
Nothing: the connection closes without a single byte (curl: Empty reply from server, Java clients: NoHttpResponseException). Over HTTP/2 the stream is reset before any frame of the response. As in WireMock. For a status line with an empty body, use a normal response without a body and connection: close. |
MALFORMED_JSON |
The status, content-type: application/json and a truncated JSON document. |
CONNECTION_RESET |
The connection closes before a complete response arrives. |
RANDOM_DATA_THEN_CLOSE |
128 random bytes instead of an HTTP response, then the connection closes. |
MALFORMED_RESPONSE_CHUNK |
HTTP/1.1 200 OK, Transfer-Encoding: chunked, then bytes that are not a valid chunk, then the connection closes. |
curl -sv localhost:8080/flaky
# < HTTP/1.1 200 OK
# < Transfer-Encoding: chunked
# * Illegal or missing hexadecimal sequence in chunked-encoding (the wording differs between curl versions)
# curl: (56) ...
RANDOM_DATA_THEN_CLOSE and MALFORMED_RESPONSE_CHUNK write raw bytes on HTTP/1.x connections. On HTTP/2 the
connection carries other requests too, so FastMock sends a 200 response whose body stream is reset after the
garbage bytes. Faults can also be injected at random with chaos rules (PUT /__admin/chaos). Every injected fault
counts in fastmock_faults_total{fault}.
Response sequences¶
responses replaces response with a list that is served in turn, for retries, polling and state that changes over
time without scenarios:
{
"name": "payment status polling",
"request": {"method": "GET", "urlPathTemplate": "/payments/{id}"},
"responseMode": "sequential",
"responses": [
{"status": 202, "jsonBody": {"id": "{{request.pathParams.id}}", "status": "PENDING"}},
{"status": 202, "jsonBody": {"id": "{{request.pathParams.id}}", "status": "PROCESSING"}},
{"status": 200, "jsonBody": {"id": "{{request.pathParams.id}}", "status": "PAID"}}
]
}
responseMode |
Order |
|---|---|
sequential (default) |
1st, 2nd, 3rd, then the last one forever. |
cycle |
1st, 2nd, 3rd, 1st, 2nd, ... |
random |
A random entry on every call. |
for i in 1 2 3 4; do curl -s localhost:8080/payments/p-1; echo; done
# {"id":"p-1","status":"PENDING"}
# {"id":"p-1","status":"PROCESSING"}
# {"id":"p-1","status":"PAID"}
# {"id":"p-1","status":"PAID"}
- Every entry is a full response object (status, headers, bodies, delay, fault, ...).
- Use
responseorresponses, not both; at most 100 entries;responseModeneedsresponses. - The position is a counter in Valkey shared by all replicas, counted per stub (not per path parameter or client).
It restarts when the stub is changed (
PUT,PATCH, re-import) and onDELETE /__admin/stubs/counters; see Stub lifecycle. - Callbacks and Kafka messages of the stub are sent with every entry.
Proxying¶
{
"request": {"urlPathPattern": "/legacy/.*"},
"response": {
"proxy": {
"baseUrl": "https://legacy.example.com",
"stripPrefix": "/legacy",
"additionalHeaders": {"x-forwarded-by": "fastmock"},
"removeHeaders": ["authorization"]
}
}
}
The request is forwarded to baseUrl + path (minus stripPrefix) + query, through the egress policy
(FASTMOCK_CALLBACK_ALLOWED_HOSTS, FASTMOCK_CALLBACK_DENIED_CIDRS). Upstream bodies are limited to 16 MiB; failures answer
502. A proxy response cannot have a body. With the global setting "proxyPassThrough": false proxy stubs do not
forward and answer 404 {"error": "proxy pass-through is disabled"} (counted in
fastmock_proxy_pass_through_blocked_total), which keeps a test run from reaching real services.
Server-Sent Events¶
sse streams a list of events instead of a body; see Server-Sent Events.
Errors and metrics¶
| Situation | Client response | Metric / log |
|---|---|---|
| A template fails while rendering | 500 {"error": "stub evaluation failed"} |
fastmock_stub_errors_total, error log with the trace id |
| A body file is missing | 500 {"error": "response body file is not available"} |
fastmock_body_file_missing_total, error log with the file name |
| A rendered header value is invalid | the header is dropped | fastmock_invalid_response_headers_total |
| A fault is injected | see Faults | fastmock_faults_total{fault} |
A proxy stub is blocked by proxyPassThrough: false |
404 |
fastmock_proxy_pass_through_blocked_total |
A times stub is used up |
the next stub answers | fastmock_stub_exhausted_total{stub} |
Every response carries x-fastmock-trace-id, which is also the trace id of the request in the journal and in
OpenTelemetry.