mockstack 0.13.0__tar.gz → 0.14.0__tar.gz

{mockstack-0.13.0 → mockstack-0.14.0}/.env.example

@@ -32,6 +32,17 @@ MOCKSTACK__PROXYRULES_REVERSE_PROXY_TIMEOUT = 10.0
 MOCKSTACK__PROXYRULES_SIMULATE_CREATE_ON_MISSING = true
 MOCKSTACK__PROXYRULES_VERIFY_SSL_CERTIFICATES = true
 
+# record mode for the proxyrules strategy: off (default), missing or overwrite.
+# missing records a fixture rule's file from the next matching URL rule when the file
+# does not exist yet; overwrite also re-records files recorded before. Requests really
+# reach the upstream until recorded. Never enable on a shared or exposed instance.
+# See https://promptromp.github.io/mockstack/strategies/proxyrules/#recording-fixtures
+MOCKSTACK__PROXYRULES_RECORD_MODE = off
+# directory every recorded fixture must resolve inside; required when recording.
+# MOCKSTACK__PROXYRULES_RECORD_ROOT = "/some/path/fixtures/"
+# optional module:function called on every body before it is recorded (must be importable).
+# MOCKSTACK__PROXYRULES_RECORD_SCRUBBER = "my_scrubbers:mask_emails"
+
 # OpenTelemetry settings
 MOCKSTACK__OPENTELEMETRY__ENABLED = true
 MOCKSTACK__OPENTELEMETRY__ENDPOINT = "http://localhost:4317/"

{mockstack-0.13.0 → mockstack-0.14.0}/.gitignore

@@ -176,3 +176,4 @@ templates/*.j2
 
 # rules files rendered from the examples' ${VAR} placeholders
 examples/**/rules.local.yml
+examples/proxyrules-cookbook/09-recording/fixtures/

{mockstack-0.13.0 → mockstack-0.14.0}/CLAUDE.md

@@ -10,9 +10,11 @@ request to one *strategy*, selected with the `strategy` setting:
 - `filefixtures`: renders Jinja templates from `templates_dir`, chosen from the request
   path, and simulates resource creation, searches and commands for POSTs.
 - `proxyrules`: evaluates an ordered YAML rules file. The first matching rule serves a
-  `file:///` fixture, reverse-proxies to a real service, or redirects. Rules match on
-  path, method and `headers`/`query`/`body`/`json` predicates, and every response is
-  stamped with `X-Mockstack-Result` and `X-Mockstack-Rule`.
+  `file:///` fixture (with the rule's optional `status` and `response_headers`),
+  reverse-proxies to a real service, or redirects. In record mode
+  (`proxyrules_record_mode`) a missing fixture is recorded from the next matching URL
+  rule. Rules match on path, method and `headers`/`query`/`body`/`json` predicates, and
+  every response is stamped with `X-Mockstack-Result` and `X-Mockstack-Rule`.
 
 Both share `CreateMixin` for simulated creates. Settings come from pydantic-settings:
 CLI flags, `MOCKSTACK__*` environment variables, or a `.env` file.
@@ -25,6 +27,8 @@ CLI flags, `MOCKSTACK__*` environment variables, or a `.env` file.
   `create_mixin.py`, `factory.py`
 - `mockstack/rules.py`: the proxyrules `Rule`: predicates, load-time validation,
   template context
+- `mockstack/recording.py`: record-mode building blocks: fixture encoding that renders
+  back to the exact body, the recorded marker, root confinement and atomic writes
 - `mockstack/templating.py`: Jinja environment and path-to-template-name resolution
 - `mockstack/intent.py`, `mockstack/identifiers.py`: POST intent (search, command,
   create) and path-identifier heuristics
@@ -32,11 +36,13 @@ CLI flags, `MOCKSTACK__*` environment variables, or a `.env` file.
 - `mockstack/tests/`: unit tests; `conftest.py` holds fixtures shared by unit and live
   tests (`make_settings`, `make_request`, `write_rules`, `write_template`, `span`), and
   `strategies/conftest.py` adds strategy helpers (`traced_request`,
-  `proxyrules_strategy`, `apply_rule`). Build settings with `make_settings`: it ignores
+  `proxyrules_strategy`, `apply_rule`, `upstream_send`, `span_attributes`). Build settings with
+  `make_settings`: it ignores
   `MOCKSTACK__*` environment variables and `.env` files
 - `mockstack/tests/live/`: live tests against real uvicorn servers on loopback sockets;
   `conftest.py` provides the session-scoped recording echo `upstream`, the module-scoped
-  `mockstack_server`, `proxyrules_settings` and `render_rules`
+  `mockstack_server`, `proxyrules_settings` and `render_rules`; `test_record_mode_live.py`
+  records into temporary directories, never the repository
 - `examples/`: runnable examples; `examples/proxyrules-cookbook/` holds the files
   embedded in the cookbook docs page
 - `docs/`: the MkDocs Material site (`mkdocs.yml`); the home page is `README.md`

{mockstack-0.13.0 → mockstack-0.14.0}/Dockerfile

