idemkit 0.1.0__py3-none-any.whl

idemkit/core/codecs.py

@@ -0,0 +1,229 @@
+"""Result codecs — the per-surface serialization seam (spec §5.4).
+
+The core stores a result as opaque bytes (``StoredResult.blob``). A codec maps a
+typed return value to and from those bytes. Following AWS Powertools' model, the
+on-the-wire form is JSON and the codec records what it serialized so a replay can
+reconstruct the typed value.
+
+This module ships the surface-neutral codecs the queue surface needs now:
+
+* ``SideEffectCodec`` — for handlers that return nothing. A completed record is
+  just a "processed" marker; replay means *skip*, not *return garbage* (§5.4).
+* ``JsonResultCodec`` — JSON in, JSON out, for result-bearing handlers whose
+  return value is already JSON-friendly.
+
+The richer typed codecs (dataclass, pydantic v1/v2, custom, and the opt-in
+``pickle`` with its security warning) land with the AI tool surface in a later
+phase; they plug into the same ``ResultCodec`` protocol.
+
+Fail-closed rule (§5.4): a value that cannot be serialized MUST raise here. The
+caller treats that as "do not cache" and re-runs rather than silently risking a
+second side effect.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import logging
+import warnings
+from collections.abc import Callable
+from typing import Any, Protocol, TypeVar
+
+from idemkit.core.runner import StoredResult
+
+_logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+T_contra = TypeVar("T_contra", contravariant=True)
+T_co = TypeVar("T_co", covariant=True)
+
+
+class ResultCodec(Protocol[T_contra, T_co]):
+    """Encode a handler's return value to bytes and back (spec §5.4).
+
+    Split into a contravariant input type and covariant output type so a codec
+    can advertise a precise input it accepts while its decode returns the same
+    or a wider type. Most codecs use the same type for both.
+    """
+
+    def encode(self, value: T_contra) -> StoredResult:
+        """Serialize ``value`` into a ``StoredResult``. MUST raise (fail closed)
+        if the value cannot be serialized — never return a lossy placeholder."""
+        ...
+
+    def decode(self, stored: StoredResult) -> T_co:
+        """Reconstruct the value from a stored record on replay."""
+        ...
+
+
+class SideEffectCodec:
+    """Codec for side-effect-only handlers that return ``None`` (spec §5.4).
+
+    Stores an empty marker. A completed record means "this dedup id was already
+    processed — skip it", and decoding always yields ``None`` (there is no
+    payload to replay).
+    """
+
+    def encode(self, value: Any) -> StoredResult:
+        # The value is ignored on purpose: a side-effect-only handler returns
+        # None, and there is nothing to replay. ``value`` is typed ``Any`` only
+        # so this codec is interchangeable with the result-bearing ones.
+        return StoredResult(blob=b"", meta={"codec": "side_effect"})
+
+    def decode(self, stored: StoredResult) -> None:
+        return None
+
+
+class JsonResultCodec:
+    """JSON-on-the-wire codec for result-bearing handlers (spec §5.4).
+
+    The return value must be JSON-serializable. If it is not, ``encode`` raises
+    (``TypeError``) and the caller fails closed rather than caching a broken
+    result. Use a typed codec (dataclass / pydantic) for richer return types.
+    """
+
+    def encode(self, value: Any) -> StoredResult:
+        try:
+            blob = json.dumps(value).encode("utf-8")
+        except (TypeError, ValueError) as e:
+            # Fail closed (§5.4): do not store a placeholder for an
+            # unserializable result, or a retry would re-run the side effect.
+            raise TypeError(
+                f"idemkit: result is not JSON-serializable ({e}). Use a typed "
+                "ResultCodec, or fix the return value. Refusing to cache so the "
+                "operation isn't silently re-run on retry."
+            ) from e
+        return StoredResult(blob=blob, meta={"codec": "json"})
+
+    def decode(self, stored: StoredResult) -> Any:
+        if not stored.blob:
+            return None
+        return json.loads(stored.blob)
+
+
+class DataclassResultCodec:
+    """Typed codec for a dataclass return type (spec §5.4).
+
+    JSON on the wire; the dataclass type is inferred from the tool's return
+    annotation. ``encode`` flattens to a dict via ``dataclasses.asdict``;
+    ``decode`` rebuilds the instance via ``cls(**data)``. Nested dataclasses
+    round-trip through ``asdict`` but rebuild as plain dicts unless the type's
+    own ``__init__`` reconstructs them — keep return types flat, or supply a
+    custom codec for nested shapes.
+    """
+
+    def __init__(self, cls: type) -> None:
+        if not dataclasses.is_dataclass(cls):
+            raise TypeError(
+                f"idemkit: result_codec='dataclass' needs a dataclass return "
+                f"annotation; {cls!r} is not a dataclass."
+            )
+        self._cls = cls
+
+    def encode(self, value: Any) -> StoredResult:
+        if not dataclasses.is_dataclass(value) or isinstance(value, type):
+            raise TypeError(
+                f"idemkit: expected a {self._cls.__name__} instance, got "
+                f"{type(value).__name__}. Refusing to cache (fail closed, §5.4)."
+            )
+        blob = json.dumps(dataclasses.asdict(value)).encode("utf-8")
+        return StoredResult(blob=blob, meta={"codec": "dataclass"})
+
+    def decode(self, stored: StoredResult) -> Any:
+        data = json.loads(stored.blob) if stored.blob else {}
+        return self._cls(**data)
+
+
+class PydanticResultCodec:
+    """Typed codec for a pydantic model return type, v1 and v2 (spec §5.4).
+
+    JSON on the wire. Works against either pydantic generation by feature-probing
+    the model class (``model_validate``/``model_dump`` on v2,
+    ``parse_obj``/``dict`` on v1) rather than importing pydantic, so idemkit
+    keeps its zero-dependency core.
+    """
+
+    def __init__(self, model: type) -> None:
+        # Probe for the v2 then v1 API so we fail loudly at decoration time, not
+        # mid-call, if the annotation isn't a pydantic model.
+        if not (hasattr(model, "model_validate") or hasattr(model, "parse_obj")):
+            raise TypeError(
+                f"idemkit: result_codec='pydantic' needs a pydantic model return "
+                f"annotation; {model!r} has neither model_validate (v2) nor "
+                "parse_obj (v1)."
+            )
+        # Typed Any: we feature-probe the v1/v2 API rather than depend on pydantic.
+        self._model: Any = model
+
+    def encode(self, value: Any) -> StoredResult:
+        if hasattr(value, "model_dump"):
+            data = value.model_dump(mode="json")  # pydantic v2
+        elif hasattr(value, "dict"):
+            data = value.dict()  # pydantic v1
+        else:
+            raise TypeError(
+                f"idemkit: expected a pydantic model instance, got "
+                f"{type(value).__name__}. Refusing to cache (fail closed, §5.4)."
+            )
+        return StoredResult(blob=json.dumps(data).encode("utf-8"), meta={"codec": "pydantic"})
+
+    def decode(self, stored: StoredResult) -> Any:
+        data = json.loads(stored.blob) if stored.blob else {}
+        if hasattr(self._model, "model_validate"):
+            return self._model.model_validate(data)  # v2
+        return self._model.parse_obj(data)  # v1
+
+
+class CustomResultCodec:
+    """Codec from a ``(to_dict, from_dict)`` pair (spec §5.4).
+
+    The escape hatch for return types the built-in codecs don't cover. JSON on
+    the wire; ``to_dict`` must return something ``json.dumps`` accepts.
+    """
+
+    def __init__(
+        self,
+        to_dict: Callable[[Any], Any],
+        from_dict: Callable[[Any], Any],
+    ) -> None:
+        self._to_dict = to_dict
+        self._from_dict = from_dict
+
+    def encode(self, value: Any) -> StoredResult:
+        blob = json.dumps(self._to_dict(value)).encode("utf-8")
+        return StoredResult(blob=blob, meta={"codec": "custom"})
+
+    def decode(self, stored: StoredResult) -> Any:
+        data = json.loads(stored.blob) if stored.blob else None
+        return self._from_dict(data)
+
+
+class PickleResultCodec:
+    """Pickle codec — OPT-IN, and a remote-code-execution risk (spec §5.4, §12).
+
+    Constructing one emits a security warning, because a stored pickle that an
+    attacker can influence is an RCE vector on ``decode``. Use a JSON or typed
+    codec unless you fully control and trust the backend contents. Provided so
+    arbitrary return types can be cached when the operator accepts the risk.
+    """
+
+    def __init__(self) -> None:
+        warnings.warn(
+            "idemkit: the pickle result codec is a remote-code-execution risk — "
+            "a stored pickle is executed on decode. Only use it if you fully "
+            "control and trust the backend's contents; prefer JSON or a typed "
+            "codec otherwise (spec §5.4, §12).",
+            stacklevel=2,
+        )
+        _logger.warning("idemkit: pickle result codec enabled (RCE risk on decode, §5.4).")
+
+    def encode(self, value: Any) -> StoredResult:
+        import pickle
+
+        return StoredResult(blob=pickle.dumps(value), meta={"codec": "pickle"})
+
+    def decode(self, stored: StoredResult) -> Any:
+        import pickle
+
+        return pickle.loads(stored.blob)

idemkit/core/config.py

@@ -0,0 +1,255 @@
+"""Public configuration for idemkit middleware, per spec §4.2 / §4.6 / §4.8 / §4.16."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from idemkit.core.events import EventHandler
+from idemkit.core.exceptions import ConfigurationError
+
+_logger = logging.getLogger(__name__)
+
+
+# Type aliases for the pluggable hooks (§4.7, §4.14).
+# Adapters pass framework-specific request types here.
+CallerIdentityExtractor = Callable[[Any], str]
+KeyExtractor = Callable[[Any], "str | None"]
+ResponseRedactor = Callable[[bytes, dict[str, str], int], "tuple[bytes, dict[str, str]]"]
+# (replay body, replay headers, status) -> the (body, headers) to send to the
+# DUPLICATE. Runs ONLY when replaying a stored response, so you can add a header,
+# tweak Cache-Control, and so on. Never runs on the first (live) request.
+ResponseHook = Callable[[bytes, dict[str, str], int], "tuple[bytes, dict[str, str]]"]
+# (raw request body, content-type) -> the bytes to fingerprint. Lets you select
+# which body fields matter (drop volatile timestamps/nonces). Returns the
+# canonical bytes idemkit hashes; return b"" to ignore the body entirely (§4.5).
+BodyFingerprint = Callable[[bytes, "str | None"], bytes]
+
+
+DEFAULT_HEADER_ALLOW: frozenset[str] = frozenset(
+    {
+        "content-type",
+        "content-encoding",
+        "content-language",
+        "content-disposition",
+        "location",
+        "etag",
+        "last-modified",
+        "link",
+        "cache-control",
+    }
+)
+
+DEFAULT_HEADER_DENY: frozenset[str] = frozenset(
+    {
+        # Privacy / auth sensitive
+        "set-cookie",
+        "authorization",
+        "www-authenticate",
+        # Vary (idemkit is not Vary-aware on replay)
+        "vary",
+        # Hop-by-hop per RFC 7230 §6.1
+        "connection",
+        "keep-alive",
+        "proxy-authenticate",
+        "proxy-authorization",
+        "te",
+        "trailers",
+        "transfer-encoding",
+        "upgrade",
+    }
+)
+
+
+@dataclass
+class IdempotencyConfig:
+    """Internal settings container for the HTTP middleware/decorator.
+
+    Built from the flat keyword arguments passed to ``IdempotencyMiddleware`` /
+    ``Idempotency``; users configure those surfaces with plain keywords and do not
+    construct this object directly. Holds the core policy (TTLs, lease, storage-error
+    policy, local cache, observability) plus the HTTP-specific options.
+    """
+
+    # ── Core policy ──
+    lease_ttl_seconds: float = 30.0
+    wait_timeout_seconds: float = 10.0
+    expires_after_seconds: float = 86_400.0
+    on_storage_error: Literal["fail_closed", "fail_open"] = "fail_closed"
+    use_local_cache: bool = False
+    local_cache_max_items: int = 1024
+    event_handlers: list[EventHandler] = field(default_factory=list)
+
+    # ── HTTP-specific ──
+
+    # Methods on which idempotency applies (§4.2 method scope)
+    applicable_methods: set[str] = field(default_factory=lambda: {"POST", "PATCH"})
+
+    # Response body size cap (§4.9)
+    max_body_bytes: int = 1024 * 1024  # 1 MiB
+
+    # Request body buffering cap. The middleware buffers the request body in
+    # memory to fingerprint it; this bounds that buffer to prevent a
+    # large-request memory DoS. A request whose body exceeds this is streamed
+    # to the handler WITHOUT idempotency (it is not deduplicated). Set to
+    # None to disable the cap (unbounded buffering — not recommended).
+    max_request_body_bytes: int | None = 1024 * 1024  # 1 MiB
+
+    # Cacheable status policy (§4.2): 5xx never cached by default
+    cacheable_status: set[int] = field(default_factory=lambda: {200, 201, 202})
+
+    # Wire-compatibility mode (§6.3.1).
+    #   "default" — 422 on payload mismatch, 423 on in-flight timeout, and the
+    #               Idempotency-Replayed header.
+    #   "stripe"  — 409 for both, and the Idempotent-Replayed header (Stripe's
+    #               deployed spelling), for drop-in compatibility with clients
+    #               written against Stripe's idempotency format.
+    compat_mode: Literal["default", "stripe"] = "default"
+
+    # Required-key enforcement (§6.1)
+    require_key_for_mutations: bool = False
+
+    # Request-body fingerprint (§4.5). The body is part of the FINGERPRINT (not the
+    # idempotency key): reusing a key with a different body is detected and rejected
+    # (422/409), so the wrong stored response is never replayed.
+    #   None (default) — fingerprint the whole body.
+    #   a callback ``body_fingerprint(raw_body, content_type) -> bytes`` —
+    #     fingerprint only what it returns, so you keep the fields that define the
+    #     operation and ignore volatile ones (a client timestamp, a nonce). Return
+    #     canonical bytes (e.g. ``json.dumps({...}, sort_keys=True).encode()``), or
+    #     ``b""`` to ignore the body entirely (dedupe on key + caller + method + path).
+    body_fingerprint: BodyFingerprint | None = None
+
+    # Pluggable extraction (§4.7) and cross-tenant scoping (§4.6).
+    # With no `scope`, idemkit runs in SINGLE-TENANT mode (all callers share one
+    # namespace). scope_mode picks what happens then:
+    #   "warn"          (default) run single-tenant and log a loud warning;
+    #   "single_tenant" run single-tenant, no warning (you acknowledged it);
+    #   "strict"        raise ConfigurationError if no scope (CI/production gate).
+    scope: CallerIdentityExtractor | None = None
+    scope_mode: Literal["warn", "single_tenant", "strict"] = "warn"
+    key: KeyExtractor | None = None
+
+    # PII redaction (§4.14)
+    response_redactor: ResponseRedactor | None = None
+
+    # Replay response hook: modify the response served to a DUPLICATE (runs only
+    # on replay, never on the first request).
+    response_hook: ResponseHook | None = None
+
+    # Header allow/deny lists (§4.10) — None falls back to module defaults
+    header_allow: set[str] | None = None
+    header_deny: set[str] | None = None
+
+    def __post_init__(self) -> None:
+        # Normalize methods
+        self.applicable_methods = {m.upper() for m in self.applicable_methods}
+
+        if self.compat_mode not in ("default", "stripe"):
+            raise ConfigurationError(
+                f"idemkit: compat_mode must be 'default' or 'stripe', got {self.compat_mode!r}."
+            )
+
+        if self.scope_mode not in ("warn", "single_tenant", "strict"):
+            raise ConfigurationError(
+                f"idemkit: scope_mode must be 'warn', 'single_tenant', or "
+                f"'strict', got {self.scope_mode!r}."
+            )
+
+        # Cross-tenant scoping (§4.6). Default: single-tenant + loud warning.
+        if self.scope is None:
+            if self.scope_mode == "strict":
+                raise ConfigurationError(
+                    "idemkit: scope_mode='strict' requires a `scope` extractor. "
+                    "Provide one, or use scope_mode='single_tenant' to run "
+                    "single-tenant on purpose. See spec §4.6."
+                )
+            if self.scope_mode == "warn":
+                _logger.warning(
+                    "idemkit: running single-tenant — no `scope` is set, so all "
+                    "callers share one idempotency namespace. That's fine for local "
+                    "dev and single-tenant services; if you have more than one user "
+                    "or tenant, set `scope` so they don't collide. Silence this with "
+                    "scope_mode='single_tenant', or make it a hard error with "
+                    "scope_mode='strict'. See spec §4.6."
+                )
+
+        # Lease sanity warning (§4.8)
+        if self.lease_ttl_seconds < 5.0:
+            _logger.warning(
+                "idemkit: lease_ttl_seconds=%.2f is very low; if your handler p99 "
+                "exceeds this, claims will expire mid-handler and adverse reclaim "
+                "races may occur. See spec §4.8.",
+                self.lease_ttl_seconds,
+            )
+
+    @property
+    def is_stripe_compat(self) -> bool:
+        """True when the Stripe wire-compatibility mode is active (§6.3.1)."""
+        return self.compat_mode == "stripe"
+
+    def effective_header_allow(self) -> frozenset[str]:
+        if self.header_allow:
+            return frozenset(h.lower() for h in self.header_allow)
+        return DEFAULT_HEADER_ALLOW
+
+    def effective_header_deny(self) -> frozenset[str]:
+        if self.header_deny:
+            return frozenset(h.lower() for h in self.header_deny)
+        return DEFAULT_HEADER_DENY
+
+
+def resolve_http_config(config: Any) -> IdempotencyConfig:
+    """Build the HTTP config from an ``HttpConfig`` (flat, widened with the HTTP
+    defaults) or the internal ``IdempotencyConfig``.
+    """
+    from idemkit.core.policy import HttpConfig
+
+    if config is None:
+        return IdempotencyConfig()
+
+    if isinstance(config, HttpConfig):
+        # A flat HttpConfig. lease/wait default to None ("use the HTTP default");
+        # other None fields fall back to the IdempotencyConfig defaults (not passed).
+        data: dict[str, Any] = {
+            "lease_ttl_seconds": (
+                config.lease_ttl_seconds if config.lease_ttl_seconds is not None else 30.0
+            ),
+            "wait_timeout_seconds": (
+                config.wait_timeout_seconds if config.wait_timeout_seconds is not None else 10.0
+            ),
+            "expires_after_seconds": config.expires_after_seconds,
+            "on_storage_error": config.on_storage_error,
+            "use_local_cache": config.use_local_cache,
+            "local_cache_max_items": config.local_cache_max_items,
+            "event_handlers": list(config.event_handlers),
+            "scope": config.scope,
+            "scope_mode": config.scope_mode,
+            "key": config.key,
+            "require_key_for_mutations": config.require_key_for_mutations,
+            "body_fingerprint": config.body_fingerprint,
+            "response_redactor": config.response_redactor,
+            "response_hook": config.response_hook,
+            "compat_mode": config.compat_mode,
+        }
+        for f in (
+            "applicable_methods",
+            "header_allow",
+            "header_deny",
+            "cacheable_status",
+            "max_body_bytes",
+            "max_request_body_bytes",
+        ):
+            v = getattr(config, f)
+            if v is not None:
+                data[f] = v
+        return IdempotencyConfig(**data)
+
+    if not isinstance(config, IdempotencyConfig):
+        raise TypeError(
+            "idemkit: config= must be an HttpConfig or IdempotencyConfig, "
+            f"got {type(config).__name__}."
+        )
+    return config