ichido 0.1.0__py3-none-any.whl

ichido/__init__.py

@@ -0,0 +1,25 @@
+"""
+Ichido (一度) — "One Time"
+
+Stripe-inspired idempotency key middleware for FastAPI.
+Guarantees exactly-once processing for unsafe HTTP methods.
+
+Usage:
+    from ichido import IchidoMiddleware, IchidoConfig, RedisIdempotencyStore
+
+    app = FastAPI()
+    store = RedisIdempotencyStore(redis_client)
+    app.add_middleware(IchidoMiddleware, store=store)
+"""
+
+from ichido.config import IchidoConfig
+from ichido.middleware import IchidoMiddleware
+from ichido.storage import RedisIdempotencyStore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "IchidoMiddleware",
+    "IchidoConfig",
+    "RedisIdempotencyStore",
+]

ichido/config.py

@@ -0,0 +1,33 @@
+"""
+Configuration for the Ichido idempotency middleware.
+
+Design decision: Using a dataclass (not Pydantic BaseModel) because this is a
+library — we don't want to force a Pydantic dependency on users who might be
+using a different validation library. dataclass is stdlib, zero cost.
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class IchidoConfig:
+    """
+    Configuration for IchidoMiddleware.
+
+    Attributes:
+        header_name: HTTP header name for the idempotency key.
+            Default matches Stripe's convention.
+        ttl_seconds: How long to keep idempotency records in Redis.
+            24 hours matches Stripe's default. After expiry, the same key
+            can be reused for a new request.
+        enforce_methods: HTTP methods that require idempotency key processing.
+            GET, DELETE, HEAD are naturally idempotent — no need to enforce.
+            POST is the primary target. PATCH and PUT are included because
+            in payment APIs, these often have side effects (e.g., updating
+            a charge amount).
+    """
+
+    header_name: str = "Idempotency-Key"
+    ttl_seconds: int = 86400  # 24 hours
+    enforce_methods: tuple[str, ...] = ("POST", "PATCH", "PUT")
+    key_prefix: str = "ichido:"

ichido/exceptions.py

@@ -0,0 +1,50 @@
+"""
+Custom exceptions for Ichido.
+
+These are internal exceptions used by the middleware to communicate state
+between the storage layer and the middleware dispatch logic. They are NOT
+exposed to the end user — the middleware catches them and converts to
+appropriate HTTP responses.
+"""
+
+
+class IchidoError(Exception):
+    """Base exception for all Ichido errors."""
+
+    pass
+
+
+class FingerprintMismatchError(IchidoError):
+    """
+    Raised when an idempotency key is reused with a different request body.
+
+    This is a real bug class: a client accidentally reuses a key meant for
+    a different operation. Returning the cached response would be dangerous
+    (e.g., replaying a $10 charge response for a $1000 charge request).
+
+    The middleware converts this to a 422 Unprocessable Entity.
+    """
+
+    def __init__(self, key: str) -> None:
+        self.key = key
+        super().__init__(
+            f"Idempotency key '{key}' was already used with different "
+            f"request parameters. Each key must be used with identical requests."
+        )
+
+
+class RequestInProgressError(IchidoError):
+    """
+    Raised when a request with the same idempotency key is already being processed.
+
+    This is the concurrent-duplicate case — two identical requests arrive
+    before either finishes. The middleware converts this to a 409 Conflict
+    with a Retry-After header.
+    """
+
+    def __init__(self, key: str) -> None:
+        self.key = key
+        super().__init__(
+            f"A request with idempotency key '{key}' is currently being "
+            f"processed. Retry after the original request completes."
+        )

ichido/fingerprint.py

@@ -0,0 +1,82 @@
+"""
+Request fingerprinting for Ichido.
+
+The fingerprint uniquely identifies a request's *intent* — the combination of
+HTTP method, URL path, and request body. This is used to detect when a client
+reuses an idempotency key with a *different* request, which is a bug.
+
+Design decisions:
+- We include method + path in the fingerprint so that the same key used on
+  two different endpoints is detected as a mismatch (e.g., POST /charge vs
+  POST /refund with the same key).
+- We canonicalize JSON bodies (sorted keys, no extra whitespace) because
+  JSON serialization order is not guaranteed. {"a":1,"b":2} and {"b":2,"a":1}
+  are semantically identical and must produce the same fingerprint.
+- Non-JSON bodies are hashed as raw bytes — this is correct for form data,
+  binary uploads, etc.
+- We use SHA-256 because it's fast, collision-resistant, and available in
+  Python's stdlib. We don't need cryptographic strength here — we just need
+  to detect accidental mismatches, not adversarial collisions.
+"""
+
+import hashlib
+import json
+
+
+def canonicalize_body(body: bytes) -> bytes:
+    """
+    Canonicalize request body for consistent fingerprinting.
+
+    For JSON bodies: parse, sort keys recursively, re-serialize with no
+    extra whitespace. This ensures that {"a":1,"b":2} and {"b":2,"a":1}
+    produce the same fingerprint.
+
+    For non-JSON bodies: return as-is (raw bytes). This handles form data,
+    binary uploads, plain text, etc.
+
+    Args:
+        body: Raw request body bytes.
+
+    Returns:
+        Canonicalized body bytes.
+    """
+    if not body:
+        return b""
+
+    try:
+        parsed = json.loads(body)
+        # sort_keys=True handles nested dicts recursively
+        # separators=(',', ':') removes all optional whitespace
+        return json.dumps(parsed, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        # Not JSON — use raw bytes
+        return body
+
+
+def compute_fingerprint(method: str, path: str, body: bytes) -> str:
+    """
+    Compute a SHA-256 fingerprint of a request's identity.
+
+    The fingerprint captures what the request *does* — method + path + body.
+    Two requests with the same fingerprint are doing the same thing and can
+    safely share an idempotency key. Different fingerprints mean the key
+    is being reused for a different operation (a bug).
+
+    Args:
+        method: HTTP method (e.g., "POST").
+        path: URL path (e.g., "/payments/charge").
+        body: Raw request body bytes.
+
+    Returns:
+        Hex-encoded SHA-256 hash string.
+    """
+    canonical_body = canonicalize_body(body)
+
+    # Build the hash input: "POST:/payments/charge:" + body_bytes
+    # The colons are delimiters to prevent ambiguity (e.g., method "POS"
+    # with path "T/foo" vs method "POST" with path "/foo").
+    hasher = hashlib.sha256()
+    hasher.update(f"{method}:{path}:".encode("utf-8"))
+    hasher.update(canonical_body)
+
+    return hasher.hexdigest()

ichido/middleware.py

@@ -0,0 +1,344 @@
+"""
+Ichido ASGI middleware — the core idempotency logic.
+
+This is a pure ASGI middleware (not BaseHTTPMiddleware) for two reasons:
+1. Performance — BaseHTTPMiddleware spawns an anyio task per request and has
+   known issues under load ("Unexpected message received" errors).
+2. Control — we need to read the request body, potentially short-circuit the
+   response, and capture the downstream response body. Pure ASGI gives us
+   direct access to the receive/send channels.
+
+The middleware implements this state machine:
+
+    [No Key] ──SET NX──▶ [PROCESSING] ──handler done──▶ [COMPLETED]
+                              │                              │
+                         2nd request                    2nd request
+                              │                              │
+                         409 Conflict                  Replay response
+
+On handler failure: DELETE key (allow retry).
+On fingerprint mismatch: 422 Unprocessable Entity.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+from typing import Callable
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from ichido.config import IchidoConfig
+from ichido.fingerprint import compute_fingerprint
+from ichido.storage import RedisIdempotencyStore
+
+logger = logging.getLogger("ichido")
+
+
+class IchidoMiddleware:
+    """
+    ASGI middleware that enforces idempotency key semantics.
+
+    Usage:
+        from fastapi import FastAPI
+        from ichido import IchidoMiddleware, RedisIdempotencyStore
+        import redis.asyncio as aioredis
+
+        app = FastAPI()
+        redis_client = aioredis.from_url("redis://localhost:6379")
+        store = RedisIdempotencyStore(redis_client)
+        app.add_middleware(IchidoMiddleware, store=store)
+
+    Args:
+        app: The ASGI application to wrap.
+        store: A RedisIdempotencyStore instance for persistence.
+        config: Optional IchidoConfig for customization.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        store: RedisIdempotencyStore,
+        config: IchidoConfig | None = None,
+    ) -> None:
+        self.app = app
+        self.store = store
+        self.config = config or IchidoConfig()
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """ASGI entry point — dispatch HTTP requests, pass through everything else."""
+        # Only process HTTP requests. WebSocket, lifespan, etc. pass through.
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        request = Request(scope)
+        method = request.method.upper()
+
+        # Only enforce on unsafe methods (POST, PATCH, PUT by default)
+        if method not in self.config.enforce_methods:
+            await self.app(scope, receive, send)
+            return
+
+        # Extract idempotency key from header
+        idempotency_key = request.headers.get(self.config.header_name)
+
+        # No key provided — pass through without idempotency enforcement.
+        # Some APIs require the key; we chose to make it optional because
+        # forcing it would break clients that don't know about idempotency.
+        # You could make this strict by returning 400 here instead.
+        if not idempotency_key:
+            await self.app(scope, receive, send)
+            return
+
+        # --- Read the full request body ---
+        # ASGI request bodies are streams. We consume the full body here
+        # so we can compute the fingerprint, then replay it to the handler.
+        body = await self._read_body(receive)
+
+        # Compute request fingerprint
+        fingerprint = compute_fingerprint(method, request.url.path, body)
+
+        # --- State machine: try to acquire the key ---
+        acquired = await self.store.try_acquire(idempotency_key, fingerprint)
+
+        if acquired:
+            # We own this key — process the request and cache the response
+            await self._process_and_cache(
+                scope, body, send, idempotency_key, fingerprint
+            )
+        else:
+            # Key already exists — check state
+            await self._handle_existing_key(
+                scope, send, idempotency_key, fingerprint
+            )
+
+    async def _read_body(self, receive: Receive) -> bytes:
+        """
+        Consume the full request body from the ASGI receive channel.
+
+        ASGI delivers the body in chunks via receive() calls. Each chunk
+        has a "body" field and a "more_body" flag. We accumulate all chunks.
+        """
+        chunks: list[bytes] = []
+        while True:
+            message = await receive()
+            chunks.append(message.get("body", b""))
+            if not message.get("more_body", False):
+                break
+        return b"".join(chunks)
+
+    async def _process_and_cache(
+        self,
+        scope: Scope,
+        body: bytes,
+        send: Send,
+        idempotency_key: str,
+        fingerprint: str,
+    ) -> None:
+        """
+        Forward the request to the handler, capture the response, cache it.
+
+        If the handler raises an exception, we DELETE the key from Redis
+        so the client can retry. This is critical — without it, the key
+        would be stuck in "processing" state until TTL expiry.
+        """
+        # Create a replay receive function — we consumed the original stream,
+        # so the downstream handler would get an empty body without this.
+        body_sent = False
+
+        async def replay_receive() -> Message:
+            nonlocal body_sent
+            if not body_sent:
+                body_sent = True
+                return {"type": "http.request", "body": body, "more_body": False}
+            # After the body has been sent, return a disconnect message
+            # if receive is called again (handles edge cases)
+            return {"type": "http.disconnect"}
+
+        # Capture the response as the handler sends it
+        response_started = False
+        response_status: int = 500
+        response_headers: list[tuple[bytes, bytes]] = []
+        response_body_parts: list[bytes] = []
+
+        async def capture_send(message: Message) -> None:
+            nonlocal response_started, response_status, response_headers
+
+            if message["type"] == "http.response.start":
+                response_started = True
+                response_status = message["status"]
+                response_headers = list(message.get("headers", []))
+
+                # Inject a header to indicate first-time processing
+                # (not a replay). This is useful for debugging.
+                response_headers.append(
+                    (b"x-ichido-status", b"executed")
+                )
+                message = {
+                    **message,
+                    "headers": response_headers,
+                }
+
+            elif message["type"] == "http.response.body":
+                response_body_parts.append(message.get("body", b""))
+
+            # Forward to the actual client
+            await send(message)
+
+        try:
+            await self.app(scope, replay_receive, capture_send)
+        except Exception:
+            # Handler crashed — delete the key so the client can retry
+            logger.warning(
+                "Handler raised exception for idempotency key '%s'. "
+                "Deleting key to allow retry.",
+                idempotency_key,
+            )
+            await self.store.delete_key(idempotency_key)
+            raise  # Re-raise so FastAPI's exception handlers can deal with it
+
+        # Cache the response only if handler succeeded (2xx or 4xx client errors).
+        # We cache all responses, not just 2xx, because the client might retry
+        # after a 400 Bad Request and should get the same 400 back (deterministic).
+        full_body = b"".join(response_body_parts)
+        headers_dict = {
+            k.decode("utf-8"): v.decode("utf-8") for k, v in response_headers
+        }
+
+        await self.store.mark_completed(
+            idempotency_key=idempotency_key,
+            fingerprint=fingerprint,
+            response_status=response_status,
+            response_headers=headers_dict,
+            response_body=base64.b64encode(full_body).decode("ascii"),
+        )
+
+        logger.info(
+            "Cached response for idempotency key '%s' (status=%d)",
+            idempotency_key,
+            response_status,
+        )
+
+    async def _handle_existing_key(
+        self,
+        scope: Scope,
+        send: Send,
+        idempotency_key: str,
+        fingerprint: str,
+    ) -> None:
+        """
+        Handle a request whose idempotency key already exists in the store.
+
+        Three possible outcomes:
+        1. Key is "completed" + fingerprint matches → replay cached response.
+        2. Key is "completed" + fingerprint differs → 422 (key reused with different request).
+        3. Key is "processing" → 409 Conflict (concurrent duplicate).
+        """
+        record = await self.store.get_record(idempotency_key)
+
+        if record is None:
+            # Race condition: key existed when we tried SET NX, but was deleted
+            # (TTL expired or handler errored) before we could GET it.
+            # Return 409 and let the client retry — they'll get a fresh slot.
+            response = JSONResponse(
+                status_code=409,
+                content={
+                    "error": "conflict",
+                    "message": "Idempotency key state is inconsistent. Please retry.",
+                },
+                headers={"Retry-After": "1"},
+            )
+            await response(scope, _noop_receive, send)
+            return
+
+        # --- Check fingerprint first (applies to both processing and completed) ---
+        if record.fingerprint != fingerprint:
+            logger.warning(
+                "Fingerprint mismatch for idempotency key '%s'. "
+                "Key is being reused with a different request body.",
+                idempotency_key,
+            )
+            response = JSONResponse(
+                status_code=422,
+                content={
+                    "error": "fingerprint_mismatch",
+                    "message": (
+                        f"Idempotency key '{idempotency_key}' was already used "
+                        f"with different request parameters. Each key must be "
+                        f"used with identical requests."
+                    ),
+                },
+            )
+            await response(scope, _noop_receive, send)
+            return
+
+        # --- Key is still processing (concurrent duplicate) ---
+        if record.status == "processing":
+            logger.info(
+                "Concurrent duplicate detected for idempotency key '%s'. "
+                "Returning 409 Conflict.",
+                idempotency_key,
+            )
+            response = JSONResponse(
+                status_code=409,
+                content={
+                    "error": "request_in_progress",
+                    "message": (
+                        f"A request with idempotency key '{idempotency_key}' "
+                        f"is currently being processed. Please retry later."
+                    ),
+                },
+                headers={"Retry-After": "1"},
+            )
+            await response(scope, _noop_receive, send)
+            return
+
+        # --- Key is completed — replay the cached response ---
+        if record.status == "completed":
+            logger.info(
+                "Replaying cached response for idempotency key '%s' (status=%d)",
+                idempotency_key,
+                record.response_status,
+            )
+
+            response_body = base64.b64decode(record.response_body)
+
+            # Rebuild the headers, adding our replay marker
+            headers: dict[str, str] = dict(record.response_headers or {})
+            headers["x-ichido-status"] = "replayed"
+
+            response = Response(
+                content=response_body,
+                status_code=record.response_status or 200,
+                headers=headers,
+            )
+            await response(scope, _noop_receive, send)
+            return
+
+        # Unknown status — should never happen, but be defensive
+        logger.error(
+            "Unknown status '%s' for idempotency key '%s'",
+            record.status,
+            idempotency_key,
+        )
+        response = JSONResponse(
+            status_code=500,
+            content={
+                "error": "internal_error",
+                "message": "Idempotency key record is in an unexpected state.",
+            },
+        )
+        await response(scope, _noop_receive, send)
+
+
+async def _noop_receive() -> Message:
+    """
+    A no-op receive function for sending responses without a real receive channel.
+
+    Used when we're short-circuiting the request (replaying cached response
+    or returning an error) and don't need to read any request body.
+    """
+    return {"type": "http.disconnect"}

ichido/storage.py

@@ -0,0 +1,197 @@
+"""
+Redis-backed storage for idempotency records.
+
+This module abstracts all Redis interactions behind a clean interface.
+The key design principle: every state transition must be atomic.
+
+Why an abstraction layer instead of calling Redis directly in the middleware?
+1. Testability — we can swap in fakeredis for unit tests.
+2. Future-proofing — adding a Postgres backend later just means implementing
+   the same interface.
+3. Separation of concerns — the middleware handles HTTP logic, the store
+   handles persistence logic.
+
+Redis key lifecycle:
+  SET NX EX → key created with "processing" state and TTL
+  SET EX    → key updated to "completed" with response data (TTL refreshed)
+  DEL       → key removed on handler failure (allows retry)
+  [TTL expires] → key auto-cleaned by Redis
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import redis.asyncio as aioredis
+
+
+@dataclass(frozen=True)
+class IdempotencyRecord:
+    """
+    An idempotency record stored in Redis.
+
+    Attributes:
+        status: Either "processing" (handler in-flight) or "completed" (response cached).
+        fingerprint: SHA-256 hash of the original request (method + path + body).
+        response_status: HTTP status code of the cached response (None while processing).
+        response_headers: HTTP headers of the cached response (None while processing).
+        response_body: Raw response body bytes, base64-encoded in Redis (None while processing).
+    """
+
+    status: str
+    fingerprint: str
+    response_status: int | None = None
+    response_headers: dict[str, str] | None = None
+    response_body: str | None = None  # base64-encoded
+
+    def to_json(self) -> str:
+        """Serialize to JSON for Redis storage."""
+        return json.dumps(
+            {
+                "status": self.status,
+                "fingerprint": self.fingerprint,
+                "response_status": self.response_status,
+                "response_headers": self.response_headers,
+                "response_body": self.response_body,
+            }
+        )
+
+    @classmethod
+    def from_json(cls, raw: str) -> IdempotencyRecord:
+        """Deserialize from Redis JSON string."""
+        data = json.loads(raw)
+        return cls(
+            status=data["status"],
+            fingerprint=data["fingerprint"],
+            response_status=data.get("response_status"),
+            response_headers=data.get("response_headers"),
+            response_body=data.get("response_body"),
+        )
+
+
+class RedisIdempotencyStore:
+    """
+    Redis-backed store for idempotency records.
+
+    Thread-safety: redis-py's async client is safe for concurrent use
+    from multiple asyncio tasks — each command is an independent round-trip.
+
+    Args:
+        redis_client: An async Redis client instance.
+        prefix: Key prefix for namespacing (default: "ichido:").
+        ttl: Time-to-live in seconds for idempotency records (default: 24h).
+    """
+
+    def __init__(
+        self,
+        redis_client: aioredis.Redis,
+        prefix: str = "ichido:",
+        ttl: int = 86400,
+    ) -> None:
+        self.redis = redis_client
+        self.prefix = prefix
+        self.ttl = ttl
+
+    def _make_key(self, idempotency_key: str) -> str:
+        """Build the full Redis key with prefix."""
+        return f"{self.prefix}{idempotency_key}"
+
+    async def try_acquire(self, idempotency_key: str, fingerprint: str) -> bool:
+        """
+        Atomically try to claim an idempotency key.
+
+        Uses Redis SET with NX (only if not exists) and EX (with TTL) in a
+        single atomic command. This is the core concurrency primitive:
+
+        - If the key doesn't exist: creates it with status="processing" → returns True.
+        - If the key already exists: does nothing → returns False.
+
+        No race condition is possible between two concurrent calls because
+        SET NX is atomic at the Redis server level.
+
+        Args:
+            idempotency_key: The client-provided idempotency key.
+            fingerprint: SHA-256 fingerprint of the request.
+
+        Returns:
+            True if the key was newly created (caller should process the request).
+            False if the key already existed (caller should check state and act).
+        """
+        record = IdempotencyRecord(status="processing", fingerprint=fingerprint)
+
+        result = await self.redis.set(
+            name=self._make_key(idempotency_key),
+            value=record.to_json(),
+            nx=True,  # Only set if Not eXists
+            ex=self.ttl,  # Auto-expire after TTL
+        )
+
+        # redis-py returns True if SET succeeded, None if key already existed
+        return result is not None
+
+    async def get_record(self, idempotency_key: str) -> IdempotencyRecord | None:
+        """
+        Retrieve the idempotency record for a key.
+
+        Args:
+            idempotency_key: The client-provided idempotency key.
+
+        Returns:
+            The IdempotencyRecord if found, None if the key doesn't exist
+            (or has expired).
+        """
+        raw = await self.redis.get(self._make_key(idempotency_key))
+        if raw is None:
+            return None
+        return IdempotencyRecord.from_json(raw)
+
+    async def mark_completed(
+        self,
+        idempotency_key: str,
+        fingerprint: str,
+        response_status: int,
+        response_headers: dict[str, str],
+        response_body: str,
+    ) -> None:
+        """
+        Update a key's record to "completed" with the cached response.
+
+        This overwrites the "processing" record. We use SET with EX (not NX)
+        to refresh the TTL — the 24-hour window starts from when the response
+        was stored, not when the request was received.
+
+        Args:
+            idempotency_key: The client-provided idempotency key.
+            fingerprint: The original request fingerprint (preserved).
+            response_status: HTTP status code to cache.
+            response_headers: HTTP headers to cache.
+            response_body: Response body to cache (base64-encoded).
+        """
+        record = IdempotencyRecord(
+            status="completed",
+            fingerprint=fingerprint,
+            response_status=response_status,
+            response_headers=response_headers,
+            response_body=response_body,
+        )
+
+        await self.redis.set(
+            name=self._make_key(idempotency_key),
+            value=record.to_json(),
+            ex=self.ttl,  # Refresh TTL
+        )
+
+    async def delete_key(self, idempotency_key: str) -> None:
+        """
+        Remove an idempotency key from the store.
+
+        Called when the handler raises an exception — we delete the key so
+        the client can safely retry. If we didn't delete it, the key would
+        be stuck in "processing" state until TTL expiry, blocking retries.
+
+        Args:
+            idempotency_key: The client-provided idempotency key.
+        """
+        await self.redis.delete(self._make_key(idempotency_key))

