Référence d'API — @nodefony/http — service

stable

Documentation › Référence d’API › @nodefony/http › service

Générée depuis les déclarations de types publiées de @nodefony/http 10.0.0-beta.5 : exactement ce que reçoit une application qui l’installe. Cette page n’existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code.

@nodefony/http#

import { … } from "@nodefony/http" — 18 symboles.

Classes (7)#

DefaultErrorRenderer#

class DefaultErrorRenderer implements IErrorRenderer

Default Nodefony error renderer — preserves the legacy JSON error shape.

• renderHttp(error: Error, context: IHttpContext): IErrorHttpResult
• renderWebsocket(error: Error, context: IWebsocketContext): IErrorWebsocketResult

DefaultRequestLogger#

class DefaultRequestLogger implements IRequestLogger

Default Nodefony per-request logger — preserves the legacy colored format.

• renderHttp(context: IHttpContext, error?: Error | null): IRequestLogEntry
• renderWebsocket(context: IWebsocketContext, error?: Error | null, acceptedProtocol?: string | null): IRequestLogEntry

HttpKernel#

class HttpKernel extends Service implements IHttpKernelInterface

• options: IHttpConfig & DefaultOptionsService
• certificates: unknown
• serviceCerticats: Certicates | null
• key: string
• cert: string
• ca: string
• serverStatic: Statics | null
• reverseProxy: ReverseProxy | null — Proxy inverse (reverse-proxy) — lu à chaque requête avant le routage ; mounts === null tant que personne n’a monté de préfixe.
• domain: string
• trustedHosts?: ITrustedHostsConfig
• get domainCheck(): boolean — Contrôle de domaine actif (domainCheck de la config d’application) — lu à la source, pour le HTTP comme pour le handshake WebSocket.
• regAlias: RegExp[]
• module: Module
• get httpsPort(): number — Port du serveur HTTPS effectivement lié, undefined s’il est inactif — lu sur le serveur, jamais recopié (lu par HttpContext.redirectHttps).
• get httpPort(): number — Port du serveur HTTP effectivement lié, undefined s’il est inactif.
• responseTimeout: { http: number; https: number; }
• closeTimeOutWs: { ws: number; wss: number; }
• sessionService?: SessionsService | null
• router?: IRequestRouter | null
• firewall?: IFirewallGate | null
• constructor(module: Module)
• describeTransportSecurityHeaders(): { strictTransportSecurity: string | null; frameOptions: string | null; contentTypeOptions: string | null; } — Ce que ce kernel ÉMET réellement comme en-têtes de sécurité transport.
• onConfigChanged(): void — Hook appelé par le data plane admin APRÈS une édition LIVE de la config (PATCH /nodefony/kernel/api/config/http, dev only).
• get rateLimitStore(): IRateLimitStore | null — Compteur de rate-limit actif, ou null s’il est désactivé — surface de LECTURE pour le data plane admin (introspection des IP suivies).
• shouldProfile(url: string): boolean — Cette requête — ou cette frame du pont — se profile-t-elle ?
• warnUnsentResponse(context: HttpContext): void — En développement, signale une action qui a rendu une valeur que le Resolver ne sait pas envoyer (null, undefined, instance de classe) et n’a rien envoyé elle-même : la requête attend son délai d’e …
• init(): Promise<this>
• getTrustProxyChecker(): TrustProxyChecker — Checker de confiance reverse-proxy, compilé une seule fois depuis options.trustProxy (lazy — pas de BlockList allouée par requête).
• isWebsocketOriginAllowed(origin: string, hostname: string, secure: boolean): boolean — L’Origin d’un handshake WebSocket est-elle acceptée ?
• checkWebsocketOrigin(context: WebsocketContext): void — B4 — Validation d’Origin au handshake WebSocket (anti-CSWSH, OWASP WSTG-CLNT-10).
• handle(request: httpRequest, response: httpResponse | null, type: ServerType): MaybePromise<HttpContext> — Ouvre le scope request de la requête et la confie au pipeline HTTP.
• prepareFrontController(context: ContextType, checkFirewall?: boolean): IRouteResolver — Arme le contexte pour l’exécution : zone firewall (context.secure) et résolveur de route — sans instancier le controller.
• handleFrontController(context: ContextType, checkFirewall?: boolean): Promise<object> — prepareFrontController + instanciation immédiate du controller (DI + hook initialize()).
• setErrorRenderer(renderer: IErrorRenderer): void — Override the default error renderer — e.g.
• getErrorRenderer(): IErrorRenderer
• setRequestLogger(logger: IRequestLogger): void — Override the default per-request logger — JSON access log, NCSA combined, pretty single-line formatter, etc.
• getRequestLogger(): IRequestLogger
• onError(error: Error | HttpError | nodefonyError, context?: ContextType, _extraHeaders?: Record<string, unknown> | object): Promise<HttpContext | WebsocketContext>
• compileAlias(): RegExp[]
• onHttpRequest(request: httpRequest, response: httpResponse, type: ServerType): Promise<void> — Point d’entrée d’une requête HTTP, appelé par les serveurs depuis leur écouteur request.
• initServers(): Promise<(httpServer | httpsServer | h2cServer | websocketServer | websocketSecureServer)[]> — Démarre les serveurs HTTP/HTTPS/WS/WSS activés par la configuration.
• startSession(context: WebsocketContext | HttpContext): MaybePromise<Session | null> — Point d’activation UNIQUE de session — symétrique HTTP et WS.
• createHttpContext(scope: Scope, request: httpRequest, response: httpResponse, type: ServerType): HttpContext
• handleHttp(scope: Scope, request: httpRequest, response: httpResponse, type: ServerType): MaybePromise<HttpContext> — Crée le contexte HTTP de la requête et la sert dans sa bulle ALS ; toute erreur — synchrone ou rejet — passe par onError.
• onRequestEnd(context: HttpContext, error?: Error | null): MaybePromise<HttpContext> — Les gardes d’une requête HTTP, corps lu : en-têtes de scheme, domaine, hook beforeResolve, armement de la route, CSRF, session, pare-feu — dans cet ordre.
• createWebsocketContext(scope: Scope, req: IncomingMessage, ws: Ws | null, type: ServerType): WebsocketContext
• onWebsocketUpgrade(req: IncomingMessage, admission: IUpgradeAdmission, type: ServerType): Promise<unknown> — Point d’entrée d’un upgrade vers une route WebSocket de Nodefony, appelé par le répartiteur d’upgrade AVANT le 101 (#596) : rien ne s’ouvre tant que le pipeline n’a pas dit oui.
• handleWebsocket(scope: Scope, req: IncomingMessage, admission: IUpgradeAdmission, type: ServerType): Promise<unknown> — Pipeline d’un handshake WebSocket, dans la bulle ALS de la connexion : jugement (onConnect), pare-feu, gardes de l’action — PUIS seulement l’acceptation, la socket et l’action de handshake.
• onConnect(context: WebsocketContext | null, error?: unknown): Promise<void> — Juge un handshake WebSocket AVANT son acceptation : hôte, origine, beforeResolve, contrôleur (protocole négocié), session.
• checkValidDomain(context: ContextType): number
• isValidDomain(context: ContextType): boolean
• isTrustedHostname(hostname: string): boolean — Ce nom d’hôte franchit-il la barrière trustedHosts ?
• websocketUpgradeRefusal(req: IncomingMessage): 400 | 404 | 429 | 503 | null — Refus d’un upgrade WebSocket AVANT le 101, par un statut HTTP (RFC 6455 §4.2.2) — appelé par le répartiteur d’upgrade, après le proxy inverse et avant le serveur ws.
• websocketQuotaRefusal(req: IncomingMessage, connection: { once(event: "close", listener: () => void): unknown; }): "rate limit" | "too many connections" | null — Bornes par IP d’un upgrade WebSocket : débit de handshakes (le MÊME compteur que les requêtes HTTP — un upgrade EST un GET) puis connexions simultanées (wsMaxConnectionsPerIp).
• acquireConnectionSlot(req: IConnectionRequest, connection: { once(event: "close", listener: () => void): unknown; }): boolean — Prend une place de connexion LONGUE pour l’IP de la requête — le plafond wsMaxConnectionsPerIp, partagé par les sockets WebSocket ET les flux SSE : un seul budget par IP, sinon N sockets plus N flux …
• revalidateStreams(): Promise<void> — Re-valide tous les flux SSE et ferme ceux dont l’identité est morte.

JsonAuditLogger#

class JsonAuditLogger implements IRequestLogger

JSON audit logger — implements IRequestLogger so it slots into httpKernel.setRequestLogger(new JsonAuditLogger()).

• constructor(opts?: JsonAuditLoggerOptions)
• shouldSample(context: IHttpContext, error?: Error | null): boolean — Decide whether the current HTTP request must be logged (audit sampling).
• renderHttp(context: IHttpContext, error?: Error | null): IRequestLogEntry
• renderWebsocket(context: IWebsocketContext, error?: Error | null, acceptedProtocol?: string | null): IRequestLogEntry

PrettyRequestLogger#

class PrettyRequestLogger implements IRequestLogger

Pretty single-line logger for dev (P3.2) — the biggest gain for humans.

• renderHttp(context: IHttpContext, error?: Error | null): IRequestLogEntry
• renderWebsocket(context: IWebsocketContext, error?: Error | null, acceptedProtocol?: string | null): IRequestLogEntry

ReverseProxy#

class ReverseProxy extends Service

Proxy inverse de Nodefony : relaie un préfixe d’URL vers un autre serveur HTTP — requêtes ET, sur demande, upgrades WebSocket — sur la MÊME origine que la page. Le client ne voit qu’un serveur, un certificat ; l’amont peut rester sur la boucle locale.

• module: Module
• mounts: IMountRecord[] | null — Montages actifs, du préfixe le PLUS LONG au plus court : le premier qui couvre une URL est le plus spécifique.
• readonly defaultTimeoutMs: number — Délai d’inactivité appliqué aux montages qui n’en fixent pas (proxy.timeoutMs).
• readonly connectTimeoutMs: number — Délai d’établissement de la connexion amont (proxy.connectTimeoutMs).
• readonly maxSockets: number — Connexions simultanées par amont (proxy.maxSockets) : pool ET tunnels WebSocket.
• readonly pseudonym: string — Nom de CE processus dans Via (RFC 9110 §7.6.3) : tiré au hasard au démarrage, il ne dit rien de la machine et distingue deux instances — un message qui le porte déjà est une boucle (508).
• constructor(module: Module)
• mount(prefix: string, options: IProxyMountOptions): void — Relaie un préfixe d’URL vers un amont.
• unmount(prefix: string): void — Retire un montage.
• closeAll(): void — Ferme tous les pools (arrêt du noyau).
• match(url: string): IProxyMount — Montage le plus spécifique qui couvre une URL, s’il y en a un.
• forward(req: ProxiedRequest, res: ProxiedResponse, scheme: string): Promise<void> — Relaie une requête HTTP si un montage la couvre — méthode comprise.
• handleUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer): boolean — Relaie un upgrade WebSocket si un montage websocket couvre son URL.

