--- title: "Référence d'API — @nodefony/http — context" source: docs/api/http/context.md url: https://nodefony.github.io/nodefony-core/docs/api/http/context/ --- [Documentation](../../../) › [Référence d'API](../../) › [`@nodefony/http`](../) › context > 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"` — 36 symboles. ### Classes (11) #### `Context` ```ts class Context extends Service implements IContextInterface ``` - `secure: boolean` - `security?: ISecurityZone | null` - `cleaned: boolean` - `validDomain: boolean` - `finished: boolean` - `pushAllowed: boolean` - `requestEnded: boolean` - `requested: boolean` - `sessionStarting: boolean` - `domain: string` - `type: ProtocolName` — Famille traitée (`network.protocol.name` d'OpenTelemetry) — union ouverte. - `serverType: ServerType` — Serveur qui a reçu la requête — choisit la configuration par serveur. - `alpnProtocol: AlpnProtocol` — Protocole du saut local (registre IANA ALPN) — union ouverte. - `server?: WebSocketServer | http.Server | https.Server | http2.Http2SecureServer | null` - `httpKernel: HttpKernel | null` - `request: contextRequest | null` - `response: contextResponse | null` - `url: string` - `method: HTTPMethod | null` - `remoteAddress: string | null` - `protected _originUrl: URL | null` - `get originUrl(): URL | null` - `set originUrl(value: URL | null)` - `cookies: Cookies` - `error: Error | HttpError | nodefonyError | null` - `sessionService?: SessionsService | null` - `session: Session | null` - `cookieSession: Cookie | null` - `user: unknown` - `userIdentifier: string | null` — Identifiant de l'appelant AUTHENTIFIÉ, posé par le pare-feu ; `null` hors zone ou pour un anonyme. - `waitAsync: boolean` - `isJson: boolean` - `protected _isHtml: boolean | null` - `get isHtml(): boolean` - `set isHtml(value: boolean)` - `protected resolveIsHtml(): boolean` — Défaut paresseux d'`isHtml` — overridé par HttpContext (négociation `Accept`). - `crossDomain: boolean` - `router: IRequestRouter | null` - `resolver: IRouteResolver | null` - `logModule: string | null` — Module qui signe les lignes de CETTE requête : la ligne d'accès et les lignes du contrôleur. - `sessionIntent: SessionIntent | null` — Intent de session de la route courante (posé par le Resolver depuis `@UseSession` / paramètre `@Session`). - `cspDirectives: Record | null` — Directives CSP additionnelles de la route courante (`@Csp`), posées par le Resolver au match. - `csrfProtect: boolean` — CSRF per-route (`@CsrfProtect`/`@CsrfExempt`), posés par le Resolver au match, lus par `Firewall.enforceCsrf` (post-resolve). - `csrfExempt: boolean` - `csrfToken: string | null` - `requestId: string` - `get cspNonce(): string` - `traceparent: string | null` - `profilerQueries: IProfilerQuery[] | null` - `profiling: boolean` - `securityTrace: ISecurityTrace | null` - `readonly phases: PhaseTiming[]` - `metaData: Data` - `scheme: SchemeType` — Schéma vu par le client — seul champ que lit une décision de sécurité. - `webSocketState: WebSocketState` - `constructor(container: Container | Scope, serverType: ServerType)` - `setMetaData(obj?: Record): Data` — Assemble l'enveloppe `metaData` de la requête (`nodefony.*` + `route` snapshot per-requête + overrides appelant). - `setScheme(): SchemeType` - `get timingEnabled(): boolean` — Le timing est-il actif sur CETTE requête ? - `phaseStart(name: PhaseName): void` - `phaseEnd(name: PhaseName): void` - `stopClock(): number | null` — Arrête l'horloge de la requête et rend sa durée, en millisecondes. - `onAfterResponse(fn: AfterResponseHandler): void` - `_runAfterResponse(): Promise` — Exécute les hooks `onAfterResponse`, une seule fois, dans l'ordre d'enregistrement ; un hook qui lève est journalisé sans arrêter les suivants. - `get signal(): AbortSignal` - `_abortIfPending(reason?: string): void` - `log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message, moduleName?: string): Pdu` — Émet une entrée de log structurée — point d'entrée central pour TOUT log Nodefony. - `holdRequestStore(store: RequestContextPayload): void` — Confie au contexte le magasin `RequestContext` de son unité de travail (requête HTTP, connexion WebSocket), pour qu'il le VIDE à son nettoyage. - `clean(): void` — Libère les ressources — retire les listeners trackés du bus partagé pour éviter les fuites mémoire, puis détache container/kernel/syslog/nc. - `fire(event: KernelEventsType, ...args: unknown[]): boolean` — Alias `emit` — émet l'événement de manière synchrone. - `emit(event: KernelEventsType, ...args: unknown[]): boolean` — Émet l'événement (API EventEmitter standard). - `emitAsync(event: KernelEventsType, ...args: unknown[]): Promise` — Émet et attend les listeners async — équivalent de `fireAsync`. - `fireAsync(event: KernelEventsType, ...args: unknown[]): Promise` — Émet l'événement et attend que tous les listeners async résolvent. - `logRequest(httpError?: Error | HttpError | nodefonyError | null): Pdu` - `logPhasesVerbose(): void` — P3.7 — Émet au teardown un log DEBUG détaillant la durée de chaque phase du pipeline (`parse · action · firewall · …` + total). - `addRequestCookie(cookie: Cookie): Cookie` - `getRequestCookies(name?: string): Cookies | Cookie | null` - `setCookie(cookie: Cookie): void | Cookie` - `getRequest(): contextRequest` - `getResponse(): contextResponse` - `isValidDomain(): boolean` - `saveSession(): Promise` - `hasSession(): boolean` - `getCookieSession(name: string): Cookie | null` - `getSessionCookieName(): string` — Nom effectif du cookie de session pour CE transport. - `parseCookies(): void` - `setContextJson(_encoding?: BufferEncoding): void` - `setContextHtml(_encoding?: BufferEncoding): void` #### `Http2Request` ```ts class Http2Request extends HttpRequest ``` - `request: http2.Http2ServerRequest` - `constructor(request: http2.Http2ServerRequest, context: HttpContext)` - `getHost(): string` — `:authority`, sinon `Host` — cf `requestAuthority` (RFC 9113 §8.3.1). - `getUserAgent(): string` - `getMethod(): HTTPMethod` - `getRawTarget(): string` — Request-target brut (origin-form) tel que reçu du transport — SOURCE UNIQUE partagée par la concaténation de `getFullUrl` et la découpe fast-path du ctor. #### `Http2Response` ```ts class Http2Response extends HttpResponse ``` - `statusCode: number` - `stream: http2.ServerHttp2Stream | null` - `streamId?: number` - `constructor(response: http2.Http2ServerResponse, context: HttpContext)` - `isHeaderSent(): boolean` - `writeHead(statusCode?: number, headers?: http.OutgoingHttpHeaders | http.OutgoingHttpHeader[]): void` - `send(chunk?: unknown, encoding?: BufferEncoding, _flush?: boolean): MaybePromise` — Écrit le corps sur le flux HTTP/2 et, pour une réponse unique, le termine d'un seul `end(corps)`. - `end(chunk?: string | Buffer, encoding?: BufferEncoding): MaybePromise` — Termine le flux HTTP/2 (ou la réponse de repli) — synchrone (#505). - `getStatusMessage(code?: number | string): string` - `getStatus(): { code: number; message: string; }` #### `HttpContext` ```ts class HttpContext extends Context implements IHttpContextInterface ``` - `proxy: ProxyType | null` - `isRedirect: boolean` - `sended: boolean` - `relayAccessLog: "all" | "errors" | null` — Requête relayée par le proxy inverse : la politique de ligne d'accès de son montage. - `request: HttpRequestType` - `response: HttpRsponseType` - `uploadService: uploadService | null` - `constructor(container: Container | Scope, request: http.IncomingMessage | http2.Http2ServerRequest, response: http.ServerResponse | http2.Http2ServerResponse, serverType: ServerType)` - `get originUrl(): URL | null` — URL d'origine effective, construite À LA DEMANDE (1ʳᵉ lecture, puis mémoïsée). - `set originUrl(value: URL | null)` — URL d'origine effective, construite À LA DEMANDE (1ʳᵉ lecture, puis mémoïsée). - `_onTimeout(): void` — Chemin timeout direct — appelé par les handlers socket/stream de `setTimeout()`. - `setScheme(): SchemeType` - `handle(): MaybePromise` — Sert la requête : délai de réponse, hooks `onRequest`, puis l'action résolue et son rendu (`resolver.callController()`). - `setTimeout(): void` - `logRequest(httpError?: Error | HttpError | nodefonyError | null): import("nodefony").Pdu` — Ligne d'accès — pour une requête RELAYÉE, avec le statut que l'amont a réellement rendu (le relais écrit la réponse brute, pas celle du contexte) ; un montage `accessLog: "errors"` ne l'écrit qu'en éc … - `clean(): void` — Nettoie le contexte, et le DÉTACHE de sa socket h1 : la connexion persistante survit à la requête, et l'entrée de `socketActiveContext` retiendrait sinon tout le contexte jusqu'à sa fermeture. - `render(chunk: unknown, encoding?: BufferEncoding, status?: string | number, headers?: Record): MaybePromise` — Sérialise la donnée selon son type (JSON, HTML, texte), pose statut et en-têtes, puis l'envoie (`send`). - `end(): Promise` - `send(chunk?: unknown, encoding?: BufferEncoding): MaybePromise` — Envoie la réponse : session sauvée, hook `onSend`, en-têtes, corps, puis fin de la réponse. - `writeHead(statusCode?: number, headers?: http.OutgoingHttpHeaders | http.OutgoingHttpHeader[]): void` - `write(chunk: unknown, encoding?: BufferEncoding, _flush?: boolean): MaybePromise` — Écrit le corps, puis termine la requête (`close`). - `openSse(options?: ISseStreamOptions): SseStream | Promise` — Répond par un flux d'événements serveur (`text/event-stream`). - `flush(chunk: unknown, encoding: BufferEncoding): MaybePromise` - `close(): MaybePromise` — Termine la requête : hook `onClose`, puis fin de la réponse si l'envoi ne l'a pas déjà faite. - `redirect(Url: string, status?: number | string, headers?: Record): HttpResponse` - `redirectHttps(status?: number | string, headers?: Record): HttpResponse` — Redirige vers la même URL en HTTPS, sur le port du serveur HTTPS lié — ou le port par défaut derrière un proxy, dont le port public est inconnu. - `redirectHttp(status?: number | string, headers?: Record): HttpResponse` — Redirige vers la même URL en HTTP, sur le port du serveur HTTP lié — ou le port par défaut derrière un proxy. - `getHostName(): string` - `getRemoteAddress(): string | null` - `getHost(): string` - `getUserAgent(): string` - `getMethod(): HTTPMethod` - `setContentType(type?: string, encoding?: BufferEncoding): void | http.ServerResponse` - `protected resolveIsHtml(): boolean` — Défaut paresseux d'`isHtml` — overridé par HttpContext (négociation `Accept`). - `setDefaultContentType(): void` - `setContextJson(encoding?: BufferEncoding): void` - `setContextHtml(encoding?: BufferEncoding): void` #### `HttpRequest` ```ts class HttpRequest ``` - `context: HttpContext` - `request: http.IncomingMessage | http2.Http2ServerRequest` - `headers: http.IncomingHttpHeaders` - `host: string` - `method: HTTPMethod` - `contentType: string | null` - `rawContentType: Record` - `domain: string` - `remoteAddress: string | null` - `hostname: string` - `sUrl: string` - `scheme: string` — Scheme effectif côté client (`http` | `https`, ou le proto `Forwarded` brut derrière un proxy de confiance) — posé par `getFullUrl`, seule source de cette décision. - `pathname: string` — Pathname de la requête, TOUJOURS sous forme normalisée WHATWG : découpe du target quand elle est prouvablement identique au parse (fast-path), `URL.pathname` sinon. - `search: string` — Query string au format `URL.search` (`?…`, ou `""`) — même provenance. - `get hasParsedUrl(): boolean` — L'objet `url` a-t-il déjà été construit ? - `get href(): string` — Sérialisation de l'URL de la requête — `URL.href` si l'objet existe, sinon `sUrl` (identique par construction sur le fast-path). - `get url(): URL` — URL WHATWG complète de la requête, construite au premier accès (fast-path) ou dès le ctor (bail-out). - `set url(u: URL)` — URL WHATWG complète de la requête, construite au premier accès (fast-path) ou dès le ctor (bail-out). - `parser: ParserType | null` - `body: RequestBody` — Le CORPS de la requête, parsé (JSON, urlencoded, XML, champs multipart) — nom universel de l'écosystème (Express, Fastify, NestJS) et celui d'`IAdminRequest.body`. - `get files(): readonly UploadedFile[]` — Les fichiers reçus dans un corps multipart, déjà écrits dans le répertoire temporaire — lus par `@UploadedFile()` / `@UploadedFiles()`. - `query: Record` — Les paramètres d'URL, seuls — jamais un champ du corps (`body`). - `queryStringOptions: (QS.IParseOptions & { decoder?: undefined; })` - `charset: BufferEncoding` - `uploadOption: IUploadOptions` - `maxBodySize: number` - `data: Buffer` - `get accept(): ReturnType` — Media-ranges de l'en-tête `Accept`, parsés au premier accès (mémoïsé). - `get acceptHtml(): boolean` — `true` si le client accepte `text/html` — résolu au premier accès (mémoïsé). - `origin: string` - `trustedProxy: boolean` - `forwarded: ResolvedProxy | null` - `constructor(request: http.IncomingMessage | http2.Http2ServerRequest, context: HttpContext)` - `initialize(): Promise` — Lit le corps de la requête, s'il y en a un, puis émet `onRequestEnd`. - `parseRequest(): Promise` - `parseMultipart(): Promise` — Parse un corps `multipart/form-data` via **busboy** (streaming pur). - `accepts(Type: string): boolean` - `createFileUpload(name: string, file: IParsedUploadFile): Promise` - `getMethod(): HTTPMethod` - `getContentType(request: http.IncomingMessage | http2.Http2ServerRequest): string | null` - `getCharset(): BufferEncoding` — Charset du corps déduit du `Content-Type` (`charset=…`), normalisé en un `BufferEncoding` Node valide. - `getDomain(): string` - `getUserAgent(): string` - `getHostName(host?: string): string` - `getHost(): string` - `getRemoteAddress(): string | null` - `getRawTarget(): string` — Request-target brut (origin-form) tel que reçu du transport — SOURCE UNIQUE partagée par la concaténation de `getFullUrl` et la découpe fast-path du ctor. - `protected resolveScheme(request: http.IncomingMessage | http2.Http2ServerRequest): string` — Scheme effectif côté client : `Forwarded`/`X-Forwarded-*` résolu de façon canonique (this.forwarded, gated proxy de confiance) ; sinon le transport réel. - `getFullUrl(request?: http.IncomingMessage | http2.Http2ServerRequest): string` - `getHeader(name: string): string | string[] | null` - `setUrl(Url: string): URL` - `getUrl(sUrl: string, baseUrl?: string): URL` - `log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu` #### `HttpResponse` ```ts class HttpResponse ``` - `context: HttpContext` - `response: http.ServerResponse | http2.Http2ServerResponse | null` - `statusCode: number` - `statusMessage: string` - `flushing: boolean` - `encoding: BufferEncoding` - `contentType: string` - `headers: http.OutgoingHttpHeaders` - `timeout?: number` - `cookies: Record` - `constructor(response: http.ServerResponse | http2.Http2ServerResponse, context: HttpContext)` - `protected ensureContentTypeHeader(): void` — Filet posé juste avant l'émission des en-têtes : si aucun `Content-Type` n'a été choisi (ni négociation, ni `render`, ni controller), émet le défaut `this.contentType` (application/octet-stream) — com … - `get body(): Buffer | null` — Corps de la réponse en octets. - `set body(value: Buffer | null)` — Corps de la réponse en octets. - `protected get payload(): string | Buffer` — Corps tel qu'il part sur le fil : le texte s'il n'a jamais été encodé, sinon les octets — vide légal si rien n'a été posé (`write(null)` jetterait ERR_STREAM_NULL_VALUES). - `protected get payloadEncoding(): BufferEncoding` — Encodage à passer avec `payload` (ignoré par Node pour des octets). - `clean(): void` - `isHeaderSent(): boolean` - `isHtml(): boolean` - `setTimeout(ms: number): void` - `addCookie(cookie: Cookie): Cookie` - `deleteCookie(cookie: Cookie): boolean` - `deleteCookieByName(name: string): boolean` - `setCookies(): void | http.ServerResponse` - `setCookie(cookie: Cookie): void | http.ServerResponse` - `setHeader(name: string, value: number | string | readonly string[]): void | http.ServerResponse` - `setHeaders(obj: OutgoingHttpHeaders): OutgoingHttpHeaders` - `setContentType(type?: string, encoding?: BufferEncoding): void | http.ServerResponse` - `setFileMimeType(type: string, encoding?: BufferEncoding): void | http.ServerResponse` - `setContentTypeByExtension(extention: string): void | http.ServerResponse` - `getMimeType(filenameOrExt: string): string | false` - `setEncoding(encoding: BufferEncoding): BufferEncoding` - `setStatusCode(status: number | string, message?: string): { code: number; message: string; }` - `getStatus(): { code: number; message: string; }` - `getStatusCode(): number` - `getStatusMessage(code?: number | string): string` - `setBody(ele: unknown, encoding?: BufferEncoding): void` — Pose le corps de la réponse : texte gardé tel quel, octets copiés sur leur seule fenêtre, tout autre valeur sérialisée en JSON. - `setLength(body?: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer): number` - `writeHead(statusCode?: number, headers?: http.OutgoingHttpHeaders | http.OutgoingHttpHeader[]): void` - `addTrailers(headers: http.OutgoingHttpHeaders): void` - `flush(chunk: unknown, encoding: BufferEncoding): MaybePromise` - `send(chunk?: unknown, encoding?: BufferEncoding, _flush?: boolean): MaybePromise` — Écrit le corps sur le flux et, pour une réponse unique, la termine. - `write(chunk?: unknown, encoding?: BufferEncoding): MaybePromise` - `writeContinue(): void` - `end(chunk?: string | Buffer, encoding?: BufferEncoding): MaybePromise` — Termine la réponse Node — un appel synchrone, rien n'y est à attendre (#505). - `getHeader(name: string): string | number | string[]` - `hasHeader(name: string): boolean` - `getHeaders(): http.OutgoingHttpHeaders` - `redirect(url: string, status?: number | string, headers?: Record): this` - `log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu` #### `Response` ```ts class HttpResponse ``` - `context: HttpContext` - `response: http.ServerResponse | http2.Http2ServerResponse | null` - `statusCode: number` - `statusMessage: string` - `flushing: boolean` - `encoding: BufferEncoding` - `contentType: string` - `headers: http.OutgoingHttpHeaders` - `timeout?: number` - `cookies: Record` - `constructor(response: http.ServerResponse | http2.Http2ServerResponse, context: HttpContext)` - `protected ensureContentTypeHeader(): void` — Filet posé juste avant l'émission des en-têtes : si aucun `Content-Type` n'a été choisi (ni négociation, ni `render`, ni controller), émet le défaut `this.contentType` (application/octet-stream) — com … - `get body(): Buffer | null` — Corps de la réponse en octets. - `set body(value: Buffer | null)` — Corps de la réponse en octets. - `protected get payload(): string | Buffer` — Corps tel qu'il part sur le fil : le texte s'il n'a jamais été encodé, sinon les octets — vide légal si rien n'a été posé (`write(null)` jetterait ERR_STREAM_NULL_VALUES). - `protected get payloadEncoding(): BufferEncoding` — Encodage à passer avec `payload` (ignoré par Node pour des octets). - `clean(): void` - `isHeaderSent(): boolean` - `isHtml(): boolean` - `setTimeout(ms: number): void` - `addCookie(cookie: Cookie): Cookie` - `deleteCookie(cookie: Cookie): boolean` - `deleteCookieByName(name: string): boolean` - `setCookies(): void | http.ServerResponse` - `setCookie(cookie: Cookie): void | http.ServerResponse` - `setHeader(name: string, value: number | string | readonly string[]): void | http.ServerResponse` - `setHeaders(obj: OutgoingHttpHeaders): OutgoingHttpHeaders` - `setContentType(type?: string, encoding?: BufferEncoding): void | http.ServerResponse` - `setFileMimeType(type: string, encoding?: BufferEncoding): void | http.ServerResponse` - `setContentTypeByExtension(extention: string): void | http.ServerResponse` - `getMimeType(filenameOrExt: string): string | false` - `setEncoding(encoding: BufferEncoding): BufferEncoding` - `setStatusCode(status: number | string, message?: string): { code: number; message: string; }` - `getStatus(): { code: number; message: string; }` - `getStatusCode(): number` - `getStatusMessage(code?: number | string): string` - `setBody(ele: unknown, encoding?: BufferEncoding): void` — Pose le corps de la réponse : texte gardé tel quel, octets copiés sur leur seule fenêtre, tout autre valeur sérialisée en JSON. - `setLength(body?: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer): number` - `writeHead(statusCode?: number, headers?: http.OutgoingHttpHeaders | http.OutgoingHttpHeader[]): void` - `addTrailers(headers: http.OutgoingHttpHeaders): void` - `flush(chunk: unknown, encoding: BufferEncoding): MaybePromise` - `send(chunk?: unknown, encoding?: BufferEncoding, _flush?: boolean): MaybePromise` — Écrit le corps sur le flux et, pour une réponse unique, la termine. - `write(chunk?: unknown, encoding?: BufferEncoding): MaybePromise` - `writeContinue(): void` - `end(chunk?: string | Buffer, encoding?: BufferEncoding): MaybePromise` — Termine la réponse Node — un appel synchrone, rien n'y est à attendre (#505). - `getHeader(name: string): string | number | string[]` - `hasHeader(name: string): boolean` - `getHeaders(): http.OutgoingHttpHeaders` - `redirect(url: string, status?: number | string, headers?: Record): this` - `log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu` #### `SseStream` ```ts class SseStream ``` Un flux `text/event-stream` ouvert sur une réponse. - `get closed(): boolean` — Le flux est-il fermé — par le serveur (`close()`) ou par le client parti ? - `send(data: unknown, options?: ISseSendOptions): Promise` — Envoie un événement. - `comment(text?: string): Promise` — Envoie un commentaire — ignoré par le client, utile pour garder une connexion vivante ou marquer le flux à la lecture. - `retry(ms: number): Promise` — Impose au client un délai de reconnexion (champ `retry:`). - `onClose(listener: () => void): void` — Appelle `listener` à la fermeture du flux, quelle qu'en soit la cause. - `close(): Promise` — Ferme le flux et termine la requête. #### `WebsocketContext` ```ts class WebsocketContext extends Context implements IWebsocketContextInterface ``` - `request: WsIncomingMessage | null` - `response: WebsocketResponse | null` - `acceptedProtocol?: string` - `port: number | string` - `rejected: boolean` - `teardownWired: boolean` - `connection: Ws | null` - `admission: IUpgradeAdmission | null` — Le verdict du handshake encore à rendre : posé par le noyau tant que le pipeline décide (pare-feu, garde de l'action), `null` dès que la socket est acceptée ou refusée. - `origin: string` - `proxy: ProxyType | null` - `forwarded: ResolvedProxy | null` - `wsUrl: URL | null` - `query: Record` - `wsPath: string` - `constructor(scope: Scope, req: IncomingMessage, ws: Ws | null, serverType: ServerType)` - `log(pci: unknown, severity?: Severity, msgid?: Msgid, msg?: Message, moduleName?: string): import("nodefony").Pdu` — Émet une entrée de log structurée — point d'entrée central pour TOUT log Nodefony. - `logRequest(httpError?: Error | HttpError | nodefonyError | null, acceptedProtocol?: string | null): import("nodefony").Pdu` - `acceptConnection(ws: Ws): void` — Rattache la socket que le handshake vient d'ouvrir (`101` envoyé) : le contexte a été construit et jugé AVANT, sans elle. - `refuseHandshake(status: number): boolean` — Refuse le handshake par un statut HTTP, avant tout `101` (RFC 6455 §4.2.2) — avec les en-têtes posés pendant la décision (`WWW-Authenticate` du pare-feu, `Retry-After`). - `connect(): Promise` - `handle(data?: unknown[]): Promise` - `render(chunk: unknown, encoding?: BufferEncoding): Promise` - `send(data?: string | Buffer | null, encoding?: BufferEncoding): Promise` - `broadcast(data?: string | Buffer | null, encoding?: BufferEncoding): null` - `beginFrame(method: string, framePath: string): FrameProfile | null` — Ouvre le profil d'**une invocation** du pont RPC (une frame `api.request`). - `collectFrame(frame: FrameProfile | null): void` — Enregistre le profil d'une invocation terminée dans le ring buffer du Profiler (no-op hors dev, ou si aucun profil n'a été ouvert). - `phaseStart(name: PhaseName): void` — Les phases émises pendant une invocation du pont (`initialize` par le Resolver, `render` par le Controller…) vont dans le profil de **la frame**, pas du contexte : sans cette redirection, `Context.pha … - `phaseEnd(name: PhaseName): void` - `handleMessage(data: Buffer | string, isBinary: boolean): Promise` - `onClose(code: number, reason: Buffer): void` - `onConnectionError(error: Error): void` — Listener `error` de la socket ws (OBLIGATOIRE — sans lui, un 'error' émis sans listener crashe le process via EventEmitter). - `setScheme(): SchemeType` - `getRemoteAddress(): string | null` - `getHost(): string` - `getHostName(): string` - `getUserAgent(): string` - `getMethod(): HTTPMethod` - `setContextJson(): void` - `clean(): void` — Libère les ressources — retire les listeners trackés du bus partagé pour éviter les fuites mémoire, puis détache container/kernel/syslog/nc. - `close(reasonCode: number | null, description: string): void` - `drop(reasonCode: number, description: string): void` - `reject(code: number | string, message?: string): void` #### `WebsocketResponse` ```ts class WebsocketResponse ``` - `statusCode: number` - `body: Buffer | null` - `encoding: BufferEncoding` - `connection: Ws | null` - `statusMessage: string` - `webSocketVersion?: number` - `cookies: Record` - `constructor(connection: Ws | null, context: WebsocketContext)` - `log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): import("nodefony").Pdu` - `setConnection(connection: Ws): Ws` - `send(data?: Buffer | string | null, encoding?: BufferEncoding): Promise` - `broadcast(data?: Buffer | string | null, type?: BufferEncoding): void` - `setBody(ele: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer, encoding?: BufferEncoding): Buffer | null` - `drop(reasonCode?: number, description?: string): void` - `close(reasonCode?: number, description?: string): void` - `getStatus(): { code: number; message: string; }` - `getStatusCode(): number` - `getStatusMessage(): string` - `setStatusCode(status: number | string, message?: string): { code: number; message: string; }` - `clean(): void` - `setEncoding(encoding: BufferEncoding): BufferEncoding` - `handshakeHeaders: Record | null` — En-têtes de la réponse au handshake, retenus tant que la socket n'est pas acceptée : ils ne partent que dans un REFUS (`refuseHandshake`) — le `101` de `ws` ne les porte pas. - `setHeader(name: string, value: number | string | readonly string[]): boolean` — Retient un en-tête du handshake (cf `handshakeHeaders`) ; sans effet une fois la socket ouverte, où il n'y a plus de réponse HTTP. - `setHeaders(obj: OutgoingHttpHeaders): boolean` - `addCookie(cookie: Cookie): void` - `setCookies(): void` - `setCookie(_cookie: Cookie): void` #### `wsResponse` ```ts class WebsocketResponse ``` - `statusCode: number` - `body: Buffer | null` - `encoding: BufferEncoding` - `connection: Ws | null` - `statusMessage: string` - `webSocketVersion?: number` - `cookies: Record` - `constructor(connection: Ws | null, context: WebsocketContext)` - `log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): import("nodefony").Pdu` - `setConnection(connection: Ws): Ws` - `send(data?: Buffer | string | null, encoding?: BufferEncoding): Promise` - `broadcast(data?: Buffer | string | null, type?: BufferEncoding): void` - `setBody(ele: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer, encoding?: BufferEncoding): Buffer | null` - `drop(reasonCode?: number, description?: string): void` - `close(reasonCode?: number, description?: string): void` - `getStatus(): { code: number; message: string; }` - `getStatusCode(): number` - `getStatusMessage(): string` - `setStatusCode(status: number | string, message?: string): { code: number; message: string; }` - `clean(): void` - `setEncoding(encoding: BufferEncoding): BufferEncoding` - `handshakeHeaders: Record | null` — En-têtes de la réponse au handshake, retenus tant que la socket n'est pas acceptée : ils ne partent que dans un REFUS (`refuseHandshake`) — le `101` de `ws` ne les porte pas. - `setHeader(name: string, value: number | string | readonly string[]): boolean` — Retient un en-tête du handshake (cf `handshakeHeaders`) ; sans effet une fois la socket ouverte, où il n'y a plus de réponse HTTP. - `setHeaders(obj: OutgoingHttpHeaders): boolean` - `addCookie(cookie: Cookie): void` - `setCookies(): void` - `setCookie(_cookie: Cookie): void` ### Fonctions (7) #### `acceptsEventStream` ```ts function acceptsEventStream(accept: string | string[]): boolean ``` Le client accepte-t-il un flux d'événements ? Lit l'en-tête `Accept`. #### `compileDomainPattern` ```ts function compileDomainPattern(pattern: DomainPattern): RegExp ``` Compile UN pattern de domaine en `RegExp` selon la politique sûre. #### `compileDomainPatterns` ```ts function compileDomainPatterns(patterns: DomainPattern | DomainPattern[]): RegExp[] ``` Compile une liste de patterns. Les string vides sont ignorées (un `^$` ne sert à rien et masque une coquille de config). #### `compileTrustedHosts` ```ts function compileTrustedHosts(domain: string, trusted: ITrustedHostsConfig, isDev: boolean): RegExp[] ``` Construit la liste `RegExp` de la barrière `trustedHosts` (kernel, avant routing). #### `isDomainAllowed` ```ts function isDomainAllowed(regAlias: RegExp[], domain: string): boolean ``` Teste un `Host` entrant contre une liste de `RegExp` pré-compilée. #### `isWebsocketContext` ```ts function isWebsocketContext(context: ContextType): context is WebsocketContext ``` Dit si un contexte sert une connexion WebSocket — la garde qui rétrécit `ContextType` à `WebsocketContext` sans conversion. #### `openSseStream` ```ts function openSseStream(context: HttpContext, options?: ISseStreamOptions): SseStream | Promise ``` Ouvre un flux d'événements sur la réponse d'un contexte HTTP. ### Constantes (4) #### `REQUEST_TRACE_CHANNEL` ```ts const REQUEST_TRACE_CHANNEL = "nodefony.http.request" ``` Nom du `TracingChannel` qui encadre chaque requête HTTP et chaque handshake WebSocket — forme `module.fonction` recommandée par la documentation de `node:diagnostics_channel` ; les sous-canaux sont `tracing:nodefony.http.request:start`, `:end`, `:asyncStart`, `:asyncEnd`, `:error`. #### `SSE_HEARTBEAT_MS` ```ts const SSE_HEARTBEAT_MS = 15000 ``` Battement de cœur par défaut, en ms (§9.2.7 : « every 15 seconds or so »). #### `decideSend` ```ts const decideSend: (ws: IBackpressureTarget, max: number, policy: WsBackpressurePolicy, closeAfterDrops?: number) => WsSendDecision ``` Décide si une frame doit partir vers `ws` selon la backpressure SORTANTE (serveur → client). Protège la RAM d'envoi du serveur quand le client est lent à RECEVOIR (ne lit pas assez vite → `ws.bufferedAmount` gonfle → OOM). `broadcast()` amplifie : un seul client lent peut, sans borne, faire tomber la diffusion entière. #### `readBackpressureOptions` ```ts const readBackpressureOptions: (wss: WebSocketServer | null) => { max: number; policy: WsBackpressurePolicy; closeAfterDrops: number; } ``` Relit le seuil + la politique depuis les options du `WebSocketServer`. ### Interfaces (5) #### `IBackpressureSocket` ```ts interface IBackpressureSocket extends Ws ``` Socket augmentée d'un compteur de drops (number lazy — lu par la sonde socket). - `_nfDrops?: number` — Nombre cumulé de frames droppées/refusées pour backpressure sur cette socket. - `_nfDropStreak?: number` — Frames refusées **d'affilée**, remis à zéro dès qu'une frame repart. #### `IBackpressureTarget` ```ts interface IBackpressureTarget ``` Ce dont la règle a besoin, et rien de plus : la taille de la file d'envoi et de quoi fermer. Typé STRUCTURELLEMENT pour que `@nodefony/realtime` applique la même règle sans importer `ws` (son transport type déjà sa connexion ainsi). - `readonly bufferedAmount?: number` - `close(code?: number, reason?: string): void` #### `ISseSendOptions` ```ts interface ISseSendOptions ``` Ce qu'un événement porte en plus de ses données. - `event?: string` — Type de l'événement (champ `event:`) — absent : `message`. - `id?: string` — Identifiant (champ `id:`) que le client renverra en `Last-Event-ID`. #### `ISseStreamOptions` ```ts interface ISseStreamOptions ``` Options d'ouverture d'un flux. - `heartbeat?: number | false` — Période du battement de cœur (commentaire `:`), en ms entre 1 et 2^31-1 — `false` pour l'éteindre. - `retry?: number` — Délai de reconnexion imposé au client (champ `retry:`), en ms. - `stallTimeout?: number | false` — Délai maximal pendant lequel une écriture peut rester bloquée — le client ne lit plus —, en ms entre 1 et 2^31-1 ; au-delà, la connexion est coupée. - `maxEventBytes?: number` — Taille maximale d'un événement écrit, en octets (UTF-8). - `maxDuration?: number | false` — Durée de vie maximale du flux, en ms entre 1 et 2^31-1 : il est fermé ensuite, et un `EventSource` se reconnecte — en repassant par le pare-feu. #### `IWsBackpressureOptions` ```ts interface IWsBackpressureOptions ``` Options de backpressure SORTANTE (serveur → client). - `maxBackpressure?: number` — Seuil (octets) de `ws.bufferedAmount` ; `0`/absent = désactivé. - `backpressurePolicy?: WsBackpressurePolicy` — Action au dépassement du seuil. - `backpressureCloseAfterDrops?: number` — Refus consécutifs au-delà desquels on ferme (1013) ; `0`/absent = jamais. ### Types (9) #### `Cookies` ```ts type Cookies = Record ``` #### `DomainPattern` ```ts type DomainPattern = string | RegExp ``` Un pattern de domaine : string (exact ou `*`-wildcard) ou `RegExp` (libre). #### `HTTPMethod` ```ts type HTTPMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE" | "PATCH" | "WEBSOCKET" ``` #### `ITrustedHostsConfig` ```ts type ITrustedHostsConfig = boolean | DomainPattern | DomainPattern[] ``` Valeur de configuration `http.trustedHosts` (barrière sécu avant routing) : - `false` / absent : défaut (domaine canonique + loopback en dev). - `true` : bypass total — tout `Host` passe (déploiement où un reverse-proxy filtre déjà le `Host`, cf doctrine cloud-native). - `string` / `string[]` : patterns additionnels (exact ou `*`-wildcard). #### `WebSocketState` ```ts type WebSocketState = "handshake" | "connected" | "closed" | "error" | "message" | null ``` #### `WsBackpressurePolicy` ```ts type WsBackpressurePolicy = "drop" | "close" ``` Politique appliquée quand le buffer d'envoi d'un client dépasse le seuil. #### `WsSendDecision` ```ts type WsSendDecision = "send" | "drop" | "close" ``` Décision pour une frame : l'émettre, la sauter, ou (socket fermée) ne rien faire. #### `contextRequest` ```ts type contextRequest = HttpRequest | Http2Request | http.IncomingMessage | null ``` #### `contextResponse` ```ts type contextResponse = HttpResponse | Http2Response | WebsocketResponse | null ``` --- [← Toutes les références d'API](../../)