idemkit 0.1.0__py3-none-any.whl

idemkit/contrib/drf.py

@@ -0,0 +1,181 @@
+"""Django REST Framework idempotency, as a view mixin.
+
+The WSGI middleware protects a whole Django app, but a DRF mixin lets you protect
+*specific* views and read DRF's request (``request.user`` for ``scope``, ``request.data``
+in the view). :func:`idempotent_view` returns a mixin class you put BEFORE the DRF
+base class:
+
+    from rest_framework.views import APIView
+    from rest_framework.response import Response
+    from idemkit import RedisBackend, HttpConfig
+    from idemkit.contrib.drf import idempotent_view
+
+    backend = RedisBackend.from_url("redis://localhost:6379")
+    Idempotent = idempotent_view(
+        backend=backend, config=HttpConfig(scope=lambda req: str(req.user.pk))
+    )
+
+    class ChargeView(Idempotent, APIView):
+        def post(self, request):
+            return Response({"charged": True}, status=201)
+
+It claims the key after DRF authentication runs (so ``request.user`` is set), replays
+the stored response on a duplicate, and releases the claim if the view raises. Works
+on ``APIView`` and ``ViewSet`` (both share the ``initial`` / ``handle_exception`` /
+``finalize_response`` lifecycle). Requires Django + DRF; this module imports neither
+until a response is built.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from idemkit.adapters.asgi import _unwrap_sf_string
+from idemkit.backends.base import IdempotencyBackend
+from idemkit.core.config import resolve_http_config
+from idemkit.core.engine import (
+    EngineOutcome,
+    IdempotencyEngine,
+    NeutralRequest,
+    NeutralResponse,
+)
+from idemkit.core.exceptions import ConfigurationError
+from idemkit.core.policy import HttpConfig
+from idemkit.core.sync_bridge import register_closable, run_sync
+
+
+class _ShortCircuit(Exception):
+    """Internal: raised from ``initial`` to return a replay/reject response without
+    running the view. Caught in the mixin's ``handle_exception``."""
+
+    def __init__(self, response: NeutralResponse) -> None:
+        self.neutral = response
+
+
+def idempotent_view(
+    *,
+    backend: IdempotencyBackend,
+    config: HttpConfig | None = None,
+) -> type:
+    """Build a DRF view mixin that applies idempotency.
+
+    Put the returned class BEFORE your DRF base (``class V(idempotent_view(...), APIView)``).
+    If it is placed AFTER the base, the mixin raises at class-definition time rather
+    than silently doing nothing. One engine is shared by every view using this mixin.
+    """
+    resolved = resolve_http_config(config)
+    engine = IdempotencyEngine(backend=backend, config=resolved)
+    # The Redis/Postgres pool binds to the sync-bridge loop; close it at exit.
+    register_closable(backend)
+
+    def _extract_key(request: Any) -> str | None:
+        if resolved.key is not None:
+            try:
+                return resolved.key(request)
+            except Exception:
+                return None
+        return _unwrap_sf_string(request.headers.get("Idempotency-Key"))
+
+    def _extract_scope(request: Any) -> str | None:
+        if resolved.scope is None:
+            return None
+        try:
+            value = resolved.scope(request)
+        except Exception:
+            # A configured-but-failing extractor fails closed (engine rejects per
+            # scope_mode); it never silently shares one namespace across tenants.
+            return None
+        return value or None
+
+    def _neutral(request: Any) -> NeutralRequest:
+        try:
+            body = request.body  # cached, so the view's request.data still parses
+        except Exception:
+            body = b""
+        return NeutralRequest(
+            idempotency_key=_extract_key(request),
+            scope=_extract_scope(request),
+            method=request.method,
+            path=request.path,
+            query=request.META.get("QUERY_STRING", "") if hasattr(request, "META") else "",
+            body=bytes(body) if isinstance(body, (bytes, bytearray)) else b"",
+            content_type=getattr(request, "content_type", None),
+        )
+
+    class IdempotencyMixin:
+        _idem_outcome: EngineOutcome | None = None
+        _idemkit_drf_mixin = True
+
+        def __init_subclass__(cls, **kwargs: Any) -> None:
+            super().__init_subclass__(**kwargs)
+            # Silent no-op guard: if a DRF base that defines `initial` precedes this
+            # mixin in the MRO, our overrides never run and idempotency does nothing.
+            # Fail at class-definition time instead of shipping unprotected.
+            mro = cls.__mro__
+            mixin_pos = next(
+                (i for i, c in enumerate(mro) if c.__dict__.get("_idemkit_drf_mixin")), None
+            )
+            base_pos = next(
+                (
+                    i
+                    for i, c in enumerate(mro)
+                    if "initial" in c.__dict__ and not c.__dict__.get("_idemkit_drf_mixin")
+                ),
+                None,
+            )
+            if mixin_pos is not None and base_pos is not None and mixin_pos > base_pos:
+                raise ConfigurationError(
+                    f"idemkit: {cls.__name__} lists idempotent_view(...) AFTER its DRF base "
+                    f"({mro[base_pos].__name__}), so the mixin's hooks are shadowed and "
+                    "idempotency would silently do nothing. Put the mixin FIRST: "
+                    "class V(idempotent_view(...), APIView)."
+                )
+
+        def initial(self, request: Any, *args: Any, **kwargs: Any) -> None:
+            # Run DRF auth/permissions/throttling first, so scope can read request.user.
+            super().initial(request, *args, **kwargs)  # type: ignore[misc]
+            outcome = run_sync(engine.decide(_neutral(request)))
+            self._idem_outcome = outcome
+            if outcome.kind in ("replay", "reject"):
+                assert outcome.response is not None
+                raise _ShortCircuit(outcome.response)
+
+        def handle_exception(self, exc: Any) -> Any:
+            if isinstance(exc, _ShortCircuit):
+                return _to_django_response(exc.neutral)
+            # The view raised: release the claim so a retry re-runs (fail-closed).
+            outcome = getattr(self, "_idem_outcome", None)
+            if outcome is not None and outcome.kind == "pass_through" and outcome.claim_token:
+                run_sync(engine.on_error(outcome.effective_key, outcome.claim_token))
+                self._idem_outcome = None
+            return super().handle_exception(exc)  # type: ignore[misc]
+
+        def finalize_response(self, request: Any, response: Any, *args: Any, **kwargs: Any) -> Any:
+            response = super().finalize_response(request, response, *args, **kwargs)  # type: ignore[misc]
+            outcome = getattr(self, "_idem_outcome", None)
+            if (
+                outcome is not None
+                and outcome.kind == "pass_through"
+                and outcome.effective_key
+                and outcome.claim_token
+            ):
+                response.render()  # DRF renders lazily; force it to capture the bytes
+                captured = NeutralResponse(
+                    status=response.status_code,
+                    headers=dict(response.items()),
+                    body=bytes(response.content),
+                )
+                run_sync(engine.on_complete(outcome.effective_key, outcome.claim_token, captured))
+                self._idem_outcome = None
+            return response
+
+    return IdempotencyMixin
+
+
+def _to_django_response(neutral: NeutralResponse) -> Any:
+    from django.http import HttpResponse
+
+    response = HttpResponse(content=neutral.body, status=neutral.status)
+    for name, value in neutral.headers.items():
+        response[name] = value
+    return response