SessionsService#

class SessionsService extends Service

• httpKernel: HttpKernel
• static registerStorage(name: string, ctor: SessionStorageCtor): void — Enregistre un storage de session sous un nom de store (insensible à la casse) et émet l’événement kernel onRegisterSessionStorage (observabilité Studio / extension).
• static getStorage(name: string): SessionStorageCtor — Storage enregistré pour un store, ou undefined.
• static storageHandlers(): string[] — Noms des handlers de session enregistrés.
• options: ISessionServiceOptions
• sessionStrategy: sessionStrategyType
• storage: ISessionStorage | null
• module: Module
• defaultSessionName: string
• secret?: Buffer
• iv?: Buffer
• certificates: Certificate | null
• constructor(module: Module, httpKernel: HttpKernel)
• init(): Promise<this>
• initializeStorage(): ISessionStorage | null
• createSecret(): Buffer
• createIv(): Buffer
• start(context: ContextType, readOnly?: boolean): Promise<Session | null>
• saveSession(context: ContextType): Promise<Session | null>
• createSession(name: string, options?: OptionsSessionType): Session
• setSessionStrategy(strategy: sessionStrategyType): void
• runGc(): Promise<void> — Une passe de purge du store (storage.gc(idle, absolute)) — point d’entrée public d’un ordonnanceur : le GcScheduler l’appelle, mais un futur worker cron (session:gc / k8s CronJob) peut l’appeler …
• supportsEnumeration(): boolean — true si le backend de session courant sait s’énumérer par pages (listPage).
• sortableFields(): readonly string[] — Champs de tri que le backend de session actuellement configuré sait honorer, en vocabulaire public.
• sessionRef(id: string): string — Dérive le pseudonyme public d’une session — HMAC-SHA256(secret, id) tronqué, préfixé sess_.
• currentSessionRef(): string | null — Référence publique de la session qui porte la requête en cours, lue dans le contexte de l’ALS — ou null quand la requête n’en porte aucune (CLI, appel interne, session jamais démarrée).
• listSessionsPage(query: ISessionListQuery): Promise<IPage<ISessionSummary>>
• countSessions(query?: Partial<ISessionListQuery>): Promise<number> — Compte les sessions sans les énumérer (KPI de la console).
• countDistinctUsers(query?: Partial<ISessionListQuery>): Promise<number> — Compte les utilisateurs distincts ayant une session — le second nombre de la console, celui que countSessions ne dit pas (« 400 sessions » n’est pas « 400 personnes »).
• countSessionFacets(query?: Partial<ISessionListQuery>): Promise<ISessionCounts> — Les compteurs de tête de la console — posés sur la collection ENTIÈRE, pas sur la page affichée.
• destroyByRef(ref: string, actor?: string | null): Promise<boolean> — Révoque une session par son ref public : re-scanne, recalcule le HMAC de chaque id pour retrouver l’id réel (l’id brut ne quitte jamais le process), puis destroy().
• destroyWhere(filter: ISessionListFilter, match: (data: ISerializedSession) => boolean): Promise<number> — Détruit TOUTES les sessions dont le contenu satisfait match — la primitive des révocations groupées (« déconnecter partout », déconnexion demandée par un fournisseur d’identité).
• destroyByUser(identifier: string, actor?: string | null): Promise<number> — « Déconnexion partout » : détruit TOUTES les sessions d’un utilisateur (scan O(N) — pas d’index inverse, acceptable en admin).
• listOwnSessionsPage(identifier: string, query: ISessionListQuery): Promise<IPage<ISessionSummary>> — Énumère une page des sessions APPARTENANT à identifier (ISessionSummary redactés).
• destroyOwnByRef(identifier: string, ref: string, actor?: string | null): Promise<boolean> — Révoque UNE session possédée par identifier, désignée par son ref public.

