Serveurs — HTTP, HTTPS, HTTP/2, WebSocket

stable@nodefony/httpmis à jour 2026-07-19

Ce sont les portes d’entrée du processus : ce qui ouvre les sockets, accepte les connexions et transmet chaque requête — web ou temps réel — au même pipeline. Une application Nodefony ouvre jusqu’à deux ports (5151 en clair, 5152 en TLS) et y adosse quatre serveurs (HTTP, HTTPS/HTTP-2, WS, WSS). Cette page décrit ce qu’ils écoutent, comment on les règle, comment ils démarrent, comment ils s’arrêtent, et pourquoi ils ne doivent jamais tomber. Chaque fait est ancré sur le code.

📍 Documentation › @nodefony/http › Serveurs

🧠 Le modèle mental — deux ports, quatre serveurs, un pipeline#

Un serveur Nodefony n’est pas un « framework qui écoute ». C’est un assemblage de services : chaque serveur est un service injectable qui possède son socket, et tous délèguent au même orchestrateur, HttpKernel. Le WebSocket n’a pas de port à lui : il se greffe sur le serveur HTTP correspondant.

Trois idées à retenir, et tout le reste en découle :

1. Un serveur = un service DI. Ils sont déclarés dans @services([…]) du module (src/packages/@nodefony/http/index.ts:52) et instanciés par le conteneur, comme n’importe quel service — donc introspectables, testables, remplaçables.
2. Le WS hérite de son porteur. server-websocket reçoit le http.Server déjà en écoute (Websocket.createServer(), ^{server-websocket.ts:62}) ; server-websocket-secure reçoit le https.Server. Couper HTTPS coupe donc le WSS, sans autre réglage.
3. Les quatre convergent vers HttpKernel. Les serveurs ne connaissent ni les routes, ni les sessions, ni le firewall : ils branchent onHttpRequest / onWebsocketRequest et se taisent.

📖 Lexique#

Qu’est-ce qu’un serveur, ici ?#

Imagine un immeuble avec deux entrées : une porte de service (HTTP en clair, 5151) et une porte principale sécurisée (TLS, 5152). Derrière chaque porte, un hall unique : peu importe par où l’on entre, on aboutit au même accueil, qui oriente vers le bon bureau. Le WebSocket, lui, n’est pas une troisième porte : c’est un interphone installé sur les portes existantes — il emprunte la même serrure, la même adresse, la même politique de sécurité.

Concrètement, un serveur Nodefony a quatre responsabilités, et rien d’autre :

1. Ouvrir — réserver un port, ou en négocier un autre si celui-ci est pris.
2. Régler le transport — délais, taille des en-têtes, TLS, compression WebSocket, limites HTTP/2.
3. Transmettre — passer chaque requête / connexion au HttpKernel, sans jamais l’interpréter.
4. Fermer proprement — vider les requêtes en cours, prévenir les clients WebSocket, libérer le port.

Tout ce qui suit (routing, session, firewall, contrôleur) appartient au pipeline, décrit dans pipeline-requete.

La vision Nodefony#

Le différenciateur du framework — HTTP et WebSocket dans le même contexte de contrôleur — se joue ici, au niveau du transport. Trois choix structurent l’implémentation.

Node natif, rien d’autre. node:http, node:https, node:http2 et la bibliothèque ws. Pas d’abstraction de serveur maison, pas de runtime alternatif. Ce que Node sait faire, Nodefony le laisse faire — il n’ajoute que ce que Node ne fournit pas : la politique de port, le drain, le keep-alive WS, les probes.

Un port TLS qui parle deux protocoles. Quand servers.https.protocol vaut "2.0" (le défaut), Nodefony crée un serveur HTTP/2 sécurisé avec allowHTTP1: true (ServerHttps.createServerH2(), ^{server-https.ts:174}) : les clients modernes négocient h2 par ALPN, les autres restent en HTTP/1.1 sur le même port. Le protocole effectif est relu socket par socket pour taguer le contexte (^{server-https.ts:222}).

