idemkit 0.1.0__py3-none-any.whl

idemkit/core/state.py

@@ -0,0 +1,95 @@
+"""Core state types for idemkit, mapping directly to spec §4.1 and §4.15.
+
+These types are the contract any backend implementation MUST honor. The
+spec lives at ``spec/README.md``.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+
+
+class State(str, enum.Enum):
+    """Record state, spec §4.1."""
+
+    CLAIMED = "CLAIMED"
+    COMPLETED = "COMPLETED"
+
+
+class Decision(str, enum.Enum):
+    """Engine outcome for one request, emitted as ``idempotency.<value>``.
+
+    Mirrors the observability event types in spec §4.15.
+    """
+
+    NEW = "new"
+    REPLAYED = "replayed"
+    IN_FLIGHT_WAIT = "in_flight_wait"
+    CONFLICT = "conflict"
+    PAYLOAD_MISMATCH = "payload_mismatch"
+    LEASE_RECLAIMED = "lease_reclaimed"
+    LEASE_RECLAIMED_LOSS = "lease_reclaimed_loss"
+    STORAGE_ERROR = "storage_error"
+    #: fail_open only: storage was down, so this operation ran WITHOUT idempotency
+    #: protection. Alert on this rate to size the blast radius of a fail_open outage.
+    RAN_UNPROTECTED = "ran_unprotected"
+    #: The lease lapsed mid-run (renewal could not be confirmed) and the handler was
+    #: cancelled. A rising rate means handlers outlive their lease (partition hazard).
+    LEASE_LOST = "lease_lost"
+    #: The side effect ran but the backend failed to record the result, so it was not
+    #: cached. A later retry re-runs it (effectively-once degrades to at-least-once).
+    COMPLETE_FAILED = "complete_failed"
+    CORRUPT_RECORD = "corrupt_record"
+
+
+class ClaimResultType(str, enum.Enum):
+    """Outcome of one ``claim`` attempt against a backend, spec §4.1."""
+
+    NEW_CLAIMED = "new_claimed"
+    ALREADY_CLAIMED = "already_claimed"
+    ALREADY_COMPLETED = "already_completed"
+    LEASE_RECLAIMED = "lease_reclaimed"
+
+
+@dataclass(frozen=True)
+class StoredRecord:
+    """A single backend record per spec §4.1.
+
+    A two-key (claim + result) layout is forbidden; this single record is the
+    only object stored per effective_key.
+
+    ``lease_until`` is set at claim time. ``completed_at`` and the
+    ``response_*`` fields are set on the conditional ``COMPLETED`` transition.
+    """
+
+    effective_key: str
+    state: State
+    fingerprint: str
+    fingerprint_version: int
+    claim_token: str
+    claimed_at: float  # monotonic seconds (in-memory) or wall seconds (distributed)
+    lease_until: float
+    completed_at: float | None = None
+    response_status: int | None = None
+    response_headers: dict[str, str] = field(default_factory=dict)
+    response_body: bytes = b""
+
+
+@dataclass(frozen=True)
+class ClaimResult:
+    """What ``IdempotencyBackend.claim`` returns.
+
+    ``our_claim_token`` is non-None only when this caller acquired the claim
+    (NEW_CLAIMED or LEASE_RECLAIMED). The token MUST be passed to subsequent
+    ``complete`` / ``release`` calls so the backend can verify ownership.
+
+    ``recovered_from_corrupt`` is set when the fresh claim was issued because
+    an existing stored record failed to deserialize (§4.12). The engine emits
+    ``idempotency.corrupt_record`` instead of ``idempotency.new`` in that case.
+    """
+
+    result: ClaimResultType
+    record: StoredRecord
+    our_claim_token: str | None = None
+    recovered_from_corrupt: bool = False

idemkit/core/sync_bridge.py

@@ -0,0 +1,115 @@
+"""Drive idemkit's async core from synchronous callers.
+
+The whole library is async (the core awaits the backend), but a large slice of
+Python side-effect code is synchronous — Celery tasks, Flask/Django views, plain
+threaded SQS/Kafka workers. The synchronous facades (``idempotent_sync`` and
+``IdempotentConsumer.dispatch_sync``) run that code on a single, shared background
+event loop kept alive in a daemon thread.
+
+Why one persistent loop rather than ``asyncio.run`` per call: a backend's
+connection pool (Redis, PostgreSQL) binds to the loop it is first used on. Spinning
+up a fresh loop per call would rebind — or orphan — the pool every time. A single
+long-lived loop keeps the pool valid across calls, exactly as an async program
+would.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import threading
+from collections.abc import Coroutine
+from typing import Any, TypeVar
+
+_T = TypeVar("_T")
+
+
+class _BackgroundLoop:
+    """A daemon thread running a dedicated asyncio loop."""
+
+    def __init__(self) -> None:
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._run, name="idemkit-sync-loop", daemon=True)
+        self._thread.start()
+
+    def _run(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_forever()
+
+    def run(self, coro: Coroutine[Any, Any, _T]) -> _T:
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        return future.result()
+
+    def close(self) -> None:
+        if not self._loop.is_closed():
+            self._loop.call_soon_threadsafe(self._loop.stop)
+            self._thread.join(timeout=5)
+            self._loop.close()
+
+
+_lock = threading.Lock()
+_instance: _BackgroundLoop | None = None
+_closables: list[Any] = []
+
+
+def register_closable(obj: Any) -> None:
+    """Track a backend used through the sync facade so it can be closed cleanly
+    on the background loop at process exit.
+
+    Without this, a Redis/Postgres pool bound to the background loop is GC'd after
+    the loop is gone, printing a spurious ``RuntimeError: Event loop is closed`` at
+    shutdown. Closing it on its own loop first avoids that. Only objects exposing
+    ``aclose`` are tracked; duplicates (by identity) are ignored.
+    """
+    if hasattr(obj, "aclose") and all(obj is not c for c in _closables):
+        _closables.append(obj)
+
+
+def run_sync(coro: Coroutine[Any, Any, _T]) -> _T:
+    """Run an idemkit core coroutine to completion from a synchronous caller.
+
+    Lazily starts the shared background loop on first use. Refuses to run from
+    inside an already-running event loop (that would block the caller's loop): in
+    async code, use the async API (``idempotent`` / ``dispatch``) directly.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        pass  # good: no running loop, we're in synchronous code
+    else:
+        coro.close()
+        raise RuntimeError(
+            "idemkit: the synchronous API (idempotent_sync / dispatch_sync) "
+            "was called from inside a running event loop, which would block it. "
+            "Use the async API (idempotent / dispatch / await) instead."
+        )
+
+    global _instance
+    if _instance is None:
+        with _lock:
+            if _instance is None:
+                _instance = _BackgroundLoop()
+    return _instance.run(coro)
+
+
+async def _aclose_all() -> None:
+    for obj in _closables:
+        try:
+            await obj.aclose()
+        except Exception:
+            pass
+
+
+@atexit.register
+def _shutdown() -> None:
+    global _instance
+    if _instance is not None:
+        # Close tracked backends ON the background loop (while it's still alive),
+        # then stop the loop — avoids the GC-after-loop-closed teardown noise.
+        try:
+            _instance.run(_aclose_all())
+        except Exception:
+            pass
+        _instance.close()
+        _instance = None
+    _closables.clear()

idemkit/problem_details.py

@@ -0,0 +1,119 @@
+"""RFC 9457 Problem Details helpers per spec §6.3.
+
+URI namespace ``urn:idemkit:*`` is OUR namespace. The IETF-namespace URIs
+``urn:ietf:idempotency:*`` are proposed to the WG but not yet registered;
+we do not use them in our own implementation.
+"""
+
+from __future__ import annotations
+
+import json
+
+CONTENT_TYPE = "application/problem+json"
+
+PROBLEM_TYPES = {
+    "missing-key": "urn:idemkit:missing-key",
+    "payload-mismatch": "urn:idemkit:payload-mismatch",
+    "in-progress": "urn:idemkit:in-progress",
+    "storage-error": "urn:idemkit:storage-error",
+    "identity-unavailable": "urn:idemkit:identity-unavailable",
+    "expired": "urn:idemkit:expired",
+}
+
+
+def problem_response(
+    *,
+    type_key: str,
+    status: int,
+    title: str,
+    detail: str,
+) -> tuple[int, dict[str, str], bytes]:
+    """Build an RFC 9457 Problem Details response.
+
+    Returns ``(status, headers, body_bytes)``.
+    """
+    payload: dict[str, object] = {
+        "type": PROBLEM_TYPES[type_key],
+        "title": title,
+        "status": status,
+        "detail": detail,
+    }
+    body = json.dumps(payload).encode("utf-8")
+    headers = {
+        "content-type": CONTENT_TYPE,
+        "content-length": str(len(body)),
+    }
+    return status, headers, body
+
+
+def missing_key() -> tuple[int, dict[str, str], bytes]:
+    return problem_response(
+        type_key="missing-key",
+        status=400,
+        title="Idempotency key required",
+        detail="This endpoint requires an Idempotency-Key header.",
+    )
+
+
+def key_too_long(max_bytes: int = 255) -> tuple[int, dict[str, str], bytes]:
+    # §6.1: oversized key → 400 with the same type URI as a missing key.
+    return problem_response(
+        type_key="missing-key",
+        status=400,
+        title="Idempotency key too long",
+        detail=(
+            f"The Idempotency-Key header exceeds the {max_bytes}-byte limit. "
+            "Use a shorter key (a UUID is a good choice)."
+        ),
+    )
+
+
+def payload_mismatch(stripe_compat: bool) -> tuple[int, dict[str, str], bytes]:
+    return problem_response(
+        type_key="payload-mismatch",
+        status=409 if stripe_compat else 422,
+        title="Idempotency key payload mismatch",
+        detail=(
+            "The idempotency key was previously used with a different request payload. "
+            "To retry safely, send the same payload as before or use a new idempotency key."
+        ),
+    )
+
+
+def in_progress(stripe_compat: bool, retry_after_seconds: int) -> tuple[int, dict[str, str], bytes]:
+    status, headers, body = problem_response(
+        type_key="in-progress",
+        status=409 if stripe_compat else 423,
+        title="Idempotency key in progress",
+        detail=(
+            "Another request with the same idempotency key is currently being processed. "
+            "Wait and retry."
+        ),
+    )
+    headers["retry-after"] = str(max(1, retry_after_seconds))
+    return status, headers, body
+
+
+def identity_unavailable() -> tuple[int, dict[str, str], bytes]:
+    return problem_response(
+        type_key="identity-unavailable",
+        status=500,
+        title="Caller identity unavailable",
+        detail=(
+            "The server could not determine a caller identity for this request. "
+            "Idempotency was refused to preserve cross-tenant isolation. "
+            "This indicates a server-side configuration issue with the "
+            "scope extractor."
+        ),
+    )
+
+
+def storage_error(retry_after_seconds: int = 5) -> tuple[int, dict[str, str], bytes]:
+    status, headers, body = problem_response(
+        type_key="storage-error",
+        status=503,
+        title="Idempotency storage unavailable",
+        detail="The idempotency backend is temporarily unavailable. Retry.",
+    )
+    headers["retry-after"] = str(max(1, retry_after_seconds))
+    return status, headers, body