idemkit/contrib/fastapi.py

@@ -0,0 +1,141 @@
+"""FastAPI-native idempotency via a custom route class.
+
+The app-wide :class:`~idemkit.IdempotencyMiddleware` already works with FastAPI, but
+a route class fits FastAPI better in two ways:
+
+* your handler can return a ``dict`` / Pydantic model (FastAPI serializes it, then
+  idemkit captures the serialized bytes for replay), so you don't rewrite endpoints
+  to return ``JSONResponse``;
+* your ``scope`` / ``key`` callables get the real ``Request``, so ``request.state``
+  works (the middleware only exposes a lightweight proxy).
+
+Use it per-router or app-wide::
+
+    from fastapi import APIRouter
+    from idemkit import RedisBackend, HttpConfig
+    from idemkit.contrib.fastapi import idempotent_route
+
+    backend = RedisBackend.from_url("redis://localhost:6379")
+    router = APIRouter(
+        route_class=idempotent_route(
+            backend=backend, config=HttpConfig(scope=lambda req: req.state.user_id)
+        )
+    )
+
+
+    @router.post("/charge")
+    async def charge(order: Order) -> dict:
+        return {"charged": True}  # a dict is fine; idemkit captures the serialized body
+
+For the whole app: ``app.router.route_class = idempotent_route(backend=backend, config=config)``.
+Non-applicable methods (GET by default) and keyless requests pass straight through,
+so the class is safe to apply broadly. Requires FastAPI.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from idemkit.backends.base import IdempotencyBackend
+from idemkit.core.config import resolve_http_config
+from idemkit.core.engine import IdempotencyEngine, NeutralRequest, NeutralResponse
+from idemkit.core.policy import HttpConfig
+
+
+def idempotent_route(
+    *,
+    backend: IdempotencyBackend,
+    config: HttpConfig | None = None,
+) -> type:
+    """Build a FastAPI ``APIRoute`` subclass that applies idempotency.
+
+    Pass it as ``route_class=`` to an ``APIRouter`` (or assign
+    ``app.router.route_class``). One engine is shared by every route on the router.
+    """
+    try:
+        from fastapi import Request
+        from fastapi.routing import APIRoute
+    except ImportError as e:  # pragma: no cover - exercised via the error message
+        raise ImportError("idemkit: install FastAPI: pip install fastapi") from e
+
+    from idemkit.adapters.asgi import _unwrap_sf_string
+
+    resolved = resolve_http_config(config)
+    engine = IdempotencyEngine(backend=backend, config=resolved)
+
+    def _extract_key(request: Request) -> str | None:
+        if resolved.key is not None:
+            try:
+                return resolved.key(request)
+            except Exception:
+                return None
+        return _unwrap_sf_string(request.headers.get("idempotency-key"))
+
+    def _extract_scope(request: Request) -> str | None:
+        if resolved.scope is None:
+            return None
+        try:
+            value = resolved.scope(request)
+        except Exception:
+            # A configured-but-failing extractor fails closed: the engine sees no
+            # identity and rejects per scope_mode (never buckets as anonymous).
+            return None
+        return value or None
+
+    class IdempotentAPIRoute(APIRoute):
+        def get_route_handler(self) -> Any:
+            original = super().get_route_handler()
+
+            async def handler(request: Request) -> Any:
+                body = await request.body()  # cached, so the handler still parses it
+                neutral = NeutralRequest(
+                    idempotency_key=_extract_key(request),
+                    scope=_extract_scope(request),
+                    method=request.method,
+                    path=request.url.path,
+                    query=request.url.query,
+                    body=body,
+                    content_type=request.headers.get("content-type"),
+                )
+                outcome = await engine.decide(neutral)
+                if outcome.kind in ("replay", "reject"):
+                    assert outcome.response is not None
+                    return _to_response(outcome.response)
+                if outcome.effective_key is None or outcome.claim_token is None:
+                    return await original(request)  # idempotency does not apply
+                try:
+                    response = await original(request)
+                except Exception:
+                    await engine.on_error(outcome.effective_key, outcome.claim_token)
+                    raise
+                captured = _capture(response)
+                if captured is None:
+                    # A streaming/file response has no buffered body to cache;
+                    # release so a retry re-runs (the client already got the bytes).
+                    await engine.on_error(outcome.effective_key, outcome.claim_token)
+                    return response
+                # on_complete enforces max_body_bytes and cacheable_status: an
+                # oversized or non-cacheable response is released, not stored.
+                await engine.on_complete(outcome.effective_key, outcome.claim_token, captured)
+                return response
+
+            return handler
+
+    return IdempotentAPIRoute
+
+
+def _to_response(neutral: NeutralResponse) -> Any:
+    from starlette.responses import Response
+
+    return Response(content=neutral.body, status_code=neutral.status, headers=neutral.headers)
+
+
+def _capture(response: Any) -> NeutralResponse | None:
+    body = getattr(response, "body", None)
+    if not isinstance(body, (bytes, bytearray)):
+        return None  # streaming / file response: no buffered body to store
+    return NeutralResponse(
+        status=response.status_code,
+        headers=dict(response.headers),
+        body=bytes(body),
+    )

idemkit/contrib/kafka.py

@@ -0,0 +1,96 @@
+"""Kafka glue for idemkit's queue surface.
+
+Kafka redelivers when a consumer doesn't make progress within
+``max.poll.interval.ms`` (the group coordinator considers it dead and reassigns
+its partitions), and on rebalances. :func:`kafka_consumer` presets an
+:class:`~idemkit.IdempotentConsumer` so a side effect runs once per record even
+across those redeliveries.
+
+Two Kafka-specific choices it gets right for you:
+
+* **Dedup id = ``topic:partition:offset``.** The globally-stable identity of a
+  record; the message *key* is not unique enough (many records share a key).
+* **Visibility-timeout analogue = ``max.poll.interval.ms``.** Kafka has no
+  per-message visibility timeout, but the redelivery deadline is the poll
+  interval, so the lease is derived from it (kept shorter, renewed by heartbeat).
+
+Kafka exposes **no native receive count**, so ``max_attempts`` needs a durable
+:class:`~idemkit.adapters.queue.AttemptStore` in a multi-consumer deployment
+(pass ``attempt_store=``); without one, counting is in-process and idemkit warns.
+
+``group_id`` is required and becomes the scope: two consumer groups read the same
+offsets, and each must process every record, so their dedup records must not
+collide.
+
+Example (confluent-kafka)::
+
+    from confluent_kafka import Consumer
+    from idemkit import RedisBackend
+    from idemkit.contrib.kafka import kafka_consumer
+
+    consumer = kafka_consumer(
+        backend=RedisBackend.from_url("redis://localhost:6379"),
+        group_id="billing",
+        max_poll_interval_seconds=300,
+    )
+
+
+    @consumer.handle
+    def process(record) -> None:
+        charge_customer(record.value())  # runs once per topic:partition:offset
+
+
+    kc = Consumer({"bootstrap.servers": "...", "group.id": "billing", "enable.auto.commit": False})
+    kc.subscribe(["charges"])
+    while True:
+        record = kc.poll(1.0)
+        if record is None or record.error():
+            continue
+        result = consumer.dispatch_sync(record)
+        if result.action.value == "ack":
+            kc.commit(record)  # advance the offset only when done
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any
+
+from idemkit.adapters.queue import IdempotentConsumer
+from idemkit.backends.base import IdempotencyBackend
+from idemkit.core.policy import QueueConfig
+
+
+def _attr(message: Any, name: str) -> Any:
+    """Read ``name`` from a record, whether it's a method (confluent_kafka) or a
+    plain attribute (kafka-python)."""
+    value = getattr(message, name)
+    return value() if callable(value) else value
+
+
+def kafka_dedup_id(message: Any) -> str:
+    """``topic:partition:offset`` for a confluent_kafka or kafka-python record."""
+    return f"{_attr(message, 'topic')}:{_attr(message, 'partition')}:{_attr(message, 'offset')}"
+
+
+def kafka_consumer(
+    *,
+    backend: IdempotencyBackend,
+    group_id: str,
+    max_poll_interval_seconds: float = 300.0,
+    config: QueueConfig | None = None,
+) -> IdempotentConsumer:
+    """Build an :class:`~idemkit.IdempotentConsumer` wired for Kafka records.
+
+    Kafka presets the dedup id (``topic:partition:offset``) and the scope
+    (``group_id``). Pass a :class:`~idemkit.QueueConfig` for behaviour.
+    """
+    cfg = config or QueueConfig()
+    presets: dict[str, Any] = {
+        "dedup_id": kafka_dedup_id,
+        "visibility_timeout_seconds": max_poll_interval_seconds,
+    }
+    if cfg.scope is None:  # group_id is the scope unless the caller set one
+        presets["scope"] = lambda _m: group_id
+    cfg = dataclasses.replace(cfg, **presets)
+    return IdempotentConsumer(backend=backend, config=cfg)