Le WebSocket n’est jamais un citoyen de seconde zone. Il est adossé au serveur HTTP porteur (^{server-websocket.ts:80}), passe par le même rate-limit d’IP que les requêtes HTTP — un upgrade est une requête HTTP (HttpKernel.onWebsocketRequest(), ^{http-kernel.ts:1497}) —, hérite de la même session et du même firewall, et se ferme avec le même soin qu’une réponse HTTP.

ℹ️ Note

Le serveur HTTP/3 (QUIC) est réservé, pas implémenté : la clé http3 existe dans le schéma, marquée reserved (^{config.ts:1029}). Elle ne fait rien aujourd’hui.

🚀 Démarrage rapide#

Dans une application générée par nodefony create app, les serveurs sont déjà là : le manifeste charge @nodefony/http, et le kernel ouvre 5151 et 5152 au boot. On n’écrit que ses écarts.

1. La topologie — quels serveurs, sur quels ports#

La topologie appartient à l’application (bloc servers), pas au module : c’est une propriété du déploiement.

// nodefony.config.ts — la topologie réseau de l'app
export default defineConfig((ctx) => ({
  // Un conteneur doit écouter TOUTES les interfaces : un bind 127.0.0.1 n'est
  // jamais atteint par le port mapping Docker/k8s.
  domain: ctx.isProd ? "0.0.0.0" : "127.0.0.1",
  servers: {
    http: { port: 5151 },
    // protocol "2.0" = HTTP/2 (h2) avec repli HTTP/1.1 sur le MÊME port.
    https: { port: 5152, protocol: "2.0" },
    // Port occupé : en dev on glisse au suivant (annoncé) ; en prod on échoue.
    portPolicy: ctx.isProd ? "strict" : "auto",
  },
  modules: ["@nodefony/http", "@nodefony/framework"],
}));

2. Le réglage — le comportement de chaque serveur#

Le réglage appartient au module, colocalisé dans le manifeste via use(). Toutes les clés ci-dessous sont facultatives : ce sont les défauts du schéma Zod, écrits ici pour les montrer.

// nodefony.config.ts — réglage transport (extrait du manifeste `modules`)
export default defineConfig(() => ({
  modules: [
    use("@nodefony/http", {
      // Ne pas exposer l'identité du serveur (anti-empreinte, recommandé en prod).
      headerServer: null,
      // Barrière Host : le domaine canonique est toujours accepté, + ceux-ci.
      trustedHosts: ["app.example.com"],
      // Un seul reverse-proxy en amont ? alors et alors seulement, lui faire confiance.
      trustProxy: false,
      http: {
        requestTimeout: 30_000, // anti slow-loris (réception complète)
        keepAliveTimeout: 5_000, // réutilisation de la socket TCP
        shutdownTimeout: 5_000, // drain avant destruction forcée
      },
      http2: {
        maxConcurrentStreams: 100, // défense CVE-2023-44487 (Rapid Reset)
        maxSessionMemory: 10, // Mo par session h2
      },
      websocket: {
        maxPayload: 1024 * 1024, // 1 MiB → au-delà, close 1009
        keepaliveInterval: 20_000, // ping toutes les 20 s
        keepaliveGracePeriod: 10_000, // pong attendu sous 10 s, sinon zombie
      },
      // Probes cloud-native — actives par défaut.
      health: {
        enabled: true,
        livenessPath: "/livez",
        readinessPath: "/readyz",
      },
      certificates: { strategy: "auto" }, // mkcert en dev, sinon auto-signé
    }),
    "@nodefony/framework",
  ],
}));

3. Le contrôleur qui répond sur les deux transports#

Rien de spécifique aux serveurs : c’est justement le propos. Le même contrôleur sert le web et le temps réel, et lit le transport dans son contexte.

// nodefony/controller/PingController.ts — complet, compile tel quel
import { Controller, controller, Get, route } from "@nodefony/framework";
import type { Context } from "@nodefony/http";

@controller("/ping")
class PingController extends Controller {
  constructor(context: Context) {
    super("PingController", context);
  }

  // HTTP : répond sur http://…:5151/ping ET https://…:5152/ping (h2 inclus).
  @Get("/")
  async ping() {
    return this.renderJson({
      scheme: this.context?.scheme, // "http" | "https"
      type: this.context?.type, // "http" | "http2" | "websocket"
    });
  }

