Nodefony 10.0.0-beta.7
Framework Node.js fullstack — HTTP & WebSocket, même contexte

gRPC — servir un service déclaré par un module

experimental@nodefony/frameworkmis à jour 2026-11-13

Un service gRPC se déclare comme une route : une classe GrpcController marquée @GrpcService(Contrat), listée dans @controllers([...]). Nodefony le sert sur les ports qu’il ouvre déjà, sous le pare-feu et @IsGranted, en gRPC, gRPC-Web et Connect à la fois. Cette page montre comment écrire le contrat et le contrôleur, puis ce que le framework décide à ta place — tailles, échéances, refus, erreurs, arrêt, CORS, journal — et pourquoi. Surface expérimentale : sa forme peut encore changer en version mineure.

📍 Documentation › Framework › gRPC

🧠 Schéma général#

Trois protocoles arrivent sur la même route : gRPC (un autre service, grpcurl, HTTP/2 obligatoire), gRPC-Web (un navigateur, qui n’a pas accès aux trailers) et Connect (un navigateur ou curl, en JSON ou en binaire). Tu écris ta méthode une fois, elle répond aux trois.

Un appel gRPC traverse le même pipeline qu’une requête HTTP ordinaire : une méthode gRPC est une route. Seule la dernière étape change : au lieu d’appeler une action, le contrôleur remet la requête à l’adaptateur Connect. Celui-ci reconnaît le protocole au content-type, décode le message, appelle ta méthode et écrit la réponse dans le format du client.

📖 Lexique#

Terme Développé En clair
RPC Remote Procedure Call appeler une fonction d’un autre programme comme si elle était locale
gRPC gRPC Remote Procedure Calls le protocole RPC de la CNCF : messages protobuf sur HTTP/2, statut dans les trailers
gRPC-Web — variante de gRPC lisible par un navigateur : statut dans le corps, HTTP/1.1 accepté
Connect protocole Connect variante HTTP simple (JSON ou binaire, curl suffit) ; aussi le nom de la bibliothèque @connectrpc/connect qui sert les trois
protobuf Protocol Buffers le langage de description des messages et le format binaire qui les encode
contrat fichier .proto la liste des services, méthodes et messages ; source unique du client et du serveur
buf outil buf compile, vérifie (lint, breaking) et génère le code d’un contrat
code généré *_pb.ts le TypeScript que buf generate tire du contrat : descripteurs et types des messages
unaire unary un message envoyé, un message reçu
flux streaming plusieurs messages : du serveur, du client, ou des deux (bidirectionnel)
trailers en-têtes de fin en-têtes envoyés APRÈS le corps ; gRPC y place grpc-status
Trailers-Only — réponse gRPC sans corps, dont les en-têtes portent déjà le statut et la fin du flux
échéance deadline délai qu’un client accorde à un appel (en-tête grpc-timeout) ; dépassé, statut 4
h2c HTTP/2 cleartext HTTP/2 sans TLS, pour une passerelle de confiance (port 5153, désactivé par défaut)
ALS AsyncLocalStorage le contexte de la requête (identité, requestId) qui suit le code asynchrone
CORS Cross-Origin Resource Sharing ce qu’un navigateur d’une autre origine a le droit d’appeler et de lire
CSRF Cross-Site Request Forgery un site tiers fait envoyer une requête par le navigateur de la victime à son insu
OTel OpenTelemetry conventions de nommage des traces et métriques

Qu’est-ce que c’est ?#

gRPC, c’est un appel de fonction à travers le réseau, avec un contrat signé des deux côtés. Le contrat (.proto) dit exactement quelles méthodes existent et quels messages elles prennent ; un outil en tire le code du client et du serveur, dans n’importe quel langage. Les deux parties ne peuvent pas se tromper de forme : le compilateur les en empêche.

On le choisit pour trois raisons :

La vision Nodefony#

