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

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=user@example.com

# 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) :

⚠️ 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]"

Contrats gouvernés

SchemaRegistry construit un StrictSchema à partir de FieldDef chargés depuis une source de vérité versionnée. Le modèle reste immuable et refuse les champs inconnus. Le cache TTL évite de reconstruire le modèle à chaque requête ; un événement distribué appelle registry.invalidate(key) sur chaque instance, et le TTL sert de filet de rattrapage si cet événement est perdu.

from mic.contracts import FieldDef, SchemaRegistry

registry = SchemaRegistry(
    loader=lambda key: (
        FieldDef("cluster", str),
        FieldDef("replicas", int, default=1),
    ),
    ttl=300,
)
Payload = registry.get("deployment@v2")
payload = Payload.model_validate({"cluster": "prod", "replicas": 3})

Isolation par organisation

TenantScopedRelationalStore injecte le filtre d'organisation dans les lectures et comptages, contrôle les insertions et refuse toute opération hors d'un tenant_context. Le repository métier doit recevoir cette vue sécurisée, jamais le store brut.

from mic.tenancy import TenantScopedRelationalStore, tenant_context

store = TenantScopedRelationalStore(raw_store)
with tenant_context(organization_id):
    rows = store.find(Project, query)

Le champ est organization_id par défaut (tenant_field permet de l'adapter). Un filtre explicite sur ce champ est refusé : sa gestion appartient au store et ne peut pas être neutralisée par l'appelant.

Jetons de service à portée limitée

ServiceAuthSigner.sign(scopes=[...]) encode le claim JWT standard scope. ServiceAuthVerifier.verify() expose les valeurs dans claims.scopes, tandis que require(token, scope=...) exige une correspondance exacte et renvoie une erreur 403 service_auth.insufficient_scope si le service authentifié n'a pas la permission demandée. Les tokens historiques sans scope restent valides pour verify() ; les opérations protégées doivent appeler explicitement require().

Extras

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).