  // WebSocket : ws://…:5151/ping/live et wss://…:5152/ping/live.
  // `message == null` = handshake (la connexion vient de s'ouvrir).
  @route("ping-live", {
    path: "/live",
    requirements: { methods: ["WEBSOCKET"], protocol: "" },
  })
  async live(message: string | Buffer | null) {
    if (message == null) {
      return this.renderJson({ handshake: true });
    }
    return this.render(message.toString());
  }
}

export default PingController;

4. Ce qu’on observe au boot#

Le kernel démarre les serveurs à la phase onReady (^{Kernel.ts:1090}), puis affiche les URL réellement en écoute — le récap de développement liste HTTP, HTTP/2, WS et WSS dans cet ordre (^{BootReporter.ts:389}) :

  ✓  Prêt en 1.4s

     Serveurs
     ➜  HTTP     http://127.0.0.1:5151
     ➜  HTTP/2   https://127.0.0.1:5152
     ➜  WS       ws://127.0.0.1:5151
     ➜  WSS      wss://127.0.0.1:5152

Hors écran animé (production, CI, --debug), ce sont les bannières par serveur qui sortent (ServerHttp.showBanner(), ^{server-http.ts:226}, appelées par le kernel — ^{Kernel.ts:457}) :

Server Listen on http://127.0.0.1:5151 Family: IPv4 Protocol : 1.1

5. Vérifier depuis le terminal#

# HTTP/1.1 en clair
curl -s http://127.0.0.1:5151/ping
# {"scheme":"http","type":"http"}

# HTTP/2 sur le port TLS (-k : le certificat de dev n'est pas dans le trust store)
curl -sk --http2 https://127.0.0.1:5152/ping
# {"scheme":"https","type":"http2"}

# Le même port TLS sert encore HTTP/1.1 (allowHTTP1) — repli négocié par ALPN
curl -sk --http1.1 https://127.0.0.1:5152/ping
# {"scheme":"https","type":"https"}

# Probes cloud-native, servies par les DEUX serveurs
curl -si http://127.0.0.1:5151/livez  | head -1   # HTTP/1.1 200 OK
curl -sik https://127.0.0.1:5152/readyz | head -1  # HTTP/2 200

Cas cloud-native — un seul port, TLS terminé à l’ingress#

C’est le déploiement nominal en Kubernetes : l’ingress porte le certificat, le pod sert en clair. https: false désactive HTTPS et le WSS qui en hérite, et supprime au passage toute génération de certificat au boot.

// nodefony.config.ts — pod k8s derrière un ingress qui termine le TLS
export default defineConfig((ctx) => ({
  domain: ctx.isProd ? "0.0.0.0" : "127.0.0.1",
  servers: {
    https: false, // un seul port exposé : 5151
  },
  modules: [
    use("@nodefony/http", {
      // L'ingress est l'unique point d'entrée → ses X-Forwarded-* sont fiables.
      trustProxy: ctx.isProd ? "uniquelocal" : false,
      // L'ingress filtre déjà le Host ; sinon lister les vhosts servis.
      trustedHosts: ["app.example.com"],
    }),
    "@nodefony/framework",
  ],
}));

🔌 Les quatre serveurs (et le cinquième service)#

Choisir en cinq secondes :

L’assemblage est fait par HttpKernel.initServers() (^{http-kernel.ts:1033}) : chaque serveur est consulté sur son drapeau active, un serveur désactivé est sauté, pas créé (^{http-kernel.ts:235}). Les serveurs WebSocket ne sont montés que si leur porteur l’a été.

⚙️ Configuration — deux niveaux, jamais mélangés#

C’est la distinction la plus utile de cette page, et celle qu’on rate le plus souvent.

Autrement dit : la topologie est une propriété du déploiement (elle change entre le poste du dev, la CI et le cluster) ; le réglage est une propriété de l’application.

Niveau 1 — la topologie (servers)#

<!-- prettier-ignore -->

Défauts matérialisés dans defaultAppConfig (^{src/nodefony/src/config/defaults.ts:34}).

Niveau 2 — le transport HTTP / HTTPS#

Table dérivée de httpServerSchema (^{config.ts:257}) ; la section https reprend les mêmes clés et en ajoute une (httpsServerSchema, ^{config.ts:315}).

