Adaptateurs HTTP¶

Les adaptateurs HTTP matérialisent la frontière entre le métier et le serveur web. Les modules déclarent des routes MIC ; l'adaptateur choisi traduit les requêtes du framework en entrées métier, puis les réponses et erreurs MIC en réponses HTTP.

MIC fournit deux familles de contrats distinctes, adaptées à leur langage :

Python — mic.http.HttpRouteSpec, servi par FastAPI ou Litestar ;
Node.js / TypeScript — @mic-struct/mic-core HttpRouteSpec, servi par Node HTTP, Express, Fastify, Hono ou NestJS.

Les API Python et TypeScript ne sont pas interchangeables. Elles appliquent la même règle d'architecture : le handler dépend du contrat MIC, jamais d'un objet Request ou Response propre au framework.

Garanties de la frontière¶

Quel que soit l'environnement d'exécution, l'adaptateur prend en charge :

la correspondance entre méthode, chemin et paramètres de route ;
la lecture des paramètres, en-têtes et cookies dans un contexte MIC ;
la validation des entrées déclarées ;
l'appel des handlers synchrones ou asynchrones ;
la sérialisation des réponses et des erreurs canoniques ;
les mécanismes transverses configurés, comme l'authentification et la corrélation.

Le métier reste ainsi testable sans démarrer de serveur HTTP. Les détails d'analyse, de cycle de vie et d'intégration au framework restent dans l'adaptateur.

Python : FastAPI et Litestar¶

mic.http expose HttpRouteSpec, HttpResponseSpec et HttpRequestContext. Les fonctions build_fastapi_router et build_litestar_router servent le même tuple de routes :

from fastapi import FastAPI
from mic.contracts import StrictSchema, wrap_http_success
from mic.fastapi import build_fastapi_router
from mic.http import HttpResponseSpec, HttpRouteSpec


class CreateItemPayload(StrictSchema):
    name: str


def create_item(*, payload: CreateItemPayload) -> HttpResponseSpec:
    return HttpResponseSpec(
        status_code=201,
        body=wrap_http_success({"name": payload.name}),
    )


routes = (
    HttpRouteSpec(
        method="POST",
        path="/items",
        name="items.create",
        category="items",
        handler=create_item,
    ),
)

app = FastAPI()
app.include_router(build_fastapi_router(routes=routes))

Le passage à Litestar remplace le builder et le montage du routeur ; les routes et les handlers ne changent pas. Les deux adaptateurs résolvent les arguments attendus par la signature du handler : contexte, payload validé, paramètres de chemin et paramètres de requête.

Les dépendances restent optionnelles : installer mic-struct[fastapi] ou mic-struct[litestar] selon le serveur retenu.

Node.js : cinq intégrations¶

@mic-struct/mic-core expose le helper route() et les contrats HTTP TypeScript. Le handler reçoit un objet normalisé { params, query, body, context } :

import { ok, route } from "@mic-struct/mic-core"
import { createNodeHttpServer } from "@mic-struct/mic-node-http"

const health = route({
  method: "GET",
  path: "/health",
  name: "system.health",
  category: "system",
  handler: ({ context }) => ok({ status: "ok", requestId: context.requestId }),
})

createNodeHttpServer({ routes: [health] }).listen(3000)

Les mêmes routes peuvent être montées avec l'adaptateur qui correspond à l'application :

Node HTTP — @mic-struct/mic-node-http : createNodeHttpServer ou createNodeHttpHandler ;
Express — @mic-struct/mic-express : createExpressMicApp ou registerMicRoutes ;
Fastify — @mic-struct/mic-fastify : createFastifyMicApp ou registerMicRoutes ;
Hono — @mic-struct/mic-hono : createHonoMicApp ou registerMicRoutes ;
NestJS — @mic-struct/mic-nest : MicNestModule.forRoot.

Les constructeurs create* créent une application complète. Les fonctions registerMicRoutes ajoutent les routes à une application Express, Fastify ou Hono existante. L'adaptateur NestJS crée des contrôleurs à partir des routes MIC et s'appuie sur @nestjs/platform-express.

Parité et différences assumées¶

La parité se vérifie dans chaque environnement d'exécution :

en Python, une suite commune exécute les mêmes scénarios sur FastAPI et Litestar ;
en Node.js, chaque paquet vérifie le contrat partagé, et les tests démarrent aussi de vrais serveurs HTTP pour les intégrations aux frameworks.

La parité ne signifie pas que les frameworks deviennent identiques. Le format des chemins, l'analyse du corps, l'ordre des composants intermédiaires, les réponses 404 et le cycle de vie de l'application restent des responsabilités propres à l'adaptateur ou à l'application hôte.

Choisir un adaptateur¶

Utiliser d'abord le framework déjà standard dans le service. Pour un nouveau service, décider à partir de contraintes explicites : écosystème requis, mode d'intégration dans une application existante, modèle d'exécution, stratégie de tests et exploitation. Le contrat MIC permet ensuite de changer d'adaptateur dans le même environnement d'exécution sans réécrire le métier.

Pour construire un premier service, suivre le quickstart Python ou le quickstart Node.js / TypeScript.