idempotency-kit 0.1.1__tar.gz → 0.3.0__tar.gz

idempotency_kit-0.3.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+## [0.3.0](https://github.com/bedrock-python/idempotency-kit/compare/idempotency-kit-v0.2.0...idempotency-kit-v0.3.0) (2026-09-07)
+
+
+### ⚠ BREAKING CHANGES
+
+* a second concurrent caller with the same key now waits for the first caller's result instead of running the action too, and coordinate() and the decorator can raise IdempotencyInProgressError. Pass in_flight="run" to the coordinator (or set it on the settings object) to keep the previous behaviour. AsyncIdempotencyRepository gained replace(record); a custom repository needs it, and the coordinator raises TypeError at construction without it unless in_flight="run". IdempotencyRecord gained status, which records written before this change read as "completed".
+
+### Features
+
+* reserve the key while the action runs ([#28](https://github.com/bedrock-python/idempotency-kit/issues/28)) ([0dbf68b](https://github.com/bedrock-python/idempotency-kit/commit/0dbf68b04ce5a54c18f041a35b77d1df2c043fb7)), closes [#26](https://github.com/bedrock-python/idempotency-kit/issues/26)
+* store a fingerprint of the request and refuse a key reused for another ([#30](https://github.com/bedrock-python/idempotency-kit/issues/30)) ([78a9ca2](https://github.com/bedrock-python/idempotency-kit/commit/78a9ca2abb1b5d6a660d1bdf0b31f32a7da256d1)), closes [#27](https://github.com/bedrock-python/idempotency-kit/issues/27)
+
+## [0.2.0](https://github.com/bedrock-python/idempotency-kit/compare/idempotency-kit-v0.1.1...idempotency-kit-v0.2.0) (2026-09-06)
+
+
+### ⚠ BREAKING CHANGES
+
+* DEFAULT_TTL_MINUTES is 60 (was 30) and MAX_TTL_SECONDS is 2592000 (was 86400), so IdempotencyDomainService() built without arguments now keeps records for an hour and accepts a TTL of up to 30 days. Pass default_ttl_minutes=30 and max_ttl_seconds=86400 to keep the old values.
+
+### Bug Fixes
+
+* the defects the agents page turned up ([#22](https://github.com/bedrock-python/idempotency-kit/issues/22)) ([1573db4](https://github.com/bedrock-python/idempotency-kit/commit/1573db4774191598cad38b02e653b2656d3bb763))
+
+
+### Documentation
+
+* an upgrade note for the unified TTL defaults ([#25](https://github.com/bedrock-python/idempotency-kit/issues/25)) ([bb90e84](https://github.com/bedrock-python/idempotency-kit/commit/bb90e8453e0ac74856b354b34f01dfe495e9393c))
+
+## [0.1.1](https://github.com/bedrock-python/idempotency-kit/compare/idempotency-kit-v0.1.0...idempotency-kit-v0.1.1) (2026-08-28)
+
+
+### Bug Fixes
+
+* **core:** store any JSON result and decide hit/miss on the record, not on None ([#8](https://github.com/bedrock-python/idempotency-kit/issues/8)) ([ddb537e](https://github.com/bedrock-python/idempotency-kit/commit/ddb537e8c39e5becb1a9b1ff7549bc11f40735d7)), closes [#6](https://github.com/bedrock-python/idempotency-kit/issues/6)
+* **dishka:** provide the metrics collector from settings so the shipped providers build a container ([#9](https://github.com/bedrock-python/idempotency-kit/issues/9)) ([2a06416](https://github.com/bedrock-python/idempotency-kit/commit/2a064169a16332762d3ab62926c03d2f203482bd)), closes [#7](https://github.com/bedrock-python/idempotency-kit/issues/7)
+* **release:** update version to 0.1.0 and fix release-please config ([016c6c4](https://github.com/bedrock-python/idempotency-kit/commit/016c6c42ba189291be56250192f9e6db7020f853))
+* update publish workflow, release-please version search, gitignore ([#3](https://github.com/bedrock-python/idempotency-kit/issues/3)) ([9915f0e](https://github.com/bedrock-python/idempotency-kit/commit/9915f0e6e784b6d59375541e6244efaca694a0bb))
+
+## 0.1.0 (2026-05-13)
+
+
+### Bug Fixes
+
+* **ci:** remove coverage threshold from integration tests ([b00f037](https://github.com/bedrock-python/idempotency-kit/commit/b00f03742925922e261790b0ee649055c31fdaae))
+* **ci:** set integration test coverage threshold to 50% ([ed4e790](https://github.com/bedrock-python/idempotency-kit/commit/ed4e7907ff977916b0be11a6597a090b9ae11cab))
+
+
+### Documentation
+
+* rewrite README to match library style with badges ([cebded3](https://github.com/bedrock-python/idempotency-kit/commit/cebded360b4c0c37d7604efd230574b4464f47c8))
+
+## Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

{idempotency_kit-0.1.1 → idempotency_kit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: idempotency-kit
-Version: 0.1.1
+Version: 0.3.0
 Summary: Production-ready idempotency library for async Python applications
 Project-URL: Repository, https://github.com/bedrock-python/idempotency-kit
 Project-URL: Documentation, https://bedrock-python.github.io/idempotency-kit/
@@ -244,6 +244,15 @@ Production-ready idempotency library for async Python applications.
 
 Ensure operations execute exactly once, even when called multiple times with the same idempotency key. Built for production microservices with graceful degradation, collision handling, and observability.
 
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://bedrock-python.github.io/idempotency-kit/agents/)** instead of the
+> whole site: the complete API surface, the rules that break code when they are broken —
+> what the key actually identifies, what two concurrent callers really do, how a TTL in
+> seconds is rounded — the mistakes models make with this API, and a map of which page to
+> fetch for the rest. Every docs page is also served as raw Markdown at its own URL, and a
+> **Copy page** button at the top of each one hands it straight to a chat window.
+
 ## Features
 
 - **Clean Architecture** — core domain separated from infrastructure
@@ -251,7 +260,8 @@ Ensure operations execute exactly once, even when called multiple times with the
 - **Type-Safe** — full type hints with Pydantic validation
 - **Async First** — built for asyncio applications
 - **Graceful Degradation** — high availability over strict exactly-once
-- **Collision Handling** — automatic resolution of concurrent requests
+- **In-flight Reservation** — a retry that arrives while the original is still running waits for its result or gets a 409; the action runs once
+- **Request Fingerprints** — name the parameters that identify a request, and a key reused for a different one is refused instead of replayed
 - **Observability** — built-in metrics (hits, misses, collisions, latency)
 - **Bulk Operations** — efficient `get_many`, `save_many`, `delete_many`
 - **Redis Cluster Compatible** — non-transactional pipelines
@@ -334,12 +344,12 @@ return order
 
 ### 4. Concurrent requests handled
 
-If two requests arrive simultaneously:
+If two requests arrive while the first is still executing:
 
-- First request: cache miss → execute → save ✅
-- Second request: collision on save → fetch first result → return ✅
+- First request: reserves the key → execute → write the result over the reservation ✅
+- Second request: finds the reservation → waits for the first result → return ✅ (or a 409 with `in_flight="raise"`)
 
-Both requests get the **same result** - idempotency guaranteed!
+Both requests get the **same result**, and the business logic ran once.
 
 ## Use cases
 
@@ -352,6 +362,7 @@ Both requests get the **same result** - idempotency guaranteed!
 
 📚 **[Full Documentation](https://bedrock-python.github.io/idempotency-kit/)**
 
+- [For AI agents](https://bedrock-python.github.io/idempotency-kit/agents/) — the whole library on one page
 - [Quick Start](https://bedrock-python.github.io/idempotency-kit/quickstart/) — get started in 5 minutes
 - [User Guide](https://bedrock-python.github.io/idempotency-kit/user_guide/) — detailed usage and patterns
 - [Architecture](https://bedrock-python.github.io/idempotency-kit/architecture/) — design principles

{idempotency_kit-0.1.1 → idempotency_kit-0.3.0}/README.md

@@ -11,6 +11,15 @@ Production-ready idempotency library for async Python applications.
 
 Ensure operations execute exactly once, even when called multiple times with the same idempotency key. Built for production microservices with graceful degradation, collision handling, and observability.
 
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://bedrock-python.github.io/idempotency-kit/agents/)** instead of the
+> whole site: the complete API surface, the rules that break code when they are broken —
+> what the key actually identifies, what two concurrent callers really do, how a TTL in
+> seconds is rounded — the mistakes models make with this API, and a map of which page to
+> fetch for the rest. Every docs page is also served as raw Markdown at its own URL, and a
+> **Copy page** button at the top of each one hands it straight to a chat window.
+
 ## Features
 
 - **Clean Architecture** — core domain separated from infrastructure
@@ -18,7 +27,8 @@ Ensure operations execute exactly once, even when called multiple times with the
 - **Type-Safe** — full type hints with Pydantic validation
 - **Async First** — built for asyncio applications
 - **Graceful Degradation** — high availability over strict exactly-once
-- **Collision Handling** — automatic resolution of concurrent requests
+- **In-flight Reservation** — a retry that arrives while the original is still running waits for its result or gets a 409; the action runs once
+- **Request Fingerprints** — name the parameters that identify a request, and a key reused for a different one is refused instead of replayed
 - **Observability** — built-in metrics (hits, misses, collisions, latency)
 - **Bulk Operations** — efficient `get_many`, `save_many`, `delete_many`
 - **Redis Cluster Compatible** — non-transactional pipelines
@@ -101,12 +111,12 @@ return order
 
 ### 4. Concurrent requests handled
 
-If two requests arrive simultaneously:
+If two requests arrive while the first is still executing:
 
-- First request: cache miss → execute → save ✅
-- Second request: collision on save → fetch first result → return ✅
+- First request: reserves the key → execute → write the result over the reservation ✅
+- Second request: finds the reservation → waits for the first result → return ✅ (or a 409 with `in_flight="raise"`)
 
-Both requests get the **same result** - idempotency guaranteed!
+Both requests get the **same result**, and the business logic ran once.
 
 ## Use cases
 
@@ -119,6 +129,7 @@ Both requests get the **same result** - idempotency guaranteed!
 
 📚 **[Full Documentation](https://bedrock-python.github.io/idempotency-kit/)**
 
+- [For AI agents](https://bedrock-python.github.io/idempotency-kit/agents/) — the whole library on one page
 - [Quick Start](https://bedrock-python.github.io/idempotency-kit/quickstart/) — get started in 5 minutes
 - [User Guide](https://bedrock-python.github.io/idempotency-kit/user_guide/) — detailed usage and patterns
 - [Architecture](https://bedrock-python.github.io/idempotency-kit/architecture/) — design principles

{idempotency_kit-0.1.1 → idempotency_kit-0.3.0}/idempotency_kit/__init__.py

@@ -8,12 +8,15 @@ from .core.adapters import (
 from .core.decorators.aio.idempotent import async_idempotent
 from .core.exceptions import (
     IdempotencyError,
+    IdempotencyInProgressError,
     IdempotencyInvalidTTLError,
     IdempotencyKeyCollisionError,
+    IdempotencyKeyReuseError,
     IdempotencyRecordExpiredError,
     IdempotencyStorageError,
     IdempotencyValidationError,
 )
+from .core.fingerprint import fingerprint_of
 from .core.models.entities import IdempotencyIdentifiers, IdempotencyRecord
 from .core.protocols.adapter import ResultAdapter
 from .core.protocols.aio.repository import AsyncIdempotencyRepository
@@ -27,8 +30,10 @@ __all__ = [
     "IdempotencyDomainService",
     "IdempotencyError",
     "IdempotencyIdentifiers",
+    "IdempotencyInProgressError",
     "IdempotencyInvalidTTLError",
     "IdempotencyKeyCollisionError",
+    "IdempotencyKeyReuseError",
     "IdempotencyMetricsProtocol",
     "IdempotencyRecord",
     "IdempotencyRecordExpiredError",
@@ -40,4 +45,5 @@ __all__ = [
     "ResultAdapter",
     "VoidResultAdapter",
     "async_idempotent",
+    "fingerprint_of",
 ]

idempotency_kit-0.3.0/idempotency_kit/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"  # x-release-please-version

idempotency_kit-0.3.0/idempotency_kit/core/adapters/basic.py

@@ -0,0 +1,61 @@
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from idempotency_kit.core.exceptions import IdempotencyValidationError
+from idempotency_kit.core.protocols.adapter import ResultAdapter
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class PydanticResultAdapter(ResultAdapter[T]):
+    """Adapter for Pydantic models.
+
+    It has no representation for an absent result: an action that may return ``None``
+    wants ``VoidResultAdapter`` or ``JsonResultAdapter`` instead.
+    """
+
+    def __init__(self, model_class: type[T]) -> None:
+        self.model_class = model_class
+
+    def encode(self, value: T) -> Any:
+        # Encoding None to null would store a record this adapter can never decode again,
+        # turning every later replay into a miss. Refusing it leaves the operation
+        # uncached and says why, which the coordinator reports and swallows.
+        model: BaseModel | None = value
+        if model is None:
+            msg = (
+                f"{type(self).__name__}({self.model_class.__name__}) cannot encode None. "
+                "Use VoidResultAdapter for an action that returns None, or JsonResultAdapter "
+                "for one that may."
+            )
+            raise IdempotencyValidationError(msg)
+        return model.model_dump(mode="json")
+
+    def decode(self, data: Any) -> T:
+        # Only a null payload is undecodable: an empty mapping or list is a model that
+        # happens to dump to nothing.
+        if data is None:
+            msg = "cannot decode a null idempotency payload"
+            raise ValueError(msg)
+        return self.model_class.model_validate(data)
+
+
+class JsonResultAdapter(ResultAdapter[Any]):
+    """Adapter for results that already are JSON values (dict, list, str, number, bool or ``None``)."""
+
+    def encode(self, value: Any) -> Any:
+        return value
+
+    def decode(self, data: Any) -> Any:
+        return data
+
+
+class VoidResultAdapter(ResultAdapter[None]):
+    """Adapter for functions that return ``None``: the record stores JSON ``null`` and decodes back to ``None``."""
+
+    def encode(self, value: None) -> Any:
+        return None
+
+    def decode(self, data: Any) -> None:
+        return None

idempotency_kit-0.3.0/idempotency_kit/core/constants.py

@@ -0,0 +1,41 @@
+"""Core constants for idempotency."""
+
+from typing import Literal
+
+# Key constraints
+# Maximum allowed length for idempotency key.
+MAX_KEY_LENGTH: int = 255
+
+# Maximum allowed length for operation name.
+MAX_OPERATION_LENGTH: int = 100
+
+# TTL defaults
+# The single source for both IdempotencyDomainService's own defaults and the field
+# defaults of BaseIdempotencySettings, so the bounds do not depend on how the service
+# was built.
+
+# Default TTL in minutes when not explicitly specified (1 hour).
+DEFAULT_TTL_MINUTES: int = 60
+
+# Minimum allowed TTL in seconds (1 minute); the coordinator floors every TTL at a minute.
+MIN_TTL_SECONDS: int = 60
+
+# Maximum allowed TTL in seconds (30 days).
+MAX_TTL_SECONDS: int = 30 * 24 * 3600
+
+# In-flight handling
+# What the coordinator does with a second caller that arrives while the first one's
+# action is still running under the same key: wait for the first caller's result, raise
+# IdempotencyInProgressError at once, or run the action too.
+InFlightMode = Literal["wait", "raise", "run"]
+
+# Wait by default: a second caller in the retry window gets the first caller's result
+# instead of producing a second one.
+DEFAULT_IN_FLIGHT_MODE: InFlightMode = "wait"
+
+# How long a reservation is held before it counts as abandoned (30 seconds). It has to
+# outlive the action; a waiting caller gives up after the same span.
+DEFAULT_IN_FLIGHT_LEASE_SECONDS: int = 30
+
+# How often a waiting caller re-reads the key.
+IN_FLIGHT_POLL_INTERVAL_SECONDS: float = 0.05

idempotency_kit-0.3.0/idempotency_kit/core/decorators/aio/idempotent.py

@@ -0,0 +1,161 @@
+import functools
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar
+
+from idempotency_kit.core.fingerprint import fingerprint_of
+from idempotency_kit.core.protocols.adapter import ResultAdapter
+from idempotency_kit.core.services.aio.coordinator import AsyncIdempotencyCoordinator
+
+T = TypeVar("T")
+
+logger = logging.getLogger(__name__)
+
+_POSITIONAL_KINDS = (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+
+
+def _positional_index(func: Callable[..., Any], key_param: str) -> int | None:
+    """Index at which ``key_param`` can arrive positionally, or ``None`` if it cannot."""
+    try:
+        parameters = list(inspect.signature(func).parameters.values())
+    except (TypeError, ValueError):
+        return None
+    for index, parameter in enumerate(parameters):
+        if parameter.name == key_param and parameter.kind in _POSITIONAL_KINDS:
+            return index
+    return None
+
+
+def _fingerprint_resolver(
+    func: Callable[..., Any], fingerprint_params: tuple[str, ...] | None
+) -> Callable[[tuple[Any, ...], dict[str, Any]], str] | None:
+    """Build the function that fingerprints a call from the named parameters, or ``None`` when there are none.
+
+    Resolved at decoration time so that a parameter the function does not have, or a
+    signature ``inspect`` cannot describe, fails at import rather than on the first call.
+    """
+    if not fingerprint_params:
+        return None
+    try:
+        signature = inspect.signature(func)
+    except (TypeError, ValueError) as e:
+        raise TypeError(f"fingerprint_params needs a signature inspect can describe; {func!r} has none") from e
+    unknown = [name for name in fingerprint_params if name not in signature.parameters]
+    if unknown:
+        raise TypeError(f"fingerprint_params names parameters {func.__qualname__} does not have: {unknown}")
+
+    def resolve(args: tuple[Any, ...], kwargs: dict[str, Any]) -> str:
+        # Defaults applied, so an argument passed at its default and one left out agree.
+        bound = signature.bind(*args, **kwargs)
+        bound.apply_defaults()
+        return fingerprint_of(**{name: bound.arguments[name] for name in fingerprint_params})
+
+    return resolve
+
+
+def async_idempotent(
+    operation: str,
+    adapter: ResultAdapter[T],
+    ttl_seconds: int | None = None,
+    key_param: str = "idempotency_key",
+    infra_param: str | None = None,
+    fingerprint_params: tuple[str, ...] | None = None,
+) -> Callable[[Callable[..., Awaitable[T]]], Callable[..., Awaitable[T]]]:
+    """Decorator for asynchronous idempotent operations.
+
+    Can be used on methods (finding coordinator in 'self') or standalone functions
+    (finding coordinator in arguments).
+
+    Args:
+        operation: Unique operation name.
+        adapter: Result adapter for encoding/decoding.
+        ttl_seconds: Optional TTL for idempotency record in seconds.
+            If not provided, uses value from coordinator settings or global default.
+        key_param: Name of the argument containing the idempotency key. Read from the
+            keyword arguments, or from the positional arguments when the parameter can
+            be passed positionally.
+        infra_param: Optional name of the argument or attribute containing AsyncIdempotencyCoordinator.
+            If not provided, searches for AsyncIdempotencyCoordinator by type.
+        fingerprint_params: Names of the parameters whose values identify the request. Their
+            bound values, defaults applied, are hashed with ``fingerprint_of`` and stored with
+            the record; a later call under the same key with a different fingerprint raises
+            ``IdempotencyKeyReuseError``. ``None`` means the key alone is the identity.
+    """
+
+    def decorator(func: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
+        key_index = _positional_index(func, key_param)
+        fingerprint = _fingerprint_resolver(func, fingerprint_params)
+
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> T:
+            # 1. Resolve idempotency key
+            idempotency_key = _resolve_key(args, kwargs)
+            if not idempotency_key:
+                return await func(*args, **kwargs)
+
+            # 2. Resolve coordinator
+            coordinator = _resolve_coordinator(args, kwargs)
+
+            if coordinator is None:
+                # Proceeding without idempotency keeps the operation available, but it is
+                # never what the decorator was put there for: say so loudly enough to be
+                # caught by whoever renamed the attribute or forgot the argument.
+                logger.warning(
+                    "No idempotency coordinator found; running the operation without idempotency",
+                    extra={
+                        "operation": operation,
+                        "idempotency_key": idempotency_key,
+                        "infra_param": infra_param,
+                    },
+                )
+                return await func(*args, **kwargs)
+
+            # 3. Delegate to coordinator
+            if fingerprint is not None:
+                kwargs = {"idempotency_fingerprint": fingerprint(args, kwargs), **kwargs}
+            return await coordinator.coordinate(
+                operation,
+                idempotency_key,
+                ttl_seconds,
+                adapter,
+                func,
+                *args,
+                **kwargs,
+            )
+
+        def _resolve_key(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+            if key_param in kwargs:
+                return kwargs[key_param]
+            if key_index is not None and key_index < len(args):
+                return args[key_index]
+            return None
+
+        def _resolve_coordinator(args: tuple[Any, ...], kwargs: dict[str, Any]) -> AsyncIdempotencyCoordinator | None:
+            # By name, if infra_param is provided
+            if infra_param:
+                named: AsyncIdempotencyCoordinator | None = kwargs.get(infra_param)
+                if named is None and args:
+                    named = getattr(args[0], infra_param, None)
+                if named is not None:
+                    return named
+
+            # By type, in the keyword arguments
+            for val in kwargs.values():
+                if isinstance(val, AsyncIdempotencyCoordinator):
+                    return val
+
+            # By type, in the positional arguments, then in their attributes:
+            # DI often injects the coordinator into an attribute of 'self'.
+            for arg in args:
+                if isinstance(arg, AsyncIdempotencyCoordinator):
+                    return arg
+                if hasattr(arg, "__dict__"):
+                    for attr_val in vars(arg).values():
+                        if isinstance(attr_val, AsyncIdempotencyCoordinator):
+                            return attr_val
+            return None
+
+        return wrapper
+
+    return decorator

{idempotency_kit-0.1.1 → idempotency_kit-0.3.0}/idempotency_kit/core/exceptions.py

@@ -54,3 +54,26 @@ class IdempotencyInvalidTTLError(IdempotencyError):
         self.min_ttl = min_ttl
         self.max_ttl = max_ttl
         super().__init__(f"Invalid TTL {ttl_seconds}s. Must be between {min_ttl}s and {max_ttl}s")
+
+
+class IdempotencyInProgressError(IdempotencyError):
+    """Raised when another call with the same key is still running its action."""
+
+    def __init__(self, operation: str, key: str) -> None:
+        self.operation = operation
+        self.key = key
+        super().__init__(f"Idempotency record for operation '{operation}', key '{key}' is still in flight")
+
+
+class IdempotencyKeyReuseError(IdempotencyError):
+    """Raised when a key is reused for a request with a different fingerprint."""
+
+    def __init__(self, operation: str, key: str, stored_fingerprint: str, fingerprint: str) -> None:
+        self.operation = operation
+        self.key = key
+        self.stored_fingerprint = stored_fingerprint
+        self.fingerprint = fingerprint
+        super().__init__(
+            f"Idempotency key '{key}' for operation '{operation}' was used for a different request: "
+            f"stored fingerprint '{stored_fingerprint}', got '{fingerprint}'"
+        )

idempotency_kit-0.3.0/idempotency_kit/core/fingerprint.py

@@ -0,0 +1,22 @@
+"""The request fingerprint: what makes two calls under one key the same request."""
+
+import hashlib
+import json
+from typing import Any
+
+from pydantic_core import to_jsonable_python
+
+
+def fingerprint_of(**values: Any) -> str:
+    """Hash the named values into the fingerprint of a request.
+
+    Pydantic models, dataclasses, UUIDs, datetimes, Decimals and the JSON types are turned
+    into JSON-able Python first, keys are sorted, and the SHA-256 hex digest is returned, so
+    two equal payloads built in different orders agree. This is what ``async_idempotent``
+    computes from ``fingerprint_params``; a caller of ``coordinate()`` uses it directly.
+
+    Raises:
+        pydantic_core.PydanticSerializationError: a value has no JSON form
+    """
+    canonical = json.dumps(to_jsonable_python(values), sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()

{idempotency_kit-0.1.1 → idempotency_kit-0.3.0}/idempotency_kit/core/models/entities.py

@@ -1,7 +1,7 @@
 """Idempotency record entity."""
 
 from datetime import UTC, datetime, timedelta
-from typing import Annotated, Self
+from typing import Annotated, Literal, Self
 
 from pydantic import BaseModel, ConfigDict, Field, JsonValue, StringConstraints, field_validator
 
@@ -34,6 +34,10 @@ class IdempotencyRecord(IdempotencyIdentifiers):
 
     Stores the result of an operation so that repeated calls with the same key
     return the cached result without re-executing business logic.
+
+    A *pending* record is an in-flight reservation: the key is taken, the action is still
+    running, and the result is not there yet. It is written before the action and replaced
+    by the completed record after it; its ``expires_at`` is the lease.
     """
 
     model_config = ConfigDict(frozen=True)
@@ -45,6 +49,19 @@ class IdempotencyRecord(IdempotencyIdentifiers):
     created_at: datetime = Field(description="When this record was created")
     expires_at: datetime = Field(description="When this record should expire from cache")
 
+    # Records written before the field existed carry no status and read as completed.
+    status: Literal["pending", "completed"] = Field(
+        default="completed",
+        description="'pending' while the action runs under a reservation, 'completed' once the result is stored",
+    )
+
+    # What the caller said the request was; None means the record carries no fingerprint
+    # and a hit never raises for it.
+    fingerprint: str | None = Field(
+        default=None,
+        description="Fingerprint of the request the result belongs to; a hit with a different one is a key reuse",
+    )
+
     @classmethod
     def create(
         cls,
@@ -52,6 +69,7 @@ class IdempotencyRecord(IdempotencyIdentifiers):
         idempotency_key: str,
         result: JsonValue,
         ttl_seconds: float,
+        fingerprint: str | None = None,
     ) -> Self:
         """Create a new record with calculated expiration."""
         now = datetime.now(UTC)
@@ -61,8 +79,34 @@ class IdempotencyRecord(IdempotencyIdentifiers):
             result=result,
             created_at=now,
             expires_at=now + timedelta(seconds=ttl_seconds),
+            fingerprint=fingerprint,
         )
 
+    @classmethod
+    def pending(
+        cls,
+        operation: str,
+        idempotency_key: str,
+        lease_seconds: float,
+        fingerprint: str | None = None,
+    ) -> Self:
+        """Create the in-flight reservation for an action that is about to run."""
+        now = datetime.now(UTC)
+        return cls(
+            operation=operation,
+            idempotency_key=idempotency_key,
+            result=None,
+            created_at=now,
+            expires_at=now + timedelta(seconds=lease_seconds),
+            status="pending",
+            fingerprint=fingerprint,
+        )
+
+    @property
+    def is_pending(self) -> bool:
+        """Whether this record is an in-flight reservation rather than a stored result."""
+        return self.status == "pending"
+
     @property
     def is_expired(self) -> bool:
         """Check if the record has expired."""

{idempotency_kit-0.1.1 → idempotency_kit-0.3.0}/idempotency_kit/core/protocols/aio/repository.py

@@ -43,6 +43,22 @@ class AsyncIdempotencyRepository(Protocol):
         """
         ...
 
+    async def replace(self, record: IdempotencyRecord) -> None:
+        """Write a record whether or not the key is already there.
+
+        The coordinator completes an in-flight reservation with it: the pending record
+        under the key gives way to the final one.
+
+        Args:
+            record: Record to write
+
+        Raises:
+            IdempotencyValidationError: If record fails validation
+            IdempotencyStorageError: If storage operation fails
+            IdempotencyError: If internal error (e.g. serialization) occurs
+        """
+        ...
+
     async def delete(self, operation: str, idempotency_key: str) -> bool:
         """Delete an idempotency record.