Ces deux sections sont permissives (z.looseObject) : toute option supplémentaire de http.Server / net.Server / TLS (insecureHTTPParser, ciphers, minVersion…) est transmise telle quelle à Node. C’est délibéré — un schéma strict effacerait silencieusement une option légitime.

Niveau 2 — HTTP/2#

Depuis http2Schema (^{config.ts:332}), appliqué seulement si défini (maxSessionMemory, ^{server-https.ts:197}).

Niveau 2 — WebSocket (websocket et websocketSecure)#

Depuis websocketSchema (^{config.ts:490}). Les deux sections partagent la forme et les défauts ; le WSS lit websocketSecure (^{config.ts:1037}).

⚠️ Attention

keepalive*, closeTimeout, maxBackpressure et backpressurePolicy sont des réglages Nodefony, pas des options de ws : la bibliothèque les ignore, c’est le framework qui les implémente. À l’inverse, server, noServer, clientTracking, host, port et backlog sont gérés par Nodefony et non exposés — les forcer n’aurait pas d’effet.

⚙️ Ports occupés — la politique de repli#

La situation#

Tu développes sur le framework et, dans un autre terminal, tu lances l’app d’un client. Les deux veulent 5151. Historiquement, la seconde mourait sur EADDRINUSE. En développement, ce n’est pas une panne, c’est une nuisance.

La règle#

resolvePortPolicy() (^{portBinder.ts:74}) tranche selon l’environnement, et la valeur explicite gagne toujours :

Le comportement observable#

WARNING  Port 5151 déjà occupé → HTTP écoute sur 5153.
         Figer le port : servers.http.port ; échouer au lieu de glisser :
         servers.portPolicy = "strict".

Le décalage est toujours annoncé (^{server-http.ts:130}) : jamais de dégradation silencieuse. Trois détails d’implémentation valent d’être connus, parce qu’ils expliquent des comportements surprenants.

1. On retente au listen(), jamais après une sonde. Demander « le port est-il libre ? » puis binder est une course : entre la réponse et le bind, un autre processus peut prendre le port. Le listen() est atomique — on retente donc sur l’échec réel (bindWithFallback(), ^{portBinder.ts:142}).
2. Le port de l’autre serveur est réservé. Si HTTP est chassé de 5151, incrémenter naïvement le ferait voler 5152 à HTTPS, qui se décalerait à son tour. Les ports convoités par les autres serveurs sont sautés d’emblée (buildBindPlan(), ^{portBinder.ts:104}, réservation ^{portBinder.ts:111}).
3. Le gestionnaire d’erreur durable est posé APRÈS le bind. Attaché avant, il verrait passer les EADDRINUSE de repli et terminerait le kernel en croyant à une panne (ServerHttp.attachErrorHandler(), ^{server-http.ts:186}).

Quand le bind échoue pour de bon — strict, ou tous les replis épuisés, ou une erreur qui n’est pas un conflit de port — c’est fatal : message explicite puis terminaison du processus (ServerHttp.reportBindError(), ^{server-http.ts:199}). Un serveur qui n’écoute pas ne doit jamais laisser un processus se croire démarré.

Le corollaire : les ports effectifs sont publiés#

Si le port peut glisser, alors « le serveur écoute sur 5151 » n’est plus une vérité mais une convention — et nodefony status, nodefony stop ou l’attente de disponibilité sonderaient un port que personne n’écoute. HttpKernel.publishRuntimePorts() (^{http-kernel.ts:1096}) écrit donc la topologie réelle (pid, ports obtenus, ports désirés) dans un fichier d’état, dans tous les environnements : une application qui déclare son port via PORT (PaaS) sort aussi de la convention, même en strict. L’écriture est au mieux-effort — une image en lecture seule ne fait jamais tomber un serveur qui, lui, écoute très bien.

🔐 Certificats TLS#

La doctrine#

Générer un certificat est un confort de développement, pas une fonction de production. Nodefony n’est pas une autorité de certification : en production, on fournit un vrai certificat (Let’s Encrypt, ingress k8s, reverse-proxy). Le service crie un avertissement si ce n’est pas le cas (Certificate.resolveStrategy(), ^{certificates.ts:409}).

