idemcheck 0.2.0__tar.gz → 0.3.0__tar.gz

{idemcheck-0.2.0 → idemcheck-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idemcheck
-Version: 0.2.0
+Version: 0.3.0
 Summary: Find the HTTP handlers that will double-charge when a client retries.
 Author: mgkvibez
 License: MIT
@@ -109,6 +109,54 @@ atomic insert, so two workers racing on one key produce one winner and one confl
 `on_conflict="raise"` is the default. `"wait"` blocks for the in-flight call and replays it;
 `"run"` lets the work through, which is only right when repeating it is already harmless.
 
+## Middleware: the header, not a changed signature
+
+The runtime needs the key passed to the function. A real app receives it as a header and will
+not rewrite every handler, so `idemcheck.adapters` does the mechanics for you.
+
+```python
+from idemcheck.adapters import IdempotencyMiddleware
+from idemcheck.runtime import SQLiteStore
+
+app.add_middleware(IdempotencyMiddleware, store=SQLiteStore("idempotency.db"))
+```
+
+```python
+# Flask, or anything WSGI
+from idemcheck.adapters import WSGIMiddleware
+
+app.wsgi_app = WSGIMiddleware(app.wsgi_app, store=store)
+```
+
+```
+$ python examples/adapter_demo.py
+delivery 1: 201 {"charged": 2500}  replayed=False
+delivery 2: 201 {"charged": 2500}  replayed=True
+times the gateway was charged: 1
+```
+
+What the middleware does with each delivery of an `Idempotency-Key`:
+
+| Situation | Response |
+|---|---|
+| no header, `require_key=False` | passes through untouched, nothing stored |
+| first delivery | runs the app, stores the status, headers and body |
+| duplicate of a completed call | the stored response, plus `Idempotency-Replayed: true` |
+| another call is still in flight | `409 idempotency_conflict`, the handler never runs |
+| same key, different body | `422 idempotency_mismatch` |
+| the app answered 5xx or 429 | key released, nothing stored, so the retry really retries |
+
+Neither middleware imports FastAPI, Starlette, Flask or Django, so installing this cannot pin a
+version of one. Three behaviours are deliberate rather than incidental:
+
+* only `POST` is intercepted by default (`methods=(...)` to change it), and anything unhandled
+  is passed straight to the app without its response being buffered, so SSE and streaming
+  endpoints behave exactly as before
+* a body over `max_body` (1 MB) is passed through **intact but unprotected**, rather than
+  silently swallowed, because a request the app never sees is worse than an unprotected one
+* a 5xx or 429 releases the key instead of storing it. Caching a server error turns a transient
+  failure into a permanent one, which is the opposite of what a retry is for
+
 ## What it looks for
 
 A handler is a finding when it answers a mutating method **and** calls something that
@@ -148,7 +196,7 @@ The clean line is exactly what it says: no unguarded write was **recognised**.
 ## Tests
 
 ```bash
-python -m pytest -q      # 33 tests
+python -m pytest -q      # 51 tests
 bash scripts/verify.sh   # the release gate
 ```
 

{idemcheck-0.2.0 → idemcheck-0.3.0}/README.md

@@ -89,6 +89,54 @@ atomic insert, so two workers racing on one key produce one winner and one confl
 `on_conflict="raise"` is the default. `"wait"` blocks for the in-flight call and replays it;
 `"run"` lets the work through, which is only right when repeating it is already harmless.
 
+## Middleware: the header, not a changed signature
+
+The runtime needs the key passed to the function. A real app receives it as a header and will
+not rewrite every handler, so `idemcheck.adapters` does the mechanics for you.
+
+```python
+from idemcheck.adapters import IdempotencyMiddleware
+from idemcheck.runtime import SQLiteStore
+
+app.add_middleware(IdempotencyMiddleware, store=SQLiteStore("idempotency.db"))
+```
+
+```python
+# Flask, or anything WSGI
+from idemcheck.adapters import WSGIMiddleware
+
+app.wsgi_app = WSGIMiddleware(app.wsgi_app, store=store)
+```
+
+```
+$ python examples/adapter_demo.py
+delivery 1: 201 {"charged": 2500}  replayed=False
+delivery 2: 201 {"charged": 2500}  replayed=True
+times the gateway was charged: 1
+```
+
+What the middleware does with each delivery of an `Idempotency-Key`:
+
+| Situation | Response |
+|---|---|
+| no header, `require_key=False` | passes through untouched, nothing stored |
+| first delivery | runs the app, stores the status, headers and body |
+| duplicate of a completed call | the stored response, plus `Idempotency-Replayed: true` |
+| another call is still in flight | `409 idempotency_conflict`, the handler never runs |
+| same key, different body | `422 idempotency_mismatch` |
+| the app answered 5xx or 429 | key released, nothing stored, so the retry really retries |
+
+Neither middleware imports FastAPI, Starlette, Flask or Django, so installing this cannot pin a
+version of one. Three behaviours are deliberate rather than incidental:
+
+* only `POST` is intercepted by default (`methods=(...)` to change it), and anything unhandled
+  is passed straight to the app without its response being buffered, so SSE and streaming
+  endpoints behave exactly as before
+* a body over `max_body` (1 MB) is passed through **intact but unprotected**, rather than
+  silently swallowed, because a request the app never sees is worse than an unprotected one
+* a 5xx or 429 releases the key instead of storing it. Caching a server error turns a transient
+  failure into a permanent one, which is the opposite of what a retry is for
+
 ## What it looks for
 
 A handler is a finding when it answers a mutating method **and** calls something that
@@ -128,7 +176,7 @@ The clean line is exactly what it says: no unguarded write was **recognised**.
 ## Tests
 
 ```bash
-python -m pytest -q      # 33 tests
+python -m pytest -q      # 51 tests
 bash scripts/verify.sh   # the release gate
 ```
 

{idemcheck-0.2.0 → idemcheck-0.3.0}/idemcheck/__init__.py

@@ -1,3 +1,3 @@
 """idemcheck: find HTTP handlers that will double-charge on a retry."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

idemcheck-0.3.0/idemcheck/adapters.py

@@ -0,0 +1,382 @@
+"""Framework adapters: the runtime behind a header, not behind a changed signature.
+
+`idemcheck.runtime` needs the key passed to the function. A real app receives it as an HTTP
+header and will not rewrite every handler, so these middlewares do the mechanics: read
+`Idempotency-Key`, claim it, run the app once, store the response, and replay it for every
+later delivery of the same key.
+
+Both are dependency-free on purpose: an ASGI middleware for FastAPI and Starlette, and a WSGI
+middleware for Flask and Django. Nothing imports those frameworks, so installing this cannot
+pin a version of one.
+
+What is deliberately not done here:
+
+* Requests whose method is not in ``methods`` (POST by default) pass straight through, and
+  their response is never buffered, so streaming and SSE endpoints are untouched.
+* A body larger than ``max_body`` passes through unprotected rather than being buffered, since
+  a middleware that silently eats a 200 MB upload is worse than a gap the linter will flag.
+* A 5xx (and 429) releases the key instead of storing it: a server error is exactly the case a
+  client should be allowed to retry.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+from .runtime import MemoryStore, Outcome, _current_key
+
+DEFAULT_HEADER = "idempotency-key"
+REPLAYED_HEADER = "idempotency-replayed"
+
+#: Statuses that must not be remembered, because they invite a retry rather than describe a
+#: final answer.
+TRANSIENT = frozenset({429, 500, 502, 503, 504})
+
+
+def _body_fingerprint(method: str, path: str, query: bytes, body: bytes) -> str:
+    """Everything that makes this a different request, hashed."""
+    digest = hashlib.sha256()
+    for part in (method.encode(), path.encode(), query or b"", body or b""):
+        digest.update(part)
+        digest.update(b"\x00")
+    return digest.hexdigest()[:32]
+
+
+def _header_value(headers: Iterable[Tuple[bytes, bytes]], name: str) -> Optional[str]:
+    wanted = name.lower().encode()
+    for key, value in headers:
+        if key.lower() == wanted:
+            return value.decode("latin-1")
+    return None
+
+
+def _encode_response(status: int, headers: Sequence[Tuple[bytes, bytes]],
+                     body: bytes) -> Dict[str, Any]:
+    return {
+        "status": status,
+        "headers": [[k.decode("latin-1"), v.decode("latin-1")] for k, v in headers],
+        "body": base64.b64encode(body).decode("ascii"),
+    }
+
+
+def _decode_body(payload: Dict[str, Any]) -> bytes:
+    return base64.b64decode(payload["body"].encode("ascii"))
+
+
+def _json_response(status: int, payload: Dict[str, Any]):
+    body = json.dumps(payload).encode()
+    return status, [(b"content-type", b"application/json"),
+                    (b"content-length", str(len(body)).encode())], body
+
+
+def _conflict_body(key: str) -> Tuple[int, List[Tuple[bytes, bytes]], bytes]:
+    return _json_response(409, {
+        "error": "idempotency_conflict",
+        "message": "another request with this Idempotency-Key is still being processed; "
+                   "retry after it completes",
+        "key": key,
+    })
+
+
+def _mismatch_body(key: str) -> Tuple[int, List[Tuple[bytes, bytes]], bytes]:
+    return _json_response(422, {
+        "error": "idempotency_mismatch",
+        "message": "this Idempotency-Key was already used with a different request body",
+        "key": key,
+    })
+
+
+def _missing_body(header: str) -> Tuple[int, List[Tuple[bytes, bytes]], bytes]:
+    return _json_response(400, {
+        "error": "idempotency_key_required",
+        "message": "this endpoint requires the %s header" % header,
+    })
+
+
+class IdempotencyMiddleware:
+    """ASGI middleware. Works with FastAPI and Starlette without importing either.
+
+    .. code-block:: python
+
+        from idemcheck.adapters import IdempotencyMiddleware
+        from idemcheck.runtime import SQLiteStore
+
+        app.add_middleware(IdempotencyMiddleware, store=SQLiteStore("idem.db"))
+    """
+
+    def __init__(self, app, store=None, header: str = DEFAULT_HEADER,
+                 methods: Sequence[str] = ("POST",), require_key: bool = False,
+                 skip_paths: Sequence[str] = (), max_body: int = 1_000_000,
+                 key_scope=None) -> None:
+        self.app = app
+        self.store = store if store is not None else MemoryStore()
+        self.header = header
+        self.methods = tuple(m.upper() for m in methods)
+        self.require_key = require_key
+        self.skip_paths = tuple(skip_paths)
+        self.max_body = max_body
+        self.key_scope = key_scope
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http" or not self._applies(scope):
+            await self.app(scope, receive, send)
+            return
+
+        headers = scope.get("headers") or []
+        key = _header_value(headers, self.header)
+        if not key:
+            if not self.require_key:
+                await self.app(scope, receive, send)
+                return
+            status, out_headers, body = _missing_body(self.header)
+            await _send_response(send, status, out_headers, body)
+            return
+
+        body, oversized = await _read_body(receive, self.max_body)
+        if oversized:                         # too large to buffer: intact, just unprotected
+            await self.app(scope, _chain_body(body, receive), send)
+            return
+
+        path = scope.get("path", "")
+        query = scope.get("query_string", b"")
+        fingerprint = _body_fingerprint(scope.get("method", ""), path, query, body)
+        scoped_key = self.key_scope(path, key, scope) if self.key_scope else key
+        claim = self.store.claim(scoped_key, fingerprint)
+
+        if claim.outcome is Outcome.MISMATCH:
+            status, out_headers, payload = _mismatch_body(scoped_key)
+            await _send_response(send, status, out_headers, payload)
+            return
+        if claim.outcome is Outcome.CONFLICT:
+            status, out_headers, payload = _conflict_body(scoped_key)
+            await _send_response(send, status, out_headers, payload)
+            return
+        if claim.outcome is Outcome.REPLAY:
+            stored = claim.record.response
+            await _send_response(send, stored["status"],
+                                 _with_replay_header(stored["headers"]),
+                                 _decode_body(stored))
+            return
+
+        captured = {"status": 0, "headers": [], "chunks": []}
+
+        async def capturing_send(message):
+            if message["type"] == "http.response.start":
+                captured["status"] = message["status"]
+                captured["headers"] = message.get("headers", [])
+            elif message["type"] == "http.response.body":
+                captured["chunks"].append(message.get("body", b""))
+            await send(message)
+
+        token = _current_key.set(scoped_key)
+        try:
+            await self.app(scope, _replay_body(body), capturing_send)
+        except BaseException:
+            self.store.release(scoped_key)
+            raise
+        finally:
+            _current_key.reset(token)
+
+        if captured["status"] in TRANSIENT:
+            self.store.release(scoped_key)     # a retry is the right response to this
+            return
+        self.store.complete(scoped_key, _encode_response(
+            captured["status"], captured["headers"], b"".join(captured["chunks"])))
+
+    def _applies(self, scope) -> bool:
+        if scope.get("method", "").upper() not in self.methods:
+            return False
+        path = scope.get("path", "")
+        return not any(path.startswith(prefix) for prefix in self.skip_paths)
+
+
+async def _read_body(receive, max_body: int):
+    """Buffer the request body. Returns (bytes, oversized)."""
+    chunks: List[bytes] = []
+    size = 0
+    while True:
+        message = await receive()
+        if message.get("type") != "http.request":
+            break
+        chunk = message.get("body", b"")
+        size += len(chunk)
+        chunks.append(chunk)
+        if size > max_body or not message.get("more_body"):
+            break
+    return b"".join(chunks), size > max_body
+
+
+def _replay_body(body: bytes):
+    """A receive that hands the buffered body downstream exactly once."""
+    sent = {"done": False}
+
+    async def receive():
+        if not sent["done"]:
+            sent["done"] = True
+            return {"type": "http.request", "body": body, "more_body": False}
+        return {"type": "http.request", "body": b"", "more_body": False}
+
+    return receive
+
+
+def _chain_body(prefix: bytes, receive):
+    """Buffered bytes first, then whatever the real client is still sending.
+
+    Used when a body had no content-length and outgrew the buffer: the request must reach the
+    app intact even though it is not being protected.
+    """
+    state = {"sent": False}
+
+    async def chained():
+        if not state["sent"]:
+            state["sent"] = True
+            return {"type": "http.request", "body": prefix, "more_body": True}
+        return await receive()
+
+    return chained
+
+
+async def _send_response(send, status: int, headers: Sequence, body: bytes) -> None:
+    pairs = headers if headers and isinstance(headers[0], tuple) else [
+        (k.encode() if isinstance(k, str) else k, v.encode() if isinstance(v, str) else v)
+        for k, v in headers]
+    await send({"type": "http.response.start", "status": status, "headers": list(pairs)})
+    await send({"type": "http.response.body", "body": body})
+
+
+def _with_replay_header(headers: Sequence[Sequence[str]]) -> List[Tuple[bytes, bytes]]:
+    pairs = [(k.encode("latin-1"), v.encode("latin-1")) for k, v in headers]
+    pairs = [(k, v) for k, v in pairs if k.lower() != REPLAYED_HEADER.encode()]
+    pairs.append((REPLAYED_HEADER.encode(), b"true"))
+    return pairs
+
+
+class WSGIMiddleware:
+    """WSGI middleware for Flask and Django. No framework import, so no version pin.
+
+    .. code-block:: python
+
+        from idemcheck.adapters import WSGIMiddleware
+        app.wsgi_app = WSGIMiddleware(app.wsgi_app, store=store)
+    """
+
+    def __init__(self, app, store=None, header: str = DEFAULT_HEADER,
+                 methods: Sequence[str] = ("POST",), require_key: bool = False,
+                 skip_paths: Sequence[str] = (), max_body: int = 1_000_000,
+                 key_scope=None) -> None:
+        self.app = app
+        self.store = store if store is not None else MemoryStore()
+        self.header = header
+        self.methods = tuple(m.upper() for m in methods)
+        self.require_key = require_key
+        self.skip_paths = tuple(skip_paths)
+        self.max_body = max_body
+        self.key_scope = key_scope
+
+    def _header(self, environ) -> Optional[str]:
+        return environ.get("HTTP_" + self.header.upper().replace("-", "_"))
+
+    def __call__(self, environ, start_response):
+        method = environ.get("REQUEST_METHOD", "").upper()
+        path = environ.get("PATH_INFO", "")
+        if method not in self.methods or any(path.startswith(p) for p in self.skip_paths):
+            return self.app(environ, start_response)
+
+        key = self._header(environ)
+        if not key:
+            if not self.require_key:
+                return self.app(environ, start_response)
+            status, headers, body = _missing_body(self.header)
+            return _wsgi_send(start_response, status, headers, body)
+
+        try:
+            length = int(environ.get("CONTENT_LENGTH") or 0)
+        except ValueError:
+            length = 0
+        if length > self.max_body:
+            return self.app(environ, start_response)     # too large: intact, unprotected
+
+        stream = environ.get("wsgi.input")
+        body = stream.read(self.max_body + 1) if stream is not None else b""
+        if len(body) > self.max_body:
+            environ["wsgi.input"] = _PrefixedBody(body, stream)
+            return self.app(environ, start_response)
+        environ["wsgi.input"] = _PrefixedBody(body, None)
+
+        query = environ.get("QUERY_STRING", "").encode()
+        fingerprint = _body_fingerprint(method, path, query, body)
+        scoped_key = self.key_scope(path, key, environ) if self.key_scope else key
+        claim = self.store.claim(scoped_key, fingerprint)
+
+        if claim.outcome is Outcome.MISMATCH:
+            status, headers, payload = _mismatch_body(scoped_key)
+            return _wsgi_send(start_response, status, headers, payload)
+        if claim.outcome is Outcome.CONFLICT:
+            status, headers, payload = _conflict_body(scoped_key)
+            return _wsgi_send(start_response, status, headers, payload)
+        if claim.outcome is Outcome.REPLAY:
+            stored = claim.record.response
+            pairs = _with_replay_header(stored["headers"])
+            start_response(str(stored["status"]),
+                           [(k.decode("latin-1"), v.decode("latin-1")) for k, v in pairs])
+            return [_decode_body(stored)]
+
+        captured: Dict[str, Any] = {"status": "200 OK", "headers": []}
+
+        def capture_start(status, headers, exc_info=None):
+            captured["status"] = status
+            captured["headers"] = headers
+            return lambda chunk: None
+
+        token = _current_key.set(scoped_key)
+        try:
+            iterable = self.app(environ, capture_start)
+            payload = b"".join(iterable)
+            close = getattr(iterable, "close", None)
+            if callable(close):
+                close()
+        except BaseException:
+            self.store.release(scoped_key)
+            raise
+        finally:
+            _current_key.reset(token)
+
+        code = int(str(captured["status"]).split()[0])
+        body_out = b"" if isinstance(payload, dict) else payload
+        if code in TRANSIENT:
+            self.store.release(scoped_key)
+            start_response(captured["status"], captured["headers"])
+            return [body_out]
+
+        self.store.complete(scoped_key, _encode_response(
+            code, [(k.encode("latin-1"), v.encode("latin-1"))
+                   for k, v in captured["headers"]], body_out))
+        start_response(captured["status"], captured["headers"])
+        return [body_out]
+
+
+class _PrefixedBody:
+    """A wsgi.input whose first read returns the bytes we already consumed."""
+
+    def __init__(self, prefix: bytes, stream) -> None:
+        self._prefix = prefix
+        self._stream = stream
+
+    def read(self, size: int = -1) -> bytes:
+        if self._prefix:
+            prefix, self._prefix = self._prefix, b""
+            return prefix
+        return self._stream.read(size) if self._stream is not None else b""
+
+    def readline(self, size: int = -1) -> bytes:
+        return self.read(size)
+
+
+def _wsgi_send(start_response, status: int, headers: Sequence[Tuple[bytes, bytes]],
+               body: bytes):
+    start_response(str(status), [(k.decode("latin-1"), v.decode("latin-1"))
+                                 for k, v in headers])
+    return [body]

{idemcheck-0.2.0 → idemcheck-0.3.0}/idemcheck.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idemcheck
-Version: 0.2.0
+Version: 0.3.0
 Summary: Find the HTTP handlers that will double-charge when a client retries.
 Author: mgkvibez
 License: MIT
@@ -109,6 +109,54 @@ atomic insert, so two workers racing on one key produce one winner and one confl
 `on_conflict="raise"` is the default. `"wait"` blocks for the in-flight call and replays it;
 `"run"` lets the work through, which is only right when repeating it is already harmless.
 
+## Middleware: the header, not a changed signature
+
+The runtime needs the key passed to the function. A real app receives it as a header and will
+not rewrite every handler, so `idemcheck.adapters` does the mechanics for you.
+
+```python
+from idemcheck.adapters import IdempotencyMiddleware
+from idemcheck.runtime import SQLiteStore
+
+app.add_middleware(IdempotencyMiddleware, store=SQLiteStore("idempotency.db"))
+```
+
+```python
+# Flask, or anything WSGI
+from idemcheck.adapters import WSGIMiddleware
+
+app.wsgi_app = WSGIMiddleware(app.wsgi_app, store=store)
+```
+
+```
+$ python examples/adapter_demo.py
+delivery 1: 201 {"charged": 2500}  replayed=False
+delivery 2: 201 {"charged": 2500}  replayed=True
+times the gateway was charged: 1
+```
+
+What the middleware does with each delivery of an `Idempotency-Key`:
+
+| Situation | Response |
+|---|---|
+| no header, `require_key=False` | passes through untouched, nothing stored |
+| first delivery | runs the app, stores the status, headers and body |
+| duplicate of a completed call | the stored response, plus `Idempotency-Replayed: true` |
+| another call is still in flight | `409 idempotency_conflict`, the handler never runs |
+| same key, different body | `422 idempotency_mismatch` |
+| the app answered 5xx or 429 | key released, nothing stored, so the retry really retries |
+
+Neither middleware imports FastAPI, Starlette, Flask or Django, so installing this cannot pin a
+version of one. Three behaviours are deliberate rather than incidental:
+
+* only `POST` is intercepted by default (`methods=(...)` to change it), and anything unhandled
+  is passed straight to the app without its response being buffered, so SSE and streaming
+  endpoints behave exactly as before
+* a body over `max_body` (1 MB) is passed through **intact but unprotected**, rather than
+  silently swallowed, because a request the app never sees is worse than an unprotected one
+* a 5xx or 429 releases the key instead of storing it. Caching a server error turns a transient
+  failure into a permanent one, which is the opposite of what a retry is for
+
 ## What it looks for
 
 A handler is a finding when it answers a mutating method **and** calls something that
@@ -148,7 +196,7 @@ The clean line is exactly what it says: no unguarded write was **recognised**.
 ## Tests
 
 ```bash
-python -m pytest -q      # 33 tests
+python -m pytest -q      # 51 tests
 bash scripts/verify.sh   # the release gate
 ```
 

{idemcheck-0.2.0 → idemcheck-0.3.0}/idemcheck.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 idemcheck/__init__.py
+idemcheck/adapters.py
 idemcheck/analyze.py
 idemcheck/cli.py
 idemcheck/runtime.py
@@ -11,5 +12,6 @@ idemcheck.egg-info/dependency_links.txt
 idemcheck.egg-info/entry_points.txt
 idemcheck.egg-info/requires.txt
 idemcheck.egg-info/top_level.txt
+tests/test_adapters.py
 tests/test_idemcheck.py
 tests/test_runtime.py

{idemcheck-0.2.0 → idemcheck-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "idemcheck"
-version = "0.2.0"
+version = "0.3.0"
 description = "Find the HTTP handlers that will double-charge when a client retries."
 readme = "README.md"
 requires-python = ">=3.9"

idemcheck-0.3.0/tests/test_adapters.py

@@ -0,0 +1,259 @@
+"""Adapters tested against bare ASGI and WSGI apps, so no framework has to be installed."""
+
+import asyncio
+import io
+
+from idemcheck.adapters import (
+    IdempotencyMiddleware,
+    WSGIMiddleware,
+    _body_fingerprint,
+)
+from idemcheck.runtime import MemoryStore
+
+
+class FakeASGI:
+    """Minimal ASGI app that records how many times it was actually reached."""
+
+    def __init__(self, status=200, body=b'{"ok":true}'):
+        self.status = status
+        self.body = body
+        self.calls = 0
+        self.seen_body = b""
+
+    async def __call__(self, scope, receive, send):
+        self.calls += 1
+        while True:
+            message = await receive()
+            self.seen_body += message.get("body", b"")
+            if not message.get("more_body"):
+                break
+        await send({"type": "http.response.start", "status": self.status,
+                    "headers": [(b"content-type", b"application/json")]})
+        await send({"type": "http.response.body", "body": self.body})
+
+
+def call_asgi(app, method="POST", path="/charge", headers=(), body=b"{}"):
+    scope = {"type": "http", "method": method, "path": path, "query_string": b"",
+             "headers": list(headers)}
+    sent = []
+    chunks = [body]
+
+    async def receive():
+        if chunks:
+            return {"type": "http.request", "body": chunks.pop(0), "more_body": False}
+        return {"type": "http.request", "body": b"", "more_body": False}
+
+    async def send(message):
+        sent.append(message)
+
+    asyncio.run(app(scope, receive, send))
+    status = next((m["status"] for m in sent if m["type"] == "http.response.start"), None)
+    payload = b"".join(m.get("body", b"") for m in sent if m["type"] == "http.response.body")
+    out_headers = dict(next((m.get("headers", []) for m in sent
+                             if m["type"] == "http.response.start"), []))
+    return status, payload, out_headers
+
+
+def _key(k):
+    return [(b"idempotency-key", k.encode())]
+
+
+def test_a_request_without_the_header_is_untouched():
+    inner = FakeASGI()
+    mw = IdempotencyMiddleware(inner)
+    status, _, _ = call_asgi(mw)
+    assert status == 200 and inner.calls == 1
+
+
+def test_the_second_delivery_replays_without_reaching_the_app():
+    inner = FakeASGI()
+    store = MemoryStore()
+    mw = IdempotencyMiddleware(inner, store=store)
+
+    first = call_asgi(mw, headers=_key("k1"))
+    second = call_asgi(mw, headers=_key("k1"))
+
+    assert inner.calls == 1, "the handler ran twice"
+    assert first[1] == second[1]
+    assert first[2].get(b"idempotency-replayed") is None
+    assert second[2][b"idempotency-replayed"] == b"true"
+
+
+def test_a_non_idempotent_method_passes_through():
+    inner = FakeASGI()
+    mw = IdempotencyMiddleware(inner, store=MemoryStore())
+    call_asgi(mw, method="GET", headers=_key("k1"))
+    call_asgi(mw, method="GET", headers=_key("k1"))
+    assert inner.calls == 2
+
+
+def test_a_request_still_in_flight_gets_409_and_does_not_run():
+    inner = FakeASGI()
+    store = MemoryStore()
+    store.claim("k1", _body_fingerprint("POST", "/charge", b"", b"{}"))
+    mw = IdempotencyMiddleware(inner, store=store)
+    status, payload, _ = call_asgi(mw, headers=_key("k1"))
+    assert status == 409
+    assert b"idempotency_conflict" in payload
+    assert inner.calls == 0
+
+
+def test_the_same_key_with_a_different_body_gets_422():
+    inner = FakeASGI()
+    store = MemoryStore()
+    store.claim("k1", _body_fingerprint("POST", "/charge", b"", b'{"amount":1}'))
+    mw = IdempotencyMiddleware(inner, store=store)
+    status, payload, _ = call_asgi(mw, headers=_key("k1"), body=b'{"amount":999}')
+    assert status == 422
+    assert b"idempotency_mismatch" in payload
+    assert inner.calls == 0
+
+
+def test_a_server_error_is_not_remembered_so_the_retry_can_work():
+    inner = FakeASGI(status=503)
+    store = MemoryStore()
+    mw = IdempotencyMiddleware(inner, store=store)
+    call_asgi(mw, headers=_key("k1"))
+    call_asgi(mw, headers=_key("k1"))
+    assert inner.calls == 2, "a 503 was cached, so the retry got a stale failure"
+    assert len(store) == 0
+
+
+def test_a_429_is_not_remembered_either():
+    inner = FakeASGI(status=429)
+    store = MemoryStore()
+    mw = IdempotencyMiddleware(inner, store=store)
+    call_asgi(mw, headers=_key("k1"))
+    call_asgi(mw, headers=_key("k1"))
+    assert inner.calls == 2
+
+
+def test_a_client_error_is_remembered():
+    """A 400 is a final answer for that payload, so replaying it is correct."""
+    inner = FakeASGI(status=400)
+    store = MemoryStore()
+    mw = IdempotencyMiddleware(inner, store=store)
+    call_asgi(mw, headers=_key("k1"))
+    status, _, _ = call_asgi(mw, headers=_key("k1"))
+    assert inner.calls == 1 and status == 400
+
+
+def test_require_key_refuses_a_missing_header():
+    inner = FakeASGI()
+    mw = IdempotencyMiddleware(inner, store=MemoryStore(), require_key=True)
+    status, payload, _ = call_asgi(mw)
+    assert status == 400 and b"idempotency_key_required" in payload
+    assert inner.calls == 0
+
+
+def test_skip_paths_is_honoured():
+    inner = FakeASGI()
+    mw = IdempotencyMiddleware(inner, store=MemoryStore(), skip_paths=("/webhooks",))
+    call_asgi(mw, path="/webhooks/stripe", headers=_key("k1"))
+    call_asgi(mw, path="/webhooks/stripe", headers=_key("k1"))
+    assert inner.calls == 2
+
+
+def test_the_body_still_reaches_the_app_intact():
+    inner = FakeASGI()
+    mw = IdempotencyMiddleware(inner, store=MemoryStore())
+    call_asgi(mw, headers=_key("k1"), body=b'{"amount":2500}')
+    assert inner.seen_body == b'{"amount":2500}'
+
+
+def test_an_oversized_body_passes_through_unbroken_and_unprotected():
+    """Buffering is skipped, but the app must still receive every byte."""
+    inner = FakeASGI()
+    store = MemoryStore()
+    mw = IdempotencyMiddleware(inner, store=store, max_body=4)
+    status, _, _ = call_asgi(mw, headers=_key("k1"), body=b"0123456789")
+    assert status == 200
+    assert inner.seen_body == b"0123456789"
+    assert len(store) == 0
+
+
+def test_the_stored_response_keeps_its_status_and_content_type():
+    inner = FakeASGI(status=201, body=b'{"id":7}')
+    mw = IdempotencyMiddleware(inner, store=MemoryStore())
+    call_asgi(mw, headers=_key("k1"))
+    status, payload, headers = call_asgi(mw, headers=_key("k1"))
+    assert status == 201
+    assert payload == b'{"id":7}'
+    assert headers[b"content-type"] == b"application/json"
+
+
+# --- WSGI ---------------------------------------------------------------------
+
+
+class FakeWSGI:
+    def __init__(self, status="200 OK", body=b'{"ok":true}'):
+        self.status = status
+        self.body = body
+        self.calls = 0
+        self.seen_body = b""
+
+    def __call__(self, environ, start_response):
+        self.calls += 1
+        self.seen_body = environ["wsgi.input"].read()
+        start_response(self.status, [("content-type", "application/json")])
+        return [self.body]
+
+
+def call_wsgi(app, method="POST", path="/charge", headers=None, body=b"{}"):
+    environ = {"REQUEST_METHOD": method, "PATH_INFO": path, "QUERY_STRING": "",
+               "CONTENT_LENGTH": str(len(body)), "wsgi.input": io.BytesIO(body)}
+    for name, value in (headers or {}).items():
+        environ["HTTP_" + name.upper().replace("-", "_")] = value
+    captured = {}
+
+    def start_response(status, pairs, exc_info=None):
+        captured["status"] = int(status.split()[0])
+        captured["headers"] = dict(pairs)
+
+    payload = b"".join(app(environ, start_response))
+    return captured["status"], payload, captured["headers"]
+
+
+def test_wsgi_replays_the_second_delivery():
+    inner = FakeWSGI()
+    mw = WSGIMiddleware(inner, store=MemoryStore())
+    first = call_wsgi(mw, headers={"Idempotency-Key": "k1"})
+    second = call_wsgi(mw, headers={"Idempotency-Key": "k1"})
+    assert inner.calls == 1
+    assert first[1] == second[1]
+    assert second[2].get("idempotency-replayed") == "true"
+
+
+def test_wsgi_leaves_other_methods_alone():
+    inner = FakeWSGI()
+    mw = WSGIMiddleware(inner, store=MemoryStore())
+    call_wsgi(mw, method="GET", headers={"Idempotency-Key": "k1"})
+    call_wsgi(mw, method="GET", headers={"Idempotency-Key": "k1"})
+    assert inner.calls == 2
+
+
+def test_wsgi_conflict_returns_409_without_running():
+    inner = FakeWSGI()
+    store = MemoryStore()
+    store.claim("k1", _body_fingerprint("POST", "/charge", b"", b"{}"))
+    mw = WSGIMiddleware(inner, store=store)
+    status, payload, _ = call_wsgi(mw, headers={"Idempotency-Key": "k1"})
+    assert status == 409 and b"idempotency_conflict" in payload
+    assert inner.calls == 0
+
+
+def test_wsgi_body_reaches_the_app_intact():
+    inner = FakeWSGI()
+    mw = WSGIMiddleware(inner, store=MemoryStore())
+    call_wsgi(mw, headers={"Idempotency-Key": "k1"}, body=b'{"amount":2500}')
+    assert inner.seen_body == b'{"amount":2500}'
+
+
+def test_wsgi_server_error_is_released():
+    inner = FakeWSGI(status="503 Service Unavailable")
+    store = MemoryStore()
+    mw = WSGIMiddleware(inner, store=store)
+    call_wsgi(mw, headers={"Idempotency-Key": "k1"})
+    call_wsgi(mw, headers={"Idempotency-Key": "k1"})
+    assert inner.calls == 2
+    assert len(store) == 0