idemkit 0.1.0__py3-none-any.whl

idemkit/cli.py

@@ -0,0 +1,165 @@
+"""idemkit command-line interface.
+
+Commands:
+    idemkit init-pg <database-url>      Create idemkit_records table + indexes.
+    idemkit pg-vacuum <database-url>    Delete expired records.
+    idemkit conformance [--redis URL] [--postgres URL] [--mongo URL] [--dynamodb ENDPOINT]
+                                       Run the shared-core conformance vectors
+                                       against InMemory (always) and any backend
+                                       whose URL is given. Exits non-zero on any
+                                       failure.
+
+``init-pg`` and ``pg-vacuum`` are idempotent and safe to re-run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+
+def _make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="idemkit",
+        description="idemkit operational tooling (schema migration, vacuum).",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init_pg = sub.add_parser(
+        "init-pg",
+        help="Create the records table and indexes (idempotent).",
+    )
+    init_pg.add_argument("database_url", help="postgres:// URL.")
+    init_pg.add_argument(
+        "--table",
+        default="idemkit_records",
+        help="Records table name (default: idemkit_records).",
+    )
+
+    vacuum = sub.add_parser(
+        "pg-vacuum",
+        help="Delete expired records from the table.",
+    )
+    vacuum.add_argument("database_url", help="postgres:// URL.")
+    vacuum.add_argument(
+        "--table",
+        default="idemkit_records",
+        help="Records table name (default: idemkit_records).",
+    )
+    vacuum.add_argument(
+        "--expires-after-seconds",
+        type=float,
+        default=86_400.0,
+        help="Records COMPLETED before (now - this) are deleted (default: 24h).",
+    )
+    vacuum.add_argument(
+        "--lease-grace-seconds",
+        type=float,
+        default=60.0,
+        help="CLAIMED records with lease_until + grace < now are deleted (default: 60s).",
+    )
+
+    conformance = sub.add_parser(
+        "conformance",
+        help="Run the shared-core conformance vectors against backends.",
+    )
+    conformance.add_argument("--redis", help="redis:// URL to also run the vectors against.")
+    conformance.add_argument("--postgres", help="postgres:// URL to also run the vectors against.")
+    conformance.add_argument("--mongo", help="mongodb:// URL to also run the vectors against.")
+    conformance.add_argument(
+        "--dynamodb",
+        metavar="ENDPOINT",
+        help=(
+            "DynamoDB endpoint URL to also run the vectors against (e.g. "
+            "http://localhost:8000 for DynamoDB Local; credentials and region come "
+            "from the environment)."
+        ),
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _make_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "init-pg":
+        from idemkit.backends.postgres import init_pg
+
+        asyncio.run(init_pg(args.database_url, table=args.table))
+        print("idemkit: PostgreSQL schema initialized")
+        return 0
+
+    if args.command == "pg-vacuum":
+        from idemkit.backends.postgres import pg_vacuum
+
+        n = asyncio.run(
+            pg_vacuum(
+                args.database_url,
+                table=args.table,
+                expires_after_seconds=args.expires_after_seconds,
+                lease_grace_seconds=args.lease_grace_seconds,
+            )
+        )
+        print(f"idemkit: vacuumed {n} expired record(s)")
+        return 0
+
+    if args.command == "conformance":
+        return asyncio.run(_run_conformance(args.redis, args.postgres, args.mongo, args.dynamodb))
+
+    parser.print_help()
+    return 2
+
+
+async def _run_conformance(
+    redis_url: str | None,
+    postgres_url: str | None,
+    mongo_url: str | None = None,
+    dynamodb_endpoint: str | None = None,
+) -> int:
+    """Run the conformance suite against InMemory plus any configured backend."""
+    from idemkit.backends.memory import InMemoryBackend
+    from idemkit.conformance import BackendConformance
+
+    all_passed = True
+
+    async def _run(backend: object, aclose: bool) -> None:
+        nonlocal all_passed
+        report = await BackendConformance(backend).run()  # type: ignore[arg-type]
+        print(report.report())
+        if not report.passed:
+            all_passed = False
+        if aclose and hasattr(backend, "aclose"):
+            await backend.aclose()
+
+    await _run(InMemoryBackend(), aclose=False)
+
+    if redis_url:
+        from idemkit.backends.redis import RedisBackend
+
+        await _run(RedisBackend.from_url(redis_url), aclose=True)
+
+    if postgres_url:
+        from idemkit.backends.postgres import PostgresBackend, init_pg
+
+        await init_pg(postgres_url)
+        await _run(PostgresBackend.from_url(postgres_url), aclose=True)
+
+    if mongo_url:
+        from idemkit.backends.mongo import MongoBackend
+
+        await _run(MongoBackend.from_url(mongo_url), aclose=True)
+
+    if dynamodb_endpoint:
+        from idemkit.backends.dynamodb import DynamoBackend
+
+        await _run(DynamoBackend(endpoint_url=dynamodb_endpoint), aclose=True)
+
+    print()
+    print("idemkit: conformance PASSED" if all_passed else "idemkit: conformance FAILED")
+    return 0 if all_passed else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

idemkit/conformance/__init__.py

@@ -0,0 +1,25 @@
+"""idemkit conformance suite — a public, reusable correctness standard (spec §11.1).
+
+The shared-core vectors (atomic claim, fencing, lease reclaim, in-flight wait,
+TTL expiry, lease renewal) packaged so ANY library whose backend implements the
+``IdempotencyBackend`` Protocol can validate itself against them, in or out of
+idemkit. This is the artifact §11.1 calls for: a correctness suite the field can
+reference, not a private test file.
+
+    from idemkit.conformance import BackendConformance
+
+    report = await BackendConformance(my_backend).run()
+    assert report.passed, report.report()
+
+The language-neutral vector descriptions (for ports to other languages) live in
+``spec/conformance.yaml``; this package is the runnable Python reference.
+"""
+
+from idemkit.conformance.backend import BackendConformance
+from idemkit.conformance.report import ConformanceReport, VectorResult
+
+__all__ = [
+    "BackendConformance",
+    "ConformanceReport",
+    "VectorResult",
+]

idemkit/conformance/backend.py

@@ -0,0 +1,257 @@
+"""Shared-core conformance vectors for the backend Protocol (spec §9).
+
+These are the language-neutral correctness checks every ``IdempotencyBackend``
+must pass — atomic claim, fencing, lease reclaim, in-flight wait, TTL expiry, and
+lease renewal — packaged so ANY implementation can point them at itself, not just
+idemkit's own three backends. That portability is the whole point of §11.1: a
+public correctness suite the field can reference, rather than a private test file.
+
+Usage from a third-party library whose backend implements the Protocol::
+
+    from idemkit.conformance import BackendConformance
+
+    report = await BackendConformance(MyBackend(...)).run()
+    assert report.passed, report.report()
+
+The vectors use a unique random key each, so they are safe to run repeatedly
+against a shared, persistent backend (e.g. one PostgreSQL database) without
+cross-run interference. They exercise only the public Protocol — backend-specific
+behavior like corrupt-record recovery is tested inside idemkit itself, since it
+needs internals a generic suite can't reach.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections import Counter
+from collections.abc import Awaitable, Callable
+
+from idemkit.backends.base import IdempotencyBackend
+from idemkit.conformance.report import ConformanceReport, VectorResult
+from idemkit.core.state import ClaimResultType, State
+
+
+class BackendConformance:
+    """Runs the shared-core vectors against one backend instance."""
+
+    def __init__(self, backend: IdempotencyBackend, *, supports_renew: bool = True) -> None:
+        self.backend = backend
+        self.supports_renew = supports_renew
+
+    async def run(self) -> ConformanceReport:
+        """Run every applicable vector and collect the results."""
+        report = ConformanceReport(backend_name=type(self.backend).__name__)
+        for vector_id, description, fn in self._vectors():
+            try:
+                await fn()
+                report.results.append(VectorResult(vector_id, True, description))
+            except AssertionError as e:
+                report.results.append(
+                    VectorResult(vector_id, False, description, error=f"assertion: {e}")
+                )
+            except Exception as e:
+                # A vector that errors (not just asserts) is still a failure, not
+                # a crash of the whole run — record it and keep going.
+                report.results.append(
+                    VectorResult(vector_id, False, description, error=f"{type(e).__name__}: {e}")
+                )
+        return report
+
+    def _vectors(self) -> list[tuple[str, str, Callable[[], Awaitable[None]]]]:
+        vectors: list[tuple[str, str, Callable[[], Awaitable[None]]]] = [
+            ("atomic-claim", "a fresh key claims NEW with a token", self._atomic_claim),
+            (
+                "duplicate-claim",
+                "a second claim on a live key returns ALREADY_CLAIMED",
+                self._duplicate_claim,
+            ),
+            (
+                "conditional-complete",
+                "complete transitions CLAIMED -> COMPLETED and replays",
+                self._conditional_complete,
+            ),
+            (
+                "fencing-wrong-token",
+                "complete with a wrong token is rejected",
+                self._fencing_wrong_token,
+            ),
+            (
+                "release-clears-claim",
+                "release with the right token frees the key",
+                self._release_clears,
+            ),
+            (
+                "lease-reclaim",
+                "an expired lease is reclaimable with a new token",
+                self._lease_reclaim,
+            ),
+            (
+                "fenced-after-reclaim",
+                "a reclaimed owner's late completion is rejected",
+                self._fenced_after_reclaim,
+            ),
+            (
+                "concurrent-claim-exactly-one",
+                "N concurrent claims yield exactly one NEW",
+                self._concurrent_claim,
+            ),
+            (
+                "in-flight-wait",
+                "a waiter receives the completed record",
+                self._in_flight_wait,
+            ),
+            (
+                "wait-timeout",
+                "a waiter times out when the claim never completes",
+                self._wait_timeout,
+            ),
+            (
+                "completed-ttl-expiry",
+                "a COMPLETED record past its TTL re-claims fresh",
+                self._completed_ttl_expiry,
+            ),
+        ]
+        if self.supports_renew:
+            vectors.extend(
+                [
+                    (
+                        "renew-extends-lease",
+                        "renew pushes out a live lease so it isn't reclaimed",
+                        self._renew_extends,
+                    ),
+                    (
+                        "renew-fenced",
+                        "renew with a wrong token, or after reclaim, is rejected",
+                        self._renew_fenced,
+                    ),
+                ]
+            )
+        return vectors
+
+    # ----- the vectors -----
+
+    async def _atomic_claim(self) -> None:
+        key = _k("atomic")
+        result = await self.backend.claim(key, "fp", 1, 30.0)
+        assert result.result == ClaimResultType.NEW_CLAIMED
+        assert result.our_claim_token is not None
+        assert result.record.state == State.CLAIMED
+
+    async def _duplicate_claim(self) -> None:
+        key = _k("dup")
+        first = await self.backend.claim(key, "fp", 1, 30.0)
+        second = await self.backend.claim(key, "fp", 1, 30.0)
+        assert second.result == ClaimResultType.ALREADY_CLAIMED
+        assert second.record.claim_token == first.our_claim_token
+
+    async def _conditional_complete(self) -> None:
+        key = _k("complete")
+        first = await self.backend.claim(key, "fp", 1, 30.0)
+        token = _token(first)
+        ok = await self.backend.complete(key, token, 201, {"h": "v"}, b"body", 3600.0)
+        assert ok is True
+        after = await self.backend.claim(key, "fp", 1, 30.0)
+        assert after.result == ClaimResultType.ALREADY_COMPLETED
+        assert after.record.response_status == 201
+        assert after.record.response_body == b"body"
+
+    async def _fencing_wrong_token(self) -> None:
+        key = _k("fence")
+        await self.backend.claim(key, "fp", 1, 30.0)
+        ok = await self.backend.complete(key, "not-the-token", 200, {}, b"x", 3600.0)
+        assert ok is False
+
+    async def _release_clears(self) -> None:
+        key = _k("release")
+        first = await self.backend.claim(key, "fp", 1, 30.0)
+        assert await self.backend.release(key, _token(first)) is True
+        after = await self.backend.claim(key, "fp", 1, 30.0)
+        assert after.result == ClaimResultType.NEW_CLAIMED
+
+    async def _lease_reclaim(self) -> None:
+        key = _k("reclaim")
+        first = await self.backend.claim(key, "fp", 1, 0.1)
+        await asyncio.sleep(0.25)
+        second = await self.backend.claim(key, "fp", 1, 30.0)
+        assert second.result == ClaimResultType.LEASE_RECLAIMED
+        assert second.our_claim_token != first.our_claim_token
+
+    async def _fenced_after_reclaim(self) -> None:
+        key = _k("fenced-reclaim")
+        first = await self.backend.claim(key, "fp", 1, 0.1)
+        await asyncio.sleep(0.25)
+        second = await self.backend.claim(key, "fp", 1, 30.0)
+        assert second.result == ClaimResultType.LEASE_RECLAIMED
+        ok = await self.backend.complete(key, _token(first), 200, {}, b"x", 3600.0)
+        assert ok is False
+        after = await self.backend.claim(key, "fp", 1, 30.0)
+        assert after.record.claim_token == second.our_claim_token
+
+    async def _concurrent_claim(self) -> None:
+        key = _k("concurrent")
+        parallel = 25
+        results = await asyncio.gather(
+            *(self.backend.claim(key, "fp", 1, 30.0) for _ in range(parallel))
+        )
+        outcomes = Counter(r.result for r in results)
+        assert outcomes[ClaimResultType.NEW_CLAIMED] == 1
+        assert outcomes[ClaimResultType.ALREADY_CLAIMED] == parallel - 1
+
+    async def _in_flight_wait(self) -> None:
+        key = _k("wait")
+        first = await self.backend.claim(key, "fp", 1, 30.0)
+        token = _token(first)
+
+        async def completer() -> None:
+            await asyncio.sleep(0.1)
+            await self.backend.complete(key, token, 200, {}, b"hi", 3600.0)
+
+        waited, _ = await asyncio.gather(
+            self.backend.wait_for_completion(key, timeout_seconds=2.0), completer()
+        )
+        assert waited is not None
+        assert waited.state == State.COMPLETED
+        assert waited.response_body == b"hi"
+
+    async def _wait_timeout(self) -> None:
+        key = _k("wait-timeout")
+        await self.backend.claim(key, "fp", 1, 30.0)
+        result = await self.backend.wait_for_completion(key, timeout_seconds=0.3)
+        assert result is None
+
+    async def _completed_ttl_expiry(self) -> None:
+        # The TTL window must comfortably outlast a backend round-trip, or a slow
+        # store can expire the record before the "still completed" check below.
+        key = _k("ttl")
+        first = await self.backend.claim(key, "fp", 1, 30.0)
+        await self.backend.complete(key, _token(first), 200, {}, b"x", 1.0)
+        immediate = await self.backend.claim(key, "fp", 1, 30.0)
+        assert immediate.result == ClaimResultType.ALREADY_COMPLETED
+        await asyncio.sleep(1.5)
+        after = await self.backend.claim(key, "fp", 1, 30.0)
+        assert after.result == ClaimResultType.NEW_CLAIMED
+
+    async def _renew_extends(self) -> None:
+        key = _k("renew")
+        first = await self.backend.claim(key, "fp", 1, 0.2)
+        assert await self.backend.renew(key, _token(first), 30.0) is True
+        await asyncio.sleep(0.4)
+        second = await self.backend.claim(key, "fp", 1, 30.0)
+        assert second.result == ClaimResultType.ALREADY_CLAIMED
+
+    async def _renew_fenced(self) -> None:
+        key = _k("renew-fenced")
+        await self.backend.claim(key, "fp", 1, 30.0)
+        assert await self.backend.renew(key, "not-the-token", 30.0) is False
+
+
+def _token(result: object) -> str:
+    """The claim token from a NEW/RECLAIMED claim, asserted present."""
+    token = getattr(result, "our_claim_token", None)
+    assert token is not None, "a NEW/RECLAIMED claim must carry a claim token"
+    return str(token)
+
+
+def _k(suffix: str) -> str:
+    return f"conformance-{suffix}-{uuid.uuid4().hex}"