@@ -2,7 +2,7 @@
 
 # Define build argument for version
 ARG PYTHON_IMAGE_VERSION=3.13-slim
-ARG MOCKSTACK_VERSION=0.13.0
+ARG MOCKSTACK_VERSION=0.14.0
 
 # ---------------------------- Base Image --------------------------------
 

{mockstack-0.13.0 → mockstack-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mockstack
-Version: 0.13.0
+Version: 0.14.0
 Summary: An API mocking workhorse
 Author-email: Adam Ever-Hadani <mockstack.contact@gmail.com>
 License-Expression: MIT
@@ -63,6 +63,8 @@ Highlights include:
 * Rule predicates for the `proxyrules` strategy: match requests on path, method, headers, query parameters and JSON body fields, then serve a fixture, reverse-proxy to a real service, or redirect. :dart:
 * Dynamic replacements: a rule's replacement can be a Jinja template, so a request header can pick the fixture scenario to serve. :twisted_rightwards_arrows:
 * Result headers: every `proxyrules` response is stamped with `X-Mockstack-Result` and `X-Mockstack-Rule`, so a test can assert it got a fixture and not the real service. :label:
+* Fixture status codes and headers: a `proxyrules` fixture can answer with any status and extra headers, e.g. a 503 with `Retry-After`, to test how a client handles a failing dependency. :vertical_traffic_light:
+* Record mode: `proxyrules` can record real responses into the fixtures its rules serve, with an optional scrubber, then replay them without the real service. :red_circle:
 * Observability via [OpenTelemetry](https://opentelemetry.io/) integration. Get detailed traces of your sessions instantly reported to backends such as [Grafana](https://grafana.com/), [Jaeger](https://www.jaegertracing.io/), [Zipkin](https://zipkin.io/), etc. :eyes:
 * Configurability via [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) supports customizing behaviour via environment variables and a `.env` file. :flags:
 * Comprehensive unit-tests, linting and formatting coverage as well as vulnerabilities and security scanning with full CI automation to ensure stability and a high-quality codebase for production-grade use. :+1:
@@ -141,8 +143,19 @@ curl -i -H "X-Test-Run: ci-42" http://127.0.0.1:8000/projects/api/v1/project/pro
 curl -i http://127.0.0.1:8000/projects/api/v1/project/proj-123
 ```
 
-The [ProxyRules cookbook](https://promptromp.github.io/mockstack/guides/proxyrules-cookbook/) walks through this recipe and more (per-scenario fixtures, matching on request bodies and query parameters, asserting in tests), each backed by a live test.
+The [ProxyRules cookbook](https://promptromp.github.io/mockstack/guides/proxyrules-cookbook/) walks through this recipe and more (per-scenario fixtures, matching on request bodies and query parameters, asserting in tests, error responses, recording fixtures), each backed by a live test.
 
+### Record fixtures from a real service
+
+Instead of writing fixtures by hand, record them: with record mode on, a fixture rule whose file does not exist yet sends the request on to the next matching URL rule, saves the response into the fixture file, and serves it from there. Later requests are replayed from the file without calling the service. Record mode is off by default:
+
+```shell
+MOCKSTACK__STRATEGY=proxyrules MOCKSTACK__PROXYRULES_RULES_FILENAME=rules.yml \
+  MOCKSTACK__PROXYRULES_RECORD_MODE=missing MOCKSTACK__PROXYRULES_RECORD_ROOT=fixtures \
+  uv run mockstack
+```
+
+Requests really reach the service until their response is recorded, so record against a safe environment and review the recorded files before committing them. An optional scrubber can mask sensitive data first; see [Recording fixtures](https://promptromp.github.io/mockstack/strategies/proxyrules/#recording-fixtures) and the cookbook's [Record fixtures from a real service](https://promptromp.github.io/mockstack/guides/proxyrules-cookbook/#9-record-fixtures-from-a-real-service).
 
 ## Testing
 

{mockstack-0.13.0 → mockstack-0.14.0}/README.md

@@ -29,6 +29,8 @@ Highlights include:
 * Rule predicates for the `proxyrules` strategy: match requests on path, method, headers, query parameters and JSON body fields, then serve a fixture, reverse-proxy to a real service, or redirect. :dart:
 * Dynamic replacements: a rule's replacement can be a Jinja template, so a request header can pick the fixture scenario to serve. :twisted_rightwards_arrows:
 * Result headers: every `proxyrules` response is stamped with `X-Mockstack-Result` and `X-Mockstack-Rule`, so a test can assert it got a fixture and not the real service. :label:
+* Fixture status codes and headers: a `proxyrules` fixture can answer with any status and extra headers, e.g. a 503 with `Retry-After`, to test how a client handles a failing dependency. :vertical_traffic_light:
+* Record mode: `proxyrules` can record real responses into the fixtures its rules serve, with an optional scrubber, then replay them without the real service. :red_circle:
 * Observability via [OpenTelemetry](https://opentelemetry.io/) integration. Get detailed traces of your sessions instantly reported to backends such as [Grafana](https://grafana.com/), [Jaeger](https://www.jaegertracing.io/), [Zipkin](https://zipkin.io/), etc. :eyes:
 * Configurability via [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) supports customizing behaviour via environment variables and a `.env` file. :flags:
 * Comprehensive unit-tests, linting and formatting coverage as well as vulnerabilities and security scanning with full CI automation to ensure stability and a high-quality codebase for production-grade use. :+1:
@@ -107,8 +109,19 @@ curl -i -H "X-Test-Run: ci-42" http://127.0.0.1:8000/projects/api/v1/project/pro
 curl -i http://127.0.0.1:8000/projects/api/v1/project/proj-123
 ```
 
-The [ProxyRules cookbook](https://promptromp.github.io/mockstack/guides/proxyrules-cookbook/) walks through this recipe and more (per-scenario fixtures, matching on request bodies and query parameters, asserting in tests), each backed by a live test.
+The [ProxyRules cookbook](https://promptromp.github.io/mockstack/guides/proxyrules-cookbook/) walks through this recipe and more (per-scenario fixtures, matching on request bodies and query parameters, asserting in tests, error responses, recording fixtures), each backed by a live test.
 
+### Record fixtures from a real service
+
+Instead of writing fixtures by hand, record them: with record mode on, a fixture rule whose file does not exist yet sends the request on to the next matching URL rule, saves the response into the fixture file, and serves it from there. Later requests are replayed from the file without calling the service. Record mode is off by default:
+
+```shell
+MOCKSTACK__STRATEGY=proxyrules MOCKSTACK__PROXYRULES_RULES_FILENAME=rules.yml \
+  MOCKSTACK__PROXYRULES_RECORD_MODE=missing MOCKSTACK__PROXYRULES_RECORD_ROOT=fixtures \
+  uv run mockstack
+```
+
+Requests really reach the service until their response is recorded, so record against a safe environment and review the recorded files before committing them. An optional scrubber can mask sensitive data first; see [Recording fixtures](https://promptromp.github.io/mockstack/strategies/proxyrules/#recording-fixtures) and the cookbook's [Record fixtures from a real service](https://promptromp.github.io/mockstack/guides/proxyrules-cookbook/#9-record-fixtures-from-a-real-service).
 
 ## Testing
 

{mockstack-0.13.0 → mockstack-0.14.0}/docs/configuration.md

@@ -53,6 +53,9 @@ See [ProxyRules](strategies/proxyrules.md) for how rules are written and evaluat
 | `proxyrules_reverse_proxy_timeout` | `MOCKSTACK__PROXYRULES_REVERSE_PROXY_TIMEOUT` | float | `10.0` | Timeout in seconds for reverse-proxied upstream requests. An upstream that does not answer in time is answered with a 504 stamped `X-Mockstack-Result: error`. `None` (when constructing `Settings` in Python) disables the timeout |
 | `proxyrules_simulate_create_on_missing` | `MOCKSTACK__PROXYRULES_SIMULATE_CREATE_ON_MISSING` | boolean | `false` | Whether a request that matches no rule and looks like a resource creation (e.g. a POST) gets a simulated 201 (`X-Mockstack-Result: create`) instead of a 404 (`missing`) |
 | `proxyrules_verify_ssl_certificates` | `MOCKSTACK__PROXYRULES_VERIFY_SSL_CERTIFICATES` | boolean | `true` | Whether to verify the TLS certificates of HTTPS upstreams when reverse proxying. Disable with caution, e.g. for a trusted upstream with a self-signed certificate |
+| `proxyrules_record_mode` | `MOCKSTACK__PROXYRULES_RECORD_MODE` | string | `off` | Applies to the `proxyrules` strategy. Record mode. `missing` writes the upstream response into a fixture rule's file when that file does not exist yet; `overwrite` also re-records files that were recorded before, never hand-written ones. Requires `proxyrules_record_root` and `reverse_proxy`. Never enable on a shared or exposed instance; see [Recording fixtures](strategies/proxyrules.md#recording-fixtures). Environment variables take the lower-case values; `mockstack --help` lists the enum names (`OFF`, `MISSING`, `OVERWRITE`), and the command line accepts either form |
+| `proxyrules_record_root` | `MOCKSTACK__PROXYRULES_RECORD_ROOT` | path | - | Applies to the `proxyrules` strategy. Existing directory that every recorded fixture file must resolve inside, symlinks followed. Required when `proxyrules_record_mode` is not `off` |
+| `proxyrules_record_scrubber` | `MOCKSTACK__PROXYRULES_RECORD_SCRUBBER` | string | - | Optional `module:function` called with every body before it is recorded; it returns the text to write, or `None` to skip that response. Imported and checked when settings load, so the module must be importable (e.g. `PYTHONPATH=.`); see [Scrubbing recorded bodies](strategies/proxyrules.md#scrubbing-recorded-bodies) |
 
 ## Resource Creation Settings
 
@@ -117,6 +120,16 @@ MOCKSTACK__PROXYRULES_REDIRECT_VIA=reverse_proxy
 MOCKSTACK__PROXYRULES_REVERSE_PROXY_TIMEOUT=5
 ```
 
+And one that records fixtures from the real services behind the rules (see
+[Recording fixtures](strategies/proxyrules.md#recording-fixtures)):
+
+```env
+MOCKSTACK__STRATEGY=proxyrules
+MOCKSTACK__PROXYRULES_RULES_FILENAME=./rules.yml
+MOCKSTACK__PROXYRULES_RECORD_MODE=missing
+MOCKSTACK__PROXYRULES_RECORD_ROOT=/path/to/fixtures
+```
+
 ## Command Line Usage
 
 You can also set configuration options via command line arguments:
@@ -124,4 +137,5 @@ You can also set configuration options via command line arguments:
 ```bash
 uvx mockstack --strategy filefixtures --templates-dir ~/mockstack-templates/
 uvx mockstack --strategy proxyrules --proxyrules-rules-filename ./rules.yml --proxyrules-redirect-via http_307_temporary
+uvx mockstack --strategy proxyrules --proxyrules-rules-filename ./rules.yml --proxyrules-record-mode missing --proxyrules-record-root ./fixtures
 ```

{mockstack-0.13.0 → mockstack-0.14.0}/docs/guides/proxyrules-cookbook.md

@@ -416,3 +416,127 @@ Things to know before choosing redirect mode:
 - The client must be able to reach the upstream itself, and must follow redirects.
 - The original query string is kept: it is appended to the rewritten URL in
   `location` (with `&` if the replacement already has a query of its own).
+
+## 8. Fixture status codes and headers
+
+A fixture is answered with HTTP 200 unless its rule sets `status`, which makes it easy to
+test how a client handles a dependency that is down, throttled, or answers with a
+non-200 success. `response_headers` adds headers such as `Retry-After` or `Location`; a
+list value sends a header once per item, and a `Content-Type` replaces the type inferred
+from the file suffix. The response is still stamped `X-Mockstack-Result: template`: the
+status came from your fixture, so `error` keeps meaning that mockstack itself failed.
+
+```yaml title="08-status-and-headers/rules.yml"
+--8<-- "examples/proxyrules-cookbook/08-status-and-headers/rules.yml"
+```
+
+```jinja title="08-status-and-headers/fixtures/errors/unavailable.json.j2"
+--8<-- "examples/proxyrules-cookbook/08-status-and-headers/fixtures/errors/unavailable.json.j2"
+```
+
+```jinja title="08-status-and-headers/fixtures/errors/rate-limited.json.j2"
+--8<-- "examples/proxyrules-cookbook/08-status-and-headers/fixtures/errors/rate-limited.json.j2"
+```
+
+```jinja title="08-status-and-headers/fixtures/orders/created.json.j2"
+--8<-- "examples/proxyrules-cookbook/08-status-and-headers/fixtures/orders/created.json.j2"
+```
+
+```bash
+curl -i -H "X-Test-Scenario: outage" http://127.0.0.1:8000/orders/api/v1/orders/ord-1001
+# HTTP/1.1 503 Service Unavailable
+# retry-after: 30
+# x-mockstack-result: template
+# x-mockstack-rule: orders-outage
+# {"error": "service unavailable", "order_id": "ord-1001"}
+
+curl -i -H "X-Test-Scenario: throttled" http://127.0.0.1:8000/orders/api/v1/orders/ord-1001
+# HTTP/1.1 429 Too Many Requests
+# content-type: application/problem+json
+# retry-after: 5
+# x-mockstack-result: template
+# x-mockstack-rule: orders-rate-limited
+# {"type": "about:blank", "title": "Too Many Requests", "status": 429}
+
+curl -i -H "Content-Type: application/json" -d '{"customer": "cust-7"}' http://127.0.0.1:8000/orders/api/v1/orders
+# HTTP/1.1 201 Created
+# location: /orders/api/v1/orders/ord-1001
+# x-mockstack-result: template
+# x-mockstack-rule: order-created
+# {"id": "ord-1001", "status": "OPEN", "customer": "cust-7"}
+
+curl -i http://127.0.0.1:8000/orders/api/v1/orders/ord-1001
+# HTTP/1.1 200 OK
+# x-mockstack-result: proxy
+# x-mockstack-rule: orders-passthrough
+# {"source":"upstream","path":"/api/v1/orders/ord-1001","method":"GET",...}
+```
+
+Things to know:
+
+- The status and headers apply only once the fixture has rendered. A missing fixture is
+  still a 404 stamped `error`, without them.
+- A `204` or `304` is sent without a body, but its fixture file must still exist.
+- `status` and `response_headers` only work on `file:///` fixture rules: mockstack
+  refuses to start when a rule whose `replacement` is a URL sets them.
+- Headers that mockstack manages cannot be set: `Content-Length`, hop-by-hop headers
+  such as `Connection` and `Transfer-Encoding`, `Date`, `Server` and the
+  `X-Mockstack-*` result headers.
+
+## 9. Record fixtures from a real service
+
+Instead of writing fixtures by hand, let mockstack record them. In record mode, a fixture
+rule whose file does not exist yet sends the request on to the next matching URL rule,
+writes the response into the fixture file, and answers from that file. A scrubber can
+rewrite each body before it is written, here to mask e-mail addresses. Start mockstack
+from the recipe directory:
+
+```bash
+mkdir -p fixtures
+PYTHONPATH=. MOCKSTACK__STRATEGY=proxyrules MOCKSTACK__PROXYRULES_RULES_FILENAME=rules.local.yml \
+  MOCKSTACK__PROXYRULES_RECORD_MODE=missing MOCKSTACK__PROXYRULES_RECORD_ROOT=fixtures \
+  MOCKSTACK__PROXYRULES_RECORD_SCRUBBER=scrubbers:mask_emails uv run mockstack
+```
+
+```yaml title="09-recording/rules.yml"
+--8<-- "examples/proxyrules-cookbook/09-recording/rules.yml"
+```
+
+<!-- fmt: off -->
+```python title="09-recording/scrubbers.py"
+--8<-- "examples/proxyrules-cookbook/09-recording/scrubbers.py"
+```
+<!-- fmt: on -->
+
+The first request is recorded from the echo upstream, with the address masked:
+
+```bash
+curl -i "http://127.0.0.1:8000/users/api/v1/users/user-7?contact=ada@example.com"
+# HTTP/1.1 200 OK
+# x-mockstack-result: record
+# x-mockstack-rule: users-recorded
+# {"source":"upstream","path":"/api/v1/users/user-7","method":"GET","query":{"contact":"***@***"},...}
+```
+
+`fixtures/users/user-7.json.j2` now holds that body, after a `{# mockstack:recorded #}`
+marker. The same request is then served from the file, without calling the upstream:
+
+```bash
+curl -i "http://127.0.0.1:8000/users/api/v1/users/user-7?contact=ada@example.com"
+# HTTP/1.1 200 OK
+# x-mockstack-result: template
+# x-mockstack-rule: users-recorded
+# {"source":"upstream","path":"/api/v1/users/user-7","method":"GET","query":{"contact":"***@***"},...}
+```
+
+Things to know:
+
+- Until a fixture is recorded, its requests really go to the real service, including
+  `POST`, `PUT` and `DELETE` -- so record against a safe environment, never production.
+- Restart without the three `RECORD` settings to replay only. `overwrite` mode re-records
+  files carrying the marker and never touches hand-written fixtures.
+- A response is recorded only when its status matches the rule's `status` (200 by
+  default) and its body is text; otherwise it is returned stamped `proxy`. See
+  [Recording fixtures](../strategies/proxyrules.md#recording-fixtures).
+- Recorded files contain whatever the real service returned. Review them before
+  committing, and never run record mode on a shared or exposed instance.

{mockstack-0.13.0 → mockstack-0.14.0}/docs/strategies/proxyrules.md

@@ -16,7 +16,7 @@ This strategy:
 - Matches requests on a path regex, the HTTP method, and optional `headers`, `query`,
   `body` and `json` predicates
 - Serves `file:///` Jinja templates as fixtures, with request data in the template
-  context
+  context, and the rule's own `status` and `response_headers`
 - Renders a `replacement` that contains Jinja delimiters as a template of its own
   (dynamic replacements), e.g. to pick a fixture directory from a header
 - Reverse-proxies to the rewritten URL by default, or answers with an HTTP redirect
@@ -24,6 +24,7 @@ This strategy:
   `X-Mockstack-Rule` headers
 - Validates and compiles every rule at startup, so a broken rules file fails fast
 - Can simulate resource creation for requests that match no rule
+- Can record real upstream responses into the fixture files its rules serve (record mode)
 - Provides OpenTelemetry integration for observability
 
 ## Configuration
@@ -86,6 +87,11 @@ rules:
   non-ASCII characters as they are. A path that is absent never matches, while a
   present `null` matches as the text `null`. A rule with `body`/`json` never matches a
   request without a body.
+- `status`: Optional HTTP status for the response of a [file template](#file-templates)
+  rule, an integer from 200 to 599 (default 200). See
+  [Status codes and headers](#status-codes-and-headers).
+- `response_headers`: Optional mapping of header name -> value added to the response of
+  a file template rule. A list value sends the header once per item.
 
 Predicate values must be strings. YAML reads unquoted `2`, `true` or `2024` as
 numbers and booleans; mockstack converts them back with `str()`, which turns `true`
@@ -145,6 +151,12 @@ offending rule, when:
 - a Jinja `replacement` has a syntax error;
 - a `replacement` mixes Jinja delimiters with a regex backreference (`\1`, `\g<id>`)
   in its literal text;
+- `status` is not an integer from 200 to 599;
+- a `response_headers` entry has an invalid name, no value, or a value that is not a
+  string or number, contains a control character, starts or ends with whitespace or is
+  not Latin-1, or names a header mockstack manages;
+- `status` or `response_headers` is set on a rule whose `replacement` is a plain URL
+  rather than a `file:///` fixture;
 - a named group in `pattern` shadows a reserved template variable (`path`, `method`,
   `query`, `headers`, `request_json`, `groups`).
 
@@ -194,10 +206,51 @@ rules:
 ```
 
 The response content type comes from the file suffix, ignoring a trailing `.j2`
-(`project.json.j2` -> `application/json`). A successfully rendered template always
-returns HTTP 200 stamped `X-Mockstack-Result: template`; see
+(`project.json.j2` -> `application/json`). A successfully rendered template returns
+HTTP 200, or the rule's `status`, stamped `X-Mockstack-Result: template`; see
 [Error handling](#error-handling) for the failure cases. Use the `tojson` filter to
-write request values into JSON fixtures, e.g. `{"id": {{ id | tojson }}}`.
+write request values into JSON fixtures, e.g. `{"id": {{ id | tojson }}}`. Fixture files
+and the rules file are read as UTF-8, matching how filefixtures reads its templates.
+
+### Status codes and headers
+
+`status` and `response_headers` set the status and extra headers a fixture is served
+with, for example to simulate a dependency that is down:
+
+```yaml
+rules:
+  - name: orders-outage
+    method: GET
+    pattern: ^/orders/api/v1/orders/(?P<order_id>[a-z0-9-]+)$
+    headers:
+      x-test-scenario: outage
+    status: 503
+    response_headers:
+      Retry-After: "30"
+    replacement: file:///fixtures/errors/unavailable.json.j2
+```
+
+- The response is still stamped `X-Mockstack-Result: template`, so a test can tell a
+  fixture's 503 from a 5xx `error` that mockstack itself returned.
+- The status and headers apply only once the fixture has rendered. A missing fixture
+  or a render failure is answered as described in [Error handling](#error-handling),
+  without them.
+- A `204` or `304` is sent without a body; the fixture file must still exist.
+- Header values are sent as written. A list value sends the header once per item (for
+  example several `Set-Cookie` headers), and a `Content-Type` replaces the type
+  inferred from the file suffix. As with predicates, quote values that YAML would read
+  as numbers or booleans.
+- Headers that mockstack manages cannot be set: `Content-Length`, the hop-by-hop
+  headers (`Connection`, `Keep-Alive`, `Proxy-Authenticate`, `Proxy-Authorization`,
+  `TE`, `Trailer`, `Transfer-Encoding`, `Upgrade`), `Date`, `Server`, and the
+  `X-Mockstack-Result` and `X-Mockstack-Rule` result headers.
+- Only fixture rules can set them. A rule whose plain `replacement` is a URL is
+  rejected at startup; a [dynamic replacement](#dynamic-replacements) is only known per
+  request, so one that renders a URL is answered with a 500 stamped `error`.
+
+The cookbook recipe
+[Fixture status codes and headers](../guides/proxyrules-cookbook.md#8-fixture-status-codes-and-headers)
+shows a 503, a 429 with `application/problem+json`, and a 201 with `Location`.
 
 ### Template context
 
@@ -268,6 +321,125 @@ optional values an explicit fallback, e.g.
     since no `..` segment is ever involved. Restrict predicates feeding a rendered
     path or URL to the character classes you actually expect, e.g. `[a-z0-9_-]+`.
 
+## Recording fixtures
+
+Record mode fills in fixtures from the real service. When a fixture rule matches and its
+file does not exist yet, mockstack sends the request to the next matching rule whose
+`replacement` is a URL, writes the response body to the fixture file, and answers by
+rendering that file, stamped `X-Mockstack-Result: record`. Later requests are served from
+the file, stamped `template`, without calling the service. Existing rules files work
+unchanged: the passthrough rule that follows a fixture rule is where it records from.
+Later rules whose `replacement` is a plain `file:///` path are skipped when looking for it.
+
+```yaml
+rules:
+  - name: users-fixture
+    method: GET
+    pattern: ^/users/api/v1/users/(?P<user_id>[a-z0-9-]+)$
+    headers:
+      x-test-scenario: "[a-z0-9_-]+"
+    replacement: file:///srv/fixtures/{{ headers['x-test-scenario'] }}/users/{{ user_id }}.json.j2
+
+  - name: users-passthrough
+    pattern: ^/users/(.*)
+    replacement: https://users.example/\1
+```
+
+Start mockstack with `MOCKSTACK__PROXYRULES_RECORD_MODE=missing` and
+`MOCKSTACK__PROXYRULES_RECORD_ROOT=/srv/fixtures`, run the traffic you want fixtures for,
+then review and commit the recorded files and run without record mode.
+
+| `proxyrules_record_mode` | Behaviour |
+| --- | --- |
+| `off` (default) | Fixtures are only served |
+| `missing` | A fixture file that does not exist yet is recorded |
+| `overwrite` | Files recorded before are recorded again, e.g. to refresh stale fixtures; hand-written fixtures are never overwritten |
+
+A response is recorded only when:
+
+- a later matching rule has a URL `replacement`;
+- the request is not a `HEAD` or `OPTIONS`;
+- the upstream's status equals the fixture rule's `status` (200 by default), so the
+  fixture replays with the status it was recorded with;
+- the body is UTF-8 text;
+- the body is not still compressed with a coding mockstack does not decode (for example
+  `br` without the optional `brotli` package); `gzip` and `deflate` bodies are recorded
+  decoded.
+
+Otherwise the upstream's response is returned stamped `proxy` with the URL rule's name,
+and the reason is logged -- at INFO for a `HEAD`/`OPTIONS` request or a scrubber that
+returns `None`, since both are expected; every other reason is logged at WARNING. With
+no later URL rule, a missing fixture is
+the usual 404 `error`. An upstream that fails is the usual 502 or 504 `error`, and a
+fixture file that cannot be written is a 500 `error`; nothing is written in either case.
+
+A later rule's `replacement` is still rendered even when it is a
+[dynamic replacement](#dynamic-replacements), to learn whether it gives a URL at all --
+so a later template replacement that fails (for example one that references a missing
+header) turns that record attempt into a 500, the same as it would for a plain proxied
+request to that rule.
+
+Recorded files:
+
+- start with `{# mockstack:recorded #}`, which renders to nothing and is how `overwrite`
+  tells them from hand-written fixtures;
+- contain the body exactly: any Jinja syntax or carriage return in it is printed by an
+  expression, so it is never evaluated and replays byte for byte;
+- are written to a temporary file and renamed into place, so concurrent requests never
+  read a partial fixture;
+- must resolve, symlinks followed, inside `proxyrules_record_root`. A fixture path
+  outside it is served as usual and not recorded, with a warning the first time for each
+  rule.
+
+While a fixture has not been recorded yet:
+
+- requests really reach the upstream, including non-idempotent methods such as `POST`,
+  `PUT` and `DELETE` -- recording a create endpoint creates real resources there;
+- a response that cannot be recorded (a status mismatch, a still-encoded or non-UTF-8
+  body, or a scrubber that returns `None`) is sent to the upstream again on every
+  request, not only the first;
+- there is no locking between requests: concurrent first requests for the same fixture
+  each reach the upstream, and the last write to complete wins. A reader never sees a
+  partial file, but overlapping requests can each record a different upstream response;
+- `HEAD` and `OPTIONS` requests for a fixture that may still be recorded are proxied
+  rather than served from a fixture file; in `overwrite` mode this also applies to a
+  fixture that was already recorded.
+
+Only the response body is recorded. The rule's `status` and `response_headers` apply when
+it is replayed, and the content type follows the file suffix as for any fixture.
+
+### Scrubbing recorded bodies
+
+`proxyrules_record_scrubber` names a `module:function` that is called with every body
+before it is written. It returns the text to write, or `None` to skip recording that
+response, which is then returned stamped `proxy`:
+
+```python
+def mask_emails(body: str, *, request: Request, rule_name: str | None, path: Path) -> str | None:
+    return EMAIL.sub("***@***", body)
+```
+
+The reference is imported and checked when the settings are loaded, so a typo or a
+target that is not callable stops mockstack from starting; the module must be
+importable, e.g. with `PYTHONPATH=.`. A scrubber that raises, or returns something
+other than a string or `None`, answers that request with a 500 `error` and nothing is
+written. `rule_name` is the matched fixture rule's `name` (`None` when the rule has
+none), and `path` is the resolved fixture file path that will be written.
+
+The scrubber must be a regular synchronous function, not `async def`: it is called
+directly, not awaited, so an `async def` scrubber returns a coroutine object rather
+than a string, and the request gets a 500 the same as any other non-`str`, non-`None`
+return value. See the cookbook's
+[Record fixtures from a real service](../guides/proxyrules-cookbook.md#9-record-fixtures-from-a-real-service).
+
+!!! warning
+    Record mode writes files whose paths can be chosen by request data and whose content
+    comes from the upstream. Enable it only for a recording session on a trusted
+    network, never on a shared or exposed instance, and review recorded fixtures before
+    committing them: they contain whatever the real service returned. A test harness
+    that asserts `X-Mockstack-Result: template` fails on `record`, so a gating run that
+    accidentally records is caught.
+
 ## Redirection methods
 
 `proxyrules_redirect_via` selects what a rule whose `replacement` is a URL does.
@@ -326,12 +498,13 @@ responses -- carries:
 
 | Header | Value |
 | --- | --- |
-| `X-Mockstack-Result` | `template`, `proxy`, `redirect`, `create`, `missing` or `error` |
+| `X-Mockstack-Result` | `template`, `proxy`, `redirect`, `create`, `missing`, `record` or `error` |
 | `X-Mockstack-Rule` | The matched rule's `name` (or its `pattern` when unnamed); absent when no rule matched |
 
 | `X-Mockstack-Result` | Status | Meaning |
 | --- | --- | --- |
-| `template` | 200 | A `file:///` fixture was rendered |
+| `template` | 200, or the rule's `status` | A `file:///` fixture was rendered |
+| `record` | The rule's `status` (200 by default) | Record mode wrote the upstream response to the fixture file and served it from that file |
 | `proxy` | Upstream's | The request was reverse-proxied to the rewritten URL |
 | `redirect` | 301 / 307 | An HTTP redirect to the rewritten URL |
 | `create` | 201 | No rule matched; resource creation was simulated |
@@ -409,7 +582,11 @@ The default metadata fields are controlled via the configuration file and at the
 ## OpenTelemetry integration
 
 The strategy automatically adds the following OpenTelemetry attributes when a rule
-matches:
+matches. The shared rule attributes (`rule_name`, `rule_method`, `rule_pattern`,
+`rule_replacement`) always describe the rule named in the response's
+`X-Mockstack-Rule` header, never some other rule that was merely consulted along the
+way (e.g. a record-mode upstream rule whose response ends up recorded and replayed
+from the fixture instead):
 
 - `mockstack.proxyrules.rule_name`: The name of the matched rule (if specified)
 - `mockstack.proxyrules.rule_method`: The HTTP method the rule matches (if specified)
@@ -417,8 +594,31 @@ matches:
 - `mockstack.proxyrules.rule_replacement`: The replacement as written in the rules file
 - `mockstack.proxyrules.rewritten_url`: The final URL after applying the rule (proxy
   and redirect results)
-- `mockstack.proxyrules.template_path`: The rendered fixture path, and
-  `mockstack.proxyrules.result_type` set to `template` (template results)
+- `mockstack.proxyrules.result_type`: The result type stamped on the response (`proxy`,
+  `redirect`, `template`, `error`, or in record mode `record`), set on every proxy,
+  redirect, template and error result
+- `mockstack.proxyrules.template_path`: The rendered fixture path (template results)
+
+An error response that names a rule (`X-Mockstack-Result: error` with an
+`X-Mockstack-Rule` header -- e.g. a missing or unrenderable fixture, an unreachable
+upstream, or a record-mode write failure) carries that rule's shared attributes and
+`result_type` `error`, overwriting any result type an earlier, now-superseded call had
+set for the same response (e.g. a reverse proxy attempt that set `proxy` before it
+failed).
+
+In record mode (`proxyrules_record_mode`), attempting to record from the next matching
+URL rule also sets:
+
+- `mockstack.proxyrules.upstream_rule_name`: The name (or pattern, when unnamed) of the
+  rule the request was proxied to while attempting to record
+- `mockstack.proxyrules.rewritten_url`: The upstream URL the request was proxied to while
+  attempting to record, whether or not the response ended up recorded
+- `mockstack.proxyrules.recorded_path`: The fixture path written, when the response was
+  recorded (`result_type` is `record`; the shared rule attributes describe the fixture
+  rule)
+- `mockstack.proxyrules.not_recorded_reason`: Why the response was not recorded, when it
+  was not (`result_type` is `proxy`; the shared rule attributes describe the upstream
+  rule, since that is what `X-Mockstack-Rule` names)
 
 ## Testing evaluation suites
 

mockstack-0.14.0/examples/proxyrules-cookbook/08-status-and-headers/fixtures/errors/rate-limited.json.j2

@@ -0,0 +1 @@
+{"type": "about:blank", "title": "Too Many Requests", "status": 429}

mockstack-0.14.0/examples/proxyrules-cookbook/08-status-and-headers/fixtures/errors/unavailable.json.j2

@@ -0,0 +1 @@
+{"error": "service unavailable", "order_id": {{ order_id | tojson }}}

mockstack-0.14.0/examples/proxyrules-cookbook/08-status-and-headers/fixtures/orders/created.json.j2

@@ -0,0 +1 @@
+{"id": "ord-1001", "status": "OPEN", "customer": {{ request_json.customer | tojson }}}

mockstack-0.14.0/examples/proxyrules-cookbook/08-status-and-headers/rules.yml

@@ -0,0 +1,36 @@
+rules:
+  # 503 with Retry-After: the orders service is down for this scenario.
+  - name: orders-outage
+    method: GET
+    pattern: ^/orders/api/v1/orders/(?P<order_id>[a-z0-9-]+)$
+    headers:
+      x-test-scenario: outage
+    status: 503
+    response_headers:
+      Retry-After: "30"
+    replacement: file://${FIXTURES_DIR}/errors/unavailable.json.j2
+
+  # 429 with a problem+json body, which replaces the type inferred from .json.j2.
+  - name: orders-rate-limited
+    method: GET
+    pattern: ^/orders/api/v1/orders/(?P<order_id>[a-z0-9-]+)$
+    headers:
+      x-test-scenario: throttled
+    status: 429
+    response_headers:
+      Content-Type: application/problem+json
+      Retry-After: "5"
+    replacement: file://${FIXTURES_DIR}/errors/rate-limited.json.j2
+
+  # 201 Created, with a Location header for the new order.
+  - name: order-created
+    method: POST
+    pattern: ^/orders/api/v1/orders$
+    status: 201
+    response_headers:
+      Location: /orders/api/v1/orders/ord-1001
+    replacement: file://${FIXTURES_DIR}/orders/created.json.j2
+
+  - name: orders-passthrough
+    pattern: ^/orders/(.*)
+    replacement: ${UPSTREAM_URL}/\1