Nodefony
Framework Node.js fullstack — HTTP & WebSocket, même contexte

@nodefony/http — la couche transport

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

Les portes d’entrée du processus. Ce module ouvre les sockets, accepte les connexions — web et temps réel — et construit le contexte de requête que tout le reste du framework consomme. Sa particularité tient en une phrase : HTTP et WebSocket ne sont pas deux mondes, ce sont deux entrées du même pipeline. C’est de là que vient le différenciateur de Nodefony.

📍 Documentation › @nodefony/http

🧭 Par où commencer#

Trois parcours selon ce que tu viens faire. L’ordre compte : chaque étape suppose la précédente.

Je découvre le module — comprendre avant de configurer.

  1. Serveurs — ce qui écoute, sur quels ports, et comment ça démarre et s’arrête.
  2. Pipeline de requête — le trajet complet d’une requête, du socket jusqu’à ton contrôleur. La page qui relie tout.
  3. Sessions — le premier état serveur que rencontre une application réelle.
  4. Routage et contrôleurs — la suite du voyage, dans @nodefony/framework.

Je mets en production — ce qu’un serveur exposé doit tenir.

  1. Serveurs — TLS, certificats, politique de port, arrêt gracieux, sondes de vie.
  2. Sessions — choisir un store partagé : sans lui, deux pods ne partagent aucune session.
  3. Pipeline de requête — où se branchent rate-limit, en-têtes et firewall.
  4. Rate-limit — plafonner le débit par client avant que la charge n’atteigne le contrôleur.
  5. Observabilité — corréler les logs par requestId pour diagnostiquer à chaud.
  6. Sécurité — le pare-feu applicatif se pose par-dessus ce module.

Je fais du temps réel — WebSocket dans le même contexte que le web.

  1. Serveurs — le WS n’a pas de port à lui : il se greffe sur son porteur HTTP.
  2. Sessions — la session côté WebSocket, et pourquoi elle passe par l’ALS.
  3. La socket Nodefony — la couche au-dessus, qui multiplexe N canaux sur une connexion.

🗂️ Les briques du module#

Le tableau pour choisir vite ; les cards en dessous pour savoir ce qu’on y trouve.

<!-- prettier-ignore -->

Brique Ce qu’elle résout Tu en as besoin quand…
Serveurs ouvrir, régler, transmettre, fermer proprement toujours — c’est la fondation
Sessions de l’état serveur rattaché à un visiteur login, panier, préférences, WS authentifié
Cookies lire/écrire des cookies sûrs (SameSite, signés) tu poses un état côté client hors session
Upload & corps parser le corps et recevoir des fichiers formulaires, imports multipart, API JSON
Rate-limit plafonner le débit par client (429) protéger une API d’un flood ou d’un abus
Observabilité tracer et journaliser chaque requête débugger en prod, corréler des logs
Pipeline de requête l’ordre exact des étapes, HTTP comme WS tu débugges « pourquoi ça passe / ça bloque ici »
servers Deux ports, quatre serveurs, un seul pipeline : politique de port, certificats et TLS de développement, réglage du transport, sondes de liveness/readiness, arrêt gracieux, défenses de bordure (slow-loris, floods, zombies WebSocket). commence ici — tout le reste suppose un serveur qui écoute session Cycle de vie complet, cookie opaque, les quatre stores (memory, drizzle, redis, mongoose) et comment auto en choisit un, les délais NIST, la révocation, la session côté WebSocket. la brique où un choix de dev (memory) devient un bug de prod cookies Lire et écrire des cookies : attributs SameSite, Secure, HttpOnly, Path, Domain, Max-Age/Expires, parsing des cookies entrants, signature HMAC, cookies côté WebSocket. Le cookie de session a sa propre page. dès que tu poses un état côté client hors session upload Réception du corps de requête (JSON, urlencoded, multipart, brut) et upload de fichiers : accès aux champs et fichiers, API UploadedFile (taille, type, move), bornes de payload (413) et sûreté du nom de fichier. formulaires, imports de fichiers, API JSON rate-limit Limiter le débit par client : fenêtre et quota configurables, réponse 429 avec en-têtes X-RateLimit-* et Retry-After, store pluggable, limites côté WebSocket (handshake + connexions concurrentes), introspection admin. protéger une API d'un flood ou d'un abus observabilite Observer les requêtes : lignes de log (pretty ou JSON), requestId de corrélation, W3C Trace Context, trace des frames WebSocket, redaction et sampling d'audit. Où partent les logs est traité par la page Syslog du cœur. débugger en prod, corréler les logs par requête pipeline-requete Où ce module s'arrête et où le framework prend le relais, et dans quel ordre s'enchaînent contexte, rate-limit, routage, session, CSRF et firewall. page transverse — celle qui relie tout

ℹ️ Note

Deux briques n’ont pas encore leur page dédiée : les fichiers statiques et les certificats. Ils sont implémentés et testés ; en attendant, leur configuration vit dans les blocs Zod de nodefony/config/config.ts et leur comportement est décrit dans la page Serveurs (repli statique, stratégies de certificats TLS).

🏛️ Place dans le framework#

@nodefony/http ne connaît ni les routes ni les contrôleurs — il ne peut pas importer @nodefony/framework (ce serait un cycle). Il expose un contexte ; le framework s’y branche.

🧰 Surface publique#

Depuis une application : Context, HttpContext, WebsocketContext, Session, SessionsService, les services de serveurs, cookie, httpError, le profiler. Les signatures exactes vivent dans .ai/symbols.json et dans les types générés — jamais recopiées à la main dans cette page, où elles se périmeraient en silence.

⚙️ Configuration#

Tout se déclare dans nodefony.config.ts via use("@nodefony/http", { … }). Les blocs Zod (nodefony/config/config.ts) couvrent : servers (ports, transport, TLS, HTTP/2), session et cookie, trustProxy, certificates, upload, le rate-limit et les fichiers statiques. Chaque page de brique détaille son bloc et ses défauts réels.

📜 Normes appliquées#

RFC 9110/9111/9112 (sémantique HTTP, cache, HTTP/1.1), RFC 9113 (HTTP/2), RFC 6455 (WebSocket et ses codes de fermeture), RFC 6265bis (cookies), RFC 6585 (429), RFC 6125 (identité des certificats), WHATWG Fetch (CORS), W3C Trace Context (traceparent).

📡 Observabilité — Studio#

Le profiler mesure les phases d’une requête et alimente le data plane admin (HttpAdminApi). Les sessions sont surfacées dans l’écran Sessions (/nodefony/sessions), les corrélations par traceparent dans l’écran Traces (/nodefony/logs/trace/{requestId}), et l’état des serveurs dans la carte du module.

🧪 Tests & couverture#

Le module porte la plus grosse couverture du dépôt — les chiffres exacts vivent dans la carte de l’aperçu, régénérée depuis vitest, jamais figés dans la prose.

Type Où Ce qui est prouvé
Unitaire tests/unit/** cookies, session, erreurs, trust-proxy, requestId
Intégration tests/{http,integration,routing}/** pipeline réel sur serveur vivant, TLS, statiques
WebSocket tests/websockets/** handshake, protocoles, binaire, broadcast, sessions
Contrat tests/support/*Contract.ts un store tiers respecte le contrat attendu
Charge / mémoire tests/load/** + memory.test.ts seuils de heap, connexions soutenues, débit de frames

🔗 Pour aller plus loin#