specrig 0.3.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specrig
-Version: 0.3.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
@@ -243,7 +243,9 @@ fixtures, autouse ones included, would change the service the cases see.
 |---|---|
 | `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>.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>.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 |

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

@@ -215,7 +215,9 @@ fixtures, autouse ones included, would change the service the cases see.
 |---|---|
 | `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>.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>.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 |

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

@@ -126,8 +126,8 @@ 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`, `time_out` and
-`requests` all take one. The contract check and the trace go on naming a request
+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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specrig"
-version = "0.3.0"
+version = "0.3.1"
 description = "A harness for a FastAPI or Django service developed specification first"
 readme = "README.md"
 license = "MIT"

{specrig-0.3.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.3.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
@@ -400,7 +400,10 @@ neighbour `harness.py` names:
   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`.
 

{specrig-0.3.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.3.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
@@ -400,7 +400,10 @@ neighbour `harness.py` names:
   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`.
 

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

@@ -27,6 +27,9 @@ class Received:
     json: Any
 
 
+Answer = Callable[[Received], tuple[int, Any]]
+
+
 class StandIn(ABC):
     origin: str
     setting: str | None
@@ -55,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, dict[str, str]]]] = {}
+        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] = []
@@ -85,17 +88,28 @@ class Backend(StandIn):
 
     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 _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), dict(headers or {}))]
+        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 _takes(path, r.path)]
 
@@ -107,22 +121,25 @@ 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(_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(_declared(self._replies, 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, headers = 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), headers)

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

@@ -166,7 +166,10 @@ neighbour `harness.py` names:
   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`.
 

{specrig-0.3.0 → specrig-0.3.1}/tests/test_backend.py

@@ -178,6 +178,75 @@ def test_a_neighbour_that_does_not_answer_in_time_is_unreachable_by_template_too
     assert get(backend, "/payments") == 200
 
 
+def test_heal_lifts_every_time_out_and_keeps_the_replies() -> None:
+    backend, _ = billing()
+    backend.reply("GET", "/invoices", 200, [])
+    backend.time_out("GET", "/invoices/7")
+    backend.time_out("GET", "/invoices", {"status": "paid"})
+    backend.reply("GET", "/invoices/7", 200, INVOICE)
+
+    with pytest.raises(Unreachable):
+        get(backend, "/invoices/7")
+    backend.heal()
+
+    assert get(backend, "/invoices/7") == 200
+    assert get(backend, "/invoices?status=paid") == 200
+
+
+def test_an_answer_is_worked_out_from_each_request() -> None:
+    backend, _ = billing()
+    backend.reply_with(
+        "GET",
+        "/invoices/{order}",
+        lambda r: (200, {**INVOICE, "order": int(r.path.rsplit("/", 1)[1])}),
+        {"X-Kind": "own"},
+    )
+
+    for order in (7, 8):
+        answered = backend.answer(Request("GET", f"https://billing.shop.test/invoices/{order}"))
+        assert (answered.status, answered.json()["order"], answered.headers["X-Kind"]) == (200, order, "own")
+    assert backend.failures() == []
+
+
+def test_an_answer_may_change_with_what_reached_the_neighbour() -> None:
+    backend, _ = billing()
+    backend.reply_with(
+        "GET",
+        "/invoices/7",
+        lambda r: (
+            (503, {"code": "busy", "message": "later"})
+            if len(backend.requests("GET", "/invoices/7")) == 1
+            else (200, INVOICE)
+        ),
+    )
+
+    assert [get(backend, "/invoices/7"), get(backend, "/invoices/7")] == [503, 200]
+    assert backend.failures() == []
+
+
+def test_an_answer_worked_out_is_a_declaration_naming_no_query() -> None:
+    backend, _ = billing()
+    backend.reply_with("GET", "/invoices", lambda r: (200, [INVOICE]))
+    backend.reply_to("GET", "/invoices", {"status": "paid"}, 200, [])
+
+    def listed(path: str) -> list[object]:
+        return backend.answer(Request("GET", f"https://billing.shop.test{path}")).json()
+
+    assert (listed("/invoices?status=unpaid"), listed("/invoices?status=paid")) == ([INVOICE], [])
+    backend.reply("GET", "/invoices", 200, [])
+    assert listed("/invoices") == []
+
+
+def test_the_contract_checks_an_answer_worked_out() -> None:
+    backend, _ = billing()
+    backend.reply_with("GET", "/invoices/{order}", lambda r: (200, {"order": 7}))
+
+    get(backend, "/invoices/7")
+
+    [failure] = backend.failures()
+    assert "GET /invoices/7 answered 200: $ 'amount' is a required property" in failure
+
+
 def test_the_contract_check_and_the_trace_name_a_request_by_its_real_path() -> None:
     backend, trace = billing()
     backend.reply("GET", "/invoices/{order}", 200, {"order": 7})