Un service gRPC est un point d’entrée du module, comme une route ou un contrôleur temps réel. Trois choix en découlent, chacun avec son pourquoi.

  1. Le pipeline, pas un second serveur. La bibliothèque de référence @grpc/grpc-js ouvre son propre serveur : ni pare-feu, ni @IsGranted, ni gRPC-Web. Nodefony emploie Connect (@connectrpc/connect-node, Apache-2.0, aucune dépendance transitive), la seule bibliothèque qui fournit une fonction (requête, réponse) branchable dans une route. Chaque méthode devient une route littérale du Router, et une seule autorisation sert HTTP, WebSocket et gRPC (Resolver.ts#Resolver._enforceSecurity).
  2. Un contrôleur dédié, la logique dans un service. GrpcController est le jumeau de RealtimeController : le développeur cherche ce qu’un module expose dans @controllers, il le trouve là. Les gardes se lisent sur la méthode du contrat (GrpcController.ts#GrpcController.assertScope).
  3. Le statut se choisit sur l’identité. Un refus sans identité part en 16 UNAUTHENTICATED, un refus d’un appelant identifié en 7 PERMISSION_DENIED, quel que soit le statut HTTP. Avec 16, un agent rafraîchit son jeton et se reconnecte ; avec 7, il abandonne (refusal.ts#transportRefusalCode).

Le compromis assumé : chaque appel paie le pipeline (≈ 24 µs de code Nodefony, mesurés plus bas) en échange du pare-feu, de l’ALS, des en-têtes de sécurité, du journal et de la trace — les mêmes que sur toute route. Les décisions et leurs essais sont tracés dans ADR-0026.

🚀 Démarrage rapide#

Un service Greet dans une application générée par nodefony create app, appelé par curl et par grpcurl.

1. Les paquets, seulement si tu sers un service gRPC. Nodefony ne les installe pas et ne les exige pas : une application sans service gRPC n’en a besoin d’aucun, et rien ne se charge. Pour servir un service, ajoute le runtime en dépendances (l’installation de production doit l’avoir) et le générateur en développement :

npm i @connectrpc/connect @connectrpc/connect-node @bufbuild/protobuf
npm i -D @bufbuild/buf @bufbuild/protoc-gen-es

2. Le contrat, proto/greet/v1/greet.proto à la racine de l’application :

edition = "2024";

package greet.v1;

service GreetService {
  rpc Greet(GreetRequest) returns (GreetResponse);
}

message GreetRequest {
  string name = 1;
}

message GreetResponse {
  string greeting = 1;
}

3. La génération, deux fichiers à côté de proto/ :

# buf.yaml
version: v2
modules:
  - path: proto
lint:
  use: [STANDARD]
breaking:
  use: [FILE]
# buf.gen.yaml
version: v2
inputs:
  - directory: proto
plugins:
  - local: protoc-gen-es
    out: nodefony/gen
    opt: target=ts
npx buf generate   # écrit nodefony/gen/greet/v1/greet_pb.ts — commité, jamais édité

4. Le contrôleur, nodefony/controllers/GreetController.ts. Chaque méthode du contrat est une méthode de la classe ; une méthode manquante ou mal typée ne compile pas.

import { GrpcController, GrpcService } from "@nodefony/framework/grpc";
import type { ContextType } from "@nodefony/http";
import { GreetService } from "../gen/greet/v1/greet_pb";
import type { GreetRequest } from "../gen/greet/v1/greet_pb";

@GrpcService(GreetService)
export class GreetController extends GrpcController {
  constructor(context: ContextType) {
    super("GreetController", context);
  }

  greet(request: GreetRequest) {
    return { greeting: `Bonjour, ${request.name} !` };
  }
}

5. La déclaration, dans index.ts de l’application, à côté des autres contrôleurs :

import { GreetController } from "./nodefony/controllers/GreetController";

@controllers([HomeController, GreetController])
class App extends Module {
  // …
}

6. Ce qu’on observe, application démarrée (npx nodefony development) :

# Connect en JSON, HTTP/1.1 — curl suffit
curl -s http://127.0.0.1:5151/greet.v1.GreetService/Greet \
  -H 'content-type: application/json' -d '{"name":"Ada"}'
# → {"greeting":"Bonjour, Ada !"}

# gRPC natif, HTTP/2 + TLS (certificat de développement)
grpcurl -insecure -import-path proto -proto greet/v1/greet.proto \
  -d '{"name":"Ada"}' 127.0.0.1:5152 greet.v1.GreetService/Greet

La ligne d’accès nomme l’appel : POST /greet.v1.GreetService/Greet … RPC : greet.v1.GreetService/Greet. Le contrat et le contrôleur de cette page sont les fichiers d’un test du framework, qui monte la route et appelle la méthode (grpcQuickstart.test.ts) : la page ne peut pas dériver du code.

🧰 Écrire un service#

Les quatre formes de méthode#

La signature vient du code généré ; Nodefony n’y ajoute rien.

@GrpcService(ChatService)
export class ChatController extends GrpcController {
  // Unaire : un message, une réponse (ou une promesse de réponse).
  send(request: SendRequest, ctx: HandlerContext) {
    return { id: this.chat.post(request.text) };
  }

  // Flux serveur : un générateur asynchrone. Passer ctx.signal aux sources.
  async *follow(request: FollowRequest, ctx: HandlerContext) {
    for await (const message of this.chat.subscribe(request.room, ctx.signal)) {
      yield { text: message };
    }
  }

  // Flux bidirectionnel : on lit pendant qu'on écrit.
  async *converse(requests: AsyncIterable<ConverseRequest>) {
    for await (const request of requests) yield { echo: request.text };
  }
}

ctx est le HandlerContext de Connect : en-têtes reçus (ctx.requestHeader), en-têtes et trailers de réponse, signal d’annulation (ctx.signal), échéance du client (ctx.timeoutMs()).

La logique dans un service injecté#

Le contrôleur traduit ; le travail vit dans un service, partagé avec les routes HTTP et le temps réel. L’injection est celle de tout contrôleur.

@GrpcService(GreetService)
export class GreetController extends GrpcController {
  constructor(
    context: ContextType,
    @Inject("greeter") private readonly greeter: Greeter,
  ) {
    super("GreetController", context);
  }

  greet(request: GreetRequest) {
    return { greeting: this.greeter.greet(request.name) };
  }
}

Protéger une méthode#

Les décorateurs de sécurité de toute route s’appliquent, posés sur la méthode du contrat ou sur la classe. L’identité se lit par this.user, comme dans toute action.

@GrpcService(AccountService)
export class AccountController extends GrpcController {
  @IsGranted("ROLE_ADMIN")
  close(request: CloseRequest) {
    return { closedBy: this.user?.identifier ?? "" };
  }
}

Un appel sans jeton reçoit 16, un jeton valide sans le rôle reçoit 7 — section Refus et codes.

Ce que la déclaration engage#

Où vivent le contrat et le code généré#

Une convention, jamais une obligation : Nodefony ne lit aucun de ces fichiers, le contrôleur importe le code généré par un import ordinaire. Identique dans une application et dans un module.

Chemin Contenu Pourquoi
proto/<paquet>/v1/*.proto le contrat public hors du bundler, lisible par les clients d’autres langages
buf.yaml, buf.gen.yaml lint, compatibilité, génération STANDARD (dossier = paquet versionné) et FILE, la règle de compatibilité la plus stricte
nodefony/gen/**/*_pb.ts le code généré, commité Nodefony ne génère rien au build ni au démarrage ; une installation de production n’a pas buf

Pour un contrat neuf, edition = "2024" ; proto3 est accepté. Les types bien connus (google/protobuf/*) viennent de @bufbuild/protobuf/wkt, jamais régénérés. Un contrat tiers non publié sur le registre buf (A2A) se génère depuis son dépôt, version épinglée : inputs: - git_repo: …, tag: v1.0.1, subdir: specification.

🔌 Protocoles et ports#

Aucun serveur ni port neuf. La méthode répond sur chaque serveur actif, avec ce que son HTTP permet ; le protocole se reconnaît au content-type, dans le même gestionnaire.

Port HTTP gRPC gRPC-Web Connect
5152 HTTP/2 + TLS ✅ ✅ ✅
5153 (h2c, à activer) HTTP/2 en clair ✅ ✅ ✅
5151 HTTP/1.1 ❌ ✅ ✅

Mettre en situation.

Ton besoin Ce que tu fais Ce qui se passe
Un service Go appelle ton pod derrière un proxy qui termine TLS servers.h2c.enabled: true, le proxy en h2c vers 5153 gRPC natif servi en clair sur le lien interne
Une page web appelle la même méthode rien gRPC-Web ou Connect sur 5151 ou 5152
Interdire gRPC-Web à toute l’application grpc: { grpcWeb: false } la méthode ne répond plus qu’en gRPC et Connect

Le navigateur ne rouvre pas le CSRF#

Un POST Connect exige application/json ou application/proto (415 sinon) : un formulaire ou un text/plain d’une autre origine est refusé. Un POST JSON d’une autre origine déclenche un contrôle préalable CORS. Le GET n’existe que pour une méthode sans effet de bord. D’où requireConnectProtocolHeader: false par défaut : exiger l’en-tête casserait curl et le JSON écrit à la main sans fermer une faille de plus.

⚙️ Configuration#

La section grpc de la configuration de @nodefony/http vaut pour toute l’application ; le grain « par service » s’ajoutera sans rupture s’il trouve un usage (http/nodefony/config/config.ts#grpcSchema).

// nodefony.config.ts
use("@nodefony/http", {
  grpc: { grpcWeb: false, readMaxBytes: 8 * 1024 * 1024 },
});
Clé Type Défaut Effet
grpc booléen true sert gRPC (HTTP/2 seulement)
grpcWeb booléen true sert gRPC-Web, sur tous les serveurs
connect booléen true sert Connect, curl compris
readMaxBytes entier 4 Mio taille maximale d’un message reçu, après décompression
writeMaxBytes entier 4 Mio taille maximale d’un message émis
requireConnectProtocolHeader booléen false exige Connect-Protocol-Version (400 sans lui)

Au moins un protocole doit rester servi : pour n’en servir aucun, ne déclarer aucun service. Une clé mal orthographiée interrompt le démarrage en la nommant.

Limites : taille, durée, flux#

Limite Valeur Au-delà Pourquoi
message reçu 4 Mio (readMaxBytes) 8 RESOURCE_EXHAUSTED, méthode non appelée sans borne, quelques Ko compressés se décompressent en plusieurs Gio ; 4 Mio est la borne des implémentations de référence
message émis 4 Mio (writeMaxBytes) 8, journalisé chez nous les clients de référence refusent au-delà : l’erreur naît où on la lit
appel unaire min(échéance du client, responseTimeout) 4 DEADLINE_EXCEEDED même délai que toute route, au format du protocole
flux aucune échéance — un abonnement vit longtemps, comme le veut gRPC
client de flux qui ne lit plus 30 s de blocage coupé entre 30 et 45 s sinon un client lent retient la mémoire du serveur

🔐 Refus et codes#

Avant ta méthode, le pipeline refuse dans l’ordre de toute route : provenance CSRF, session, zone du pare-feu, puis @IsGranted. Le noyau écrit le refus au format du client, sans construire l’adaptateur (refusal.ts#prepareGrpcRefusal).

Situation Code
refus, aucune identité authentifiée (un anonyme compte comme personne) 16 UNAUTHENTICATED
refus, appelant identifié 7 PERMISSION_DENIED

Refus avant ta route : chemin inconnu, débit, hôte#

Un refus de transport (aucune route, méthode HTTP refusée, débit, hôte) suit la correspondance normative des statuts HTTP, distincte de celle des erreurs de ton application (refusal.ts#transportRefusalCode) :

HTTP gRPC
400 13 INTERNAL
401, 403 16 ou 7, selon l’identité
404, 405 12 UNIMPLEMENTED
421, 429, 502, 503, 504 14 UNAVAILABLE
autre 2 UNKNOWN

405 et 421 manquent à la table normative ; Nodefony les ajoute (aucune méthode gRPC à ce chemin ; réessayer sur une autre connexion). En protocole Connect, le statut HTTP voyage avec la réponse : le code est alors celui que le client en déduit (405 et 421 → unknown), comme la spécification de Connect le veut.

La forme écrite, par protocole#

Protocole Statut HTTP Corps
gRPC (application/grpc*) 200, Trailers-Only aucun
gRPC-Web (application/grpc-web*) 200, Trailers-Only aucun
Connect unaire celui du refus (401, 403…) {"code":"unauthenticated"}
Connect en flux 200 message de fin {"error":{"code":"…"}}

❗ Important

Un 404 ou un 405 ne lit plus le corps de la requête, pour toute route : un client de flux qui attend une réponse avant de finir son envoi (grpcurl list sur un chemin inconnu) n’est plus bloqué jusqu’à son échéance.

Erreurs levées pendant un appel#

Ce que ta méthode lève Ce que reçoit le client
ConnectError son code et son message, tels quels
HttpError d’un service partagé avec des routes HTTP le code de la table ci-dessous
toute autre exception 13 INTERNAL ; message en développement, générique en production

Table des erreurs de l’application, celle de google/rpc/code.proto (refusal.ts#applicationErrorCode) :

HTTP gRPC
400, 422 3 INVALID_ARGUMENT
401, 403 16 ou 7, selon l’identité
404 5 NOT_FOUND
409 10 ABORTED (ALREADY_EXISTS : lever une ConnectError)
412 9 FAILED_PRECONDITION
413, 429 8 RESOURCE_EXHAUSTED
499 1 CANCELLED
501 12 UNIMPLEMENTED
502, 503 14 UNAVAILABLE
408, 504 4 DEADLINE_EXCEEDED
autre 5xx 13 INTERNAL
autre 2 UNKNOWN
import { Code, ConnectError } from "@connectrpc/connect";

reserve(request: ReserveRequest) {
  if (this.stock.isEmpty(request.sku)) {
    throw new ConnectError("rupture de stock", Code.FailedPrecondition);
  }
  return this.stock.reserve(request.sku);
}

Arrêt du serveur#

À l’arrêt, Nodefony termine les flux avant de vider les connexions, dans cet ordre : sonde de disponibilité à 503, fermeture 1001 des WebSocket et fin des flux longs, puis drain HTTP.

Ce qui est en vol Ce qui se passe
un flux gRPC interrompu en 14 UNAVAILABLE (« réessaie, ailleurs ») ; le client rejoue sur un autre exemplaire
un appel unaire il finit pendant le drain, comme l’arrêt gracieux de gRPC
un appel neuf après l’annonce HTTP/2 refusé par HTTP/2, le client réessaie

La même liste des flux longs termine aussi SSE et les flux d’octets vivants : une seule implémentation pour tous (StreamLifecycle.ts#ShutdownRegistry).

🛡️ CORS — les navigateurs d’une autre origine#

Une seule politique CORS, celle de l’application : la section grpc n’en a pas.

Voir CORS pour la politique elle-même.

📡 Observabilité#

Un appel gRPC se lit dans les journaux comme une requête, avec son code gRPC en plus.

Pour une extension OpenTelemetry, la correspondance :

Attribut OTel Source
nom du span rpc.method
rpc.system.name grpc (convention stable) ou connectrpc
rpc.method HttpContext.rpc.method
rpc.status_code le nom du code
rpc.server.call.duration durationMs / 1000

Interopérabilité#

Éprouvée contre les clients que l’écosystème emploie, en intégration continue :

Deux comportements du serveur viennent de ces essais :

Une requête gRPC native qui aboutit à une route qui n’est pas gRPC (une page unique en attrape-tout, par exemple) reçoit 12 UNIMPLEMENTED, jamais la page.

Installation, chargement et stabilité#

⚡ Performance & mémoire#

Mesuré sur secteur, serveur de production, HTTP/2 + TLS, service d’écho de 16 octets (le pire cas : aucun travail métier), contre l’adaptateur Connect nu sur http2.createSecureServer, médiane de 7 passes en camps alternés (grpc-unary-overhead.mjs, skill nodefony-load-test) :

Mesure Valeur
surcoût du pipeline par appel unaire ≈ 84 µs en charge, ≈ 129 µs en série
dont code Nodefony (profil comparé) ≈ 24 µs : contexte et ALS, pare-feu, routage, ligne d’accès, en-têtes, code au close
refus gRPC face au 401 JSON, même route dans le bruit (×0,93 à ×0,95)
un refus face à un appel servi moins de la moitié du coût

📜 Normes appliquées#

Norme Ce qu’elle exige Où Nodefony s’y conforme
gRPC sur HTTP/2 (PROTOCOL-HTTP2) :path = /Service/Méthode, statut en trailers, Trailers-Only pour une erreur immédiate une route par méthode (GrpcService.ts#GrpcService), refus en Trailers-Only (refusal.ts#prepareGrpcRefusal)
gRPC-Web (PROTOCOL-WEB) statut dans un cadre de trailers du corps écrit par l’adaptateur ; refus en Trailers-Only
Protocole Connect GET pour NO_SIDE_EFFECTS seulement ; code d’erreur textuel ; code déduit du statut HTTP route GET conditionnelle ; refusal.ts#connectRefusalCode
Codes de statut gRPC (statuscodes.md) PERMISSION_DENIED interdit sans identité choix 16 ou 7 sur l’identité (refusal.ts#transportRefusalCode)
Correspondance HTTP → gRPC 404 → 12, 429/503 → 14… refusal.ts#transportRefusalCode
google/rpc/code.proto table HTTP des erreurs d’application refusal.ts#applicationErrorCode
RFC 9113 §6.7 et §8.1 PING prioritaire ; le serveur PEUT couper un flux après une réponse complète grâce d’un aller-retour (http2StreamGrace.ts#closeStreamAfterGrace)
OpenTelemetry, conventions RPC rpc.method, rpc.status_code, gravité du serveur HttpContext.rpc, gravité de la ligne d’accès

⚠️ Pièges (symptôme → cause → correction)#

Symptôme Cause Correction
Le démarrage s’arrête : « … sans effet sur un appel gRPC » un décorateur HTTP (@Body, @UseSession, @Csp…) sur une méthode du contrat le retirer ; un paramètre gRPC est le message, pas la requête HTTP
Cannot find package '@connectrpc/connect-node' au démarrage pair facultatif non installé npm i @connectrpc/connect @connectrpc/connect-node @bufbuild/protobuf
Le client gRPC échoue tout de suite en INTERNAL il vise 5151 (HTTP/1.1) 5152 en TLS, ou 5153 avec h2c activé
Un client d’agent abandonne au lieu de se reconnecter il a reçu 7 alors que son jeton a expiré ne pas réécrire le code : Nodefony rend 16 sans identité
Le flux finit en 13 au lieu du code voulu erreur levée APRÈS le premier message lever une ConnectError avec le code choisi
La méthode tourne encore après l’arrêt ou la révocation elle n’écoute pas ctx.signal passer ctx.signal aux sources (base, abonnement, fetch)
Le client gRPC-Web voit UNKNOWN sans statut réponse d’une origine non autorisée par CORS autoriser l’origine : l’exposition des en-têtes gRPC suit
Le JSON d’un google.protobuf.Any est refusé en 3 le type emballé est hors du graphe d’imports du contrat importer son .proto dans le contrat ; en binaire il passe
Le client lit 4 alors que le serveur journalise 1 échéance du client et délai du serveur expirent au même instant course sans gravité : les deux disent « trop long »
nodefony/gen/ diffère de ce que génère buf contrat modifié sans régénérer, ou version de protoc-gen-es changée npx buf generate et commiter

🧪 Tests & couverture#

Les chiffres exacts vivent dans la carte de tests de la page, régénérée depuis les fichiers, jamais figée dans le texte.

Couverture : npm run coverage dans @nodefony/framework et @nodefony/http.

🔗 Pour aller plus loin#