specrig 0.2.0__tar.gz → 0.3.1__tar.gz

{specrig-0.2.0 → specrig-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specrig
-Version: 0.2.0
+Version: 0.3.1
 Summary: A harness for a FastAPI or Django service developed specification first
 Project-URL: Homepage, https://github.com/specrig/specrig-python
 Project-URL: Protocol, https://github.com/specrig/protocol
@@ -241,10 +241,12 @@ fixtures, autouse ones included, would change the service the cases see.
 
 | | |
 |---|---|
-| `harness.<backend>.reply(method, path, status, body)` | what the neighbour answers |
-| `harness.<backend>.reply_to(method, path, query, status, body)` | the same, for a request whose query has these values; the reply naming the most of them wins |
-| `harness.<backend>.time_out(method, path, query=None)` | the neighbour does not answer in time: the client meets the timeout it would meet, at once |
-| `harness.<backend>.requests(method, path)` | what reached the neighbour: `method`, `path`, `query` and `json`, its decoded body |
+| `harness.<backend>.reply(method, path, status, body, headers)` | what the neighbour answers; `headers`, strings to strings, are added to the response the client sees. A segment in braces, `/orders/{id}`, takes any one segment, the exact path wins over a template and the first declared of two templates over the second — in every call here that names a path |
+| `harness.<backend>.reply_to(method, path, query, status, body, headers)` | the same, for a request whose query has these values; the reply naming the most of them wins |
+| `harness.<backend>.reply_with(method, path, answer, headers)` | the answer worked out from each request: `answer` takes what `requests` returns one of and gives `(status, body)`; a reply naming no query, checked as the others |
+| `harness.<backend>.time_out(method, path, query=None)` | the neighbour does not answer in time: the client meets the timeout it would meet, at once; no reply lifts it |
+| `harness.<backend>.heal()` | the neighbour answers again: every `time_out` is lifted, the replies stay |
+| `harness.<backend>.requests(method, path)` | what reached the neighbour: `method`, `path`, `query` and `json`, its decoded body; a template returns the requests it takes |
 | `harness.http()` | a client of the service's own stack: `get`, `post`, `put`, `patch`, `delete`, `send`; a response with `status`, `headers`, `text`, `json()` |
 | `harness.run(job, *args, **kwargs)` | a job — see below |
 | `harness.command(name, *args)` | a command of the service's console; returns its exit code, and `harness.output` what it wrote |
@@ -253,6 +255,10 @@ fixtures, autouse ones included, would change the service the cases see.
 | `harness.logs` | what the service logged, under its real logging configuration |
 | `harness.clock` | the service's clock: the wall clock until a step calls `set()`, then `advance()` |
 | `harness.<resource>.fail_with(error=None)` | the resource goes down for the service — see Postgres and Redis |
+| `harness.<postgres>.refuse(table, *writes)` | every insert, update and delete on the table, or those given, fails in Postgres itself, whoever sends it; reads go on working — see Postgres |
+| `harness.<postgres>.refuse_after(table, rows, *writes)` | the same after the first `rows` rows |
+| `harness.<postgres>.refuse_commit(table, *writes)` | the statements go through, and the commit of a transaction that wrote the table fails |
+| `harness.<postgres>.heal()` | the database comes back: `fail_with` and every refusal end, and the rows stay |
 | `harness.application` | FastAPI: the app the case runs |
 
 The service boots at the first step that reaches it, so a `Given` declares and
@@ -269,7 +275,8 @@ every request and every answer is checked against the neighbour's contract: an
 unknown route or method, an undocumented status, or a body of the wrong shape
 fails it. So does a request the service sends past the stand-ins — through
 `urllib`, or `aiohttp` reading the proxy from the environment —, which the
-harness's proxy refused.
+harness's proxy refused. A path template in a step changes nothing there: the
+check and the records start from the path the request came with.
 
 A step's request returns when the service has answered it and done everything
 the request made it do, background tasks included: nothing is in flight between
@@ -396,6 +403,23 @@ with it — through SQLAlchemy's events, or Django's execute wrappers. A fault a
 step sets before the boot waits for the service to start, so the migration and
 the start go through; the next case starts whole.
 
+`harness.database.refuse("orders")` makes Postgres refuse one table's writes —
+every insert, update and delete, or only those named, `Write.INSERT`,
+`Write.UPDATE`, `Write.DELETE` — with `specrig: insert on orders is refused`. A
+trigger refuses, not the service's driver, so every connection meets it, the
+case's own included, and a write in `RETURNING` or a CTE as well as a plain one;
+reads and the other tables go on working, so a case can check what the failed
+write left behind. The table is `orders` or `schema.orders`. `refuse_after("orders",
+1)` lets that many rows through first, and a rolled-back row gives its place back.
+`refuse_commit("orders")` lets every statement through and fails the commit of a
+transaction that wrote the table, for a case about what gets out before the commit.
+A refusal set before the boot waits for the service to start, as a fault does.
+`heal()` is the database coming back in the middle of a case: it ends `fail_with`
+and every refusal and keeps the rows. The reset before every case lifts the
+refusals, before it writes the rows back. They live in a schema of their own,
+`specrig_refusal`, which the reset's discovery and the `specrig_baseline` copy never
+see.
+
 ## Redis
 
 ```python

{specrig-0.2.0 → specrig-0.3.1}/README.md

@@ -213,10 +213,12 @@ fixtures, autouse ones included, would change the service the cases see.
 
 | | |
 |---|---|
-| `harness.<backend>.reply(method, path, status, body)` | what the neighbour answers |
-| `harness.<backend>.reply_to(method, path, query, status, body)` | the same, for a request whose query has these values; the reply naming the most of them wins |
-| `harness.<backend>.time_out(method, path, query=None)` | the neighbour does not answer in time: the client meets the timeout it would meet, at once |
-| `harness.<backend>.requests(method, path)` | what reached the neighbour: `method`, `path`, `query` and `json`, its decoded body |
+| `harness.<backend>.reply(method, path, status, body, headers)` | what the neighbour answers; `headers`, strings to strings, are added to the response the client sees. A segment in braces, `/orders/{id}`, takes any one segment, the exact path wins over a template and the first declared of two templates over the second — in every call here that names a path |
+| `harness.<backend>.reply_to(method, path, query, status, body, headers)` | the same, for a request whose query has these values; the reply naming the most of them wins |
+| `harness.<backend>.reply_with(method, path, answer, headers)` | the answer worked out from each request: `answer` takes what `requests` returns one of and gives `(status, body)`; a reply naming no query, checked as the others |
+| `harness.<backend>.time_out(method, path, query=None)` | the neighbour does not answer in time: the client meets the timeout it would meet, at once; no reply lifts it |
+| `harness.<backend>.heal()` | the neighbour answers again: every `time_out` is lifted, the replies stay |
+| `harness.<backend>.requests(method, path)` | what reached the neighbour: `method`, `path`, `query` and `json`, its decoded body; a template returns the requests it takes |
 | `harness.http()` | a client of the service's own stack: `get`, `post`, `put`, `patch`, `delete`, `send`; a response with `status`, `headers`, `text`, `json()` |
 | `harness.run(job, *args, **kwargs)` | a job — see below |
 | `harness.command(name, *args)` | a command of the service's console; returns its exit code, and `harness.output` what it wrote |
@@ -225,6 +227,10 @@ fixtures, autouse ones included, would change the service the cases see.
 | `harness.logs` | what the service logged, under its real logging configuration |
 | `harness.clock` | the service's clock: the wall clock until a step calls `set()`, then `advance()` |
 | `harness.<resource>.fail_with(error=None)` | the resource goes down for the service — see Postgres and Redis |
+| `harness.<postgres>.refuse(table, *writes)` | every insert, update and delete on the table, or those given, fails in Postgres itself, whoever sends it; reads go on working — see Postgres |
+| `harness.<postgres>.refuse_after(table, rows, *writes)` | the same after the first `rows` rows |
+| `harness.<postgres>.refuse_commit(table, *writes)` | the statements go through, and the commit of a transaction that wrote the table fails |
+| `harness.<postgres>.heal()` | the database comes back: `fail_with` and every refusal end, and the rows stay |
 | `harness.application` | FastAPI: the app the case runs |
 
 The service boots at the first step that reaches it, so a `Given` declares and
@@ -241,7 +247,8 @@ every request and every answer is checked against the neighbour's contract: an
 unknown route or method, an undocumented status, or a body of the wrong shape
 fails it. So does a request the service sends past the stand-ins — through
 `urllib`, or `aiohttp` reading the proxy from the environment —, which the
-harness's proxy refused.
+harness's proxy refused. A path template in a step changes nothing there: the
+check and the records start from the path the request came with.
 
 A step's request returns when the service has answered it and done everything
 the request made it do, background tasks included: nothing is in flight between
@@ -368,6 +375,23 @@ with it — through SQLAlchemy's events, or Django's execute wrappers. A fault a
 step sets before the boot waits for the service to start, so the migration and
 the start go through; the next case starts whole.
 
+`harness.database.refuse("orders")` makes Postgres refuse one table's writes —
+every insert, update and delete, or only those named, `Write.INSERT`,
+`Write.UPDATE`, `Write.DELETE` — with `specrig: insert on orders is refused`. A
+trigger refuses, not the service's driver, so every connection meets it, the
+case's own included, and a write in `RETURNING` or a CTE as well as a plain one;
+reads and the other tables go on working, so a case can check what the failed
+write left behind. The table is `orders` or `schema.orders`. `refuse_after("orders",
+1)` lets that many rows through first, and a rolled-back row gives its place back.
+`refuse_commit("orders")` lets every statement through and fails the commit of a
+transaction that wrote the table, for a case about what gets out before the commit.
+A refusal set before the boot waits for the service to start, as a fault does.
+`heal()` is the database coming back in the middle of a case: it ends `fail_with`
+and every refusal and keeps the rows. The reset before every case lifts the
+refusals, before it writes the rows back. They live in a schema of their own,
+`specrig_refusal`, which the reset's discovery and the `specrig_baseline` copy never
+see.
+
 ## Redis
 
 ```python

{specrig-0.2.0 → specrig-0.3.1}/docs/design.md

@@ -82,7 +82,7 @@ flight between steps, and `time_out` stands in for a slow neighbour, as in PHP.
 | clock | `time-machine`, from the step that sets it | the same |
 | logs | a handler on the root logger, beside the service's | the same |
 | grants | `replace(name, instance)`: the name replaced in every module of the service that holds it, and in FastAPI's `dependency_overrides` | the name replaced in every module that holds it |
-| Postgres | `alembic upgrade head` once per run, in a process of its own, and the rows it wrote kept aside; before every case every table but `alembic_version` and `keep` truncated and those rows written back, with the sequences where they stood; a refusal by the gate, an error by SQLAlchemy's `before_cursor_execute` | `migrate` once per run, and the rows it wrote kept aside; every table but Django's bookkeeping and `keep` truncated and those rows written back; an error by the connections' execute wrappers |
+| Postgres | `alembic upgrade head` once per run, in a process of its own, and the rows it wrote kept aside; before every case every table but `alembic_version` and `keep` truncated and those rows written back, with the sequences where they stood; a refusal by the gate, an error by SQLAlchemy's `before_cursor_execute`, a table's writes by triggers in a schema of their own | `migrate` once per run, and the rows it wrote kept aside; every table but Django's bookkeeping and `keep` truncated and those rows written back; an error by the connections' execute wrappers; a table's writes by the same triggers |
 | Redis | `FLUSHDB` before every case; a refusal by the gate | the same |
 | steps | pytest-bdd: a plugin of `pytest11` marks Given, When and Then, fails a case on what the harness found, and writes `tests/flows.yaml` after a whole run | |
 | `tests/surface.yaml` | Python's `ast` over the service's modules: routes from FastAPI's decorators and routers | routes from the `ROOT_URLCONF` and the views' methods |
@@ -124,12 +124,30 @@ at import, in a lifespan, inside a job — so the stand-ins sit where every clie
 sends: `httpx`'s `HTTPTransport` and `AsyncHTTPTransport`, the same in `httpx2`,
 and `requests`' `HTTPAdapter`. Every other client meets the proxy.
 
+**A template names what a step answers, not what the service sent.** As in
+specrig-js, a path segment in braces takes any one segment, the exact path wins,
+and of two templates the first declared; `reply`, `reply_to`, `reply_with`,
+`time_out` and `requests` all take one. The contract check and the trace go on naming a request
+by the path it came with, so a template that matches too much is not hidden by
+the contract it is checked against. A reply's headers are added to the response
+as the transports hand it to the client, so `httpx`, `httpx2` and `requests` see
+them alike.
+
 **A gate, not an address.** PHP points a refused connection at a port where
 nothing listens, which works because the application is built anew for every
 case. Here the engine was built at import, with the address it was given, so the
 address is a gate on loopback that the case opens and closes: a refusal reaches
 every connection the service holds and every one it makes, whatever its driver.
 
+**Triggers, not hooks, for a refused table.** Ported from gorib's `sqltest`: a
+trigger refuses in Postgres itself, so every connection meets it — the service's,
+a job's, the case's own — and the service meets the driver's own exception, where
+a hook in SQLAlchemy or Django reaches only the clients that go through it. The
+triggers, and the quota that lets `refuse_after`'s rows through, live in a
+`specrig_refusal` schema, outside the tables the reset truncates and the baseline
+copies, and the reset drops it first. A refusal a step sets before the boot waits
+for the start, since the reset would lift it and the schema may not exist yet.
+
 **Alembic in a process of its own.** Alembic's `env.py` configures logging as it
 runs, disabling the loggers the service already made; production runs the
 migration as a job of its own, and so does the harness.
@@ -168,5 +186,5 @@ libraries.
 | 0 | the records and the fixtures | built |
 | 1 | boot, settings, HTTP stand-ins and the contract check, the pytest-bdd binding, Postgres, logs, the clock; HTTP, jobs and commands as ways in; `tests/flows.yaml` | built |
 | 2 | `tests/surface.yaml` and `tests/checks.yaml`, `init`, `rules`, `specrig.md` | built |
-| 3 | Redis, grants, `fail_with` | built |
+| 3 | Redis, grants, `fail_with`, a refused table and `heal`, reply headers and path templates | built |
 | 4 | a bus and a queue | not started |

{specrig-0.2.0 → specrig-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specrig"
-version = "0.2.0"
+version = "0.3.1"
 description = "A harness for a FastAPI or Django service developed specification first"
 readme = "README.md"
 license = "MIT"
@@ -44,6 +44,7 @@ Protocol = "https://github.com/specrig/protocol"
 dev = [
     "alembic>=1.16",
     "httpx>=0.27",
+    "httpx2>=2.0",
     "psycopg[binary]>=3.2",
     "pydantic-settings>=2.8",
     "redis>=5.0",

{specrig-0.2.0 → specrig-0.3.1}/samples/reminders/specrig.md

@@ -1,7 +1,7 @@
 # specrig.md
 
 How an agent works in this service under specrig: Rule #11, and how the suite runs.
-`../../.venv/bin/specrig agents` writes this file with `specrig` 0.2.0, and an edit here is lost on the next
+`../../.venv/bin/specrig agents` writes this file with `specrig` 0.3.1, and an edit here is lost on the next
 run; `AGENTS.md` beside it is the service's own.
 
 **Read `CONTRIBUTING.md` first, if it exists.** It holds service-specific
@@ -395,17 +395,29 @@ sessions; a `Then` reads back through them, not out of the answer.
 `tests/steps/` takes it as the `harness` fixture, with an attribute for each
 neighbour `harness.py` names:
 
-- `harness.<neighbour>.reply(method, path, status, body)` — what the neighbour
-  answers;
+- `harness.<neighbour>.reply(method, path, status, body, headers)` — what the
+  neighbour answers; a segment in braces, `/orders/{id}`, takes any value here and in
+  every call below, and the exact path wins;
 - `harness.<neighbour>.reply_to(method, path, query, status, body)` — the same, for a
   request whose query has these values;
-- `harness.<neighbour>.time_out(method, path)` — the neighbour not answering in time;
+- `harness.<neighbour>.reply_with(method, path, answer)` — the answer worked out from
+  each request, `(status, body)`;
+- `harness.<neighbour>.time_out(method, path)` — the neighbour not answering in time,
+  until `harness.<neighbour>.heal()`;
 - `harness.<neighbour>.requests(method, path)` — what reached the neighbour, for a
   `Then`.
 
 A call to a neighbour no step answered fails the case, and so does a request to an
 origin `harness.py` does not name — it is refused before it leaves.
 
+**An outage is not a replacement.** `harness.<resource>.fail_with()` takes the
+database or the cache away until the next case. A write that fails halfway is not an
+outage: `harness.<database>.refuse(table)` makes one table refuse writes,
+`refuse_after(table, rows)` lets that many rows through first, and reads keep working,
+so a `Then` can check what the failed write left; `refuse_commit(table)` fails only
+the commit. `heal()` is the database coming back: it ends the fault and every refusal
+and keeps the rows.
+
 **What may be stood in for is given, not chosen.** `tests/internal/` is read-only. A
 case that needs another neighbour, or an answer the stand-in cannot give, is a stop:
 name the neighbour or the behaviour, and the assertion it would carry.

{specrig-0.2.0 → specrig-0.3.1}/samples/shop/specrig.md

@@ -1,7 +1,7 @@
 # specrig.md
 
 How an agent works in this service under specrig: Rule #11, and how the suite runs.
-`../../.venv/bin/specrig agents` writes this file with `specrig` 0.2.0, and an edit here is lost on the next
+`../../.venv/bin/specrig agents` writes this file with `specrig` 0.3.1, and an edit here is lost on the next
 run; `AGENTS.md` beside it is the service's own.
 
 **Read `CONTRIBUTING.md` first, if it exists.** It holds service-specific
@@ -395,17 +395,29 @@ sessions; a `Then` reads back through them, not out of the answer.
 `tests/steps/` takes it as the `harness` fixture, with an attribute for each
 neighbour `harness.py` names:
 
-- `harness.<neighbour>.reply(method, path, status, body)` — what the neighbour
-  answers;
+- `harness.<neighbour>.reply(method, path, status, body, headers)` — what the
+  neighbour answers; a segment in braces, `/orders/{id}`, takes any value here and in
+  every call below, and the exact path wins;
 - `harness.<neighbour>.reply_to(method, path, query, status, body)` — the same, for a
   request whose query has these values;
-- `harness.<neighbour>.time_out(method, path)` — the neighbour not answering in time;
+- `harness.<neighbour>.reply_with(method, path, answer)` — the answer worked out from
+  each request, `(status, body)`;
+- `harness.<neighbour>.time_out(method, path)` — the neighbour not answering in time,
+  until `harness.<neighbour>.heal()`;
 - `harness.<neighbour>.requests(method, path)` — what reached the neighbour, for a
   `Then`.
 
 A call to a neighbour no step answered fails the case, and so does a request to an
 origin `harness.py` does not name — it is refused before it leaves.
 
+**An outage is not a replacement.** `harness.<resource>.fail_with()` takes the
+database or the cache away until the next case. A write that fails halfway is not an
+outage: `harness.<database>.refuse(table)` makes one table refuse writes,
+`refuse_after(table, rows)` lets that many rows through first, and reads keep working,
+so a `Then` can check what the failed write left; `refuse_commit(table)` fails only
+the commit. `heal()` is the database coming back: it ends the fault and every refusal
+and keeps the rows.
+
 **What may be stood in for is given, not chosen.** `tests/internal/` is read-only. A
 case that needs another neighbour, or an answer the stand-in cannot give, is a stop:
 name the neighbour or the behaviour, and the assertion it would carry.

{specrig-0.2.0 → specrig-0.3.1}/src/specrig/__init__.py

@@ -1,7 +1,7 @@
 from .backend import Backend, Received
 from .http import Response
-from .postgres import Postgres
+from .postgres import Postgres, Write
 from .redis import Redis
 from .rig import Logged
 
-__all__ = ["Backend", "Logged", "Postgres", "Received", "Redis", "Response"]
+__all__ = ["Backend", "Logged", "Postgres", "Received", "Redis", "Response", "Write"]

{specrig-0.2.0 → specrig-0.3.1}/src/specrig/backend.py

@@ -16,6 +16,8 @@ T = TypeVar("T")
 
 Query = Mapping[str, str | int | Sequence[str | int]]
 
+Headers = Mapping[str, str]
+
 
 @dataclass(frozen=True)
 class Received:
@@ -25,6 +27,9 @@ class Received:
     json: Any
 
 
+Answer = Callable[[Received], tuple[int, Any]]
+
+
 class StandIn(ABC):
     origin: str
     setting: str | None
@@ -53,7 +58,7 @@ class Backend(StandIn):
         self.name = ""
         self._trace = Trace()
         self._checked: Contract | None = None
-        self._replies: dict[str, list[tuple[dict[str, list[str]], int, Any]]] = {}
+        self._replies: dict[str, list[tuple[dict[str, list[str]], Answer, dict[str, str]]]] = {}
         self._timeouts: dict[str, list[dict[str, list[str]]]] = {}
         self._received: list[Received] = []
         self._unanswered: list[str] = []
@@ -78,22 +83,35 @@ class Backend(StandIn):
             )
         return failures
 
-    def reply(self, method: str, path: str, status: int, body: Any = None) -> None:
-        self.reply_to(method, path, {}, status, body)
+    def reply(self, method: str, path: str, status: int, body: Any = None, headers: Headers | None = None) -> None:
+        self.reply_to(method, path, {}, status, body, headers)
+
+    def reply_to(
+        self, method: str, path: str, query: Query, status: int, body: Any = None, headers: Headers | None = None
+    ) -> None:
+        declared = copy.deepcopy(body)
+        self._declare(method, path, _listed(query), lambda _: (status, declared), headers)
+
+    def reply_with(self, method: str, path: str, answer: Answer, headers: Headers | None = None) -> None:
+        self._declare(method, path, {}, answer, headers)
 
-    def reply_to(self, method: str, path: str, query: Query, status: int, body: Any = None) -> None:
+    def _declare(
+        self, method: str, path: str, asked: dict[str, list[str]], answer: Answer, headers: Headers | None
+    ) -> None:
         key = f"{method.upper()} {path}"
-        asked = _listed(query)
         kept = [r for r in self._replies.get(key, []) if r[0] != asked]
-        self._replies[key] = [*kept, (asked, status, copy.deepcopy(body))]
+        self._replies[key] = [*kept, (asked, answer, dict(headers or {}))]
 
     def time_out(self, method: str, path: str, query: Query | None = None) -> None:
         key = f"{method.upper()} {path}"
         asked = _listed(query or {})
         self._timeouts[key] = [*(q for q in self._timeouts.get(key, []) if q != asked), asked]
 
+    def heal(self) -> None:
+        self._timeouts = {}
+
     def requests(self, method: str, path: str) -> list[Received]:
-        return [r for r in self._received if r.method == method.upper() and r.path == path]
+        return [r for r in self._received if r.method == method.upper() and _takes(path, r.path)]
 
     def answer(self, request: Request) -> Response:
         method = request.method.upper()
@@ -103,31 +121,54 @@ class Backend(StandIn):
         body = http.decoded(request.body)
         call = self._trace.begin()
         try:
-            self._received.append(Received(method, path, asked, body))
+            received = Received(method, path, asked, body)
+            self._received.append(received)
             if self._checked is not None:
                 self._violations.extend(self._checked.request(method, path, body))
-            if _pick(self._timeouts.get(key, []), asked, lambda q: q) is not None:
+            if _pick(_declared(self._timeouts, method, path), asked, lambda q: q) is not None:
                 raise Unreachable(f"{self.name} did not answer {key} in time", timed_out=True)
-            return self._fulfil(method, path, key + request.search(), asked)
+            return self._fulfil(received, key + request.search())
         finally:
             name = self._checked.name(method, path) if self._checked is not None else key
             self._trace.end(call, "out", "http", name, body)
 
-    def _fulfil(self, method: str, path: str, asked: str, query: dict[str, list[str]]) -> Response:
-        reply = _pick(self._replies.get(f"{method} {path}", []), query, lambda r: r[0])
+    def _fulfil(self, received: Received, asked: str) -> Response:
+        method, path = received.method, received.path
+        reply = _pick(_declared(self._replies, method, path), received.query, lambda r: r[0])
         if reply is None:
             self._unanswered.append(asked)
             return _respond(501, {"code": "unanswered", "message": f"{method} {path}"})
-        _, status, body = reply
+        _, answer, headers = reply
+        status, body = answer(received)
         if self._checked is not None:
             self._violations.extend(self._checked.response(method, path, status, {} if body is None else body))
-        return _respond(status, None if status == 204 else ({} if body is None else body))
+        return _respond(status, None if status == 204 else ({} if body is None else body), headers)
 
 
-def _respond(status: int, body: Any) -> Response:
+def _respond(status: int, body: Any, headers: Headers | None = None) -> Response:
+    given = dict(headers or {})
     if body is None:
-        return Response(status)
-    return Response(status, {"Content-Type": "application/json"}, http.encoded(body))
+        return Response(status, given)
+    typed = {} if "content-type" in {name.lower() for name in given} else {"Content-Type": "application/json"}
+    return Response(status, {**typed, **given}, http.encoded(body))
+
+
+def _declared(table: dict[str, list[T]], method: str, path: str) -> list[T]:
+    exact = table.get(f"{method} {path}")
+    if exact is not None:
+        return exact
+    prefix = f"{method} "
+    for key, found in table.items():
+        if key.startswith(prefix) and _takes(key[len(prefix) :], path):
+            return found
+    return []
+
+
+def _takes(template: str, path: str) -> bool:
+    segments, wanted = template.split("/"), path.split("/")
+    return len(segments) == len(wanted) and all(
+        (s.startswith("{") and s.endswith("}")) or s == w for s, w in zip(segments, wanted, strict=True)
+    )
 
 
 def _pick(candidates: list[T], query: dict[str, list[str]], of: Callable[[T], dict[str, list[str]]]) -> T | None:

{specrig-0.2.0 → specrig-0.3.1}/src/specrig/postgres.py

@@ -6,6 +6,7 @@ import threading
 import time
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass, replace
+from enum import StrEnum
 from typing import TYPE_CHECKING, Any
 from urllib.parse import parse_qsl, quote, unquote, urlencode, urlsplit
 
@@ -19,6 +20,38 @@ if TYPE_CHECKING:
 
 _MARK = "specrig "
 _BASELINE = "specrig_baseline"
+_REFUSAL = "specrig_refusal"
+
+_REFUSAL_SETUP = f"""
+CREATE SCHEMA IF NOT EXISTS {_REFUSAL};
+CREATE TABLE IF NOT EXISTS {_REFUSAL}.quota (
+    relation oid,
+    name text,
+    remaining int NOT NULL,
+    PRIMARY KEY (relation, name)
+);
+CREATE OR REPLACE FUNCTION {_REFUSAL}.refuse() RETURNS trigger LANGUAGE plpgsql AS $$
+DECLARE
+    rest int;
+BEGIN
+    UPDATE {_REFUSAL}.quota SET remaining = remaining - 1
+    WHERE relation = tg_relid AND name = tg_name
+    RETURNING remaining INTO rest;
+    IF rest < 0 THEN
+        RAISE EXCEPTION 'specrig: % on % is refused', lower(tg_op), tg_table_name;
+    END IF;
+    IF tg_op = 'DELETE' THEN
+        RETURN old;
+    END IF;
+    RETURN new;
+END $$;
+"""
+
+
+class Write(StrEnum):
+    INSERT = "insert"
+    UPDATE = "update"
+    DELETE = "delete"
 
 
 @dataclass(frozen=True)
@@ -176,7 +209,34 @@ class _Server:
                     stood = connection.execute(f"SELECT last_value, is_called FROM {sequence}").fetchone()
                     self._sequences.append((sequence, *stood))
 
+    def refuse(self, table: str, rows: int, events: Sequence[str], commit: bool) -> None:
+        relation = ".".join(_quoted(part) for part in table.split("."))
+        name = "specrig_refuse_" + ("commit_" if commit else "") + "_".join(events)
+        on = " OR ".join(events)
+        trigger = (
+            f"CREATE CONSTRAINT TRIGGER {name} AFTER {on} ON {relation} DEFERRABLE INITIALLY DEFERRED FOR EACH ROW"
+            if commit
+            else f"CREATE TRIGGER {name} BEFORE {on} ON {relation} FOR EACH ROW"
+        )
+        connection = self._connected()
+        try:
+            with connection.transaction():
+                connection.execute(_REFUSAL_SETUP)
+                connection.execute(
+                    f"INSERT INTO {_REFUSAL}.quota (relation, name, remaining) VALUES (%s::regclass, %s, %s)"
+                    " ON CONFLICT (relation, name) DO UPDATE SET remaining = excluded.remaining",
+                    (relation, name, rows),
+                )
+                connection.execute(f"DROP TRIGGER IF EXISTS {name} ON {relation}")
+                connection.execute(f"{trigger} EXECUTE FUNCTION {_REFUSAL}.refuse()")
+        except Exception as e:
+            raise RuntimeError(f"cannot refuse writes to {table}: {e}") from e
+
+    def lift(self) -> None:
+        self._connected().execute(f"DROP SCHEMA IF EXISTS {_REFUSAL} CASCADE")
+
     def reset(self, keep: Sequence[str]) -> None:
+        self.lift()
         tables = [f"{_quoted(schema)}.{_quoted(table)}" for schema, table in self._tables(keep)]
         if not tables:
             return
@@ -196,8 +256,8 @@ class _Server:
     def _tables(self, keep: Sequence[str]) -> list[tuple[str, str]]:
         found = self._connected().execute(
             "SELECT schemaname, tablename FROM pg_tables"
-            " WHERE schemaname NOT IN ('pg_catalog', 'information_schema', %s) ORDER BY 1, 2",
-            (_BASELINE,),
+            " WHERE schemaname NOT IN ('pg_catalog', 'information_schema', %s, %s) ORDER BY 1, 2",
+            (_BASELINE, _REFUSAL),
         )
         return [(schema, table) for schema, table in found.fetchall() if table not in keep]
 
@@ -236,6 +296,7 @@ class Postgres(Resource):
         self._started = False
         self._refusing = False
         self._error: BaseException | None = None
+        self._refusals: list[Callable[[], None]] = []
 
     def fresh(self) -> Postgres:
         return Postgres(self.setting, self._given, self._image, self._keep, self._scheme)
@@ -269,15 +330,45 @@ class Postgres(Resource):
         if self._started:
             self._apply()
 
+    def refuse(self, table: str, *writes: Write) -> None:
+        self.refuse_after(table, 0, *writes)
+
+    def refuse_after(self, table: str, rows: int, *writes: Write) -> None:
+        self._refuse(table, rows, writes, False)
+
+    def refuse_commit(self, table: str, *writes: Write) -> None:
+        self._refuse(table, 0, writes, True)
+
+    def heal(self) -> None:
+        self._calm()
+        if self._started:
+            self._held().lift()
+
     def release(self) -> None:
+        self._calm()
+        self._rig = None
+        self._started = False
+
+    def _calm(self) -> None:
         if self._server is not None:
             self._server.gate.reopen()
         if self._rig is not None and (self._refusing or self._error is not None):
             self._rig.databases().heal()
-        self._rig = None
-        self._started = False
         self._refusing = False
         self._error = None
+        self._refusals = []
+
+    def _refuse(self, table: str, rows: int, writes: Sequence[Write], commit: bool) -> None:
+        events = _events(writes)
+
+        def refusal() -> None:
+            self._held().refuse(table, rows, events, commit)
+
+        # Before the start the schema may not exist, and the reset would lift it.
+        if self._started:
+            refusal()
+        else:
+            self._refusals.append(refusal)
 
     def _apply(self) -> None:
         assert self._rig is not None
@@ -285,6 +376,9 @@ class Postgres(Resource):
             self._held().gate.refuse()
         if self._error is not None:
             self._rig.databases().fail(self._held().database, self._error)
+        refusals, self._refusals = self._refusals, []
+        for refusal in refusals:
+            refusal()
 
     def _of(self, service: str) -> _Server:
         if self._server is None:
@@ -327,5 +421,15 @@ def _sweep(connection: Any, stem: str) -> None:
             connection.execute(f"DROP DATABASE IF EXISTS {_quoted(name)} WITH (FORCE)")
 
 
+def _events(writes: Sequence[str]) -> list[str]:
+    given = []
+    for write in writes:
+        try:
+            given.append(Write(write))
+        except ValueError:
+            raise ValueError(f"specrig: {write!r} is not a write, refuse an insert, update or delete") from None
+    return [write.value for write in Write if not given or write in given]
+
+
 def _quoted(name: str) -> str:
     return '"' + name.replace('"', '""') + '"'

{specrig-0.2.0 → specrig-0.3.1}/src/specrig/tool/templates.py

@@ -161,17 +161,29 @@ sessions; a `Then` reads back through them, not out of the answer.
 `tests/steps/` takes it as the `harness` fixture, with an attribute for each
 neighbour `harness.py` names:
 
-- `harness.<neighbour>.reply(method, path, status, body)` — what the neighbour
-  answers;
+- `harness.<neighbour>.reply(method, path, status, body, headers)` — what the
+  neighbour answers; a segment in braces, `/orders/{id}`, takes any value here and in
+  every call below, and the exact path wins;
 - `harness.<neighbour>.reply_to(method, path, query, status, body)` — the same, for a
   request whose query has these values;
-- `harness.<neighbour>.time_out(method, path)` — the neighbour not answering in time;
+- `harness.<neighbour>.reply_with(method, path, answer)` — the answer worked out from
+  each request, `(status, body)`;
+- `harness.<neighbour>.time_out(method, path)` — the neighbour not answering in time,
+  until `harness.<neighbour>.heal()`;
 - `harness.<neighbour>.requests(method, path)` — what reached the neighbour, for a
   `Then`.
 
 A call to a neighbour no step answered fails the case, and so does a request to an
 origin `harness.py` does not name — it is refused before it leaves.
 
+**An outage is not a replacement.** `harness.<resource>.fail_with()` takes the
+database or the cache away until the next case. A write that fails halfway is not an
+outage: `harness.<database>.refuse(table)` makes one table refuse writes,
+`refuse_after(table, rows)` lets that many rows through first, and reads keep working,
+so a `Then` can check what the failed write left; `refuse_commit(table)` fails only
+the commit. `heal()` is the database coming back: it ends the fault and every refusal
+and keeps the rows.
+
 **What may be stood in for is given, not chosen.** `tests/internal/` is read-only. A
 case that needs another neighbour, or an answer the stand-in cannot give, is a stop:
 name the neighbour or the behaviour, and the assertion it would carry.