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

{idempotency_kit-0.2.0 → idempotency_kit-0.3.0}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: idempotency-kit
-Version: 0.2.0
+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/
@@ -260,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
@@ -343,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
 

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

@@ -27,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
@@ -110,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
 

{idempotency_kit-0.2.0 → 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/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.2.0 → idempotency_kit-0.3.0}/idempotency_kit/core/decorators/aio/idempotent.py

@@ -4,6 +4,7 @@ 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
 
@@ -26,12 +27,40 @@ def _positional_index(func: Callable[..., Any], key_param: str) -> int | None:
     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.
 
@@ -48,10 +77,15 @@ def async_idempotent(
             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:
@@ -78,6 +112,8 @@ def async_idempotent(
                 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,

{idempotency_kit-0.2.0 → 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.2.0 → 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.2.0 → 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.