Les quatre stratégies#

Réglées par certificates.strategy (certificatesSchema, ^{config.ts:448}), résolues par Certificate.resolveStrategy() (^{certificates.ts:370}).

// nodefony.config.ts — production : certificat fourni, jamais généré
export default defineConfig(() => ({
  modules: [
    use("@nodefony/http", {
      certificates: {
        strategy: "explicit",
        key: "/etc/tls/privkey.pem",
        cert: "/etc/tls/fullchain.pem",
        ca: "/etc/tls/chain.pem",
      },
      https: { rejectUnauthorized: true },
    }),
    "@nodefony/framework",
  ],
}));

💡 Astuce

Pour un HTTPS de développement sans avertissement navigateur (indispensable au HMR cross-origin et au WSS) : brew install mkcert nss && mkcert -install. Nodefony le détecte tout seul, sinon il l’annonce et retombe sur l’auto-signé (^{certificates.ts:392}).

Ce que le chemin explicit évite#

node-forge est une grosse dépendance. Elle est chargée paresseusement, uniquement sur le chemin de génération (Certificate.loadForge(), ^{certificates.ts:218}) : en production avec un certificat fourni, elle n’entre jamais dans le processus (^{certificates.ts:325}).

Conformité de l’auto-signé#

Un certificat de développement bâclé fait perdre des heures (« not yet valid », « common name invalid »). Celui de Nodefony respecte les règles qui comptent :

Régénération automatique#

Un certificat présent sur disque n’est pas forcément adéquat. Certificate.isCertAdequate() (^{certificates.ts:533}) le régénère s’il est expiré, s’il est signé en SHA-1, ou si son SAN ne couvre plus les noms requis — le dernier cas est celui qui sauve : changer le domaine d’écoute sans ce contrôle laisserait un certificat obsolète en place indéfiniment.

🛡️ Derrière un reverse-proxy#

Dès qu’un proxy est devant l’application, trois questions se posent — et trois réglages y répondent.

« Quelle est la vraie IP du client ? » → trustProxy#

Sans barrière, n’importe quel client peut envoyer X-Forwarded-For: 1.2.3.4 et usurper son IP : contournement de rate-limit, journaux d’audit falsifiés. Le défaut est donc false — ces en-têtes sont ignorés (^{config.ts:959}), et l’IP retenue est celle de la socket réelle, non falsifiable.

La politique est compilée une seule fois au premier usage (HttpKernel.getTrustProxyChecker(), ^{http-kernel.ts:538}, via buildTrustProxy(), ^{trustProxy.ts:100}) : aucune structure allouée par requête. La résolution de l’IP cliente remonte la chaîne de droite à gauche depuis la socket réelle (resolveForwarded(), ^{forwarded.ts:253}) — conforme RFC 7239 et à la recommandation OWASP.

« Ce Host est-il le mien ? » → trustedHosts#

Barrière testée avant le routage, contre l’injection d’en-tête Host. Le domaine canonique du kernel est toujours accepté, plus le loopback en développement (HttpKernel.compileAlias(), ^{http-kernel.ts:936}). false (défaut) = ce socle seul ; une liste ajoute des vhosts (exact ou joker d’un seul niveau, *.cdn.example.com) ; true désactive la barrière — à réserver au cas où le proxy filtre déjà le Host (^{config.ts:968}).

« Cette page a-t-elle le droit d’ouvrir un WebSocket ? » → allowedOrigins#

Les navigateurs n’appliquent pas CORS aux WebSockets. Sans contrôle, une page tierce peut ouvrir un WS authentifié par le cookie de session de la victime (CSWSH, OWASP WSTG-CLNT-10). Nodefony exige donc par défaut que l’Origin du handshake corresponde au Host servi (HttpKernel.checkWebsocketOrigin(), ^{http-kernel.ts:599}), avec tolérance loopback en développement et allowlist explicite pour les SPA cross-origine. Un refus se solde par une fermeture 1008 (Policy Violation), jamais par un code HTTP.

ℹ️ Note

Une requête sans Origin (client non navigateur : script, agent, test) est acceptée (^{http-kernel.ts:551}). Ce n’est pas un trou : un attaquant non navigateur n’a aucun besoin de CSWSH, il se connecte directement. Le contrôle protège les utilisateurs, pas le port.