idemkit/conformance/report.py

@@ -0,0 +1,54 @@
+"""Result types for the conformance runner."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class VectorResult:
+    """The outcome of one conformance vector."""
+
+    vector_id: str
+    passed: bool
+    description: str
+    error: str | None = None
+
+    @property
+    def status(self) -> str:
+        return "PASS" if self.passed else "FAIL"
+
+
+@dataclass
+class ConformanceReport:
+    """The result of running a set of vectors against one backend."""
+
+    backend_name: str
+    results: list[VectorResult] = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        """True only if every vector passed."""
+        return all(r.passed for r in self.results)
+
+    @property
+    def total(self) -> int:
+        return len(self.results)
+
+    @property
+    def failures(self) -> list[VectorResult]:
+        return [r for r in self.results if not r.passed]
+
+    def summary(self) -> str:
+        """One-line human summary, e.g. ``RedisBackend: 13/13 vectors passed``."""
+        passed = sum(1 for r in self.results if r.passed)
+        return f"{self.backend_name}: {passed}/{self.total} vectors passed"
+
+    def report(self) -> str:
+        """A multi-line report listing each vector's status."""
+        lines = [self.summary()]
+        for r in self.results:
+            lines.append(f"  [{r.status}] {r.vector_id} — {r.description}")
+            if r.error:
+                lines.append(f"         {r.error}")
+        return "\n".join(lines)