idemkit/contrib/logging.py

@@ -0,0 +1,61 @@
+"""Structured-logging exporter for idemkit's observability events.
+
+A zero-dependency handler that logs one structured line per operation. Route
+idemkit's :class:`~idemkit.IdempotencyEvent` to your logger when you don't (yet)
+have a metrics pipeline::
+
+    from idemkit import MethodConfig, idempotent
+    from idemkit.contrib.logging import logging_handler
+
+
+    @idempotent(
+        backend=backend,
+        config=MethodConfig(
+            key_fields=["order_id"],
+            event_handlers=(logging_handler(),),
+        ),
+    )
+    async def refund(*, order_id): ...
+
+Each record carries the decision, surface, backend, latencies, and the hashed
+``effective_key`` (safe to log; never the raw idempotency key). Fields go in the
+``extra`` dict so a JSON log formatter picks them up as structured fields.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from idemkit.core.events import EventHandler, IdempotencyEvent
+
+_default_logger = logging.getLogger("idemkit.events")
+
+
+def logging_handler(
+    logger: logging.Logger | None = None, *, level: int = logging.INFO
+) -> EventHandler:
+    """Build an :data:`~idemkit.EventHandler` that logs one line per operation.
+
+    Pass your own ``logger`` (default ``idemkit.events``) and ``level``.
+    """
+    log = logger or _default_logger
+
+    def handle(event: IdempotencyEvent) -> None:
+        log.log(
+            level,
+            "idemkit %s surface=%s backend=%s latency=%.4fs",
+            event.decision.value,
+            event.surface,
+            event.backend_name,
+            event.latency_seconds,
+            extra={
+                "idempotency_decision": event.decision.value,
+                "idempotency_surface": event.surface,
+                "idempotency_backend": event.backend_name,
+                "idempotency_effective_key": event.effective_key,
+                "idempotency_latency_seconds": event.latency_seconds,
+                "idempotency_wait_seconds": event.wait_duration_seconds,
+            },
+        )
+
+    return handle

idemkit/contrib/mcp.py

@@ -0,0 +1,113 @@
+"""Enforce idempotency on MCP / LLM tool calls.
+
+The Model Context Protocol lets a tool advertise ``idempotentHint: true`` in its
+annotations — but that is advisory metadata for the model/client, and **nothing
+enforces it**. An agent that retries, re-plans, or runs parallel branches can
+still call a side-effectful tool twice.
+
+idemkit's method surface (:func:`idemkit.idempotent`) *is* the enforcement layer.
+This module is a thin bridge:
+
+* :func:`mcp_idempotent` — decorate a tool so duplicate calls with the same
+  arguments replay the first result instead of re-running, and stamp the
+  ``idempotentHint`` so the tool truthfully advertises what it now guarantees.
+* :func:`wrap_if_idempotent` — given a handler and its MCP annotations, enforce
+  dedup automatically *when the tool already declares* ``idempotentHint: true``.
+* :func:`read_idempotent_hint` — read the hint off a function or an annotations
+  object/dict.
+
+No dependency on the ``mcp`` package: these operate on plain functions and an
+annotations mapping, so they work with the official Python SDK (FastMCP), a hand
+-rolled server, or an Anthropic / OpenAI tool-dispatch loop.
+
+Example — a FastMCP tool that really is safe to call twice::
+
+    from mcp.server.fastmcp import FastMCP
+    from idemkit import RedisBackend
+    from idemkit.contrib.mcp import mcp_idempotent
+
+    mcp = FastMCP("payments")
+    backend = RedisBackend.from_url("redis://localhost:6379")
+
+
+    @mcp.tool()
+    @mcp_idempotent(backend=backend, config=MethodConfig(key_fields=["order_id", "amount"]))
+    async def refund(order_id: str, amount: int) -> dict:
+        return await payments.refund(order_id, amount)  # charged once per (order_id, amount)
+
+The agent re-emitting ``refund("A123", 50)`` on a re-plan replays the first
+result instead of issuing a second refund.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Mapping
+from typing import Any, cast
+
+from idemkit.adapters.ai import idempotent, idempotent_sync
+from idemkit.backends.base import IdempotencyBackend
+from idemkit.core.policy import MethodConfig
+
+HINT_KEY = "idempotentHint"
+
+
+def mcp_idempotent(
+    *,
+    backend: IdempotencyBackend,
+    config: MethodConfig | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Enforce idempotency on an MCP tool and mark it as idempotent.
+
+    Works on ``async def`` and plain ``def`` tools alike (it picks the matching
+    idemkit decorator). Dedup on ``config.key_fields`` — the argument fields that
+    define "the same call"; volatile per-turn ids (``tool_call_id``) are never
+    listed, so a retry with a fresh id still dedupes.
+
+    The returned function carries ``idempotent_hint = True`` so a server can surface
+    ``idempotentHint`` in the tool's advertised annotations.
+    """
+
+    def decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
+        deco = idempotent if inspect.iscoroutinefunction(fn) else idempotent_sync
+        wrapped: Any = deco(backend=backend, config=config)(fn)
+        wrapped.idempotent_hint = True
+        return cast("Callable[..., Any]", wrapped)
+
+    return decorate
+
+
+def read_idempotent_hint(source: Any) -> bool:
+    """Return whether ``source`` declares ``idempotentHint``.
+
+    ``source`` may be a function (checks the ``idempotent_hint`` attribute set by
+    :func:`mcp_idempotent`), a mapping (checks the ``idempotentHint`` key), or any
+    object exposing an ``idempotentHint`` attribute (e.g. an MCP tool annotations
+    object).
+    """
+    if isinstance(source, Mapping):
+        return bool(source.get(HINT_KEY, False))
+    if hasattr(source, "idempotent_hint"):
+        return bool(source.idempotent_hint)
+    if hasattr(source, HINT_KEY):
+        return bool(getattr(source, HINT_KEY))
+    return False
+
+
+def wrap_if_idempotent(
+    fn: Callable[..., Any],
+    *,
+    annotations: Any,
+    backend: IdempotencyBackend,
+    config: MethodConfig | None = None,
+) -> Callable[..., Any]:
+    """Enforce dedup on ``fn`` only if its MCP ``annotations`` declare the hint.
+
+    Use this to auto-apply idempotency across a registry of tools: a tool that
+    already advertises ``idempotentHint: true`` gets real enforcement; a tool that
+    doesn't is returned unchanged (wrapping a pure tool only wastes storage, so
+    idemkit never guesses — the declaration is the caller's, §8.2).
+    """
+    if not read_idempotent_hint(annotations):
+        return fn
+    return mcp_idempotent(backend=backend, config=config)(fn)

idemkit/contrib/prometheus.py

@@ -0,0 +1,79 @@
+"""Prometheus exporter for idemkit's observability events.
+
+idemkit emits one :class:`~idemkit.IdempotencyEvent` per operation; you decide
+where it goes. This is a ready-made handler that records the standard four metrics
+so you get a dashboard without writing the plumbing yourself::
+
+    from idemkit import IdempotencyMiddleware, RedisBackend, HttpConfig
+    from idemkit.contrib.prometheus import prometheus_handler
+
+    app.add_middleware(
+        IdempotencyMiddleware,
+        backend=RedisBackend.from_url("redis://..."),
+        config=HttpConfig(event_handlers=(prometheus_handler(),)),
+    )
+
+The same handler works on every surface (HTTP, queue, method), so one dashboard
+covers all three: filter by the ``surface`` label.
+
+Metrics (namespaced ``idemkit_`` by default):
+
+* ``idemkit_operations_total``: Counter, labels ``decision`` / ``surface`` / ``backend``.
+  Derive replay rate, conflict rate, and storage-error rate from ``decision``.
+* ``idemkit_latency_seconds``: Histogram, labels ``surface`` / ``backend``.
+* ``idemkit_wait_seconds``: Histogram, labels ``surface`` / ``backend`` (only observed
+  when a duplicate waited on an in-flight run).
+
+The hashed ``effective_key`` is deliberately NOT a label: it is high-cardinality and
+would blow up your metrics store. Requires the ``prometheus`` extra
+(``pip install 'idemkit[prometheus]'``).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from idemkit.core.events import EventHandler, IdempotencyEvent
+
+
+def prometheus_handler(registry: Any = None, *, namespace: str = "idemkit") -> EventHandler:
+    """Build an :data:`~idemkit.EventHandler` that records idemkit metrics.
+
+    Pass a custom ``registry`` (a ``prometheus_client.CollectorRegistry``) to isolate
+    the metrics, e.g. in tests; the default is the global registry. ``namespace``
+    prefixes every metric name.
+    """
+    try:
+        from prometheus_client import Counter, Histogram
+    except ImportError as e:  # pragma: no cover - exercised via the error message
+        raise ImportError(
+            "idemkit: install the `prometheus` extra: pip install 'idemkit[prometheus]'"
+        ) from e
+
+    kwargs: dict[str, Any] = {"registry": registry} if registry is not None else {}
+    operations = Counter(
+        f"{namespace}_operations_total",
+        "idemkit operations by decision, surface, and backend.",
+        ["decision", "surface", "backend"],
+        **kwargs,
+    )
+    latency = Histogram(
+        f"{namespace}_latency_seconds",
+        "idemkit end-to-end operation latency.",
+        ["surface", "backend"],
+        **kwargs,
+    )
+    wait = Histogram(
+        f"{namespace}_wait_seconds",
+        "Time a duplicate waited on an in-flight run before replaying.",
+        ["surface", "backend"],
+        **kwargs,
+    )
+
+    def handle(event: IdempotencyEvent) -> None:
+        operations.labels(event.decision.value, event.surface, event.backend_name).inc()
+        latency.labels(event.surface, event.backend_name).observe(event.latency_seconds)
+        if event.wait_duration_seconds:
+            wait.labels(event.surface, event.backend_name).observe(event.wait_duration_seconds)
+
+    return handle