Probes de santé — /livez et /readyz#

Deux questions différentes, deux réponses différentes — les confondre casse les déploiements.

Le détail qui compte : livez reste à 200 pendant l’arrêt gracieux. Répondre 503 là ferait redémarrer le pod en plein drain par le kubelet, et casserait précisément ce qu’on essaie de protéger.

Implémentation : court-circuit total du pipeline dans HttpKernel.onHttpRequest() (^{http-kernel.ts:944}) — pas de contexte, pas de portée DI, pas de session, pas de journal par sonde, réponses pré-allouées (HttpKernel.#respondHealth(), ^{http-kernel.ts:473}). Et surtout : avant le rate-limit. Un kubelet qui reçoit un 429 croit le pod mort → cascade de redémarrages.

Retenir la mise en service — kernel.setReadiness()#

Un pod peut être parfaitement démarré et incapable de servir : son schéma de base est en retard, un cache n’est pas chaud, un service dont il dépend n’a pas encore répondu. Tout composant peut alors retenir /readyz, et l’orchestrateur en tire la conséquence : il n’envoie pas de trafic, l’ancien exemplaire continue de servir, le déploiement s’arrête proprement.

// Dans un service, au boot puis à chaque re-vérification.
kernel.setReadiness("schema", false, "3 migrations en attente"); // → /readyz 503
// …le travail de migration s'applique (depuis l'extérieur, par un Job) :
kernel.setReadiness("schema", true); // → /readyz 200, sans redéploiement
kernel.clearReadiness("schema"); // le composant s'arrête : sa voix ne compte plus

Trois règles à connaître :

• Le verdict est déjà calculé. setReadiness prend un booléen, jamais une fonction : la sonde ne déclenche aucune vérification. Une sonde qui interroge une base tombe avec elle — celle-ci lit un entier, et répond même quand la base est injoignable.
• Un seul « pas prêt » suffit à retenir ; il faut que tous soient prêts pour libérer. Un même nom réenregistré ne compte qu’une voix.
• livez reste à 200. Un schéma en retard est un état EXTERNE : redémarrer le processus ne le répare pas. C’est aussi pourquoi le pod redevient disponible tout seul dès que la cause est levée.

Ce que voit l’exploitant : le journal du pod NOMME ce qui retient (CRITIC à chaque bascule), le plan d’administration publie ready et readinessBlocked (GET /nodefony/kernel/api/livez ; les noms sont réservés à un appelant authentifié), et nodefony status affiche une ligne disponibilité. Le corps de /readyz, lui, reste une constante — c’est le prix à ne pas payer sur un chemin sondé toutes les 2 à 10 secondes.

Le match est strict sur l’URL brute : /livez?x=1 repart dans le pipeline normal. Les deux serveurs (HTTP et HTTPS) servent ces chemins — un kubelet configuré en scheme: HTTPS fonctionne.

Arrêt gracieux — la séquence du SIGTERM#

Un arrêt brutal coupe les requêtes en vol : à chaque mise à jour progressive, des utilisateurs voient une erreur. L’arrêt de Nodefony est une séquence ordonnée, et l’ordre est le cœur du sujet.

Étape 1 — la disponibilité bascule en premier. L’écouteur est posé à onPostReady pour être inséré en tête et donc s’exécuter en premier (^{http-kernel.ts:515}). readyz répond 503, le load balancer cesse d’envoyer du trafic, et shutdownDelay laisse à cette information le temps de se propager.

Étape 2 — les clients WebSocket sont prévenus. Websocket.terminate() (^{server-websocket.ts:117}) envoie un message applicatif puis une frame Close 1001 « Going Away » (^{server-websocket.ts:134}). Sans elle, la coupure TCP ferait voir un 1006 au client — code réservé, jamais émis sur le fil, indiscernable d’une panne réseau. Avec 1001, le client sait qu’il doit simplement se reconnecter.

Étape 3 — les requêtes HTTP se terminent. Le drain est délégué à http-terminator (createDrainTerminator(), ^{serverShutdown.ts:25}) : en-tête connection: close injecté sur les réponses en cours, sockets inactives fermées, destruction forcée au-delà de shutdownTimeout (défaut 5000 ms, ^{serverShutdown.ts:38}).

❗ Important

L’ordre WS-avant-HTTP n’est pas cosmétique. Les serveurs WebSocket s’inscrivent en prependOnceListener (^{server-websocket.ts:91}), les serveurs HTTP en once (^{server-http.ts:151}). Inversé, le terminator détruirait les sockets déjà upgradées sans frame Close : retour du 1006 pour tous les clients temps réel.

Deux garde-fous encadrent la séquence : shutdownTimeout par serveur (le drain nominal) et shutdownDeadline global au kernel (défaut 15 s, ^{src/nodefony/src/config/defaults.ts:46}), filet anti-écouteur bloqué. Les deux doivent rester sous la période de grâce de l’orchestrateur — 30 s en Kubernetes, 10 s avec Docker.

Résilience — ce qui ne doit jamais tuer le processus#

Un serveur runtime se juge à ce qu’il fait des cas anormaux. Quatre défenses vivent au niveau du transport.

En-têtes malformés — le piège clientError de Node#

Dès qu’un écouteur clientError est attaché, Node cesse de fermer la socket automatiquement. Un écouteur naïf (« je journalise et je passe ») transforme donc une requête malformée en fuite de socket et de descripteur de fichier — c’est-à-dire un vecteur de déni de service. Nodefony répond et ferme explicitement (handleClientError(), ^{clientError.ts:15}) : 431 si les en-têtes débordent (RFC 6585 §5), 400 sinon (^{clientError.ts:25}), et rien du tout si la socket est déjà morte.

Connexions WebSocket zombies#

Une socket dont le pair a disparu sans frame Close reste « ouverte » côté TCP : slot mémoire et descripteur retenus pour personne. Le battement de cœur les réclame (startHeartbeat(), ^{wsHeartbeat.ts:69}) : un ping toutes les keepaliveInterval ms ; sans pong dans les keepaliveGracePeriod ms, la socket est détruite (terminate, ^{wsHeartbeat.ts:98}).

L’implémentation est délibérément frugale — c’est du chemin chaud : un seul setInterval par serveur, jamais un timer par connexion ; deux horodatages posés directement sur la socket (trackPong(), ^{wsHeartbeat.ts:41}), donc zéro allocation par tick et aucun nettoyage à prévoir (les horodatages meurent avec la socket) ; une granularité de réveil plancher à 250 ms pour borner une configuration pathologique (tick, ^{wsHeartbeat.ts:81}) ; et un timer unref qui ne retient jamais le processus à l’arrêt.

Floods de connexions#

L’upgrade WebSocket est une requête HTTP : il passe donc par le même compteur de rate-limit par IP que les requêtes ordinaires, vérifié avant toute allocation de contexte (HttpKernel.onWebsocketRequest(), ^{http-kernel.ts:1497}). Le 101 étant déjà émis par ws, un 429 est impossible → la connexion est fermée en 1013 « Try Again Later » (rateLimiter, ^{http-kernel.ts:287}), sans journalisation (un journal par handshake rejeté serait lui-même un amplificateur sous flood).

Un second plafond, désactivé par défaut, borne le nombre de connexions simultanées par IP : wsMaxConnectionsPerIp (^{config.ts:1046}). En cloud-native, laisser null et déléguer à l’edge — nginx limit_conn, HAProxy sc_conn_cur — qui voit tout le trafic, rejette avant le coût du descripteur et du TLS, et couvre tous les pods. Ne l’activer que sur une machine sans ingress.

Bornes de payload#

maxPayload (1 MiB par défaut) fait fermer en 1009 « Message Too Big » ; maxBackpressure (4 MiB) protège contre le client lent à recevoir, dont le tampon d’envoi gonflerait jusqu’à l’OOM — un seul lent peut plomber une diffusion générale. La politique par défaut, drop, saute la frame et garde le client connecté.

⚡ Performance & mémoire#

Le transport est du chemin chaud absolu : ce qui coûte ici est multiplié par le nombre de requêtes par seconde. Les choix visibles dans le code :

• Aucun timer par connexion — un setInterval par serveur WebSocket, unref, et deux number par socket (^{wsHeartbeat.ts:69}).
• Rien de compilé par requête — la politique de trust-proxy, celle des Origin WS et les motifs de trustedHosts sont compilés une fois et mémoïsés (^{http-kernel.ts:937}, ^{http-kernel.ts:489}).
• Rejets avant allocation — rate-limit HTTP et bornes WS sont vérifiés avant le contexte, la portée DI et l’ALS : un flood coûte une recherche dans une table de hachage.
• Probes hors pipeline — réponses pré-allouées, aucun objet créé, aucun journal (^{http-kernel.ts:383}). Un kubelet qui sonde toutes les 2 secondes ne pèse rien.
• Fichiers statiques en repli — depuis la bascule « router d’abord », une requête qui matche une route ne paie plus l’appel disque de serve-static (+28 % de requêtes par seconde mesurés en production mono-processus).
• node-forge jamais chargé en production avec un certificat fourni (^{certificates.ts:218}).

Ordre de grandeur mesuré : un processus Node saturé sur un cœur tient environ 400 requêtes/s en boucle locale avec dégradation gracieuse (1600 connexions concurrentes, aucun crash) ; côté WebSocket, plus de 750 connexions simultanées et 33 000 à 38 000 messages/s soutenus. Rejouer ces mesures : skill nodefony-load-test. Gate mémoire avant tout commit touchant le pipeline : npm run test:memory (skill nodefony-check-memory-health).

Mise à l’échelle. Un processus = un pod. Le passage à l’échelle est horizontal, confié à l’orchestrateur ; sur une seule machine, nodefony cluster -w N fork des workers. Attention à la conséquence : broadcast() ne touche que les clients du même worker — un fan-out inter-processus demande le backplane realtime.

📜 Normes appliquées#

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

📡 Observabilité — Studio et CLI#

Studio. L’onglet Configuration rend la config du module en réglages documentés (type, défaut, état, valeur effective) à partir du JSON Schema dérivé du schéma Zod (src/packages/@nodefony/http/index.ts:79). Le profiler expose les phases par requête, y compris l’origine du transport.

CLI. Trois commandes touchent directement aux serveurs :

proxy:generate mérite un mot : la configuration nginx/HAProxy est dérivée des domaines de confiance, des ports effectifs et des dossiers statiques montés — donc elle ne diverge pas du code. Le résumé de certificat vient de Certificate.describe() (^{certificates.ts:803}), source unique partagée par la commande, le boot et un futur écran d’administration.

Runtime. nodefony status et nodefony stop lisent les ports effectifs publiés au boot ; ils fonctionnent donc même après un décalage de port.

🧪 Tests & couverture#

Les chiffres exacts vivent dans la carte de tests de cette page (régénérée depuis vitest, jamais figés dans le Markdown).

Ce qui manque aujourd’hui : aucun test d’intégration ne couvre le décalage de port de bout en bout (le repli est prouvé unitairement sur de vraies sockets, pas via un boot complet), et il n’existe pas de banc dédié au keep-alive WebSocket (la détection de zombie est exercée indirectement par les tests de charge).

Suites : npm test (unitaires), npm run test:integration (serveur requis), npm run test:load et npm run test:memory (serveur lancé avec --expose-gc). Couverture : npm run coverage dans @nodefony/http — le pourcentage vit dans le rapport vitest, jamais figé ici. Skills associés : nodefony-load-test, nodefony-check-memory-health, nodefony-security-review.

🔗 Pour aller plus loin#

• ⬆️ Retour au hub : @nodefony/http — vue du module · Toute la documentation
• 🧭 Pages sœurs : Sessions
• Le pipeline qui reçoit ce que les serveurs transmettent → pipeline-requete
• Déployer en conteneur (probes, arrêt gracieux, TLS à l’ingress) → docker-cloud-native
• Configuration d’application (defineConfig, use, env) → configuration
• Zones, authentification et autorisation par-dessus le transport → Firewall
• En-têtes de sécurité applicatifs (CSP, Referrer-Policy…) → En-têtes
• WebSocket applicatif : canaux, diffusion, backplane → @nodefony/realtime
• Vue d’ensemble de l’architecture → vue-ensemble