idemkit/contrib/__init__.py

@@ -0,0 +1,30 @@
+"""Optional broker glue for idemkit's queue surface.
+
+The core queue adapter (:class:`idemkit.IdempotentConsumer`) is broker-agnostic —
+you supply small callables that read the dedup id, scope, and receive count from
+whatever message object your library hands you. That is deliberately flexible but
+means everyone rewrites the same wiring for the same two or three brokers.
+
+``idemkit.contrib`` presets that wiring for the common cases so it's import-and-go:
+
+* :mod:`idemkit.contrib.sqs` — Amazon SQS (boto3 message dicts).
+* :mod:`idemkit.contrib.kafka` — Kafka (``confluent_kafka`` or ``kafka-python`` records).
+* :mod:`idemkit.contrib.mcp` — enforce idempotency on MCP / LLM tool calls.
+* :mod:`idemkit.contrib.fastapi` — a FastAPI route class (return a dict, read
+  ``request.state`` in ``scope``).
+* :mod:`idemkit.contrib.drf` — a Django REST Framework view mixin (read
+  ``request.user`` in ``scope``).
+
+For Celery there is no separate module: a task body is a plain synchronous
+function, so :func:`idemkit.idempotent_sync` is the tool (stack it UNDER
+``@app.task``). See ``examples/method/sync_function.py``.
+
+None of these import a broker SDK; they read duck-typed message objects and (for
+SQS) take the client you already created. Install the broker library yourself.
+
+For observability there are two ready-made event handlers, so you don't hand-roll
+the metric plumbing:
+
+* :mod:`idemkit.contrib.prometheus` — record operations / latency to Prometheus.
+* :mod:`idemkit.contrib.logging` — one structured log line per operation.
+"""