mic-struct 0.0.1__tar.gz

mic_struct-0.0.1/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Build / packaging
+dist/
+build/
+*.egg-info/
+.coverage
+coverage.xml
+
+# OS / Editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.bak
+
+# Reports / temp
+reports/
+.benchmarks/
+.mutmut-cache/
+.wily/

mic_struct-0.0.1/CHANGELOG.md

@@ -0,0 +1,582 @@
+# Changelog
+
+All notable changes to **mic-struct** are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] — 2026-05-22
+
+First public release of `mic-struct` — the building blocks below have
+been consolidated, hardened, and locked behind a 100 % line + branch
+coverage gate (+ xenon complexity gate, bandit SAST, pip-audit). Pre-1.0:
+per semver 0.x, minor bumps may carry breaking changes.
+
+### Removed — 2026-05-22 : `mic.feature_flags` + `mic.graphql` (orphelins, RDL-423)
+
+Décision du jalon **RDL-423** (revue des modules orphelins, ADR-0012) : ces deux
+modules n'avaient **aucun consumer** dans la flotte rdlink et **aucun plan
+d'adoption** (≠ briques de montée en charge `queue`/`shard`, gardées différées) :
+
+- `mic.feature_flags` — `FeatureFlagEngine` ABC + backends Unleash / GrowthBook /
+  in-memory. Extras `[unleash]` / `[growthbook]` supprimés.
+- `mic.graphql` — adapter Strawberry code-first. Extra `[graphql]` + dépendance
+  `strawberry-graphql` supprimés.
+
+**Breaking** (acceptable pré-1.0) : `mic-struct[graphql|unleash|growthbook]` et
+les imports `mic.feature_flags.*` / `mic.graphql.*` ne sont plus disponibles. À
+ré-introduire (rebrand `mic-struct-experimental` ou ré-import) si un besoin
+produit émerge. **−737 LOC.**
+
+### Added — 2026-05-22 : outillage qualité complexité + duplication (RDL-616)
+
+Quatre outils, deux niveaux :
+
+**Report-only** (hors gate, à la demande) :
+- `make complexity` — `radon cc` (complexité cyclomatique A–F) + `radon mi`
+  (maintainability index) sur `src/mic`.
+- `make complexity-trend` — `wily build` + `wily diff` (tendance dans l'historique
+  git ; cache `.wily/` git-ignoré ; requiert un arbre propre).
+
+**Gate bloquant** (dans `make quality`/`gate`) :
+- `make complexity-gate` — `xenon --max-absolute C --max-average A src/mic`.
+  Seuils dérivés de la baseline mic (moyenne **A=2.48**, pire bloc **C**, aucun
+  D/E/F) → passe à vert sans refactor. Pure Python → CI-safe.
+
+**Duplication** (Node/npx, hors gate Python) :
+- `make duplication` — `jscpd` seuil **3 %** (config `.jscpd.json` ; baseline mic
+  **1.49 % lignes / 2.39 % tokens**). À basculer bloquant côté CI une fois
+  l'image node-capable (cf. RDL-606).
+
+Seuils proposés à ratifier dans l'ADR **RDL-601**. wily 1.25 épingle radon
+`>=5.1,<5.2` (compatible xenon 0.9 + py314).
+
+### Added — 2026-05-22 : `mic.grpc.GrpcRpcSpec` + `build_grpc_servicers` (couche gRPC dict-handler, RDL-266/267)
+
+Couche gRPC *framework-agnostique* dict-in / dict-out, complémentaire de
+`GrpcServiceSpec` (servicers générés par protoc) :
+
+- `GrpcRpcSpec` : description d'un RPC unaire (`service_name`, `rpc_name`,
+  `handler: Callable[[dict], dict]`) — les handlers ne dépendent **pas** de
+  grpcio/protobuf, donc testables hors transport.
+- `build_grpc_servicers(rpcs=...)` : regroupe par service et génère
+  dynamiquement une classe `Servicer` par service (une méthode par RPC) qui
+  duck-type le servicer protoc. Traduit `DomainError` → `INVALID_ARGUMENT` et
+  `TransientError` → `UNAVAILABLE` via `context.abort` (grpcio importé
+  paresseusement → module import-safe sans l'extra `[grpc]`).
+
+Élimine la duplication identique de cette couche dans `rdlink-extract` et
+`rdlink-moderation` (`app/shared/interface/grpc/rpc_spec.py` +
+`app/frameworks/grpc/service_builder.py`) au profit d'un import `from mic.grpc`.
+
+### Added — 2026-05-21 : `HttpRequestContext.subject_id` (identité caller au handler)
+
+Champ optionnel `subject_id: str | None = None` sur `HttpRequestContext` :
+l'identité résolue de l'appelant (posée par le `SubjectResolverMiddleware` du
+consumer) est désormais transmise au handler, sans coupler les routes au
+mécanisme d'auth. Publié en `0.0.1.dev10` (le champ avait été ajouté après la
+publication de `dev9`, d'où le re-publish pour les consumers comme l'analytics
+`unique_searchers` de rdlink-api).
+
+### Added — 2026-05-20 : `mic.observability.RedactingLogFilter` (redaction logs, RDL-490)
+
+Pilier *Logs* de la redaction MELT (épic RDL-488) — **clôt l'épic** (events ✅,
+metrics ✅, traces ✅, logs ✅). RDL-490 spécifiait un processor structlog, mais
+`mic.observability.logging` est en **stdlib `logging`** ; l'équivalent stdlib
+est un `logging.Filter`. Reframé en conséquence :
+
+- `RedactingLogFilter(logging.Filter)` : redacte récursivement les **champs
+  extra** d'un `LogRecord` (`logger.info(..., extra={...})`) avant émission,
+  selon des `FieldRedactors` injectés. À attacher au(x) handler(s).
+- `redact_fields(value, redactors)` : primitive de redaction **récursive**
+  (dicts / listes / tuples imbriqués), renvoie une **copie** (n'altère pas
+  l'entrée). Complète `apply_field_redactors` (top-level).
+- Champs standard du `LogRecord` jamais touchés ; stdlib-only (pas d'extra).
+
+Portée V1 : champs extra structurés (vecteur PII principal). Le texte libre des
+tracebacks (`exc_info`) n'est pas parsé — scrubber à la source.
+
+### Added — 2026-05-20 : `mic.observability.RedactingSpanProcessor` (redaction traces, RDL-491)
+
+Dernier pilier de la redaction MELT (épic RDL-488 ; events ✅ `sanitize_payload`,
+metrics ✅ `SanitizingMetricsBackend`, **traces** = ce ticket). `SpanProcessor`
+OTel qui scrubbe les attributs de span **et** d'events (`db.statement`,
+`exception.message`, `http.request.body`, …) avant l'export OTLP/Tempo, selon
+des `FieldRedactors` injectés (mécanisme, pas politique).
+
+- Redaction in-place via le hook `_on_ending` (le seul moment où le span est
+  mutable — `on_end` reçoit un `ReadableSpan` immuable) : mutation directe de
+  `span._attributes` + reconstruction de `span._events` (les `Event` étant
+  immuables).
+- Order-indépendant : tous les `_on_ending` tournent avant tous les `on_end`,
+  donc l'exporter voit toujours le span redacté.
+- Extra `[tracing]` (subclasse `opentelemetry.sdk.trace.SpanProcessor`). Le test
+  d'intégration valide que le hook est appelé → fail-closed visible si une
+  version OTel le change (jamais d'export en clair silencieux).
+
+### Added — 2026-05-20 : `mic.observability.SanitizingMetricsBackend` (garde-fou labels, RDL-493)
+
+Décorateur `MetricsBackend` qui protège le TSDB Prometheus — pilier *Metrics*
+de la redaction MELT (épic RDL-488, complète `sanitize_payload` côté events) :
+
+- **Refus des labels sensitive/secret** (`denied_labels` injectés par le
+  consumer — mécanisme, pas politique, comme `TopicRedactionPolicy`) : un
+  `email`/`token`/`user_id` en label = fuite PII/secret dans les séries.
+- **Cap de cardinalité** par métrique (`max_cardinality`, défaut 10 000) :
+  garde-fou contre l'explosion de séries (OOM Prometheus). Les combinaisons
+  déjà vues continuent de passer ; les nouvelles au-delà du cap sont refusées.
+- **Deux modes** : `strict=True` (dev/CI) lève `MetricLabelViolation` ;
+  `strict=False` (prod) logge un warning, incrémente `mic_metric_labels_rejected_total{reason}`
+  (`denied_label` / `cardinality`) et **drop** l'émission fautive (jamais de
+  crash du hot path métier pour un souci d'observabilité).
+
+Import-safe (ne tire que `MetricsBackend`, pas `prometheus_client`).
+
+### Changed — 2026-05-20 : `TracingMiddleware` — `SpanKind.SERVER` + `http.route` (RDL-593 port)
+
+Port upstream depuis le middleware custom rdlink-api (RDL-513) :
+
+- Le span racine HTTP est désormais créé avec `kind=SpanKind.SERVER`
+  (sémantique span entrant — distingue le span serveur des spans clients
+  sortants dans le backend de traces).
+- Attribut `http.route` (template de route, ex. `/users/{id}`) posé quand
+  le framework l'a renseigné dans `scope["route"]` après match — permet de
+  grouper les spans par pattern plutôt que par path concret (avec IDs). Set
+  en `finally` (présent même sur exception) ; absent sans crash sur un 404
+  (pas de route) ou un scope sans `.path`.
+
+Rétro-compatible (attributs additifs ; passthrough inchangé sans OTel).
+
+### Added — 2026-05-20 : `mic.observability.metrics_backend` (MetricsBackend ABC + RDL-592)
+
+Harmonisation : `mic.observability` gagne l'abstraction backend des
+implémentations custom rdlink (api/sync/ai), en complément des wrappers
+thin Prometheus (`mic.observability.metrics`). Nouveau module
+`mic.observability.metrics_backend` :
+
+- `MetricsBackend` **ABC** — `increment` / `observe` (Summary) /
+  `set_gauge` / `observe_histogram` (Histogram agrégat server-side, fallback
+  `observe`) / `snapshot` / `render_prometheus`. Découple le call-site métier
+  du transport → un service injecte `InMemoryMetrics` en test, `Prometheus`
+  en prod.
+- `InMemoryMetrics` (accumulateur thread-safe, `snapshot()`), `StatsDMetrics`
+  (UDP push), `PrometheusMetrics` (registry `prometheus_client` lazy ;
+  Counter/Summary/Histogram/Gauge ; gauges auto `*_metrics_backend_info` +
+  `*_process_start_time_seconds`).
+- Type **Summary** (`observe` → quantiles client-side) distinct de
+  l'**Histogram** (`observe_histogram` → `histogram_quantile()` multi-replicas).
+- **SLO bucket defaults** `DEFAULT_LATENCY_BUCKETS` (5 ms → 10 s, cible
+  p95 < 200 ms / p99 < 500 ms).
+- **Sanitizers** (absorbe RDL-493) : `sanitize_metric_name` (namespace +
+  `.`/`-`/espaces → `_`), `sanitize_label_name`, `sanitize_labels` avec
+  allowlist `allowed=` — garde-fou anti high-cardinality. `PrometheusMetrics`
+  applique le filtre via `allowed_labels=`.
+
+InMemory/StatsD restent stdlib-only (pas d'extra requis) ; Prometheus tire
+`[observability]` en lazy à la construction.
+
+### Added — 2026-05-20 : `mic.ratelimit` couche policy déclarative (RDL-591)
+
+Harmonisation : `mic.ratelimit` gagne la couche policy déclarative des
+implémentations custom rdlink-api, tout en conservant son backend
+token-bucket robuste (anti clock-drift, EVALSHA, `TransientError`). Le
+module `mic.ratelimit.spec` ajoute :
+
+- `RateLimitSpec(bucket, requests_per_window, window_seconds, key)` —
+  politique lisible « N req / fenêtre », qui dérive ses paramètres
+  token-bucket (`capacity` = burst, `refill_per_second` = débit moyen).
+- `RateLimitRegistry` — map `route_name → spec` avec **fallback global**
+  (`default`) ; `lookup` (exact) vs `resolve` (avec fallback).
+- **Extracteurs d'identité composables**, framework-agnostiques (opèrent
+  sur un `KeyContext` headers/cookies/body/client_host/subject, pas sur
+  le scope ASGI brut) : `ip_key`, `subject_key`, `body_field_key`,
+  `cookie_key`, `header_key`, `static_key` + combinateurs
+  `first_available` (OR/fallback) et `combine` (AND). Retournent `None`
+  quand l'identité est non résolvable (politique « laisse passer » —
+  jamais de 429 forcé chez la victime).
+- `enforce(spec, context, *, limiter, cost=1)` — moteur pur : extrait
+  l'identité, namespace la clé (`bucket:identity`), délègue au backend.
+- `RateLimiter.try_consume` accepte désormais un **override per-call**
+  `capacity` / `refill_per_second` (rétro-compatible, `None` = défauts
+  constructeur) — un seul backend (client Redis partagé) sert toutes les
+  routes avec leurs politiques distinctes.
+
+Hors scope (reste app-spécifique) : la résolution métier de l'identité
+(lookup session depuis cookie, normalisation email OTP) se branche en
+amont via les extracteurs.
+
+### Added — 2026-05-20 : `mic.outbox.sanitize_payload` (redaction MELT par-topic)
+
+Mécanisme de redaction des payloads outbox pour l'observability
+(logs / traces / event-store public / audit long-terme), sans toucher
+au payload original qui sert à la livraison. La **politique** (quels
+champs, quelle stratégie) est config injectée par le consumer (dérivée
+de l'ADR data-classification MELT) — `mic.outbox` fournit l'outil, pas
+les listes PII app-spécifiques.
+
+- `sanitize_payload(event, *, policy)` → copie redacted (l'event
+  original n'est pas muté).
+- `TopicRedactionPolicy(default, per_topic)` : redactors par-field,
+  fusionnés (per_topic override default).
+- 3 redactors standard alignés sur les stratégies MELT :
+  `redact_drop` (secret → `[REDACTED]`), `redact_mask` (sensitive
+  traces → `***`), `redact_hash` (sensitive logs/events → blake2 court
+  corrélable). Réutilise `mic.observability.logging.apply_field_redactors`.
+
+Top-level only en V1 (les payloads outbox rdlink sont plats). Pur-stdlib
+(pas de dépendance à l'extra `[observability]`).
+
+### Added — 2026-05-20 : `mic.outbox` maturité V2 (lease-based claim + backoff + dédup temporel)
+
+Suite de l'harmonisation V1 (idempotency_key + priority). `mic.outbox`
+acquiert la maturité des implémentations outbox custom rdlink (api +
+sync) — objectif : devenir le store production-grade que les consumers
+peuvent adopter sans régression. Tout est rétro-compatible (defaults
+neutres ; `pending()` et le comportement at-least-once classique
+inchangés).
+
+**Lease-based claim** (`OutboxStore.claim` + `recover_expired_processing`) :
+
+- Nouveau `OutboxStatus.PROCESSING` + champ `OutboxEvent.next_run_at`.
+- `claim(*, limit, lease_ttl_seconds, now)` : passe les events
+  claimables en `PROCESSING` avec un lease (`next_run_at = now +
+  lease_ttl`). Sur SQL : `FOR UPDATE SKIP LOCKED` → multi-worker safe
+  (events disjoints). Impl par défaut dans l'ABC = fallback `pending()`.
+- `recover_expired_processing(*, now)` : leases expirés → `PENDING`
+  (reprise après crash worker). Impl par défaut = no-op.
+- `OutboxDispatcher(use_claim=True, lease_ttl_seconds=...)` : `run_once`
+  recover puis claim au lieu de `pending`.
+
+**Retry backoff + auto-DLQ** (`mark_failed`) :
+
+- `mark_failed(..., backoff_seconds=0, max_attempts=None)` : si
+  `backoff_seconds > 0`, l'event reste `PENDING` avec `next_run_at =
+  now + backoff` (re-claim différé) ; si `max_attempts` atteint, auto-DLQ
+  (terminal) sans que le dispatcher ait à gérer le cap.
+
+**Dédup temporel** (`enqueue(..., dedup_window_seconds=0)`) :
+
+- Si `> 0` et qu'un event de même `(aggregate_type, aggregate_id,
+  event_type)` existe dans la fenêtre, retourne l'existant (absorbe un
+  burst d'events identiques sans clé pré-calculée). Testé après
+  `idempotency_key`.
+
+Migration schéma (consumers SQL via Alembic) : 1 colonne supplémentaire
+`next_run_at` (TIMESTAMPTZ nullable) sur table `outbox`, + le status
+`processing` dans les valeurs possibles. `prepare()` (dev/tests) à jour.
+
+Hors scope (restent app-spécifiques) : workflow status `acked`/`published`,
+~30 routes admin CRUD, dispatchers spécialisés par topic.
+
+### Added — 2026-05-20 : `mic.outbox` harmonisation V1 (idempotency_key + priority)
+
+`OutboxEvent` gagne deux champs optionnels, rétro-compatibles (defaults
+neutres) :
+
+- **`idempotency_key: str | None = None`** — dédup côté **producteur**.
+  Quand `enqueue` reçoit un event dont la clé existe déjà dans le store,
+  il retourne l'event EXISTANT au lieu d'insérer un doublon (insert
+  idempotent). Implémenté sur `SqlOutboxStore` (SELECT-before-INSERT
+  partagé avec la session de l'enqueue → dédup atomique) et
+  `InMemoryOutboxStore`. La colonne SQL porte une contrainte `UNIQUE`
+  (plusieurs `NULL` permis — events sans clé ne collisionnent jamais).
+- **`priority: int = 100`** — ordre de drain. **Plus bas = dispatché en
+  premier** (convention nice/cron) ; à priorité égale, FIFO `created_at`.
+  Tant que tous les events gardent le défaut 100, l'ordre reste
+  strictement FIFO (rétro-compat). `pending()` ordonne désormais par
+  `(priority, created_at)` côté SQL et `(priority, insertion)` côté RAM.
+
+Motivation : aligner `mic.outbox` sur les besoins réels des consumers
+(rdlink-api avait ces deux features inline sur 14 producers). Le swap
+d'un store custom vers `mic.outbox.SqlOutboxStore` devient nettement
+moins lossy. Hors scope V1 (restent app-spécifiques) : workflow status
+enrichi (`processing`/`published`), `dedup_window_seconds` temporel,
+retry backoff `next_run_at`.
+
+Migration schéma : 2 nouvelles colonnes nullables sur la table `outbox`
+(`idempotency_key` UNIQUE indexée, `priority` indexée default 100). Pas
+de backfill requis (defaults). Pour les apps Alembic : ajouter une
+migration ; `prepare()` (dev/tests) crée le schéma à jour.
+
+### Added — 2026-05-19 : `mic.auth.ServiceAuthSigner.sign(extra_claims=...)`
+
+`ServiceAuthSigner.sign()` accepte un paramètre optionnel
+`extra_claims: dict[str, Any] | None` pour embedder des claims JWT
+additionnels aux côtés du jeu standard (`iss`, `aud`, `iat`, `exp`,
+`sub`, `jti`). Use case canonique : propager une identité applicative
+secondaire (`profile_id`, `tenant_id`, `role`) pour que le consumer
+puisse skipper un lookup DB sur les hot paths.
+
+Sécurité : toute tentative d'override d'un claim réservé (`iss`,
+`aud`, `iat`, `exp`, `sub`, `jti`, `nbf`) via `extra_claims` lève
+`ValueError` au site d'appel — un override silencieux permettrait à
+un caller de forger `aud`, faussement étendre `exp`, etc.
+
+`ServiceAuthClaims` gagne un champ `extra: dict[str, Any] = {}` que
+`ServiceAuthVerifier.verify()` peuple avec les claims non-standard.
+Les tokens signés avec la version antérieure (sans extra_claims)
+round-trippent avec `extra == {}`.
+
+### BREAKING — 2026-05-17 : HTTP framework adapters reorganised
+
+The FastAPI and Litestar integration code has been moved out of
+`mic.http.*` into dedicated opt-in packages :
+
+- `mic.http.fastapi_adapter` → `mic.fastapi.router`
+- `mic.http.fastapi_middlewares` → `mic.fastapi.middlewares`
+- `mic.http.litestar_adapter` → `mic.litestar.router`
+- `mic.http._resolve` → `mic.fastapi._resolve` + `mic.litestar._resolve`
+  (per-package copy ; the module is private to each adapter)
+
+The top-level convenience exports (`build_fastapi_router`, the three
+middlewares, `build_litestar_router`) are now available via lazy
+loading from `mic.fastapi` and `mic.litestar` :
+
+```python
+# Before
+from mic.http.fastapi_adapter import build_fastapi_router
+from mic.http.fastapi_middlewares import ServiceAuthMiddleware
+
+# After
+from mic.fastapi import build_fastapi_router, ServiceAuthMiddleware
+```
+
+The `[fastapi]` and `[litestar]` extras are kept (still pull `fastapi`
++ `uvicorn` / `litestar` respectively). They guard the OPT-IN packages
+so a consumer who imports nothing from `mic.fastapi.*` / `mic.litestar.*`
+never pulls those framework deps transitively.
+
+**Rationale** : MIC dependency-inversion principle. `mic.http`
+exposes only framework-agnostic primitives (`HttpRouteSpec`,
+`HttpResponseSpec`, `HttpCookieSpec`, `HttpRequestContext`,
+`HttpHandler`). The framework-specific code lives in clearly-named
+sibling packages — a consumer who uses neither FastAPI nor Litestar
+never imports a single line of framework code.
+
+**Migration** : substitute the import paths as shown above. No code
+changes — the symbols themselves (`build_fastapi_router`, middleware
+class names, signatures) are unchanged. ~5 minutes per service.
+
+The cookiecutter template under `template/` still references the old
+import paths and is currently broken until a refonte commit lands —
+documented at the top of the template files.
+
+### Added
+
+**Core — HTTP, contracts, auth**
+
+- `mic.contracts` — `StrictSchema` (Pydantic v2, `extra=forbid`,
+  `frozen=True`), `HttpSuccessEnvelope[T]`, `wrap_http_success()`.
+- `mic.model` — `DomainError(code, message, details)` + `TransientError`
+  (machine-readable, 4xx vs 503 mapping).
+- `mic.http` — framework-agnostic `HttpRouteSpec` / `HttpResponseSpec` /
+  `HttpCookieSpec` / `HttpRequestContext` primitives. `HttpResponseSpec`
+  exposes an optional `cookies: tuple[HttpCookieSpec, ...]` field;
+  `HttpCookieSpec` defaults to `HttpOnly + Secure + SameSite=Lax +
+  Path=/` — the combination that covers 99 % of well-secured
+  session/auth cookies. Common patterns (clear-cookie on logout,
+  double-submit CSRF token with `httponly=False`, refresh-token with
+  `Path=/auth/refresh`, cross-domain federation with
+  `samesite="none"`) are expressed as declarative spec ; consumers
+  materialise them when translating `HttpResponseSpec` to their
+  framework response.
+- `mic.http.bearer` — `parse_bearer_token(header)` : extract a Bearer
+  JWT from an `Authorization` header (RFC 6750, scheme case-insensitive).
+- `mic.http.basic_auth` — `parse_basic_auth(header) -> (username,
+  password)` : decode Basic Auth credentials (RFC 7617, UTF-8). Strict
+  base64 validation (rejects crafted payloads with invalid chars);
+  password can be empty (caller decides semantic).
+- `mic.http.api_key` — `parse_api_key(header, scheme=None)` : extract
+  an API key. Default `scheme=None` treats the header value as the key
+  itself (`X-API-Key` pattern, à la Stripe / OpenAI). With `scheme="ApiKey"`
+  (or any custom name), expects `Authorization: ApiKey <key>` format.
+- `mic.grpc.make_authed_channel` — new `subject_provider:
+  Callable[[], str | None] = None` kwarg for end-user delegated auth.
+  When set, the interceptor calls it per-RPC to resolve the `sub`
+  claim ; pattern : the caller's HTTP middleware sets `user_id` in a
+  ContextVar, the `subject_provider` reads it at the outbound RPC
+  moment. The downstream service then logs the operation with the
+  real user identity, not just the calling service's. Default `None`
+  = JWT without `sub` (service-to-service pure).
+- `mic.idempotency.IdempotencyStore` — fusion of the single-flight
+  Stripe-style pattern with the "check-then-act with payload-hash
+  mismatch detection" pattern :
+  - `IdempotencyRecord.payload_hash: str | None` (new optional field,
+    backward-compatible — legacy records without the field still
+    dedupe).
+  - `IdempotencyAttempt.mismatch: bool` (new) — set when
+    `acquire_or_replay` observes a cached record whose stored
+    `payload_hash` differs from the caller-provided one. No lock is
+    acquired in that case ; the caller returns 409 Stripe-style.
+  - `IdempotencyDecision(outcome, record)` dataclass — return type of
+    the new `evaluate(key, *, payload_hash=None)` method, a check-only
+    path that does not acquire a lock (caller composes their own
+    persistence — accepts the TOCTOU race window).
+  - `compute_payload_hash(payload)` — SHA-256 canonical (json.dumps
+    sort_keys + tight separators) helper, exposed for callers that
+    want to compute the hash themselves.
+- `mic.fastapi.MetricsMiddleware` + `mic.litestar.MetricsMiddleware` —
+  measure latency + status per request and delegate the emission to a
+  consumer-injected `MetricsRecorder` (Protocol with one method:
+  `record(method, route, status, duration_seconds)`). Route label
+  defaults to `"unknown"` when no template matched, to keep
+  cardinality bounded for Prometheus. The middleware is a no-op when
+  `recorder=None`, useful for test harnesses that don't wire a backend.
+- `mic.http.csrf` — framework-agnostic CSRF double-submit cookie/header
+  engine: `CsrfPolicy` (overrideable header/cookie names + auth-cookie
+  list + exempt paths/prefixes + protected methods), `CsrfDecision`
+  dataclass with `outcome` (proceed/exempt/reject) + machine-readable
+  `reason`, pure `evaluate_csrf(...)` helper. Adapters
+  `mic.fastapi.CsrfMiddleware` + `mic.litestar.CsrfMiddleware`
+  materialise the engine output ; the 403 response shape is decided
+  by the consumer via an `on_reject(request, reason)` callback —
+  mic stays agnostic of the envelope catalog.
+- `mic.http.HttpRouteSpec.auth: AuthMode = AuthMode.PUBLIC` — optional
+  per-route auth mode declaration, consumed by
+  `mic.fastapi.AuthGateMiddleware` / `mic.litestar.AuthGateMiddleware`
+  via `build_auth_policy(route_modes={(r.method, r.path): r.auth for r in routes})`.
+  Default ``PUBLIC`` is backward-compatible — consumers that don't use
+  the gate auth ignore the field (just an extra frozen attribute on
+  the dataclass).
+- `mic.http.correlation` — framework-agnostic HTTP correlation engine:
+  `CorrelationSpec` (overridable header names + ID factories),
+  `CorrelationStart` / `CorrelationFinish` dataclasses, pure
+  `start_correlation(...)` / `finish_correlation(...)` helpers.
+  Adapters `mic.fastapi.CorrelationMiddleware` +
+  `mic.litestar.CorrelationMiddleware` materialise the engine output
+  on the request (`request.state.{correlation_id,request_id,duration_ms}`)
+  and the response headers (`X-Correlation-Id`, `X-Request-Id`,
+  `X-Response-Time-ms` defaults). Optional `on_start` callback lets
+  the consumer propagate the ids into its structured logger
+  context-var (mic stays agnostic of the logger).
+- `mic.http.auth_gate` — framework-agnostic per-route auth gate
+  engine : `AuthMode` (PUBLIC / USER / ADMIN / SERVICE), `AuthDecision`,
+  `AuthPolicy`, `evaluate_auth()`, `build_auth_policy()`. Sister
+  primitive to `mic.fastapi.ServiceAuthMiddleware`, but for the
+  matricial case (every route declares its own auth mode, multiple
+  credential sources : cookie + bearer, role check + crypto verify
+  via opt-in callbacks). Adapters `mic.fastapi.AuthGateMiddleware`
+  and `mic.litestar.AuthGateMiddleware` materialise the decision into
+  an HTTP response via consumer-provided `on_missing_credentials` /
+  `on_forbidden` callbacks — mic does not impose an error body shape
+  (the consumer keeps its envelope catalog).
+- All 4 parsers emit `DomainError` with categorised codes
+  (`service_auth.invalid_header`, `basic_auth.invalid_header`,
+  `api_key.invalid_header`) — middlewares map them to HTTP 401 +
+  `WWW-Authenticate` header. The parsing is purely transport — secret
+  verification (constant-time compare against a hash, DB lookup,
+  rate-limit per key, etc.) stays on the caller.
+- `mic.auth` — `ServiceAuthSigner` / `ServiceAuthVerifier`: HS256
+  audience-bound JWT with double-key rotation and an issuer whitelist.
+  The verifier iterates all secrets (timing-safe) and never leaks the
+  underlying PyJWT message or the issuer whitelist back to the caller.
+  `sign()` auto-generates a unique `jti` claim (RFC 7519 §4.1.7) per
+  token via `uuid.uuid4().hex` (128 bits of entropy), with an optional
+  override for advanced use cases (deterministic test fixtures, trace-id
+  propagation). `ServiceAuthClaims.jti` is exposed so consumers can do
+  per-token revocation through `RevokeBlacklist.revoke_jti(claims.jti,
+  ttl=remaining_lifetime)` without coordination signer↔caller. Legacy
+  tokens emitted by services that don't propagate `jti` still verify
+  (the claim stays `None`).
+- `mic.auth` — `RevokeBlacklist`: revocation tracker for short-lived
+  JWTs backed by any `CacheBackend`. Two complementary patterns —
+  per-`jti` (single-token revoke, e.g. logout-this-device or refresh
+  rotation) and per-subject revoke-epoch (mass revocation, e.g.
+  "logout everywhere" or password change). Auto-cleanup via TTL
+  (Redis EXPIRE), O(1) per check. Decoupled from `ServiceAuthVerifier`
+  so the verifier stays stateless and the blacklist stays optional.
+- `mic.client` — `ServiceHttpClient`: thin httpx wrapper with
+  auto-signing and canonical error mapping.
+- `mic.client` — `AsyncServiceHttpClient`: async-native variant of
+  `ServiceHttpClient`, built on `httpx.AsyncClient`. Same contract
+  (auto JWT signing, 4xx→`DomainError`, 5xx/network/timeout→
+  `TransientError`, optional `CircuitBreaker.async_call`, optional
+  `Idempotency-Key` factory, W3C trace-context propagation). Async
+  lifecycle (`aclose()` / `__aenter__` / `__aexit__`). For BFFs and
+  async-native services that fan out via `asyncio.gather` instead of
+  `ThreadPoolExecutor`.
+- `mic.cli` — `CliCommandSpec`, `build_parser()`, `dispatch()`:
+  argparse-based operator CLI scaffold (stdlib only).
+
+**Data — storage, caching, sharding**
+
+- `mic.datastorage` — `DataStorage` ABC (mandatory lifecycle: `check_health` /
+  `prepare` / `dispose`) + optional capability mixins
+  (`KeyValueCapability` / `DocumentCapability` / `GraphCapability`).
+  Implementations: `SqlDataStorage` (SQLModel), `DocumentDataStorage` (MongoDB),
+  `GraphDataStorage` (Neo4j), `InMemoryKeyValueDataStorage`,
+  `InMemoryDocumentDataStorage`.
+- `mic.cache` — `CacheBackend` ABC + `InMemoryCache`, `RedisCache`,
+  `RedisClusterCache` (with `ConsistentHashRing`).
+- `mic.response_cache` — ASGI middleware: HTTP response caching with
+  ETag, cache-stampede protection, and SHA-256 vary keys (length-prefixed
+  per field to prevent cross-user key collisions).
+- `mic.read_models` — denormalised CQRS read-model helpers (Timeline,
+  Counter, Leaderboard, Membership, UniqueCount).
+- `mic.shard` — application-level Postgres sharding (`ShardSelector`,
+  `ShardedSessionFactory`).
+
+**Messaging — events, queues, realtime**
+
+- `mic.eventbus` — `EventBus` ABC: sync pub/sub (`InMemoryEventBus`,
+  `RedisStreamsEventBus`).
+- `mic.queue` — `AsyncEventBus` ABC: durable async pub/sub
+  (`NATSEventBus`, `KafkaEventBus`, in-memory) with per-message ack.
+- `mic.realtime` — WebSocket fan-out: `RealtimeBackend` ABC (in-memory /
+  Redis Streams), `Room`, audience-bound WebSocket authenticator.
+- `mic.outbox` — transactional outbox pattern: `OutboxStore` ABC +
+  `OutboxDispatcher` with at-least-once delivery, a capped retry budget
+  (`max_attempts` → dead-letter), a transient-exception whitelist, and
+  Prometheus counters.
+
+**Reliability — resilience, rate limiting, idempotency, locking**
+
+- `mic.resilience` — `CircuitBreaker` (sync + async). Half-open state
+  admits exactly one probe at a time; concurrent calls are rejected
+  rather than amplified onto a still-failing upstream.
+- `mic.ratelimit` — `RateLimiter` ABC: token bucket. `RedisRateLimiter`
+  derives time from the Redis server clock (`redis.call('TIME')`), so a
+  replica with a skewed wall clock cannot bypass the limit.
+- `mic.idempotency` — `IdempotencyStore` with a single-flight
+  `acquire_or_replay` / `complete` / `fail` API (a distributed lock
+  closes the check-then-act window, so concurrent requests with the
+  same `Idempotency-Key` run the handler exactly once).
+- `mic.locking` — `DistributedLock` ABC: `InMemoryDistributedLock` and
+  `RedisDistributedLock` (Redlock-style `SET NX` + Lua-atomic release).
+
+**Policy & observability**
+
+- `mic.authz` — `AuthorizationEngine` ABC: inline RBAC, OPA Rego,
+  OpenFGA ReBAC.
+- `mic.feature_flags` — `FeatureFlagEngine` ABC: in-memory, Unleash,
+  GrowthBook.
+- `mic.observability` — `configure_logging()` (JSON / text, idempotent,
+  with automatic OpenTelemetry `trace_id` / `span_id` injection when a
+  span is active) + idempotent Prometheus `counter()` / `gauge()` /
+  `histogram()` + opt-in Sentry helper + OpenTelemetry tracing.
+- `mic.healthcheck` — `ReadinessChecker` and probes; distinguishes
+  `/health` (liveness) from `/ready` (dependency readiness).
+
+**Transports**
+
+- `mic.grpc` — `GrpcServiceSpec`, server + client builders, audience-bound
+  auth interceptor, gRPC health-check service.
+- `mic.graphql` — `GraphqlSchemaSpec`, Strawberry code-first schema +
+  ASGI mount + audience-bound auth extension.
+
+**Packaging & tooling**
+
+- Every optional integration sits behind a `pip` extra; a bare
+  `pip install mic-struct` pulls only Pydantic. Importing any
+  `mic.<package>` is safe even when its extra is not installed —
+  the missing-dependency error is raised (with a clear `pip install`
+  hint) only when a dependency-backed symbol is actually used.
+- Cookiecutter scaffold under `template/` — answer 3 questions, get a
+  complete FastAPI or Litestar service that passes `make gate` at 100 %
+  coverage on the first run.
+- Quality gate: `black`, `ruff` (incl. `PT011` — every `pytest.raises`
+  needs a `match=`), `mypy --strict`, `bandit`, `pip-audit`, a
+  documentation-drift lint, and 100 % line + branch test coverage
+  (1124 tests). Mutation testing and performance benchmarks run in
+  nightly CI.
+- Python 3.14, MIT-licensed.

mic_struct-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mic-struct contributors
+
+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.