mic-core 0.1.11

MIC — fondations agnostiques (contracts, model, http, auth, client, observability, healthcheck, resilience, cli, grpc).

mic-core

Fondations agnostiques du framework MIC (Model / Interface / Controller). mic-core est le socle : il ne dépend d'aucune brique de persistance ni de plateforme (voir le DAG platform → data → core dans ../README.md).

Modules

Module	Rôle
mic.contracts	Contrats / DTO partagés inter-couches
mic.model	Erreurs de domaine (DomainError, TransientError), value objects
mic.http	Spécifications HTTP agnostiques (HttpRouteSpec, HttpResponseSpec, HttpCookieSpec, HttpRequestContext)
mic.fastapi	Adaptateur FastAPI (router builder, middlewares) — extra [fastapi]
mic.litestar	Adaptateur Litestar — extra [litestar]
mic.auth	JWT service-to-service (signer/verifier) — extra [auth]
mic.client	Client HTTP inter-services (httpx) — extra [client]
mic.observability	Logs JSON, métriques Prometheus, traces OTel — extra [observability] / [full-observability]
mic.healthcheck	Sondes liveness/readiness
mic.resilience	Circuit breaker, retry, timeouts
mic.cli	Squelette CLI (argparse stdlib) — extra [cli]
mic.grpc	Transport gRPC — extra [grpc]
mic.event_replay	Replay d'events archivés vers un bus (CLI mic-events-replay)

Le paquet est un namespace PEP 420 (pas de mic/__init__.py) : import mic.* reste identique côté consommateur, qu'on installe mic-core seul ou avec mic-datastore / mic-platform.

Replay d'events (mic-events-replay)

Rejoue des events archivés (DLQ outbox exportée en JSON, ou archive ClickHouse long-terme) vers un sink. Cas d'usage : audit forensic, bug-fix rétroactif (un handler a swallow des events pendant N heures → on les rejoue après fix), amorçage d'un nouveau read-model depuis l'historique.

# Dry-run (compte uniquement) depuis un dump JSON
mic-events-replay --from-json dump.json \
  --topic mail.send --from 2026-06-22T08:00:00Z --to 2026-06-22T10:00:00Z

# Source ClickHouse + filtre payload (répétable)
mic-events-replay --from-clickhouse http://clickhouse.svc:8123 \
  --topic mail.send --from 2026-06-22T08:00:00Z --to 2026-06-22T10:00:00Z \
  --filter to_email=[e-mail]

# Sink NATS JetStream (republie avec header x-replay) — extra mic-datastore[nats]
mic-events-replay --from-clickhouse http://clickhouse.svc:8123 \
  --topic mail.send --from ... --to ... \
  --to-nats nats://nats-0:4222,nats://nats-1:4222 --nats-stream events

Sinks : aucun = dry-run ; --target module:callable = callback sync ; --to-nats = NATS JetStream. Exit 0 = OK, 1 = aucun event matché (topic/range mal pinnés ?), 2 = erreur de setup.

Convention header x-replay

Chaque event republié via --to-nats porte deux headers transport (le payload n'est pas réécrit — flag transparent) :

Header	Valeur
x-replay	true
x-replay-batch-id	UUID unique par invocation (corrélation / traçabilité)

⚠️ Les consumers doivent être idempotents — un replay redélivre des events déjà traités. Un consumer idempotent (clé dérivée de event_id / original_id, ou opérations naturellement idempotentes) absorbe les replays sans effet de bord ; le header x-replay lui permet en plus de tracer ou ignorer explicitement un replay sans changer son décodage de payload. Le support des headers est fourni par mic.queue (cf. mic-datastore).

Installation

pip install "mic-core[fastapi,auth,client,observability]"

Extras

Extra	Tire
fastapi	fastapi + uvicorn[standard] + starlette
litestar	litestar
auth	pyjwt
client	httpx
observability	prometheus-client + opentelemetry-api
sentry	sentry-sdk (+ urllib3 patché)
tracing	opentelemetry-sdk + exporter OTLP
full-observability	observability + sentry + tracing
grpc	grpcio + grpcio-health-checking
cli	(rien — argparse stdlib)

Versionnage

mic-core démarre en 0.x (pré-releases dev/rc sur TestPyPI). Il graduera en 1.0 une fois les frontières prouvées et les services migrés (fin du split, cf. ADR-0001). En 0.x, un bump minor peut porter un changement cassant (SemVer 0.x) — contraindre avec >=0.1,<1.

Release

Voir ../../RELEASING.md § « Release par paquet » (make release-pkg PKG=core VERSION=x.y.z → tag core-vX.Y.Z).