Fonctions (2)#

schemaMismatchOf#

function schemaMismatchOf(error: unknown): SchemaMismatchConfidence | null

Reconnaît, dans une erreur ou l’une de ses causes, un schéma en retard sur le code — et dit avec quelle FORCE.

toValidationFields#

function toValidationFields(error: Error): IValidationField[] | null

Reconnaît une erreur de validation — ZodError, ou SchemaValidationError d’une route à schéma — et en extrait les champs fautifs.

Interfaces (4)#

AuditErrorEntry#

interface AuditErrorEntry

Enriched error description for audit logs (P3.5). Includes optional cause chain (Error.cause) and stack (dev only).

• name: string
• message: string
• code?: number
• errorType?: string — nodefonyError’s domain classifier when available (P1.5 / Phase 1).
• stack?: string — Multi-line stack — dev/development only, omitted in prod for safety.
• cause?: AuditErrorEntry — Recursive — capped to depth 5 to avoid pathological cycles.

AuditLogEntry#

interface AuditLogEntry

Canonical audit log entry — 1 JSON PDU per request (P3.1).

• ts: string
• requestId: string
• userIdentifier: string | null — Identifiant de l’appelant authentifié (context.userIdentifier), null sinon.
• type: "http" | "ws"
• scheme: string
• method: string | null
• url: string
• status: number | null
• durationMs: number | null
• remoteAddress: string | null
• host: string | null
• userAgent: string | null
• hasAuthorization: boolean
• hasCookie: boolean
• phases?: { name: string; durationMs: number | null; }[]
• error?: AuditErrorEntry
• protocol?: string | null

