Service gRPC — un point d'entrée déclaré par un module, servi par le pipeline
accepted
Summary. Nodefony applications needed to serve gRPC without a second server, a second port or a second authorization path. This ADR decides that a gRPC service is declared by a module as a dedicated controller (
GrpcController+@GrpcService(Contract)): each method of the contract is a route of the existing HTTP pipeline, so the firewall,@IsGranted, CORS, logging and graceful shutdown apply unchanged. For a user, gRPC, gRPC-Web and Connect are served on the ports the application already listens on (native gRPC over HTTP/2), refusals and errors reach the client as proper gRPC statuses, and an application that declares no service installs and loads nothing. The surface is@experimental: it may change in a minor release.
Cet ADR porte le pourquoi ; le comment — déclarer un service, générer le code, l’appeler — est dans le guide Service gRPC.
Statut#
Accepté (2026-11-11). Treize décisions (D1 à D13), chacune avec sa ligne datée, relues côte à côte
avec ADR-0021 et ADR-0022. Annoncé par ADR-0021.
Jugé contre le catalogue scenarios/grpc.md : matrice en fin de document.
La surface naît @experimental (politique de compatibilité,
« Surfaces expérimentales »).
Précise deux ADR acceptés, par une ligne datée dans chacun (2026-11-11) :
- ADR-0021 : le transport se charge au démarrage quand un service est déclaré, et non au premier appel (D12) ; à l’arrêt, les flux longs (SSE, octets, gRPC) reçoivent une fin au lieu d’être détruits (D8) ; le pont vers le hub hérite d’une sérialisation par appel (« Contrôle de non-blocage », plus bas).
- ADR-0022 : gRPC n’amène protobuf qu’en pair facultatif de http et
framework, jamais au client ; la preuve « poids de protobuf dans
nodefony/client» ne lui revient pas (D12).
Contexte#
Une preuve de concept a servi un service gRPC dans le pipeline HTTP/2, sans second serveur, par un
contrôleur écrit à la main, depuis retiré : une route
bodyStream, le délai par flux désarmé, l’adaptateur @connectrpc/connect-node chargé au premier
appel et appelé sur la requête et la réponse brutes de Node. Une application ne doit pas réécrire
ce geste : elle DÉCLARE un service, le framework le sert sur ses ports (5152 TLS, 5153 h2c ; 5151
pour gRPC-Web et Connect), sous le pare-feu.
ADR-0021 a déjà rangé les morceaux : le transport (adaptateur, corps en flux, délai désarmé,
statut dans les trailers) est une primitive de @nodefony/http, au rang de SseStream ; le
pont vers le hub vit dans @nodefony/realtime.
Normes et antériorités#
Corpus hors ligne : .claude/skills/nodefony-rfc/references/grpc/ (index README.md).
- gRPC sur HTTP/2 (
grpc-PROTOCOL-HTTP2.md) :Path → ":path" "/" Service-Name "/" {method name}— la clé d’aiguillage d’un appel est dans l’URL, sensible à la casse ; le statut part toujours dans les trailers ; une erreur immédiate est une réponse Trailers-Only ; uncontent-typequi ne commence pas parapplication/grpcreçoit 415. - Protocole Connect (
connect-protocol.md) : unaire enPOST, ou enGETpour les seules méthodes annotéesidempotency_level = NO_SIDE_EFFECTS. - Correspondance HTTP → gRPC (
grpc-http-grpc-status-mapping.md) : un client qui reçoit un statut HTTP autre que 200 le traduit (401 →UNAUTHENTICATED, 403 →PERMISSION_DENIED) — un serveur conforme rend lui-même le statut gRPC. - Intercepteurs et porte d’entrée de connect-node (
connect-node-interceptors.md) :requestGatedécide avant la lecture du corps. Écarté par D5 (point 2) : le pipeline de Nodefony décide déjà avant la lecture du corps, et un seul écrivain rend tous les refus. - Antériorités (relues aux sources le 2026-11-11) : trois familles de frameworks serveur. Une ligne d’enregistrement explicite de la classe de service ; une annotation à nom figé sur la classe, en singleton, le contexte de requête actif pendant l’appel ; un contrôleur dont les méthodes portent un décorateur de méthode gRPC. Dans les trois, l’autorisation déclarative de la classe ou de la méthode, et les gardes des routes HTTP, s’appliquent à l’appel gRPC.
- Bornes par défaut des implémentations de référence : 4 Mio par message reçu, aucune borne à
l’émission (grpc-go,
server.go; grpc-js,constants.js).
Le même critère range les autres protocoles du framework : la clé d’un appel MCP est dans le
corps JSON-RPC, sur une seule route (crochet de module getMcpTools, ADR-0017) ; celle d’une action
temps réel est dans la trame (RealtimeController). Celle d’un appel gRPC est dans le CHEMIN :
une méthode gRPC est une route.
Décisions#
D1 — La forme de la déclaration#
Décision (2026-11-11) : le point d’entrée d’un service gRPC est un contrôleur dédié,
classe qui étend GrpcController (base fournie par @nodefony/framework, jumelle de
RealtimeController), marquée par le décorateur à nom figé @GrpcService(Contrat) (le descripteur
généré par buf), et déclarée par @controllers([...]) comme tout point d’entrée du module. La
logique métier vit dans un service injectable, que le point d’entrée appelle — le découpage
déjà en usage pour HTTP et le temps réel.
@GrpcService(EchoService)
export class EchoController extends GrpcController {
constructor(
context: ContextType,
@Inject("echo") private readonly echo: EchoBusiness,
) {
super("EchoController", context);
}
@IsGranted("ROLE_ECHO")
say(request: SayRequest, ctx: HandlerContext) {
return this.echo.say(request.sentence);
}
}
@controllers([EchoController])
class Echo extends Module {}
Ce que la forme engage :
- Une route littérale du Router par méthode du contrat,
POST /<paquet.Service>/<Méthode>, etGETen plus pour une méthodeNO_SIDE_EFFECTSseulement. Le pare-feu,@IsGranted,@RequireAuthentication,@Scope, les hôtes virtuels, le profileur et la liste des routes s’appliquent sans code neuf — une seule implémentation de l’autorisation (Resolver.ts#Resolver._enforceSecurity), comme le pontapi.requestdu temps réel (RealtimeController.ts,executeActionGuarded). - Les gardes sont lues sur la méthode du contrat (
say), l’action exécutée est celle de la base, qui remet la requête brute à l’adaptateur ; l’adaptateur appelle la méthode avec(request, HandlerContext). - Singleton par défaut (
Controller.scope) : aucune instance par appel. - Typage :
@GrpcService(Contrat)contraint la classe à respecter le contrat généré. - Garde au démarrage : un décorateur sans effet en gRPC (
@UseSession,@Csp,@Idempotent, schéma de route…) posé sur une méthode du contrat interrompt le démarrage en la nommant (S-grpc-18) ; une méthode du contrat absente de la classe aussi. - Casse : le Router compare sans la casse, l’adaptateur avec ; un chemin à casse modifiée
finit en
UNIMPLEMENTEDsans atteindre la méthode (S-grpc-9). Le 404 nu que l’adaptateur écrit par défaut ne le garantit que pour grpc-js et connect-es : grpc-go y litINTERNAL. D’où lefallbackfourni par Nodefony (D13, point 2). - Rien de chargé pour une application qui ne déclare aucun service : adaptateur, runtime
protobuf et code généré ne sont jamais chargés (seul reste le champ
rpc,null, de D10). Quand un service est déclaré, ils se chargent au démarrage, pas au premier appel (D12 point 4 : le contrôleur importe le code généré, et un pair manquant doit se voir au déploiement).
D2 — Où vivent le contrat et le code généré#
Décision (2026-11-11) : une convention par défaut, jamais une obligation — Nodefony ne lit aucun de ces fichiers à l’exécution ; le contrôleur importe le code généré par un import ordinaire. Identique dans une application (sa racine est un module) et dans un module :
<application ou module>/
├── buf.yaml modules: [proto, …], deps, lint STANDARD, breaking FILE
├── buf.gen.yaml protoc-gen-es → out: nodefony/gen, target=ts
├── proto/<paquet>/v1/*.proto
└── nodefony/
├── controller/… les points d'entrée (D1)
└── gen/<paquet>/v1/*_pb.ts GÉNÉRÉ, versionné, jamais édité
-
proto/à la racine, hors du bundler : le contrat public, lisible par les clients d’autres langages. Nom des guides protobuf-es et connect-node (modules: - path: proto). Plusieurs dossiers de contrats sont permis (modules: [proto, vendor], essayé :buf buildles réunit). -
nodefony/gen/: nom de l’écosystème (out: genchez connect-node,src/genchez protobuf-es) ; pasgrpc/, les messages protobuf servent au-delà de gRPC (codec, ADR-0022). Chaque fichier garde le suffixe imposé*_pb.ts, que les outils du dépôt excluent déjà (.prettierignore,.oxlintrc.json). -
Le développeur génère (
npx buf generate) après avoir modifié un contrat ; le code généré est commité ; Nodefony ne génère rien au build ni au démarrage. La CI refuse la dérive : elle régénère et échoue sur toute différence, en lisantbuf.gen.yaml(aucun chemin codé en dur). La dérive existait : le fichier du POC venait de protoc-gen-es 2.16.0 quand la 2.17.0 était installée. Gate :scripts/gates/check-generated-protobuf.mjs. Il rejoue chaquebuf.gen.yamlversionné dans un dossier jetable et signale tout fichier manquant, en trop ou différent. -
edition = "2024"pour un contrat neuf ;proto3accepté (A2A, santé et réflexion le sont). -
Lint
STANDARD(dossier = paquet, paquet versionné.v1) etbreaking FILE, la règle la plus stricte, qui inclutWIRE_JSON— Connect sert aussi du JSON. -
Outils :
@bufbuild/bufet@bufbuild/protoc-gen-esen dépendances de développement ; buf publie ses binaires pour les trois plateformes (Windows x64 et arm64 compris). -
Contrats tiers — essayés le 2026-11-11, code produit compilé en
strict:- santé et réflexion :
buf.build/grpc/grpc(--path grpc/health/v1/health.proto,--path grpc/reflection/v1/reflection.proto) ; le framework les livrera générées, l’application n’aura rien à générer ; - A2A n’est PAS publié sur le registre buf (
resource "a2aproject/a2a" was not found— uncurlqui rend 200 surbuf.build/…ne prouve rien, c’est une page générique). Il se génère depuis son dépôt, version épinglée, sans copie :inputs: - git_repo: https://github.com/a2aproject/A2A.git, tag: v1.0.1, subdir: specification; ses importsgoogle/api/*suivent par son proprebuf.lock; include_imports: trueest requis pour générer ces imports ; les types bien connus (google/protobuf/*) viennent de@bufbuild/protobuf/wkt, jamais régénérés.
- santé et réflexion :
-
Dépendances npm : le générateur (
@bufbuild/buf,@bufbuild/protoc-gen-es) endevDependencies; le runtime (@bufbuild/protobuf,@connectrpc/connect,@connectrpc/connect-node) endependenciesde l’application — une installation de production (npm ci --omit=dev) n’aurait sinon pas l’adaptateur (le POC les range tous en développement : module de test, jamais installé en production). Plages et pairs facultatifs : D12. -
En développement, le superviseur régénère (décision du 2026-11-12). Le constat de départ : modifier un
.protone déclenchait rien, pour deux raisons.DevSupervisor.ts#isIgnoredWatchPathignore tout fichier qui n’est pas en.ts, et leproto/à la racine de l’application est hors deDevSupervisor.ts#DEV_WATCH_PATHS(celui d’un module local, sousmodules/, y est déjà). Décision :- le superviseur surveille aussi les
.protode tout dossier qui porte unbuf.gen.yaml; - un changement lance
buf generatedans ce dossier, depuis le superviseur lui-même. Le.protone déclenche donc pas de redémarrage par lui-même : c’est le*_pb.tsrégénéré, déjà surveillé, qui provoque le redémarrage habituel, un seul ; - si
buféchoue (erreur de syntaxe dans le contrat), sa sortie s’affiche et l’exemplaire en cours continue de servir l’ancien code. Sibufest absent, le message nommenpm i -D @bufbuild/buf @bufbuild/protoc-gen-es, jamais un échec muet ; - rien de tout cela en production, où le superviseur ne tourne pas : le code généré reste commité (point 3), et le gate de dérive en CI garde l’écart.
- le superviseur surveille aussi les
Hors D2 : la variante nodefony create controller --kind grpc (contrat, buf.yaml,
buf.gen.yaml, code généré, contrôleur, dépendances) et un script grpc:generate au gabarit
d’application — un travail distinct, mené après cette décision.
D3 — Sur quels ports, avec quels protocoles#
Décision (2026-11-11) :
- Aucun serveur ni port neuf. Une méthode gRPC étant une route (D1), elle répond sur tous les
serveurs DÉJÀ actifs, chacun avec ce que son HTTP permet (
connect-node-server-plugins.md, « HTTP/2, TLS, and gRPC ») : 5152 (HTTP/2 + TLS) sert navigateur, Connect, gRPC-Web et gRPC ; 5153 (h2c) sert Connect, gRPC-Web et gRPC ; 5151 (HTTP/1.1) sert navigateur, Connect et gRPC-Web — jamais le gRPC natif, qui exige HTTP/2. Un service qui ne doit jamais passer en clair l’exige par le mécanisme existant (Route.ts,requirements.scheme), sans code neuf. - Les trois protocoles ouverts par défaut (gRPC, gRPC-Web, Connect) : défaut de l’adaptateur
(
@connectrpc/connect,router.d.ts: « The protocol is enabled by default »). Aucun coût par appel : l’adaptateur choisit le protocole aucontent-type, dans le même gestionnaire. - Pas de faille CSRF ouverte par les navigateurs : un POST Connect exige
application/jsonouapplication/proto, sinon 415 (connect-protocol.md) — un formulaire, untext/plainsont refusés ; un POST JSON d’une autre origine déclenche un contrôle préalable CORS, refusé tant que D9 ne l’autorise pas ; leGETn’existe que pourNO_SIDE_EFFECTS(D1) et sa réponse reste illisible d’une autre origine.requireConnectProtocolHeaderpeut ajouter une couche ; elle est désactivée par défaut, parce que ces trois défenses suffisent (D4, point 6). - h2c reste une activation explicite (
kernelServers.ts#isH2cEnabled: seulenabled: truel’allume) : déclarer un service n’ouvre jamais un port en clair ; h2c ne sert que derrière une passerelle de confiance (A2A §10 exige TLS en production). - Restreindre les protocoles se fait pour l’application entière, par une option de la section
grpcde la configuration http, branchée sur les optionsgrpc/grpcWeb/connectde l’adaptateur. Le grain « par service » attend un usage réel ; il s’ajoutera sans rupture. Les méthodes s’inscrivent SANS option (router.rpc(méthode, impl)) : une option passée à l’inscription rallumerait gRPC et gRPC-Web coupés (signalement connect-es 1835). - Le JSON résout les types du contrat (précision du 2026-11-12).
Le mappage JSON de proto3 exige de résoudre le type emballé dans un
google.protobuf.Any; sans registre, Connect répondINVALID_ARGUMENTen Connect JSON et en gRPC-Web JSON (constaté aux trois ports), quand le binaire passe. L’adaptateur reçoit doncjsonOptions.registry: le fichier du contrat et tous ses imports, types bien connus compris, construit une fois, consulté par Connect pourAnyen JSON seulement — aucun coût par appel. UnAnyqui emballe un type hors du graphe d’imports du contrat ne se lit qu’en binaire.
Un client gRPC natif qui vise 5151 n’obtient pas un statut gRPC : le serveur HTTP/1.1 ne comprend
pas la préface HTTP/2 et la connexion échoue — le test exige qu’elle échoue franchement et vite.
Constaté : le client lit ERR_HTTP2_ERROR: Protocol error en une quinzaine de
millisecondes, que Connect classe 13 INTERNAL ; jamais une échéance atteinte.
D4 — Les limites : taille, durée, flux#
Décision (2026-11-11) :
Deux faits du pipeline fondent la décision.
- Le pipeline lit le corps d’un POST avant le contrôleur
(
http-kernel.ts#HttpKernel.serveHttpRequest→Request.ts#HttpRequest.initialize), ce qui rendrait tout flux gRPC impossible. La route gRPC pose doncbodyStream: true(mécanisme existant, celui de@Body({ stream: true })). Conséquence :http.maxBodySize(1 Mio, 413) ne la borne plus, et seule reste la borne de l’adaptateur. - À l’expiration du délai de réponse, Nodefony écrit lui-même un 504/408
(
HttpContext.ts#HttpContext._onTimeout). Sur une réponse que l’adaptateur possède, ce serait un second écrivain. Sur une route gRPC, le délai de Nodefony n’écrit donc jamais : désarmé pour un flux, il termine un appel unaire par sa fiche (point 3), au format du protocole — un seul écrivain.
readMaxBytes= 4 Mio par message, au-delà le statut 8RESOURCE_EXHAUSTED(grpc-statuscodes.md: « Sent or received message was larger than configured limit »).- Le défaut de l’adaptateur vaut
0xffffffff(limit-io.js), c’est-à-dire aucune borne. - La borne s’applique aussi à la décompression (
envelope.js:decompress(data, readMaxBytes)) : sans elle, quelques Ko compressés peuvent devenir 4 Gio. - C’est la valeur que conseille
connect-node-server-plugins.md.
- Le défaut de l’adaptateur vaut
writeMaxBytes= 4 Mio : l’erreur naît chez nous, journalisée, au lieu d’arriver chez un client qui refuse au-delà. Les implémentations de référence ne bornent pas l’émission ; leurs clients, eux, refusent au-delà de 4 Mio par défaut.- Les deux bornes se règlent dans la section
grpcde la configuration http : un framework borne par défaut, il n’interdit pas à une application d’échanger de plus gros messages.
- Les deux bornes se règlent dans la section
- Appel unaire : l’échéance vaut
min(échéance du client, responseTimeout).- L’échéance du client reste celle de l’adaptateur : il la lit dans son en-tête, abaisse
ctx.signalet rend le statut 4DEADLINE_EXCEEDEDdans le format du protocole. - Le délai du serveur n’est pas écrit dans l’en-tête d’échéance.
ctx.timeoutMs()rend l’échéance envoyée par le client, et elle seule. Poser l’en-tête faisait échouer 1 717 cas sur 4 932 de la suite de conformité de Connect (« server echoed back a timeout but none was expected »). - Le délai du serveur est celui que Nodefony arme déjà sur toute requête (
HttpContext.setTimeout). Sur une route unaire, il reste armé ; seul un flux le désarme. À son expiration,HttpContext._onTimeouttermine l’appel par sa fiche (HttpContext.rpc, D10) au lieu d’écrire un 408/504 :GrpcCall.expireabaissectx.signal(ctx.abort) et l’appel se termine en 4. Aucun minuteur de plus. - L’appel se termine même quand le gestionnaire ne lit pas son signal. L’adaptateur, lui,
attend sans fin la promesse du gestionnaire
(
invoke-implementation.js#invokeUnaryImplementation). - Un gestionnaire synchrone n’est pas suivi.
HttpContext.rpcarrive donc dès ce lot, avec le seul membre dont il a besoin (expire) ; D10 y ajoute système, méthode et code.- Le client n’obtient jamais le 408 ou 504 générique, qu’il lirait comme
UNKNOWN. - Aucune clé neuve : la valeur est celle de toute route.
- L’échéance du client reste celle de l’adaptateur : il la lit dans son en-tête, abaisse
- Flux (serveur, client, bidirectionnel) : aucune échéance par défaut, comme le veut gRPC
(un abonnement vit longtemps).
- Le flux s’ouvre par
StreamLifecycle.ts#openStreamLifecycle, comme SSE et les flux d’octets :- le délai d’inactivité est désarmé ;
- le flux prend une place dans le budget de connexions longues par IP (
wsMaxConnectionsPerIp) ; maxDurationest désactivé ;- la fermeture est suivie.
- Le client qui ne lit plus est coupé après le délai de blocage (30 s,
StreamLifecycle.ts#STREAM_STALL_TIMEOUT_MS). Comme l’adaptateur garde ses écritures, ce blocage s’observe par un seul balayage (StreamLifecycle.ts#StallSweep), armé seulement s’il y a un flux, de période la moitié du seuil (15 s) :- un tour qui voit
writableNeedDrainouvre l’attente et pose undrain; seul cedrain— un progrès réel — la ferme, jamais un tour qui verrait le tampon vide ; - une attente qui dure le seuil coupe le client : entre 30 et 45 s après la première contre-pression vue, jamais avant le seuil ;
- le seuil reste dans
StreamLifecycle.sweepStall(une règle, une implémentation), et le coût par message est nul.
- un tour qui voit
- Écartés, sur essai réel (h2c et HTTP/1.1, client bloqué, muet, lent, et bloqué à côté d’un
voisin lu sur la même session) :
- effacer l’attente quand un tour voit le tampon vide (la forme d’abord écrite ici) : un client LENT qui lit voit son tampon se remplir aussitôt, chaque tour le trouve plein, et il est coupé à tort ;
- garder le délai d’inactivité que Node tient déjà sur le flux, sans minuteur de plus : en
HTTP/2 il est repoussé tant que la SESSION avance (
internal/http2/core#callTimeout, compteur de session) — un flux bloqué n’est jamais coupé si un voisin de la même connexion est lu, le cas même d’un client gRPC qui multiplexe tout sur une connexion ; - les autres minuteurs du noyau :
RevocationWatch(passe asynchrone par entrée, anonymes exclus),ReceiveDeadline(échéance absolue d’un corps reçu), battements WS et SSE.
- Le flux s’ouvre par
maxTimeoutMsn’est pas posé : il REFUSERAIT (INVALID_ARGUMENT) le client qui demande plus long (connect-node-timeouts.md). On rabote son échéance au lieu de la refuser.requireConnectProtocolHeader=false, réglable dans la sectiongrpc:- le CSRF est déjà fermé (D3, point 3) ;
- exiger l’en-tête casse
curlet le JSON écrit à la main ; - la norme dit « may reject » (
connect-protocol.md).
Coût, mesuré (médiane de 7 passes d’un million d’itérations, Node du poste) :
| Geste | Quand | Coût |
|---|---|---|
Comparaison de taille (readMaxBytes, writeMaxBytes) |
chaque message | 0 de plus : l’adaptateur la fait déjà avec son défaut (≈ 5 ns) |
| Fin au délai du serveur (délai existant gardé, fiche accrochée) | chaque appel unaire | ≈ 24 ns : reconnaître le chemin unaire, accrocher la fiche. Écarté : désarmer puis tenir un anneau partagé, 97 ns en HTTP/2 et 174 ns en HTTP/1.1 keep-alive (réarmement de la socket à la requête suivante). Mesuré sur une vraie socket et un vrai flux, médiane de 9 × 200 000 |
| Cycle de vie du flux | ouverture d’un flux | celui de SSE, une fois par flux, jamais par message |
| Balayage de blocage | un minuteur pour tous les flux, armé seulement s’il y en a | 0 par message ; ~6 ns par flux et par tour (58 µs par tour à 10 000 flux, toutes les 15 s) ; ~60 ns pour inscrire puis retirer un flux, une fois. Mesuré sur 300 flux HTTP/2 réels, médiane de 9 passes |
Ce que D4 ne décide pas, et qu’il faut mesurer : le plancher par message de l’adaptateur. Chaque
écriture crée une promesse et pose puis retire deux écouteurs
(node-universal-handler.js#write). Pour un framework de référence du temps réel, le débit d’un
flux serveur se compare à celui de la socket binaire, à charge utile égale.
D5 — Comment un refus atteint un client gRPC#
Décision (2026-11-11) :
Le constat. Avant l’action, le pipeline refuse (HttpKernel.onRequestEnd) dans cet ordre :
provenance CSRF (Firewall.enforceCsrf, étape Fetch Metadata / Origin), session, zone du
pare-feu, puis @IsGranted. Ces refus lèvent un 401 ou un 403, que HttpKernel.onError rend en
HTML ou JSON. Un client gRPC y cherche un grpc-status, ne le trouve pas, et lit UNKNOWN : il
ne sait pas pourquoi l’appel a échoué.
-
Nodefony décide, sans rien de neuf. Les mêmes gardes que pour toute route, une seule autorisation (D1).
- L’étape CSRF Fetch Metadata /
Origins’applique au POST gRPC : un appel cross-site est refusé. Un client natif n’envoie niSec-Fetch-SiteniOrigin, et passe. - La redirection vers la page de connexion exige GET,
Accept: text/htmletSec-Fetch-Mode: navigate(entryPoint.ts) : un client gRPC ne reçoit jamais de 302.
- L’étape CSRF Fetch Metadata /
-
Le noyau écrit le refus, au format du client, par la fonction de refus de D13 (point 2) — la même que pour un chemin inconnu ou une méthode refusée. Corrigé le 2026-11-12 : la première rédaction confiait l’écriture à Connect par
requestGate.- Pourquoi l’abandon : D13 a ensuite imposé une fonction de http, sans Connect, qui écrit les
refus en forme gRPC. Garder
requestGateaurait fait deux écrivains pour le même refus, aux sorties différentes (Connect envoie en-têtes puis trailers, la fonction de D13 un Trailers-Only) et à la vidange du corps HTTP/1.1 faite deux fois, de deux façons. - Le corps non lu suit la seule règle du noyau (
HttpResponse.closeUnfinishedRequest, D13 point 1) ; un refus ne construit plus l’adaptateur. onErrorreconnaît le protocole du client à ses en-têtes (content-type,connect-protocol-version), sur le chemin d’erreur seulement. La route gRPC porte un champ optionnel du contratIResolvedRoutede http (grpc, ajout sans rupture), que lit la garde de D13 (point 3).
- Pourquoi l’abandon : D13 a ensuite imposé une fonction de http, sans Connect, qui écrit les
refus en forme gRPC. Garder
-
Le code se choisit sur l’IDENTITÉ, pas sur le chiffre HTTP :
Situation Code refus, aucune identité authentifiée ( RequestContext.getAuthenticatedUser()vautnull, un anonyme compte comme personne)16 UNAUTHENTICATEDrefus, appelant identifié 7 PERMISSION_DENIEDPourquoi ce choix :
@IsGrantedrépond 403 même sans identité (Resolver.ts#Resolver._enforceSecurity). Or la norme interditPERMISSION_DENIED« if the caller can not be identified » (grpc-statuscodes.md).- L’enjeu est concret. Avec 16, un client sait qu’il doit présenter ou rafraîchir son jeton. Avec 7, il abandonne : un agent dont le jeton a expiré s’arrêterait au lieu de se reconnecter.
- La correspondance des autres erreurs (400, 500…) relève de D7.
-
Message envoyé au client : le libellé générique du code, jamais le texte de l’erreur, qui nommait la zone refusée (même règle que
onError). Le détail va au journal, avec lerequestId. -
Refus avant routage — corrigé par D13. La norme traduit un statut HTTP en code gRPC (
grpc-http-grpc-status-mapping.md) : 429 enUNAVAILABLE, 404 enUNIMPLEMENTED. On en concluait « rien à coder ». C’est faux pour les clients de la famille grpc-go (grpcurl, tout client en Go) : ils lisentINTERNALdès que le statut arrive avec un corps, ou sans que la trame d’en-têtes porte la fin du flux. Une requête gRPC refusée avant l’adaptateur s’écrit donc en forme gRPC, avec la correspondance des refus de transport (D13, point 2).
Constaté sur le fil (essai jetable de la première rédaction, connectNodeAdapter nu, porte qui
lève 16, corps envoyé incomplet puis complet ; implémentation appelée 0 fois). La forme des
protocoles reste celle-ci ; seul le gRPC natif part désormais en Trailers-Only (D13, point 2) :
| Protocole | HTTP/2 | HTTP/1.1 |
|---|---|---|
| gRPC unaire et bidirectionnel | 200, en-têtes puis trailers grpc-status: 16 |
sans objet (D3) |
| gRPC-Web | 200, cadre de trailers grpc-status: 16 dans le corps |
idem |
| Connect unaire | 401 + {"code":"unauthenticated"} |
idem |
| Connect en flux | 200 + fin de flux {"error":{"code":"unauthenticated"}} |
— |
- Ce n’est pas un Trailers-Only : Connect envoie des en-têtes puis des trailers. Les deux
formes sont valides (
grpc-PROTOCOL-HTTP2.md), et le statut arrive bien au client. - HTTP/2 : le refus part sans attendre le corps. Connect coupe ensuite le flux avec
NO_ERROR(node-universal-handler.js#universalResponseToNodeResponse). - HTTP/1.1 : Connect lit et jette le reste du corps, jusqu’à 256 Kio, AVANT de répondre, pour garder la connexion réutilisable.
- Au-delà de 256 Kio, il répond avec
connection: close(essai : 1 Mio envoyé, réponse en 3 ms). - Un client qui n’envoie jamais la fin de son corps tient la connexion jusqu’à
requestTimeout(30 s), comme sur toute route POST : l’exposition n’est pas nouvelle.
- Au-delà de 256 Kio, il répond avec
Coût
| Chemin | Coût |
|---|---|
| Appel accepté | 0 : aucune porte |
| Appel refusé | deux lectures d’en-tête et une d’identité, déjà en mémoire, puis l’écriture du refus sans Connect, à la place du rendu HTML ou JSON |
La bibliothèque. @connectrpc/connect et @connectrpc/connect-node 2.3.0, sous Apache-2.0
comme Nodefony.
- Aucune dépendance transitive : un seul pair,
@bufbuild/protobuf, qui n’en a aucune non plus. - Dépôt
connectrpc/connect-es, créé par Buf (l’outilbufetprotobuf-es, D2). - Projet CNCF au niveau Sandbox (
cncf/landscape, entrée « Connect RPC », relu le 2026-11-11). - Elle est retenue parce qu’elle est la seule, parmi les bibliothèques étudiées, à fournir une fonction
(requête, réponse), donc branchable dans une route. Le besoin exclut toute bibliothèque qui ouvre son propre serveur : l’appel n’y passerait ni par le pare-feu ni par@IsGranted, et gRPC-Web ne serait pas servi. L’interopérabilité se prouve contre les clients de@grpc/grpc-js, que le SDK A2A JS emploie (D13).
D6 — Le contexte de Nodefony dans un appel#
Décision (2026-11-11) :
Le constat. L’appel s’exécute dans la bulle de la requête. RequestContext (ALS) et la portée
d’injection request sont ouverts par HttpKernel, et ne se referment qu’au close de la réponse
(http-kernel.ts#HttpKernel.createHttpContext → HttpKernel.teardownHttp), donc après le dernier
message d’un flux. En revanche, Connect écrit sur la réponse Node native
(node-universal-handler.js#universalResponseToNodeResponse → writeHead), alors que Nodefony
range ses en-têtes dans une réserve que seul Response.ts#HttpResponse.writeHead vide.
-
Identité, ALS, portée : rien de neuf. Le gestionnaire lit
this.user(accesseur deController, soitRequestContext.getAuthenticatedUser()) etRequestContext, et résout ses servicesrequestcomme toute action, pendant toute la durée du flux.- L’identité n’est PAS recopiée dans
contextValuesde Connect : ce serait une seconde source de vérité, et une écriture par appel pour rien quand le gestionnaire ne la lit pas. contextValuessert à Nodefony seul : il porte la fiche de l’appel, que lisent la porte (D5), l’interruption (D8) et la ligne d’accès (D10). Connect en alloue un par appel de toute façon (implementation.js#createHandlerContext) ; le nôtre le remplace.- Une seule composition :
connectNodeAdapter, avec deux de ses options publiques —contextValues(la fiche) etfallback(D13).requestGaten’est plus employé (D5, point 2). Recomposer soi-mêmeuniversalRequestFromNodeRequestetuniversalResponseToNodeResponsen’apporterait rien, et exposerait à leur promesse qui ne se résout jamais (D7 point 4, signalé : connect-es 1876).
- L’identité n’est PAS recopiée dans
-
Les en-têtes du pipeline passent sur la réponse gRPC. Avant de confier la réponse à Connect, l’adaptateur la remet en état comme
HttpResponse.writeHeadle ferait :- la réserve (CORS,
Vary,Set-Cookie),X-Request-Id,traceparent; - la politique d’en-têtes de sécurité, choisie sur le type de la requête, pour un corps écrit par un tiers (comme un relais).
Il les pose en en-têtes natifs. Node les fusionne avec ceux de Connect, qui l’emportent en cas de conflit (
content-type). Sans cela, la corrélation client↔serveur et le CORS disparaissent en silence.- Antériorité : un adaptateur officiel de Connect, écrit pour un serveur qui range lui aussi ses en-têtes à part, fait le même geste pour la même raison — il les recopie sur la réponse native avant de la confier à Connect.
- Constaté sur le fil (Connect réel, HTTP/2 et HTTP/1.1) :
x-request-id,varyetaccess-control-allow-originposés en natif reviennent sur la réponse ; uncontent-typeposé avant est remplacé par celui de Connect. L’ALS est lu dans l’implémentation, à l’appel unaire comme au cinquième message d’un flux.
- la réserve (CORS,
-
Un flux ne survit pas à l’identité qui l’a ouvert, l’invariant des sockets (
FirewallRealtimeAuthenticator.ts#FirewallRealtimeAuthenticator).- Le flux s’ouvre par
openStreamLifecycle(D4) : il est déjà inscrit dans la surveillance de révocation du noyau (HttpKernel.watchStream, fenêtreREVOCATION_REVALIDATE_MSde 30 s). - Mais la révocation ferme par
StreamLifecycle.close(), qui appellecontext.close(): sur une réponse que Connect possède, ce serait un second écrivain (S-grpc-27).StreamLifecyclereçoit donc une fermeture fournie par l’adaptateur, qui interrompt l’appel avec le statut 16UNAUTHENTICATED: l’agent rafraîchit son jeton et se reconnecte. Sans fermeture fournie, un flux dont un tiers tient les écritures est fermé en DÉTRUISANT son transport, jamais parcontext.close(). - L’interruption suit le mécanisme de D8 (point 2) : au plus le message déjà en vol part encore vers l’identité morte (constaté à l’essai), puis plus rien.
- Un appel unaire n’est pas surveillé : il est autorisé à son début et borné par son échéance (D4).
- Le flux s’ouvre par
Coût
| Geste | Quand | Coût |
|---|---|---|
| ALS, portée, identité | — | 0 : la bulle existe déjà |
contextValues de Nodefony |
chaque appel | 0 de plus : il remplace celui que Connect alloue |
| Remise en état des en-têtes | chaque appel | le travail que HttpResponse.writeHead fait sur toute route, déplacé |
| Surveillance de la révocation | chaque flux, à chaque fenêtre | celle de SSE, déjà payée par D4 ; 0 par message |
D7 — Les erreurs levées pendant un appel#
Décision (2026-11-11) :
Le constat (lu dans Connect). Une exception qui n’est pas une ConnectError devient 13
INTERNAL, message « internal error ». Sa cause est gardée côté serveur et jamais envoyée
(protocol-grpc/handler-factory.js#createHandler, transformCatchFinally). La cause brute ne se
lit ailleurs que dans ctx.signal.reason (context.abort(e)). Une ConnectError part telle quelle.
Connect la reconnaît à sa forme (name === "ConnectError") : une HttpError de Nodefony, levée par
un service partagé avec des routes HTTP, devient donc 13.
-
Une table pour les erreurs de l’application, celle de
google-rpc-code.proto(« HTTP Mapping »), servie par une seule fonction. Elle ne sert pas aux refus de transport (chemin inconnu, limite de débit), qui ont leur propre correspondance normative (D13, point 2) ; les deux partagent seulement la règle d’identité de la ligne 401/403 (D5) :HTTP gRPC 400, 422 3 INVALID_ARGUMENT401, 403 16 ou 7, selon l’identité (D5) 404 5 NOT_FOUND409 10 ABORTED412 9 FAILED_PRECONDITION413, 429 8 RESOURCE_EXHAUSTED499 1 CANCELLED501 12 UNIMPLEMENTED502, 503 14 UNAVAILABLE408, 504 4 DEADLINE_EXCEEDEDautre 5xx 13 INTERNALautre 2 UNKNOWNcode.protoassocie 409 àABORTEDet àALREADY_EXISTS.ABORTED(conflit, réessayer plus haut) est le sens le plus large ;ALREADY_EXISTSse lève enConnectErrorquand c’est le cas.- Chemin d’erreur seulement : un
switch.
-
Le message suit la règle d’
HttpKernel.onError(error-renderer.ts) : en production, un 5xx part avec un message générique ; sinon, le message de l’erreur. Les refus de D5 gardent leur libellé générique. -
Où la traduction s’applique.
- Appel unaire et flux client (une seule réponse) : à chaque erreur.
- Flux serveur et bidirectionnel : aux erreurs levées AVANT le premier message (validation,
entité introuvable, droit refusé), là où un service partagé lève. Après le premier message,
l’erreur devient 13, et sa cause va au journal ; le code en cours de flux se choisit en levant
une
ConnectError. - Pourquoi cette borne : traduire en cours de flux impose une promesse par message, mesurée à +45 ns par message (+27 % sur un itérateur nu), pour un travail qui ne sert qu’en cas d’erreur.
-
Journal. À la fin de l’appel, l’adaptateur lit
ctx.signal.reason. Une cause qui n’est pas uneConnectError, ou un code 2, 13 ou 15, part au journal en ERROR avec lerequestIdet la pile. Aucun écouteur de plus : la lecture se fait auclosede la réponse, que le noyau écoute déjà (HttpKernel.teardownHttp). Ce journal est la ligne d’accès de l’appel (D10, point 3).- ⚠️ PAS à la fin de l’
await universalResponseToNodeResponse(…): cette promesse attend un événementendqu’une réponse Node n’émet jamais (finish, oui). Constaté à l’essai : elle ne se résout pas, en HTTP/1.1 comme en HTTP/2.connectNodeAdapterne l’attend pas, d’où l’absence de symptôme chez Connect (signalé : connect-es 1876). - Essai : une exception banale porte sa cause brute dans
ctx.signal.reason(« base injoignable… »), et le client reçoit 13 « internal error », sans la cause.
- ⚠️ PAS à la fin de l’
-
Détails riches (
google.rpc.Status,ErrorInfo) : aucun par défaut.ConnectErrorles porte déjà (details). Les typesgoogle.rpc.*s’engendrent par une entrée buf (D2), comme le fera le pont A2A (A2A §10.6).- Ils voyagent dans le trailer
grpc-status-details-bin, que les clients bornent avec les en-têtes (8 Kio courants, A2A 2433). La documentation le dit ; Nodefony ne le borne pas.
Coût
| Chemin | Geste | Coût |
|---|---|---|
| Appel unaire réussi | une promesse (.then) par appel |
≈ 45 ns (mesuré sur le même geste, par message) |
| Flux réussi | une promesse au premier message, 0 ensuite | ≈ 45 ns par flux, 0 par message |
| Fin d’appel | lecture de ctx.signal.reason |
une lecture et un test de forme |
| Erreur | switch + journal |
chemin d’erreur seulement |
D8 — L’arrêt du serveur#
Décision (2026-11-11) :
Le constat. À onTerminate, la séquence existe (HttpKernel.init) : readyz passe à 503,
fermeture 1001 des WebSocket, drain HTTP (GOAWAY en deux temps), destruction à shutdownTimeout
(5 s). Un flux gRPC détruit sans statut laisse le client deviner.
Connect offre shutdownSignal, mais il y lie un écouteur par appel, unaire compris
(signals.js#createLinkedAbortController). Or l’ajout et le retrait d’un écouteur sur un
AbortSignal parcourent les écouteurs déjà posés : le coût de CHAQUE appel croît avec le nombre
d’appels ouverts (mesure ci-dessous).
-
Une seule liste de flux longs, celle du noyau, pas une liste gRPC. Nodefony n’emploie pas
shutdownSignal.- Ce qui existe (relu au code) :
HttpKernel.#streams, unRevocationWatchdont leSetne tient que les flux PORTEURS D’UNE IDENTITÉ (StreamLifecycles’y inscrit seulement sirevalidate !== null) ; un flux anonyme n’y est pas ;WsConnectionCounter, des COMPTES par IP, et seulement si le plafond est armé ;- les
Setde sockets et de sessions HTTP/2 deserverShutdown.ts#createDrainTerminator, des CONNEXIONS, pas des flux.
- Aucun ne liste tous les flux ouverts, et aucun flux long (SSE, octets) ne reçoit de fin à
l’arrêt aujourd’hui : il est détruit à
shutdownTimeout. - Donc : le noyau gagne UN registre de tous les flux longs ouverts
(
StreamLifecycle.ts#ShutdownRegistry), rempli parStreamLifecycleà l’endroit même où il appelle déjàwatchStream/unwatchStream. À l’arrêt, le noyau termine chacun parStreamLifecycle.ts#StreamLifecycle.shutdown: un appel RPC au format de son protocole (14, point 2), un flux SSE ou d’octets parclose. gRPC n’apporte que sa fermeture (D6 point 3) ; SSE et les flux d’octets en profitent aussi. - Seules les sources VIVANTES s’y inscrivent. Un flux d’octets à source finie
(
live: false, une archive, un fichier) reste hors du registre et garde le drain pour finir : le terminer proprement au début de l’arrêt ferait croire au client qu’il a reçu le tout (ByteStream.ts#openByteStream,endsAtShutdown). - L’écouteur se pose à
init()du noyau HTTP (http-kernel.ts#HttpKernel.shutdownStreams), pas àonPostReady: unSIGTERMreçu pendant le démarrage trouve déjà la fin des flux. Ordre àonTerminate: readyz à 503, fermeture 1001 des WebSocket, fin des flux, drain HTTP. - L’arrêt attend la fin des flux, au plus 1 s (
SHUTDOWN_STREAMS_WAIT_MS, le plafond d’annonce du GOAWAY), puis le drain commence. Il se termine plus tôt dès que le dernier flux s’est retiré ; un flux ouvert pendant l’attente est terminé au tour suivant. Les restants sont comptés dans la ligne d’arrêt (WARNING). - Le flux garde le noyau pris à l’ouverture : le nettoyage du contexte (
Context.clean, qui remethttpKernelànull) passe AVANT la fin du flux, et un flux fermé restait sinon inscrit, avec son contexte, à la révocation, au balayage et à l’arrêt (11 Ko par flux abandonné, vu par le gate mémoire). - Le
RevocationWatchreste réservé aux flux à identité : y mettre les anonymes ferait travailler chaque fenêtre de 30 s pour rien. - Pour SSE, la fin à l’arrêt est une fermeture simple du flux :
EventSourcese reconnecte, vers un autre exemplaire. Ce n’est jamais la fin d’un canal d’ADR-0021 S4 (le 204, qui dit de ne pas revenir). Changement de comportement d’une livraison gelée : précisé dans ADR-0021.
- Ce qui existe (relu au code) :
-
À l’étape de la fermeture 1001 des WebSocket, chaque flux ouvert est interrompu avec 14
UNAVAILABLE(« réessaie, ailleurs ») parctx.abort(…).- Coopératif :
ctx.signalprévient le gestionnaire, qui termine. La documentation le prescrit : passerctx.signalà ses sources. abortn’est pas sur le typeHandlerContextque reçoit le gestionnaire. Il est déclaré par le type de retour decreateHandlerContext, fonction PUBLIQUE de@connectrpc/connect(index.d.ts, sans marque@private), qui crée ce contexte. L’adaptateur l’atteint par un garde de type, jamais une conversion, et un test casse si Connect le retire. Sans lui, l’enrobage de l’itérateur (point suivant) arrête seul le gestionnaire qui produit.- Pour le gestionnaire sourd qui produit encore : l’itérateur de l’appel est enrobé. Après l’interruption, sa lecture et son écriture suivantes échouent avec ce statut, que Connect écrit en trailer. La révocation (D6) emprunte le même mécanisme.
- Le gestionnaire qui écoute son signal puis rend la main termine la source de l’appel :
l’enrobage (
GrpcEndpoint.ts#FirstMessageTranslator) relit alors l’interruption à la fin de la source et la lève. Sans cela, l’appel finissait en 0OKet le client prenait un flux tronqué pour complet — à l’arrêt (14) comme à la révocation (16). - Filet : un gestionnaire bloqué qui n’écoute pas son signal tombe à
shutdownTimeout, connexion détruite ; pour la révocation, à la fenêtre suivante (flux détruit). Le statut lu vient alors du CLIENT, pas de Nodefony : constaté, 13INTERNALchez@connectrpc/connect-node(point 3 pour les autres clients).
Constaté sur le fil (Connect 2.3.0 réel, flux bidirectionnel, interruption en 14) :
Gestionnaire Sans enrobage Avec enrobage écoute ctx.signal14 en 14 ms, 0 message après idem sourd, produit toutes les 20 ms jamais fini, 19 messages après en 400 ms 14 en 17 ms, 1 message après (en vol) sourd et bloqué ouvert ouvert, 0 message → filet La deuxième ligne vaut aussi pour
shutdownSignalde Connect : il ne fait qu’abattrectx.signal, et n’arrête pas un gestionnaire sourd. - Coopératif :
-
Un appel unaire en vol n’est pas interrompu : il finit pendant le drain, comme l’arrêt gracieux de gRPC. Un appel neuf après le GOAWAY est refusé par HTTP/2, et le client réessaie.
-
Le drain dure
shutdownTimeout(5 s), l’échéance par défaut d’un unaire 30 s (D4) : un appel plus long que le drain voit sa connexion détruite. Le serveur envoie la même chose à tous les clients ; le statut lu vient du CLIENT. Constaté sur le fil (S-grpc-35) :Client Statut lu @grpc/grpc-js14 UNAVAILABLE(« Connection dropped »)grpcurl(grpc-go)Unavailable@connectrpc/connect-node1 CANCELLED(session détruite lue en annulation) -
Forcer 14 chez tous les clients exigerait d’inscrire chaque appel unaire (≈ 50 ns par appel) : écarté, l’unaire reste à 0. L’écart de connect-node appartient au client.
-
Une application aux appels longs règle
shutdownTimeoutau-dessus de son échéance.
-
Coût, mesuré (médiane de 7 passes, Node du poste) :
| Geste | Quand | Coût |
|---|---|---|
| Registre du noyau : ajout + retrait | chaque flux long (SSE, octets, gRPC) | 44 à 77 ns, constant de 0 à 10 000 flux ouverts |
| Enrobage de l’itérateur | chaque message d’un flux | +34 ns : la relecture de l’interruption à chaque message (then), qui ferme le 0 OK du point 2 |
| Appel unaire | — | 0 ; constaté sur serveur réel : 783 / 760 / 742 / 753 µs par appel à 0, 1 000, 10 000 puis 0 flux ouverts |
| Interruption à l’arrêt | une fois | proportionnel aux flux ouverts ; attente bornée à 1 s avant le drain |
Écarté : shutdownSignal |
CHAQUE appel, unaire compris | mesuré sur createHandlerContext réel : +0,2 µs à vide, +12 µs à 1 000 appels ouverts, +122 µs à 10 000 |
Relevé en passant, hors décision : le contexte que Connect crée par appel (createHandlerContext,
signaux liés, puis un abort() final) coûte 7 à 12 µs par appel selon la charge du poste,
mesuré sur la fonction réelle, sans shutdownSignal. L’essentiel vient de l’abort() SANS motif,
qui alloue une DOMException avec sa pile : 12,3 µs contre 4,8 µs avec un motif préalloué, soit
≈ 7,5 µs évitables sur chaque appel. C’est un plancher de la bibliothèque, pas un surcoût de
Nodefony ; il entre dans la mesure par appel (« Conséquences »).
Trois signalements amont sont envoyés à Connect, reproductions et mesures comprises :
connect-es 1876 (promesse qui ne
se résout pas), 1877
(DOMException par appel), 1878
(shutdownSignal linéaire). Un quatrième, chez Node (coût linéaire d’EventTarget), est retenu :
le cas courant y va bien, et le motif disparaît si Connect corrige le sien.
D9 — Les navigateurs d’une autre origine (CORS)#
Décision (2026-11-11) :
Le constat. Le pare-feu répond au préflight OPTIONS en 204 AVANT le routage, avec la politique
unique de l’application (firewall.ts#Firewall.handleCors, cors.ts#Cors). Il pose les en-têtes
de la requête réelle dans la réserve de la réponse. L’étape CSRF accepte déjà une origine autorisée
par CORS (csrf.ts#Csrf.enforce, point 1). Connect publie les en-têtes que ses protocoles exigent
(cors.allowedHeaders, cors.exposedHeaders, cors.allowedMethods, connect-cors.md).
- Une seule politique CORS, celle de l’application : aucune section CORS dans
grpc. - Préflight. Dès qu’un service gRPC est déclaré et que le CORS est actif, la politique reçoit au
démarrage l’union de ses listes avec celles de Connect (
grpc-timeout,connect-protocol-version,x-grpc-web…, méthodesPOSTetGET). Le préflight ne connaît pas la route : l’union est la seule voie. Le démarrage l’annonce.- L’union se fait à
onReady(firewall.ts#Firewall.#widenCorsForRpc) : après TOUS lesonBoot— les routes gRPC s’y marquent, dans un ordre de modules que rien ne fixe —, avant l’ouverture des ports. Comparaison sans casse : une liste écritecontent-typene reçoit pas un secondContent-Type. - Les listes sont celles de Connect (
corsde@connectrpc/connect), RECOPIÉES dans@nodefony/httpprincipal (grpc/cors.ts#rpcCorsLists), qui ne charge jamais Connect (D12) ; un test compare la copie à l’original. - Nécessaire : la liste par défaut vaut
Authorization, Content-Type, X-Requested-With(security/…/config/config.ts,corsSchema) ; un client gRPC-Web qui envoiex-grpc-webougrpc-timeoutserait refusé au préflight.
- L’union se fait à
- Réponse réelle. La remise en état des en-têtes (D6, point 2) y porte les en-têtes CORS. Sur
une réponse gRPC d’une origine autorisée seulement,
Access-Control-Expose-Headersreçoit la liste exposée de Connect —Grpc-Status,Grpc-Message,Grpc-Status-Details-Bin,Content-Encoding,Connect-Content-Encoding—, ajoutée à celle de l’application (GrpcEndpoint.ts#exposeRpcHeaders) : sans elle, un client gRPC-Web ne lit ni le statut ni l’encodage d’une réponse compressée. Les autres routes n’en reçoivent rien. - CSRF : rien à coder. Une origine autorisée passe ; une autre est refusée en gRPC (D5).
Coût : 0 par requête ; au démarrage, un écouteur onReady par pare-feu — même sans service
gRPC, retiré dès qu’il a tourné — et la politique recomposée une fois s’il y a lieu ; ≈ 110 octets
de plus, sur une réponse gRPC d’une origine autorisée seulement (une chaîne composée au
chargement, une lecture de la réserve).
D10 — Ce que voient la ligne d’accès et le traçage#
Décision (2026-11-11) :
Le constat. Les trois journaux (request-logger.ts#DefaultRequestLogger,
pretty-request-logger.ts#PrettyRequestLogger, audit-logger.ts#AuditLogEntry) et le canal
nodefony.http.request (requestTrace.ts#closeRequestTrace) lisent context.response.statusCode.
Connect écrit sur la réponse native : ce statut reste 200. Constaté sur le fil (Connect 2.3.0,
24 cas, trois protocoles, HTTP/1.1 et HTTP/2) : en protocole Connect, une erreur part en 404 ou 500
natif, que Nodefony ne voit pas ; en gRPC et gRPC-Web, le résultat n’est que dans le trailer
grpc-status, que personne ne lit.
-
Un enregistrement d’appel RPC sur le contexte, générique.
HttpContext.rpc,nullpar défaut commerequestTrace: le système (le protocole parlé sur le fil :grpc,grpc-web,connect), la méthode (paquet.Service/Méthode, connue de la route : jamais_OTHER), le code et son nom (UNAVAILABLE, tiré d’une table constante).- C’est la fiche d’appel de D6 qui le porte : aucune allocation de plus.
- Le contrat vit dans http et ne nomme rien de Connect. Un appel JSON-RPC (porte MCP, A2A) pourra
le remplir (
jsonrpc,-32602) sans rupture.
-
Le code se lit une fois, au
close, avant la ligne d’accès (HttpKernel.settleRpc, appelé parHttpKernel.teardownHttp), sur le motif d’interruption du contexte d’appel (ctx.signal.reason) :Motif d’interruption responseEndedCode ConnectErrorvrai son code ; sa cause, une Error, devient l’erreur (3)ConnectErrord’une fin posée par le serveur (4, fiche)faux son code : échéance 4, délai 4 ou identité révoquée 16 toute autre ConnectErrorfaux 1 CANCELLED: le client est parti, quel que soit son RSTAbortError, aucunvrai 0 OKAbortError, aucunfaux 1 CANCELLED: le client est partiautre — 13 INTERNAL, la cause devient l’erreur (3)- Le contexte d’appel est capté AVANT le corps, par l’option
requestGatede l’adaptateur prise en simple observateur (GrpcEndpoint.ts#observeCall) : elle ne refuse jamais, les refus gardent leur unique écrivain (D5 point 2). C’est le seul crochet de Connect qui voie les refus posés AVANT le gestionnaire — message trop grand ou bombe de décompression (8), encodage inconnu (12), en-tête d’échéance illisible —, Connect abaissant alors le signal sans jamais appeler le gestionnaire : capté par le gestionnaire seul, l’appel se lisait 0OK. Les intercepteurs ne conviennent pas : ils s’exécutent après la lecture du premier message. - Réponse non finie : 1, sauf une fin posée par le serveur. Le signal relaie le
RST_STREAMdu client traduit en code (node-error.js#connectErrorFromH2ResetCode) : connect-node coupe à son échéance enINTERNAL_ERROR, que le serveur lisait 13 — une ligne499 … INTERNALen gravité ERROR, pour un client simplement parti. Le code du RST est le fait du client ; le fait du serveur, c’est que la réponse n’a pas été terminée. - « Réponse finie » =
responseEnded.ts#responseEnded, la règle unique du noyau, celle qui pose déjà 499 quand le client part (HttpKernel.createHttpContext). Elle sépare, en HTTP/2, la fin posée par le serveur de l’annulation du client (RST_STREAM), quewritableFinishedconfond. Le code 1 et le statut 499 disent donc le même fait, comme la table de D7 (499 → 1). - Constaté sur le fil, avec cette règle : les 24 codes sont ceux que lit le client, sauf une course. Quand l’échéance du client expire, il coupe au même instant que le minuteur du serveur, en HTTP/1.1 comme en HTTP/2. Selon le premier arrivé, le serveur journalise 4 ou 1 ; les deux sont vus d’un passage à l’autre, et rien côté serveur ne permet de trancher.
- « Aucun motif » arrive en HTTP/1.1 : l’écouteur
closedu noyau, posé à la création du contexte, passe avant celui de Connect. - Le statut HTTP natif est recopié si la réponse est finie, et seulement alors. C’est la
règle du relais (
HttpContext.ts#HttpContext.logRequest), tenue au même endroit pour toute réponse écrite par un tiers. Le relais, lui, recopie aujourd’hui sans condition : un client parti au milieu d’une requête relayée voit son 499 écrasé par le statut de l’amont (lu au code, pas encore vu sur le fil). La règle commune le corrige ; un test vu rouge le prouvera.
- Le contexte d’appel est capté AVANT le corps, par l’option
-
Un appel en erreur = une ligne, comme une exception de route HTTP. Une cause qui n’est pas une
ConnectErrordevientcontext.error: la ligne d’accès la porte, le canal publieerror. Précise D7 point 4 : « le journal » est cette ligne, jamais une seconde. -
Gravité selon la convention OpenTelemetry du serveur gRPC : 0 → INFO ; 2, 4, 12, 13, 14, 15 → ERROR (« SHOULD be considered errors ») ; les autres → WARNING. Une fonction, à côté de
severityFromStatus, pour les trois journaux.- La ligne garde le statut HTTP et ajoute
RPC : <méthode> <NOM>. - L’audit JSON reçoit un champ
rpc,nullhors RPC (forme stable).
- La ligne garde le statut HTTP et ajoute
-
Canal de traçage.
IRequestTracegagnerpc(nullhors RPC) : un ajout, pas une rupture.statusCodereste le statut HTTP, vrai sur le fil (http.response.status_code).- Nodefony n’importe rien d’OpenTelemetry. La documentation donne la correspondance : nom du span
=
rpc.method;rpc.system.name=grpc(convention stable) ouconnectrpc(convention en développement, celle de l’implémentation), au choix de l’extension ;rpc.status_code= le nom ;error.type;rpc.server.call.duration=durationMs / 1000. - Même horloge que le span, comme la norme l’exige. Un flux = un span, de l’ouverture au
close.
- Nodefony n’importe rien d’OpenTelemetry. La documentation donne la correspondance : nom du span
=
-
traceparent: rien à coder. Les métadonnées gRPC sont des en-têtes HTTP : la propagation W3C existante les lit déjà. -
Rien par message : ni trace ni ligne, comme pour les trames WebSocket.
Normes : conventions sémantiques OpenTelemetry, docs/rpc/{rpc-spans,grpc,connect-rpc,rpc-metrics}.md
(open-telemetry/semantic-conventions@d0d92008).
Coût, mesuré (médiane de 7 passes, Node du poste) :
| Geste | Quand | Coût |
|---|---|---|
Code lu au close |
chaque appel | ≈ 14 ns (lecture du motif déjà comptée par D7) |
Observateur requestGate |
chaque appel | ≈ 55 à 95 ns isolé, invisible dans un appel (¹) |
Segment RPC : … de la ligne d’accès |
chaque appel | ≈ +6 ns (64 → 70 ns pour la ligne) |
Champ rpc du contexte |
chaque requête HTTP | un champ null (8 octets), un test au démontage |
Champ rpc de la trace |
chaque requête, avec abonné | une écriture de champ |
| Message d’un flux | — | 0 |
(¹) Connect écrit await opt.requestGate(context) : même pour une fonction synchrone qui rend
undefined, l’await suspend le gestionnaire et le reprend par une microtâche. L’appel lui-même
coûte ≈ 4 ns (un instanceof, une écriture de champ) ; la suspension, le reste. Ni allocation
retenue, ni entrée-sortie, ni tour de boucle : une microtâche, pas une latence réseau. Dans un appel
unaire Connect complet servi en process (≈ 36 µs), l’écart reste sous le bruit d’une mesure A/A
(± 0,6 µs). Le ramener à 0 relève de Connect — n’attendre que ce qui est une promesse —, pas de
Nodefony.
D11 — Une surface expérimentale dans des paquets stables#
Décision (2026-11-11) :
Le constat. La politique ne connaît que le paquet entier : la clé nodefony.stability, recopiée
à quatre endroits et gardée par src/nodefony/src/tests/stability.test.ts. Or la surface gRPC naît
dans deux paquets STABLES : la déclaration dans @nodefony/framework (D1), le transport dans
@nodefony/http (ADR-0021). Un paquet @nodefony/grpc à part suivrait le précédent de
@nodefony/realtime, mais rouvrirait D1 et ADR-0021, accepté et sous le gel du temps réel :
écarté. Le dépôt porte déjà une étiquette de symbole que la politique ignore :
bundler/buildReport.ts#buildReportDevtools, publiée par nodefony/bundler, est @experimental
sans être nommée nulle part. Le grain manque, et il a déjà dérivé une fois.
- La source est l’étiquette TSDoc
@experimentalsur le symbole, ou sur le membre (un champ neuf d’une interface stable, commeIRequestTrace.rpc). C’est une étiquette standard de TSDoc (StandardTags.experimental, même sens que@beta), conservée dans le.d.tspublié : l’éditeur et l’agent de l’utilisateur la voient au survol. - Tout symbole public, ou membre public, qu’ajoute cette décision naît
@experimental. Cela vaut pour la déclaration (GrpcController,@GrpcService), le transport, le champ de route de D5, la fermeture fournie de D6, le contrat d’appel RPC de D10 (IRpcCall,HttpContext.rpc,IRequestTrace.rpc) et la sectiongrpcde la configuration. Ce qui n’est pas exporté ne porte rien : ce n’est pas une surface (docs/guides/compatibilite.md, « la garantie porte surexports»). - Deux copies, gardées par le contrôle de stabilité, étendu au symbole (il lit le
.d.tsbâti, donc tourne après le build) :- la politique gagne un tableau « Symboles expérimentaux d’un paquet stable » (symbole, paquet, pourquoi). Le contrôle exige que l’ensemble des symboles étiquetés dans les paquets stables publiés soit EXACTEMENT celui du tableau, dans les deux sens ;
- une page d’un paquet stable peut porter
status: experimentalsi elle documente un symbole expérimental de son paquet, et seulement alors. - Un seul lecteur de la surface :
scripts/release/api-diff-core.mjs, qui lit déjà le.d.tspublié de chaque entrée d’exports, membre par membre, avec un programme TypeScript (readTypeDeclarations). Il apprend à rendre l’étiquette (ts.getJSDocTags). Ce qu’il lit est l’artefact reçu, et seulement la surface publique. Jamais une expression régulière sur les sources : une étiquette sur un membre doit nommer le membre. buildReportDevtoolsentre au tableau (« suit une option expérimentale de rolldown ») : le contrôle, vu rouge une fois, le signale avant toute correction.
- Mêmes règles que le paquet : un symbole sort de l’expérimental en version mineure, en perdant son étiquette et sa ligne ; un symbole stable ne redevient jamais expérimental au cours d’une série ; chaque changement est annoncé au changelog. Aucun avertissement à l’exécution.
- Le changelog distingue une rupture d’un changement expérimental. Aujourd’hui,
api-diff-core.mjs#apiDiffChangelogEntriesmarquerupture: truetout retrait mesuré, sans regarder la stabilité (aucune mention destabilitydansscripts/release/). Un retrait dans@nodefony/ai, paquet expérimental, sortirait donc en « rupture » dans une version mineure, ce que la politique permet sans rupture. Ce défaut existe déjà, avec ou sans gRPC.- Désormais, un changement qui touche un symbole étiqueté (lu dans la version publiée de
référence, celle qui portait le symbole) ou un paquet
experimentalest écrit au changelog comme changement expérimental, toujours annoncé, jamais marqué rupture.
- Désormais, un changement qui touche un symbole étiqueté (lu dans la version publiée de
référence, celle qui portait le symbole) ou un paquet
Coût : 0 à l’exécution (un commentaire) ; une lecture d’étiquette de plus dans un lecteur qui tourne déjà à la publication.
D12 — Comment Connect et protobuf arrivent dans une application#
Décision (2026-11-11) :
Le constat.
@connectrpc/connect-node2.3.0 exige@connectrpc/connectexactement en 2.3.0, et@bufbuild/protobuf^2.7.0.@bufbuild/protoc-gen-esexige protobuf exactement à sa propre version : le générateur et le runtime de l’application vont donc ensemble (D2).- Coût du chargement, mesuré avec un processus neuf par passe (médiane de 7) : importer
connect-nodeet le code généré coûte 171 ms et 6,6 Mo de tas, une fois par processus.connect-nodetire les deux autres paquets, si bien que ce chiffre est le coût réel, pas une borne. Sur disque, l’installation pèse 4,7 Mo. - Les types. Un
.d.tsqui importe un paquet absent, même parimport type, rend TS2307 à une application enskipLibCheck: false(constaté). Le gabarit le met àtrue, mais l’application reste libre de le changer. - Le bundler. Les
rolldown.config.tsde http et de framework listent leurs dépendances externes à la main : un paquet absent de cette liste serait recopié dansdist. - Le diagnostic.
Kernel.ts#Kernel.bootRemediationHintlit toutERR_MODULE_NOT_FOUNDcomme un « dist périmé ». Or Node distingue les deux cas :Cannot find package '<nom>'pour un paquet absent,Cannot find module '<chemin>'pour un fichier absent. - Le « premier appel » du POC ne tient pas pour protobuf.
@GrpcService(Contrat)fait importer le code généré directement par le contrôleur, si bien que protobuf se charge au démarrage (D1 point 7, écrit en conséquence).
- Pairs facultatifs, jamais des
dependencies:@nodefony/httpdéclare les trois paquets (peerDependenciesetpeerDependenciesMeta.optional) ;@nodefony/frameworkdéclare@bufbuild/protobufet@connectrpc/connect, pour les types ;- une application sans gRPC n’installe rien, ce qui suit le précédent
pg(drizzle) etargon2(user) ; - l’application qui sert un service les déclare dans ses
dependencies(D2 point 8).
- Plages de versions :
^2.3.0pour les deux paquets Connect (la version éprouvée par D7 et D10) ;^2.7.0pour protobuf (le plancher de Connect lui-même) ;- la majeure suivante est exclue, et l’élargir plus tard est un changement expérimental (D11), jamais une rupture ;
- un test compare les plages déclarées par http et par framework, car la frontière entre les
paquets impose deux copies. La règle est générale : un pair déclaré par plusieurs paquets
publiés n’a qu’une plage (
scripts/release/peers.mjs#divergentPeerRanges).
- Deux sous-chemins,
@nodefony/http/grpcet@nodefony/framework/grpc, sur le modèle denodefony/react:- le point d’entrée principal ne cite ni Connect ni protobuf, même en type.
HttpContext.rpc,IRpcCalletIRequestTrace.rpcrestent dans le point d’entrée principal, puisqu’ils ne dépendent pas de Connect (D10) ; - la reconnaissance d’une
ConnectErrorà la fermeture de la réponse (D10, point 2) vit dans le sous-chemin, où elle est posée dans la fiche d’appel. Elle peut se faire là grâce àConnectError[Symbol.hasInstance]; - les sources de chaque sous-chemin sont déjà prises par le bundler (
nodefonyInput) et partsconfig.declarations.json(nodefony/**/*.ts) ; - le contrôle de stabilité de D11 lit chaque entrée d’
exports, donc aussi les deux nouvelles ; - deux contrôles de la chaîne de publication gardent la promesse, pour TOUT pair facultatif et
non pour gRPC seul. Côté types,
scripts/release/dts-deps.mjs#reachableTypeImportssuit les imports relatifs depuis les types d’exports["."]: c’est ce que TypeScript charge, donc un pair facultatif atteint vaut TS2307. Côté exécution,scripts/release/peers.mjsimporte le point d’entrée principal dans un processus neuf et relève les paquets résolus parmodule.registerHooks. Une application témoin compilée sans les pairs était envisagée ; elle est écartée, car dans le dépôt les pairs sont hissés dansnode_moduleset seraient trouvés quand même. Les deux contrôles ont été vus rouges sur unimport typede protobuf et un import de Connect posés au fond du graphe de http, et le second a relevé aussi la contagion à framework.
- le point d’entrée principal ne cite ni Connect ni protobuf, même en type.
- Chargement au démarrage, et seulement si un service est déclaré (précise D1 point 7) :
- le contrôleur importe le sous-chemin, qui importe Connect directement ;
- une application sans service ne charge rien, ce qui garde la promesse « coût nul sans service » ;
- un pair manquant se voit au déploiement, au lieu d’un exemplaire déclaré prêt qui échoue à chaque appel ;
- les 171 ms ne tombent pas sur le premier appel ;
- pas d’
import()dynamique. Le démarrage s’arrête en production pour un module critique, le défaut (Kernel.ts#Kernel.isBootErrorFatal). Un module marquécritical: falsedémarre sans le service, avec un avertissement : c’est le choix explicite de l’application.
- Un pair absent est nommé.
bootRemediationHintdistingueCannot find package '<nom>'et rendnpm i <nom>; « dist périmé » ne vaut que pour un fichier absent. Ce défaut existe déjà, et le correctif vaut pour tout pair. - Deux fichiers de configuration changent :
package.jsonde http et de framework : les entréesexports,peerDependenciesetpeerDependenciesMeta;rolldown.config.tsde http et de framework : les trois paquets dansexternal.
Coût
| Chemin | Coût |
|---|---|
| Application sans service gRPC | rien d’installé, rien de chargé ; le champ rpc null de D10 (8 octets par contexte) |
| Démarrage avec un service | 171 ms et 6,6 Mo de tas, une fois par processus (mesurés) |
| Appel, message | 0 |
D13 — Interopérabilité avec @grpc/grpc-js et grpcurl#
Décision (2026-11-11) :
Le constat. Deux sources d’essai :
- le service de démonstration du serveur de développement, interrogé en lecture seule (h2c 5153, TLS 5152, HTTP/1.1 5151) ;
- l’adaptateur nu sur
node:http2.
Les clients éprouvés sont @grpc/grpc-js 1.14.7, grpcurl 1.9.4 (bâti sur grpc-go) et les trois
transports de connect-es.
- Chemin nominal : conforme. Sur les deux clients :
- appel unaire, en h2c et en TLS (ALPN
h2) ; - flux bidirectionnel réellement entrelacé ;
- erreur métier (code et message) ;
- échéance (
grpc-timeoutreçu, code 4) ; - métadonnées texte et binaires (
-bin), dans les deux sens ; - compression gzip ;
- requête de 5 Mio ;
- battements de maintien (PING HTTP/2 toutes les 200 ms).
- appel unaire, en h2c et en TLS (ALPN
- Refus : la forme décide du code, et elle n’est pas la même pour tous. Essai sur trois formes
de refus :
- quand la trame d’en-têtes porte la fin du flux, les deux clients lisent
UNIMPLEMENTED, que la réponse soit un 404 nu, un 404text/htmlou la forme gRPC (statut 200 etgrpc-status: 12) ; - quand la fin arrive dans une trame DATA, grpc-go lit
INTERNAL. C’est le cas d’unwriteHeadsuivi deend()dans l’API de compatibilité : « server closed the stream without sending trailers ». - Le 404 JSON de Nodefony (chemin inconnu) et le 404 nu de l’adaptateur (méthode inconnue, casse
modifiée) sont dans ce second cas. grpc-js et connect-es lisent tous deux
UNIMPLEMENTED. - ⚠️ La forme gRPC écrite par l’API de compatibilité échoue aussi : grpc-js y lit
INTERNAL(« RST_STREAM with code 0 »).
- quand la trame d’en-têtes porte la fin du flux, les deux clients lisent
- Un appel en flux vers un chemin inconnu reste bloqué.
grpcurl listtient 60 s, jusqu’à son échéance.- Cause : quand aucune route ne correspond,
http-kernel.ts#HttpKernel.serveHttpRequestlit le corps jusqu’au bout avant le 404. Le client d’un flux attend une réponse avant de finir son envoi. - En HTTP/2, aucun délai ne bornait cette lecture : défaut général du transport, hors gRPC, constaté sur un POST nu (aucune réponse au bout de 40 s, alors que HTTP/1.1 coupe à 30 s). Corrigé depuis : 408 vers 31 s. Le point 1 reste nécessaire, un 404 n’a pas à attendre le corps.
- Cause : quand aucune route ne correspond,
- Ne pas lire le corps quand le routage a déjà échoué (404, 405) :
- l’ordre des gardes reste inchangé : en-têtes du schéma, domaine (421), crochet
beforeResolve, puis le refus. Seule la lecture du corps est sautée, car un refus n’en a pas besoin ; - le corps non lu est traité par la règle de D5 : en HTTP/2, réponse puis
RST NO_ERRORsi le client ÉMET ENCORE ; en HTTP/1.1, vidange d’au plus 256 Kio. Une seule implémentation pour les deux usages (HttpResponse.closeUnfinishedRequest, surchargée parHttp2Response) ;- précisé le 2026-11-12 : « émet encore » se décide après une grâce d’un
aller-retour — un
PING(RFC 9113 §6.7), puis l’état du flux (stream.state.remoteClose). Ce n’est PAS une garantie : §6.7 fait passer l’écho d’unPINGavant les autres trames (« SHOULD be given higher priority »), une trame DATA encore en file chez le client peut donc arriver après lui ; leRST_STREAMreste alors conforme (§8.1 : le serveur PEUT couper, le client NE DOIT PAS jeter la réponse). - Pratique courante (sources lues : grpc-go
http2_server.go#WriteStatus, Gonet/http2, nginxngx_http_v2.c) : couper AUSSITÔT si le client n’a pas fini d’émettre, en s’appuyant sur §8.1 — sansPING. LePINGrépond à une particularité de Node, et son motif est mesuré : Node répond AVANT de lire les trames DATA déjà en route, quand ces serveurs lisent la requête d’abord, si bien que la coupe immédiate frappait des clients qui finissaient d’émettre. Le client HTTP/2 de Go (connect-go, référence de la suite de conformité) lit ceRST_STREAMen erreur malgré §8.1 (stream error … NO_ERROR; received from peer) : 4 casunexpected-urirouges, et 13 cas du bancgrpc-refusal.test.tsavec les clients Node et connect-es. - Bornes : un
PINGpar aller-retour et PAR SESSION, quel que soit le nombre de refus en attente (http2StreamGrace.ts#closeStreamAfterGrace), chemin d’erreur seul. Un refus arrivé pendant unPINGen vol attend le suivant ; jamais de coupe sans grâce : unRST_STREAMsoumis pendant que la réponse attend dans la file de nghttp2 la fait jeter, ce que §8.1 exclut (« after sending a complete response »). La première version coupait aussitôt au-delà des 10PINGen vol de Node : 22 réponses perdues sur 32 refus simultanés (banc des refus simultanés). Session en fermeture gracieuse : plus dePINGpossible, coupe au tour de boucle suivant. Un client muet ou qui émet sans fin est coupé en un aller-retour (banc vert).request.completene sert pas : il ne passe àtruequ’une fois le corps CONSOMMÉ ;
- précisé le 2026-11-12 : « émet encore » se décide après une grâce d’un
aller-retour — un
- un 404 coûte moins qu’aujourd’hui.
- l’ordre des gardes reste inchangé : en-têtes du schéma, domaine (421), crochet
- Une requête
application/grpc(gRPC natif) refusée avant l’adaptateur s’écrit en forme gRPC — statut 200,content-typegRPC,grpc-status,grpc-messagegénérique (D5, point 4), et fin du flux portée par la trame d’en-têtes :-
une seule fonction dans
@nodefony/http, sans Connect, appelée à deux endroits :- par le rendu d’erreur du noyau (404, 405, 429, 421…) ;
- comme
fallbackdeconnectNodeAdapter(méthode inconnue, casse modifiée) ;
-
le code est celui qu’un client conforme aurait déduit du statut HTTP : la correspondance des refus de transport (
grpc-http-grpc-status-mapping.md), servie par une seule fonction, distincte de la table des erreurs de l’application (D7) :HTTP gRPC 400 13 INTERNAL401, 403 16 ou 7, selon l’identité (D5) 404, 405 12 UNIMPLEMENTED(405 : aucune méthode gRPC à ce chemin)421 14 UNAVAILABLE(RFC 9110 : réessayer sur une autre connexion)429, 502, 503, 504 14 UNAVAILABLEautre 2 UNKNOWN405 et 421 manquent à la table normative, qui les laisserait en
UNKNOWN; le motif de chacun est écrit dans la colonne ; -
en HTTP/2, l’écriture passe par
stream.respond(en-têtes, { endStream: true }), jamais parwriteHeadpuisend. Cette seconde forme est constatée fausse chez les deux clients ; -
le protocole Connect garde ses statuts HTTP : connect-es les lit correctement, et c’est ce que la spécification de Connect prescrit (précisé ci-dessous, avec la forme de gRPC-Web).
-
Précision (2026-11-12) : le statut seul ne suffit pas, le CORPS aussi doit être celui du protocole. Constaté par la suite de conformité officielle de Connect (
connectconformancev1.0.7, 20 casunexpected-uri/unexpected-verb) : le 404 ou 405 du routeur porte le JSON générique de Nodefony ("code": 404, numérique), que le client de référence refuse.- Connect : corps absent, ou une
Errorà code TEXTE ({"code":"unimplemented"}) enapplication/json(connect-protocol.md§Unary-Response, table des codes) ; - gRPC-Web : une réponse au format gRPC-Web portant le statut gRPC de la table ci-dessus ;
- la requête Connect se reconnaît à
connect-protocol-version(ouapplication/connect+*), gRPC-Web àapplication/grpc-web*; le JSON d’une API ordinaire reste inchangé ; - preuve : la liste
src/modules/test/conformance/known-failing.txtest vide.
- Connect : corps absent, ou une
-
Précision (2026-11-12) : en Connect, le code est celui que le client DÉDUIT du statut HTTP, par la table « HTTP to Error Code » de
connect-protocol.md(405 et 421 →unknown), jamais par la table ci-dessus.- Pourquoi : en Connect le statut HTTP voyage avec la réponse, et la norme veut que le code de
l’
Errorcorresponde au statut (« HTTP-Status should match Error.code »). Les lignes 405 et 421 de la table ci-dessus sont des ajouts de Nodefony pour le gRPC natif, où le statut HTTP vaut 200 et ne dit rien ; en Connect, elles contrediraient le statut qui part avec. - Constaté : la suite de conformité exige
405+unknownen Connect (connect_server_unexpected.yaml, casunexpected-verb), et accepteUNIMPLEMENTEDpour la même requête en gRPC et en gRPC-Web. - La règle d’identité (D5) s’applique aussi : un refus sans identité part en
unauthenticatedavec le statut 401, un appelant identifié enpermission_deniedavec 403.
- Pourquoi : en Connect le statut HTTP voyage avec la réponse, et la norme veut que le code de
l’
-
Formes écrites, par protocole :
Protocole Statut HTTP Corps gRPC ( application/grpc*)200, Trailers-Only aucun gRPC-Web ( application/grpc-web*)200, Trailers-Only aucun ( grpc-PROTOCOL-WEB.md, point 4)Connect unaire ( connect-protocol-version)celui du refus (401/403 : D5) {"code":"<code>"},application/jsonConnect en flux ( application/connect+*)200 un message de fin {"error":{"code":"<code>"}}En HTTP/2, toute réponse dont les en-têtes portent
grpc-statusse termine sur la trame d’en-têtes (Http2Response.writeHead) : c’est la définition du Trailers-Only, et la règle ne dépend d’aucun drapeau.
-
- Une requête gRPC native qui aboutit à une route qui n’est pas gRPC est refusée en 12
UNIMPLEMENTED, jamais servie. Le Router fusionne routes littérales et motifs par ordre d’insertion, les replis en dernier (router.ts, commentaire de l’index) : sous une route attrape-tout (page unique), une méthode inconnue n’échoue pas au routage, elle reçoit la page en 200 ou un 405 (S-grpc-19). Coût : une comparaison de préfixe ducontent-type, sur une requête POST qui aboutit à une route non gRPC, et seulement quand un service est déclaré. - Les preuves tournent sur les deux clients :
@grpc/grpc-jset@grpc/proto-loaderen dépendances de développement du banc ;grpcurl, version figée, installé dans la CI Linux sur le patron de gitleaks (.github/workflows/secrets.yml), et déclaré dansscripts/test/vitest/gates.ts;- le cas «
writeHeadpuisend» est vu rouge une fois.
- Signalement amont : le 404 nu par défaut que grpc-go lit
INTERNAL. Envoyé à connect-es (connect-es 1882), qui l’a refusé : le défaut est un bug de grpc-go introduit en 1.82.0 et corrigé en 1.84.0 (grpc-go 9217), et le 404 nu reste le bon défaut d’un routeur qui partage le serveur avec d’autres routes. La mise à jour de la dépendance est demandée à grpcurl (grpcurl 592) : sa v1.9.4, celle que la CI fige, embarque grpc-go 1.83.2. Ce point 2 ne change pas : Nodefony possède tout le serveur, il écrit doncUNIMPLEMENTEDlui-même, comme la spécification le demande au serveur, quelle que soit la version du client.
Coût
| Chemin | Coût |
|---|---|
| Appel accepté, message d’un flux | 0 |
| Refus d’une requête gRPC | une lecture d’en-tête (content-type) |
| 404 ou 405, tout protocole | la lecture du corps en moins |
Alternatives écartées (D1)#
- Un service injectable servi hors du Router (
@GrpcServicesur unService, table privée dans http) : l’autorisation par méthode vit dans le Resolver du framework, que http ne peut pas importer — une seconde autorisation, ou un@IsGrantedmuet (S-grpc-1) ; hôtes virtuels et priorité face aux autres routes à réécrire (S-grpc-19) ; contredit le pipeline où tous les transports convergent versrouter.resolve(docs/architecture/pipeline-requete.md). - Le même service, publié dans le Router par un pont : une autorisation unique, mais aucun point
d’entrée visible dans le module (S-grpc-12) — le développeur cherche ce que le module expose dans
nodefony/controller/et@controllers. - Un crochet de module
getGrpcServices()(modèle MCP) : nul endroit pour une garde par méthode, injection à la main (S-grpc-1). - Une entrée de configuration : la configuration porte des valeurs validées (Zod
strictObject), pas des classes. - Deux formes de déclaration au choix : deux pages, deux jeux de tests, et un agent qui hésite (S-grpc-12, S-grpc-14). Le « deux » existe déjà sous forme de couches : contrôleur pour l’entrée, service pour la logique.
Ailleurs dans l’ADR, les autres écarts sont écrits à leur décision : shutdownSignal (D8),
paquet @nodefony/grpc à part (D11), maxTimeoutMs (D4), recomposition de l’adaptateur (D6).
Contrôle de non-blocage#
Les travaux qui bâtissent sur cet adaptateur ne doivent pas exiger de rupture.
| Travail à venir | Ce qu’il lui faut | Empêché ? |
|---|---|---|
Pont vers le hub (@nodefony/realtime) |
un ChannelSink par abonné, refus avant le premier message, fin à motif |
non : realtime dépend déjà de http et de framework ; D7 traduit les refus avant le premier message. Contrainte : Connect sérialise chaque message par appel (serialization.js#createBinarySerialization), sans voie publique pour des octets déjà encodés. La règle d’ADR-0021 (« jamais un réencodage par abonné ») se tient par un message à champ bytes portant les octets de ChannelFrame : une copie par abonné en binaire, un base64 par abonné en JSON (Connect, gRPC-Web JSON). Coût à mesurer et forme à trancher avec ce pont ; ses pairs Connect s’ajoutent au test de parité des plages (D12, point 2). |
| Santé et réflexion | servies sans jeton, joignables par la sonde de Kubernetes | non, mais trois choix sont ouverts et lui appartiennent : les sortir d’une zone de pare-feu qui couvre / (sinon D5 rend 16 à la sonde) ; leur paquet d’accueil (un GrpcController vit dans framework, que http ne peut pas importer) ; la sonde en clair face à h2c, activation explicite (D3, point 4). |
Conséquences#
@nodefony/frameworkgagneGrpcControlleret@GrpcService, et le sous-chemin@nodefony/framework/grpc;@nodefony/httpgarde la primitive de transport, sous@nodefony/http/grpc. Connect et protobuf sont des pairs facultatifs des deux paquets (D12).- Le noyau change pour toutes les routes, gRPC ou non :
- un 404 ou un 405 ne lit plus le corps (D13, point 1) ;
- un registre des flux longs vivants termine SSE, octets et gRPC à l’arrêt, avant le drain (D8) ;
HttpContext.rpcetIRequestTrace.rpcexistent,nullhors RPC (D10) ;- le relais ne recopie plus le statut de l’amont quand le client est parti (D10, point 2) ;
bootRemediationHintdistingue un paquet absent d’undistpérimé (D12, point 5).
- Configuration : une section
grpcdans la configuration http (protocoles servis, bornes de taille,requireConnectProtocolHeader) ; la politique CORS reçoit au démarrage l’union avec les listes de Connect quand un service est déclaré (D9). - Politique de compatibilité : contrôle de stabilité au grain du symbole, tableau des symboles expérimentaux d’un paquet stable, changelog qui distingue un changement expérimental d’une rupture (D11).
- Preuves exigées (tests vus rouges une fois) : un test par critère de fin de la décision,
dont l’interopérabilité en CI contre
@grpc/grpc-jsetgrpcurl(D13). - Mesures exigées : surcoût du pipeline par appel unaire contre l’adaptateur nu sur
http2.createServer, serveur en production, médiane de N passes, petite charge comprise ; débit d’un flux serveur contre la socket binaire, avec le plancher par message de l’adaptateur (D4) ; coût d’un unaire à 0, 1 000 et 10 000 flux ouverts (D8).
Matrice des scénarios#
Chaque scénario du catalogue, avec la décision qui le tient. « À prouver » : la décision le tient sur le papier, un test doit le montrer.
| Scénario | Décision(s) | Verdict |
|---|---|---|
| 1 | D1, D5 | tient |
| 2 | — | ouvert, appartient à « santé et réflexion » (contrôle de non-blocage) |
| 3 | — | ouvert, appartient au pont vers le hub (contrôle de non-blocage) |
| 4 | D1, D3 | tient : chemins à la racine, h2c opt-in |
| 5 | D1 point 3, D4 | tient ; mesure exigée |
| 6 | D4, D8 | tient, sans shutdownSignal |
| 7 | D3 | tient : aucun état partagé par le transport |
| 8 | D11 | tient |
| 9 | D1 point 6, D4, D5, D13 | tient |
| 10 | D2 point 6 | tient |
| 11 | D1 | tient |
| 12 | D1, D2 | tient |
| 13 | D10 | tient |
| 14 | D1, D7, D8 | tient : une fonction par correspondance, un registre |
| 15 | D1 | tient |
| 16 | D11, D12 | tient |
| 17 | D1 | tient |
| 18 | D1 point 5 | tient |
| 19 | D1, D13 point 3 | tient ; à prouver sous une route attrape-tout |
| 20 | D2 point 3 | tient |
| 21 | D2 point 1 | tient |
| 22 | D3 point 3, D9 | tient |
| 23 | D3 | tient |
| 24 | D4 point 1 | tient |
| 25 | D4 point 4 | tient |
| 26 | D4 point 3 | tient |
| 27 | D4 | tient |
| 28 | D5 point 3 | tient |
| 29 | D13 point 2 | tient |
| 30 | D5 | tient |
| 31 | D6 point 1 | tient |
| 32 | D6 point 2 | tient |
| 33 | D6 point 3, D8 point 2 | tient |
| 34 | D7 | tient |
| 35 | D8 | tient ; unaire plus long que le drain : statut lu par le client (D8 point 3) |
| 36 | D8 | tient, mesuré (D8, coût) |
| 37 | D9 | tient |
| 38 | D10 | tient |
| 39 | D10 point 2 | tient |
| 40 | D10 point 5 | tient |
| 41 | D11 | tient |
| 42 | D11 point 5 | tient |
| 43 | D12 point 3 | tient |
| 44 | D12 points 4 et 5 | tient |
| 45 | D12 point 2 | tient |
| 46 | D13 point 1 | tient ; à remesurer avec la borne de lecture du corps en HTTP/2 |
| 47 | D13 point 2 | tient |
| 48 | D13 point 4 | tient |