ichido-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akhil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ichido-0.1.0.dist-info/METADATA

@@ -0,0 +1,317 @@
+Metadata-Version: 2.2
+Name: ichido
+Version: 0.1.0
+Summary: Stripe-inspired idempotency key middleware for FastAPI — exactly-once request processing.
+Author: Akhil
+License: MIT
+Project-URL: Homepage, https://github.com/akhil/ichido
+Project-URL: Repository, https://github.com/akhil/ichido
+Project-URL: Issues, https://github.com/akhil/ichido/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: redis>=5.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: fakeredis>=2.21; extra == "dev"
+Requires-Dist: uvicorn>=0.30; extra == "dev"
+
+# Ichido (一度) — "One Time"
+
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-009688.svg)](https://fastapi.tiangolo.com)
+[![Redis](https://img.shields.io/badge/Redis-5.0%2B-red.svg)](https://redis.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Ichido** is a drop-in, production-grade idempotency key middleware for **FastAPI**, backed by **Redis**. It guarantees exactly-once processing on unsafe HTTP endpoints (like payments, charge actions, or refunds) by ensuring retry requests with the same idempotency key are safely replayed or gracefully throttled.
+
+It implements the core idempotency specifications used by leading API platforms like **Stripe** and **Razorpay**.
+
+---
+
+## 💡 Why Ichido? (Motivation & Business Value)
+
+In distributed systems, the network is fundamentally unreliable. When a client makes an API request (e.g., to charge a credit card) and the network drops before the server can return a response, the client is left in an ambiguous state: **Did the payment succeed or fail?**
+
+To recover, the client must retry the request. However, naive retries on non-idempotent endpoints (like `POST /charges`) lead to the **double-charging problem** (charging a user twice for a single order).
+
+```
+[ Client ] ───────── POST /charge ─────────► [ Server ] (Processes payment successfully)
+[ Client ] ◄─── (Network drops / Timeout) ─── [ Server ] (Response lost)
+                  
+            *Client retries the request*
+            
+[ Client ] ───────── POST /charge ─────────► [ Server ] (Processes payment AGAIN - Double Charge!)
+```
+
+### The Solution: Exactly-Once Semantics
+**Ichido** intercepts retry requests before they execute any business logic. By deduplicating requests on the server side using a unique client-generated header token (`Idempotency-Key`), it achieves **effectively-exactly-once execution**:
+
+- **Card Charge Protection**: Prevents duplicate financial transactions, keeping disputes and chargebacks low.
+- **Resource Protection**: Stops redundant database writes and expensive third-party API executions (e.g., mail sending, billing endpoints).
+- **Robust Client Retry Loops**: Allows client software to safely retry requests aggressively with exponential backoff, without developers having to implement complex transaction checks manually at the application layer.
+
+---
+
+## 🏗️ Architecture & State Machine
+
+```
+              Client Request (Idempotency-Key)
+                            │
+                            ▼
+              Atomically claim key (SET NX EX)
+               /                            \
+        [Lock Acquired]               [Key Already Exists]
+             /                                \
+            ▼                                  ▼
+      State: PROCESSING                 Get stored record
+            │                          /                 \
+    Run endpoint logic        State: PROCESSING     State: COMPLETED
+            │                        │                        │
+       [Completion]           Return 409 Conflict    Compare fingerprint
+      /            \          (Retry-After: 1)       /                 \
+  Success         Failure                          Match             Mismatch
+    /                \                              /                     \
+Update to          DELETE key                      ▼                       ▼
+COMPLETED        (Allow retry)               Replay cached         Return 422 Error
+with response                                  response            (Key reused for
+                                                                   different body)
+```
+
+### Redis Record JSON Schema
+Each record is serialized to JSON and stored with a namespace prefix (`ichido:`). When in the `completed` state, the response body is stored using base64 encoding to support binary and text payloads cleanly.
+
+```json
+{
+  "status": "processing" | "completed",
+  "fingerprint": "sha256_hash_value",
+  "response_status": 200,
+  "response_headers": {
+    "content-type": "application/json",
+    "x-custom-header": "value"
+  },
+  "response_body": "eyJhIjoxLCJiIjoyfQ==" // Base64 encoded payload
+}
+```
+
+---
+
+## 🛠️ File Structure
+
+```
+Ichido-Idempotency/
+├── pyproject.toml              # Package config and metadata
+├── LICENSE                     # MIT license
+├── README.md                   # You are here
+├── src/
+│   └── ichido/
+│       ├── __init__.py         # Public exports (Middleware, Config, Store)
+│       ├── config.py           # Frozen configuration dataclass
+│       ├── exceptions.py       # Library internal exceptions
+│       ├── fingerprint.py      # Request body canonicalizer & SHA256 hasher
+│       ├── middleware.py       # Pure ASGI middleware handling request/response flows
+│       └── storage.py          # Redis connection client wrapper & record schema
+├── tests/
+│   ├── conftest.py             # pytest setup with mock FastAPI & fakeredis client
+│   ├── test_concurrency.py      # Multi-task concurrent execution tests
+│   ├── test_fingerprint.py      # JSON sorting & fingerprint verification
+│   ├── test_middleware.py       # Standard request lifecycle tests
+│   └── test_storage.py          # Redis store serialization tests
+└── examples/
+    ├── demo_app.py             # Runnable local FastAPI server with fallback support
+    └── demo_concurrent.py      # Client script firing concurrent/sequential request scenarios
+```
+
+---
+
+## ⚙️ Configuration Reference
+
+Use `IchidoConfig` to customize the middleware's behavior:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `header_name` | `str` | `"Idempotency-Key"` | The HTTP request header checked by the middleware. |
+| `ttl_seconds` | `int` | `86400` (24 Hours) | Time-to-Live in seconds for the cached responses in Redis. |
+| `enforce_methods` | `tuple[str, ...]` | `("POST", "PATCH", "PUT")` | HTTP methods that will run through the idempotency filter. GET/DELETE are naturally idempotent. |
+| `key_prefix` | `str` | `"ichido:"` | Namespace prefix prepended to all Redis keys to avoid collisions. |
+
+---
+
+## 🚀 Quick Start
+
+### 1. Installation
+
+Install the package directly in editable development mode:
+
+```bash
+pip install -e ".[dev]"
+```
+
+### 2. Basic Integration
+
+```python
+import redis.asyncio as aioredis
+from fastapi import FastAPI
+from ichido import IchidoMiddleware, RedisIdempotencyStore, IchidoConfig
+
+app = FastAPI()
+
+# 1. Initialize Redis connection pool
+redis_client = aioredis.from_url("redis://localhost:6379/0", decode_responses=True)
+
+# 2. Setup the idempotency storage backend
+store = RedisIdempotencyStore(redis_client=redis_client, ttl=86400)
+
+# 3. Add the middleware to FastAPI
+app.add_middleware(
+    IchidoMiddleware,
+    store=store,
+    config=IchidoConfig(
+        header_name="Idempotency-Key",
+        ttl_seconds=86400 # 24 Hours
+    )
+)
+
+@app.post("/payments/charge")
+async def process_payment(amount: float):
+    # This logic is guaranteed to execute exactly once for any unique Idempotency-Key header.
+    return {"status": "success", "charge_id": "ch_12345"}
+```
+
+---
+
+## 🧪 Testing & Live Demo
+
+Ichido includes an automated suite and an end-to-end sandbox application.
+
+### Running Unit Tests
+
+To run the unit tests (which automatically mock Redis using `fakeredis`):
+
+```bash
+python -m pytest tests/ -v
+```
+
+---
+
+### Running the Live Sandbox Demo
+
+You can run the live demo either locally (via a mock store) or connected to a **free Cloud Redis** provider (like Upstash).
+
+#### Option A: Zero Configuration (In-Memory Mock)
+If you don't have Redis installed, the demo app will automatically fall back to an in-memory `fakeredis` database.
+
+1. **Start the API Server**:
+   ```bash
+   uvicorn examples.demo_app:app --port 8000 --reload
+   ```
+2. **Execute the Simulator Client** in another terminal:
+   ```bash
+   python examples.demo_concurrent.py
+   ```
+
+#### Option B: Connected to a Cloud Redis Server (e.g. Upstash)
+1. Go to [Upstash](https://console.upstash.com/) and create a free serverless database.
+2. Copy the connection string under **Redis URL** (`rediss://default:...`).
+3. **Start the API Server** with the environment variable set:
+   ```bash
+   # Windows PowerShell
+   $env:REDIS_URL="rediss://default:yourpassword@your-endpoint.upstash.io:6379"
+   uvicorn examples.demo_app:app --port 8000 --reload
+   ```
+4. **Execute the Simulator Client**:
+   ```bash
+   python examples.demo_concurrent.py
+   ```
+
+---
+
+### Expected Console Output Trace
+
+When executing `demo_concurrent.py`, the client output demonstrates the state transitions:
+
+```text
+======================================================================
+DEMO 1: CONCURRENT DUPLICATE REQUESTS (State: PROCESSING)
+Idempotency Key: 2391c028-804f-460f-b1f2-1e3e4110b127
+Firing 2 requests simultaneously. The server takes ~2.5s to process...
+======================================================================
+
+Response #1:
+  Status Code: 200
+  Headers:
+    X-Ichido-Status: executed
+    Retry-After: None
+  Body: {"status":"success","transaction_id":"tx_2fc0df1b420d","amount_charged":49.99,"currency":"USD","msg":"Payment processed successfully."}
+
+Response #2:
+  Status Code: 409
+  Headers:
+    X-Ichido-Status: None
+    Retry-After: 1
+  Body: {"error":"request_in_progress","message":"A request with idempotency key '2391c028-804f-460f-b1f2-1e3e4110b127' is currently being processed.Please retry later."}
+
+======================================================================
+DEMO 2: REPLAYED REQUEST (State: COMPLETED)
+Firing a 3rd request with the SAME key and SAME body...
+======================================================================
+
+Response #3 (Replayed):
+  Status Code: 200
+  Headers:
+    X-Ichido-Status: replayed
+  Body: {"status":"success","transaction_id":"tx_2fc0df1b420d","amount_charged":49.99,"currency":"USD","msg":"Payment processed successfully."}
+
+======================================================================
+DEMO 3: REQUEST PARAMETER MISMATCH (State: COMPLETED, Different Body)
+Firing a 4th request with the SAME key but a DIFFERENT amount ($99.99)...
+======================================================================
+
+Response #4 (Mismatch):
+  Status Code: 422
+  Body: {"error":"fingerprint_mismatch","message":"Idempotency key '2391c028-804f-460f-b1f2-1e3e4110b127' was already used with different request parameters. Each key must be used with identical requests."}
+```
+
+---
+
+## 💡 Interview Q&A / Architecture Defense
+
+Be ready to explain these core distributed systems design decisions:
+
+### 1. Why Redis instead of PostgreSQL for Idempotency?
+- **Speed**: Idempotency checks sit in the critical hot path of payments APIs. Redis is an in-memory datastore that offers sub-millisecond lookups. 
+- **Auto Expiration**: Redis provides built-in Time-to-Live (TTL) key expiration natively. Relational databases require custom cron tasks, worker scripts, or database trigger cleanups to delete outdated idempotency keys.
+- **Atomic Operations**: Redis executes commands single-threaded, allowing us to perform atomic `SET NX EX` locks in a single roundtrip.
+- **Tradeoff**: Redis is not durable. If a node crashes, in-flight keys are lost. In a massive scale production payments app, you would use Redis for the fast concurrency lock and short-term caching, backed by a persistent relational database (Postgres) as the source-of-truth for completed transactions.
+
+### 2. How is the concurrent duplicate request problem solved?
+- When two identical requests with the same key arrive simultaneously, both attempt a Redis `SET key value NX EX TTL`.
+- Exactly one request succeeds (receiving the lock) and proceeds to run the downstream endpoint logic, setting the state to `processing`.
+- The second request fails to write the key, reads the current state as `processing`, and immediately aborts, returning `409 Conflict` with a `Retry-After: 1` header.
+- **Tradeoff vs. Polling**: We return `409` instead of holding the second connection open and polling. Holding connections open consumes web server threads/workers. Under load, this could exhaust the worker pool and lead to a server-wide denial of service. Pushing the retry logic to the client is significantly more resilient.
+
+### 3. Why did you choose pure ASGI middleware instead of Starlette's `BaseHTTPMiddleware`?
+- Starlette's `BaseHTTPMiddleware` wraps requests in separate background threads using `anyio`. This adds substantial latency overhead, triggers memory leaks, and causes socket disconnect errors under high-concurrency request streams.
+- Pure ASGI middleware directly implements `__call__(scope, receive, send)`. This gives us raw access to ASGI request streams and response chunks without threading overhead, which is critical for high-throughput gateway services.
+
+### 4. What is At-Least-Once vs. Exactly-Once processing?
+- **At-Least-Once**: The network is unreliable. If a request times out, the client retries. Without server-side deduplication, this results in duplicate side effects (e.g. charging a card twice).
+- **Exactly-Once**: Combining client-side retries (At-Least-Once delivery) with server-side deduplication (using idempotency keys) achieves **Exactly-Once** execution. The action occurs exactly once, even if the request was sent multiple times.
+
+---
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for details.

ichido-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ichido/__init__.py,sha256=Xl1hRwgGpH4HM9g6sR4FsLsujwSUV5SanM114Rhik04,611
+ichido/config.py,sha256=W33_H1P5CnCIYpGm3zxm0wfqzv6syiCDzuowE9lnFrs,1266
+ichido/exceptions.py,sha256=fLckw6WwjoqaVipGwuVZ9khyi2Nsxb2tB6oeqeZyVuo,1635
+ichido/fingerprint.py,sha256=UCQYaUjzCweBs8YGYeAUaUQNna-N3Ligkd8XK2ednL4,2978
+ichido/middleware.py,sha256=fPtdMN61yloEse2zv6eTFw17m2kljwieYWqdMiwBDqY,13047
+ichido/storage.py,sha256=njOfZrC5y7h2jQI9p2NGmhbE_8BEwDXJAW6l_IUh6aY,7026
+ichido-0.1.0.dist-info/LICENSE,sha256=FZJj4Jg7ad6E9QqB4H5n1Wy2dvtddwh2Bg5ja08DUFg,1062
+ichido-0.1.0.dist-info/METADATA,sha256=OT0P3xZKwEJAnh6ZpjC4YiwZ766STvgueBP2mQ3t8FE,15297
+ichido-0.1.0.dist-info/WHEEL,sha256=beeZ86-EfXScwlR_HKu4SllMC9wUEj_8Z_4FJ3egI2w,91
+ichido-0.1.0.dist-info/top_level.txt,sha256=hC5WMlHxYFpWm6QVz2jQ3QFxDF4H2p8bRTJZlxGraIE,7
+ichido-0.1.0.dist-info/RECORD,,

ichido-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (76.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ichido-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ichido