idemkit 0.1.0__py3-none-any.whl

idemkit/core/fingerprint.py

@@ -0,0 +1,153 @@
+"""Length-prefixed SHA-256 hashing for fingerprint (§4.5) and effective key (§4.6).
+
+The construction ``SHA-256(len_be32(c0) ‖ c0 ‖ len_be32(c1) ‖ c1 ‖ …)`` is
+collision-resistant for arbitrary inputs, including those containing 0x00
+bytes. This matters because both request bodies and idempotency keys are
+user-controlled.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import struct
+import urllib.parse
+
+FINGERPRINT_VERSION = 1
+
+
+def _len_be32(b: bytes) -> bytes:
+    """4-byte big-endian unsigned length prefix."""
+    return struct.pack(">I", len(b))
+
+
+def _length_prefixed_sha256(components: list[bytes]) -> str:
+    """Lowercase hex SHA-256 of length-prefixed concatenation."""
+    h = hashlib.sha256()
+    for component in components:
+        h.update(_len_be32(component))
+        h.update(component)
+    return h.hexdigest()
+
+
+_PCT_RE = re.compile(rb"%([0-9a-fA-F]{2})")
+
+
+def _uppercase_percent_bytes(s: bytes) -> bytes:
+    """Normalize ``%xx`` escapes to uppercase hex per RFC 3986 §6.2.2.1."""
+    return _PCT_RE.sub(lambda m: b"%" + m.group(1).upper(), s)
+
+
+def canonicalize_path(path: str) -> str:
+    """Canonicalize a URL path per spec §4.5.
+
+    - Collapse repeated slashes.
+    - Strip trailing slash except for root ``/``.
+    - Normalize percent-encoding to uppercase hex.
+    """
+    while "//" in path:
+        path = path.replace("//", "/")
+    if len(path) > 1 and path.endswith("/"):
+        path = path[:-1]
+    return _uppercase_percent_bytes(path.encode("utf-8")).decode("utf-8")
+
+
+def canonicalize_query(query: str) -> str:
+    """Canonicalize a query string per spec §4.5.
+
+    Percent-decode once, sort params lexicographically by (name, value),
+    re-encode with uppercase percent escapes.
+    """
+    if not query:
+        return ""
+    parsed = urllib.parse.parse_qsl(query, keep_blank_values=True)
+    parsed.sort()
+    encoded = urllib.parse.urlencode(parsed, doseq=False)
+    return _uppercase_percent_bytes(encoded.encode("utf-8")).decode("utf-8")
+
+
+def canonicalize_body(body: bytes, content_type: str | None) -> bytes:
+    """Canonicalize a request body per spec §4.5.
+
+    Returns canonicalized bytes. On parse failure, falls back to raw bytes
+    (normative per spec — implementations MUST NOT raise on parse failure).
+    """
+    if not body or not content_type:
+        return body
+
+    ct_main = content_type.lower().split(";", 1)[0].strip()
+
+    if ct_main == "application/json":
+        try:
+            parsed = json.loads(body)
+        except (json.JSONDecodeError, ValueError, UnicodeDecodeError):
+            return body
+        return json.dumps(parsed, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+            "utf-8"
+        )
+
+    if ct_main == "application/x-www-form-urlencoded":
+        try:
+            decoded = body.decode("utf-8")
+        except UnicodeDecodeError:
+            return body
+        parsed_form = urllib.parse.parse_qsl(decoded, keep_blank_values=True)
+        parsed_form.sort()
+        return urllib.parse.urlencode(parsed_form).encode("utf-8")
+
+    # Other content types fall back to the raw decoded bytes. NOTE: spec §4.5
+    # describes a per-part canonicalization for multipart/form-data; v0.1 does
+    # NOT implement it and treats multipart bodies as raw bytes, so a re-encoded
+    # multipart body with a different boundary fingerprints differently. This is
+    # a documented v0.1 limitation; full multipart canonicalization is deferred.
+    return body
+
+
+def compute_fingerprint(
+    method: str,
+    path: str,
+    query: str,
+    body: bytes,
+    content_type: str | None,
+) -> str:
+    """Compute fingerprint v1 per spec §4.5."""
+    return _length_prefixed_sha256(
+        [
+            method.upper().encode("ascii"),
+            canonicalize_path(path).encode("utf-8"),
+            canonicalize_query(query).encode("utf-8"),
+            canonicalize_body(body, content_type),
+        ]
+    )
+
+
+def compute_effective_key(
+    idempotency_key: str,
+    scope: str,
+    method: str,
+    path: str,
+) -> str:
+    """Compute effective key per spec §4.6 with length-prefixed composition."""
+    return _length_prefixed_sha256(
+        [
+            idempotency_key.encode("utf-8"),
+            scope.encode("utf-8"),
+            method.upper().encode("ascii"),
+            canonicalize_path(path).encode("utf-8"),
+        ]
+    )
+
+
+def compose_key(components: list[str]) -> str:
+    """Length-prefixed SHA-256 over arbitrary string scope components (spec §5.1).
+
+    The surface-neutral effective-key builder for the queue and AI surfaces,
+    where the scope is a tuple of plain strings rather than HTTP's
+    (key, caller, method, path). Length-prefixing keeps it collision-resistant
+    even when a component contains a 0x00 byte, same as the HTTP construction.
+
+    Queue: ``compose_key([dedup_id, queue_or_topic, consumer_group])``.
+    AI tool: ``compose_key([tool_name, version, args_hash, scope])``.
+    """
+    return _length_prefixed_sha256([c.encode("utf-8") for c in components])

idemkit/core/policy.py

@@ -0,0 +1,143 @@
+"""One flat config object per surface: ``HttpConfig`` / ``QueueConfig`` / ``MethodConfig``.
+
+Each surface is configured with exactly one of these objects, passed as ``config=``.
+There are no loose keyword overrides: the config is the one way in. To reuse settings
+across surfaces or call sites, write a small factory that returns the config you want
+(there is no separate shared object to learn).
+
+The datastore is configured separately, on the backend (``PostgresBackend(table=...)``,
+``RedisBackend.from_url(url, namespace=...)``): the backend is WHERE dedup state
+lives; the config is HOW a duplicate is judged and replayed.
+
+Surface-option fields are typed loosely here (this module cannot import the HTTP
+config's aliases without a cycle); the adapters validate them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from idemkit.core.events import EventHandler
+
+
+class _Unset:
+    """Sentinel for a keyword that was not passed, so a config can supply it."""
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "<use default>"
+
+
+# Typed as Any so a signature can default a real-typed keyword to it without
+# upsetting type checkers, while the runtime can still detect "not passed".
+UNSET: Any = _Unset()
+
+
+# The options shared by every surface (lease/wait default to None = "use the
+# surface's own default"). They are inlined flat into each surface config below.
+@dataclass(frozen=True)
+class MethodConfig:
+    """Config for ``@idempotent`` / ``idempotent_sync`` (flat: all options on one
+    object). Pass ``config=MethodConfig(...)``."""
+
+    # method-specific
+    key_fields: list[str] | None = None
+    scope: Callable[[Any], Any] | None = None
+    validation_fingerprint: Callable[[Any], bytes] | None = None
+    normalize_args: Callable[[Any], Any] | None = None
+    result_codec: Any = "json"
+    strict_keys: bool = True
+    # When True, refuse to derive the key from all arguments: the call must name its
+    # key via key_fields, normalize_args, or a per-call idempotency_key (else raises
+    # IdempotencyKeyMissing). The enforcing analogue of Powertools raise_on_no_idempotency_key.
+    require_key: bool = False
+    # Exception types that are DETERMINISTIC: instead of releasing the claim (retry
+    # re-runs), cache the exception and re-raise it on a duplicate. Default: cache
+    # nothing (every raise is treated as a transient crash and re-run).
+    cache_exceptions: tuple[type[BaseException], ...] = ()
+    version: str = "1"
+    # shared
+    lease_ttl_seconds: float | None = None
+    wait_timeout_seconds: float | None = None
+    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: tuple[EventHandler, ...] = ()
+
+
+@dataclass(frozen=True)
+class QueueConfig:
+    """Config for ``IdempotentConsumer`` (flat). ``dedup_id`` (how to read the broker's
+    dedup id from a message) and ``visibility_timeout_seconds`` (the broker's window)
+    are required for a direct consumer; the ``contrib`` helpers (sqs/kafka) preset
+    ``dedup_id`` for you."""
+
+    # required wiring
+    dedup_id: Callable[[Any], str] | None = None
+    visibility_timeout_seconds: float | None = None
+    # queue-specific
+    scope: Callable[[Any], Any] | None = None
+    max_attempts: int = 5
+    on_exhausted: Callable[[Any, Any], Any] | None = None
+    receive_count: Callable[[Any], Any] | None = None
+    attempt_store: Any | None = None
+    cache_result: bool = False
+    result_codec: Any | None = None
+    # A field that must match on a dedup-id hit but isn't part of the key: catches a
+    # producer that reused a message id with a different body (raises PayloadMismatch).
+    validation_fingerprint: Callable[[Any], bytes] | None = None
+    # shared
+    lease_ttl_seconds: float | None = None
+    wait_timeout_seconds: float | None = None
+    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: tuple[EventHandler, ...] = ()
+
+
+@dataclass(frozen=True)
+class HttpConfig:
+    """Config for the HTTP middleware / route decorator (flat). ``None`` fields fall
+    back to the HTTP defaults."""
+
+    # http-specific
+    scope: Callable[[Any], str] | None = None
+    scope_mode: Literal["warn", "single_tenant", "strict"] = "warn"
+    key: Callable[[Any], str | None] | None = None
+    require_key_for_mutations: bool = False
+    applicable_methods: set[str] | None = None
+    body_fingerprint: Callable[[bytes, Any], bytes] | None = None
+    response_redactor: Any | None = None
+    response_hook: Any | None = None
+    header_allow: set[str] | None = None
+    header_deny: set[str] | None = None
+    cacheable_status: set[int] | None = None
+    max_body_bytes: int | None = None
+    max_request_body_bytes: int | None = None
+    compat_mode: Literal["default", "stripe"] = "default"
+    # shared
+    lease_ttl_seconds: float | None = None
+    wait_timeout_seconds: float | None = None
+    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: tuple[EventHandler, ...] = ()
+
+
+def pick(explicit: Any, config: Any, field_name: str, default: Any) -> Any:
+    """Resolve one value: an explicit keyword wins, then the config field, then the
+    default. A config field of ``None`` means "inherit the default". ``config`` is a
+    flat surface config or ``None``."""
+    if explicit is not UNSET:
+        return explicit
+    if config is not None:
+        value = getattr(config, field_name)
+        if value is not None:
+            return value
+    return default