IValidationField#

interface IValidationField

Champ fautif, tel qu’exposé au client dans le corps JSON (error.fields).

• field: string — Chemin pointé du champ ("author.email").
• message: string — Message lisible.
• rule?: string — Contrôle qui a échoué (too_small…) — utile au client pour réagir finement.
• in?: string — Partie de l’entrée qui porte le champ (body, query, params, headers) — présente pour une route à schéma, où deux parties peuvent porter le même nom.

JsonAuditLoggerOptions#

interface JsonAuditLoggerOptions

• includeStack?: boolean — Whether to include error.stack and recursive error.cause.stack.
• maxCauseDepth?: number — Max depth for Error.cause chain serialisation.
• sampleRate?: number — Sampling rate for nominal (2xx/3xx) audit logs — perf lever on the hot path (L3).
• nominal?: boolean — T1 (profil delta vs Express) — audit du chemin NOMINAL (2xx/3xx).

Types (5)#

ContextType#

type ContextType = WebsocketContext | HttpContext | Context

ProtocolType#

type ProtocolType = "1.1" | "2.0" | "3.0"

SchemaMismatchConfidence#

type SchemaMismatchConfidence = "certain" | "probable"

Force du signal « la base ne porte pas ce que le code demande ».

httpRequest#

type httpRequest = http.IncomingMessage | http2.Http2ServerRequest

httpResponse#

type httpResponse = http.ServerResponse | http2.Http2ServerResponse

← Toutes les références d’API