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

La page Hors périmètre précise les responsabilités que MIC laisse durablement à l'application, à l'infrastructure ou à un produit spécialisé. Le guide Quitter MIC documente comment remplacer les contrats et adaptateurs du cœur sans changer les contrats publics du service.

Prérequis Python

mic-core exige Python 3.14 ou une version ultérieure. CPython 3.14 est la cible actuellement qualifiée par un gate CI bloquant ; Python 3.13 et les versions antérieures ne sont pas pris en charge. Consultez la politique Python avant une adoption sur un hébergement dont l'environnement d'exécution ou l'image de base n'est pas sous votre contrôle.

Erreurs HTTP décidables

Les adaptateurs FastAPI et Litestar exposent DomainError avec une enveloppe canonique contenant retryable: false; TransientError produit retryable: true. Les clients MIC donnent priorité à ce booléen avant leur repli sur le statut HTTP. Le guide de reprise HTTP détaille le contrat et la règle d'idempotence.

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 trois 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 x-original-event-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).