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

stable

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.6 : 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" — 51 symboles.

Classes (11)#

Context#

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<string, readonly string[]> | 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<string, unknown>): 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<void> — 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<unknown> — Émet et attend les listeners async — équivalent de fireAsync.
• fireAsync(event: KernelEventsType, ...args: unknown[]): Promise<unknown> — É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<Session | null>
• 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#

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#

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<Http2Response> — É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<http.ServerResponse | http2.ServerHttp2Stream> — Termine le flux HTTP/2 (ou la réponse de repli) — synchrone (#505).
• getStatusMessage(code?: number | string): string
• getStatus(): { code: number; message: string; }

HttpContext#

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<this> — 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<string, string | number>): MaybePromise<Http2Response | HttpResponse> — Sérialise la donnée selon son type (JSON, HTML, texte), pose statut et en-têtes, puis l’envoie (send).
• end(): Promise<Http2Response | HttpResponse>
• send(chunk?: unknown, encoding?: BufferEncoding): MaybePromise<Http2Response | HttpResponse> — 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<Http2Response | HttpResponse> — Écrit le corps, puis termine la requête (close).
• openSse<Events extends EventsMap = DefaultEventsMap>(options?: ISseStreamOptions): SseStream<Events> | Promise<SseStream<Events>> — Répond par un flux d’événements serveur (text/event-stream).
• openStream(source: ByteStreamSource, options?: IByteStreamOptions): Promise<IByteStreamResult> — Répond par un FLUX D’OCTETS : un <video src>, un fetch(), un téléchargement ou un outil tiers (curl) le consomment comme n’importe quelle réponse HTTP, une réponse par consommateur.
• flush(chunk: unknown, encoding: BufferEncoding): MaybePromise<HttpResponse>
• close(): MaybePromise<Http2Response | HttpResponse> — 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<string, string | number>): HttpResponse
• redirectHttps(status?: number | string, headers?: Record<string, string | number>): 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<string, string | number>): 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
• 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#

class HttpRequest

• context: HttpContext
• request: http.IncomingMessage | http2.Http2ServerRequest
• headers: http.IncomingHttpHeaders
• host: string
• method: HTTPMethod
• contentType: string | null
• rawContentType: Record<string, string>
• 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<string, unknown> — 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<typeof acceptParser> — 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<unknown> — Lit le corps de la requête, s’il y en a un, puis émet onRequestEnd.
• parseRequest(): Promise<ParserType | null>
• parseMultipart(): Promise<ParserType> — Parse un corps multipart/form-data via busboy (streaming pur).
• accepts(Type: string): boolean
• createFileUpload(name: string, file: IParsedUploadFile): Promise<UploadedFile>
• 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 — L’autorité de la requête : celle de la cible en forme absolue, sinon l’en-tête Host (RFC 9112 §3.2.2 — le serveur DOIT alors ignorer Host).
• 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#

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<string, Cookie>
• headerPolicy: IFirewallGate | null — Pare-feu qui posera les en-têtes de sécurité applicatifs juste avant l’émission des en-têtes, une fois le type de la réponse fixé : la politique suit ce type (ADR-0024 §C11).
• 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
• setCookie(cookie: Cookie): void
• setHeader(name: string, value: number | string | readonly string[]): void — Pose un en-tête de la réponse ; en flux chunké déjà ouvert, le range en trailer.
• setValidatedHeader(name: string, value: string): void — Pose un en-tête dont la valeur a DÉJÀ été validée par l’appelant — une table figée et contrôlée au démarrage (en-têtes de sécurité).
• setDefaultHeader(name: string, value: string): void — Pose un en-tête validé au démarrage SAUF si la réponse en porte déjà un : la valeur du framework est un défaut, celle que l’application a écrite gagne.
• protected applyHeaderPolicy(contentType: string | null, servedAsFile?: boolean): void — Pose les en-têtes de la politique armée (headerPolicy) pour une réponse de type contentType — une fois, juste avant l’émission.
• protected contentTypeForPolicy(): string | null — Type qui choisit la politique : null pour une réponse sans contenu (204, corps vide) — même si un Content-Type y a été posé, rien n’y sera rendu ; sinon le Content-Type posé.
• commitHeaders(): void — Recopie la réserve sur la réponse Node, pour un émetteur qui écrit sans passer par writeHead — fichier statique, relais vers un amont.
• commitBeforeNativeWrite(): void — Recopie la réserve sur la réponse Node au PREMIER setHeader qu’un tiers y fera — fichier statique servi, redirection de dossier — et seulement alors : un raté du repli statique (la 404 d’une route i …
• disarmNativeWrite(): void — Retire l’interception posée par commitBeforeNativeWrite.
• removeHeader(name: string): void — Retire un en-tête, de la réserve comme de la réponse Node.
• setHeaders(obj: OutgoingHttpHeaders): OutgoingHttpHeaders
• setContentType(type?: string, encoding?: BufferEncoding): void
• setFileMimeType(type: string, encoding?: BufferEncoding): void
• setContentTypeByExtension(extention: string): void
• 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
• protected headerList(): readonly OutgoingHttpHeader[] — La réserve amorcée — pour une remise sous une autre forme (HTTP/2).
• addTrailers(headers: http.OutgoingHttpHeaders): void
• flush(chunk: unknown, encoding: BufferEncoding): MaybePromise<HttpResponse> — Écrit un morceau d’une réponse en flux, sans la terminer — c’est end() qui la clôt après le dernier.
• send(chunk?: unknown, encoding?: BufferEncoding, _flush?: boolean): MaybePromise<HttpResponse> — Écrit le corps sur le flux et, pour une réponse unique, la termine.
• write(chunk?: unknown, encoding?: BufferEncoding): MaybePromise<HttpResponse>
• writeContinue(): void
• end(chunk?: string | Buffer, encoding?: BufferEncoding): MaybePromise<http.ServerResponse | http2.ServerHttp2Stream> — Termine la réponse Node — un appel synchrone, rien n’y est à attendre (#505).
• getHeader(name: string): string | number | string[] — Valeur d’un en-tête posé — dans la réserve, sinon sur la réponse Node (ce qu’un tiers y a écrit directement : send, quota).
• hasHeader(name: string): boolean
• getHeaders(): http.OutgoingHttpHeaders — Tous les en-têtes posés, noms en minuscules — une copie, à chaque appel.
• redirect(url: string, status?: number | string, headers?: Record<string, string | number>): this
• log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu

Response#

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<string, Cookie>
• headerPolicy: IFirewallGate | null — Pare-feu qui posera les en-têtes de sécurité applicatifs juste avant l’émission des en-têtes, une fois le type de la réponse fixé : la politique suit ce type (ADR-0024 §C11).
• 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
• setCookie(cookie: Cookie): void
• setHeader(name: string, value: number | string | readonly string[]): void — Pose un en-tête de la réponse ; en flux chunké déjà ouvert, le range en trailer.
• setValidatedHeader(name: string, value: string): void — Pose un en-tête dont la valeur a DÉJÀ été validée par l’appelant — une table figée et contrôlée au démarrage (en-têtes de sécurité).
• setDefaultHeader(name: string, value: string): void — Pose un en-tête validé au démarrage SAUF si la réponse en porte déjà un : la valeur du framework est un défaut, celle que l’application a écrite gagne.
• protected applyHeaderPolicy(contentType: string | null, servedAsFile?: boolean): void — Pose les en-têtes de la politique armée (headerPolicy) pour une réponse de type contentType — une fois, juste avant l’émission.
• protected contentTypeForPolicy(): string | null — Type qui choisit la politique : null pour une réponse sans contenu (204, corps vide) — même si un Content-Type y a été posé, rien n’y sera rendu ; sinon le Content-Type posé.
• commitHeaders(): void — Recopie la réserve sur la réponse Node, pour un émetteur qui écrit sans passer par writeHead — fichier statique, relais vers un amont.
• commitBeforeNativeWrite(): void — Recopie la réserve sur la réponse Node au PREMIER setHeader qu’un tiers y fera — fichier statique servi, redirection de dossier — et seulement alors : un raté du repli statique (la 404 d’une route i …
• disarmNativeWrite(): void — Retire l’interception posée par commitBeforeNativeWrite.
• removeHeader(name: string): void — Retire un en-tête, de la réserve comme de la réponse Node.
• setHeaders(obj: OutgoingHttpHeaders): OutgoingHttpHeaders
• setContentType(type?: string, encoding?: BufferEncoding): void
• setFileMimeType(type: string, encoding?: BufferEncoding): void
• setContentTypeByExtension(extention: string): void
• 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
• protected headerList(): readonly OutgoingHttpHeader[] — La réserve amorcée — pour une remise sous une autre forme (HTTP/2).
• addTrailers(headers: http.OutgoingHttpHeaders): void
• flush(chunk: unknown, encoding: BufferEncoding): MaybePromise<HttpResponse> — Écrit un morceau d’une réponse en flux, sans la terminer — c’est end() qui la clôt après le dernier.
• send(chunk?: unknown, encoding?: BufferEncoding, _flush?: boolean): MaybePromise<HttpResponse> — Écrit le corps sur le flux et, pour une réponse unique, la termine.
• write(chunk?: unknown, encoding?: BufferEncoding): MaybePromise<HttpResponse>
• writeContinue(): void
• end(chunk?: string | Buffer, encoding?: BufferEncoding): MaybePromise<http.ServerResponse | http2.ServerHttp2Stream> — Termine la réponse Node — un appel synchrone, rien n’y est à attendre (#505).
• getHeader(name: string): string | number | string[] — Valeur d’un en-tête posé — dans la réserve, sinon sur la réponse Node (ce qu’un tiers y a écrit directement : send, quota).
• hasHeader(name: string): boolean
• getHeaders(): http.OutgoingHttpHeaders — Tous les en-têtes posés, noms en minuscules — une copie, à chaque appel.
• redirect(url: string, status?: number | string, headers?: Record<string, string | number>): this
• log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu

SseStream#

class SseStream<Events extends EventsMap = DefaultEventsMap>

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<K extends EventNames<Events> = never>(data: SseEventData<Events, K>, options?: ISseSendOptions<K>): Promise<void> — Envoie un événement.
• comment(text?: string): Promise<void> — Envoie un commentaire — ignoré par le client, utile pour garder une connexion vivante ou marquer le flux à la lecture.
• retry(ms: number): Promise<void> — 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<void> — Ferme le flux et termine la requête.

WebsocketContext#

class WebsocketContext extends Context implements IWebsocketContextInterface

• request: WsIncomingMessage | null
• response: WebsocketResponse | null
• acceptedProtocol?: string
• frameCodec: IFrameCodec | null — Codec des trames BINAIRES de cette connexion, posé par la couche qui l’a négocié (le temps réel, ADR-0022 §2).
• port: number | string
• rejected: boolean
• teardownWired: boolean
• connection: Ws | null
• frameRate: IFrameRateWindow | null — Fenêtre de la borne de débit entrante — null tant que la borne est désactivée ou qu’aucune trame n’est arrivée (créée au premier usage).
• 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<string, string>
• 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<Ws>
• handle(data?: unknown[]): Promise<this>
• render(chunk: unknown, encoding?: BufferEncoding): Promise<WebsocketResponse>
• send(data?: string | Buffer | null, encoding?: BufferEncoding): Promise<WebsocketResponse>
• broadcast(data?: string | Buffer | null, encoding?: BufferEncoding): null
• outboundTracer(): (data: unknown) => void | null — Traceur des trames SORTANTES écrites hors de send — le temps réel écrit droit sur la socket.
• 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<unknown>
• 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#

class WebsocketResponse

• statusCode: number
• body: Buffer | null
• encoding: BufferEncoding
• connection: Ws | null
• statusMessage: string
• webSocketVersion?: number
• cookies: Record<string, Cookie>
• 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<WebsocketResponse>
• broadcast(data?: Buffer | string | null, type?: BufferEncoding): void
• setBody(ele: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer, encoding?: BufferEncoding): Buffer<ArrayBufferLike> | 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<string, string | number> | 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#

class WebsocketResponse

• statusCode: number
• body: Buffer | null
• encoding: BufferEncoding
• connection: Ws | null
• statusMessage: string
• webSocketVersion?: number
• cookies: Record<string, Cookie>
• 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<WebsocketResponse>
• broadcast(data?: Buffer | string | null, type?: BufferEncoding): void
• setBody(ele: string | NodeJS.ArrayBufferView | ArrayBuffer | SharedArrayBuffer, encoding?: BufferEncoding): Buffer<ArrayBufferLike> | 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<string, string | number> | 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 (10)#

acceptsEventStream#

function acceptsEventStream(accept: string | string[]): boolean

Le client accepte-t-il un flux d’événements ? Lit l’en-tête Accept.

compileDomainPattern#

function compileDomainPattern(pattern: DomainPattern): RegExp

Compile UN pattern de domaine en RegExp selon la politique sûre.

compileDomainPatterns#

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#

function compileTrustedHosts(domain: string, trusted: ITrustedHostsConfig, isDev: boolean): RegExp[]

Construit la liste RegExp de la barrière trustedHosts (kernel, avant routing).

isContentlessStatus#

function isContentlessStatus(status: number): boolean

Vrai pour un statut dont la réponse n’a, par définition, aucun contenu — 204, 205 et 304 (RFC 9110 §15.3.5, §15.3.6, §15.4.5).

isDomainAllowed#

function isDomainAllowed(regAlias: RegExp[], domain: string): boolean

Teste un Host entrant contre une liste de RegExp pré-compilée.

isWebsocketContext#

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.

openByteStream#

function openByteStream(context: HttpContext, source: ByteStreamSource, options?: IByteStreamOptions): Promise<IByteStreamResult>

Répond par un flux d’octets sur la réponse d’un contexte HTTP.

openSseStream#

function openSseStream<Events extends EventsMap = DefaultEventsMap>(context: HttpContext, options?: ISseStreamOptions): SseStream<Events> | Promise<SseStream<Events>>

Ouvre un flux d’événements sur la réponse d’un contexte HTTP.

parseRequestTarget#

function parseRequestTarget(target: string): ISplitTarget | null

Analyse un request-target origin-form (/chemin[?query]) dans la forme NORMALISÉE que la porte HTTP donne au routeur (HttpRequest) : découpe exacte quand le parse WHATWG serait l’identité (splitTarget), vrai parse WHATWG sinon — dot-segments résolus, \ replié, percent-encoding posé.

Constantes (9)#

FRAME_RATE_WINDOW_MS#

const FRAME_RATE_WINDOW_MS = 1000

Durée d’une fenêtre de comptage (ms) : la borne s’exprime en trames PAR SECONDE.

REQUEST_TRACE_CHANNEL#

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#

const SSE_HEARTBEAT_MS = 15000

Battement de cœur par défaut, en ms (§9.2.7 : « every 15 seconds or so »).

admitFrame#

const admitFrame: (win: IFrameRateWindow, now: number, bound: number, closeAfter: number) => BackpressureVerdict

Décide du sort d’une trame reçue, AVANT tout décodage : l’admettre, l’écarter, ou fermer la connexion.

decideSend#

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.

frameRateRejectedTotal#

const frameRateRejectedTotal: () => number

Nombre cumulé de trames entrantes écartées par la borne de débit dans ce processus (unité : une trame reçue).

readBackpressureOptions#

const readBackpressureOptions: (wss: WebSocketServer | null) => { max: number; policy: WsBackpressurePolicy; closeAfterDrops: number; }

Relit le seuil + la politique depuis les options du WebSocketServer.

readFrameRateBound#

const readFrameRateBound: (server: unknown) => number

Borne de débit entrante du serveur WebSocket (maxFramesPerSecond) ; 0 = désactivée.

readFrameRateCloseAfter#

const readFrameRateCloseAfter: (server: unknown) => number

Solde de refus qui ferme la connexion (frameRateCloseAfterRejects) ; 0 = jamais.

Interfaces (10)#

IBackpressureSocket#

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#

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
• _nfDrops?: number — Cumul des frames refusées pour contre-pression (lazy — lu par la sonde socket).
• _nfDropStreak?: number — Solde de refus courant (cf nextDropBalance) ; absent = 0.

IByteStreamOptions#

interface IByteStreamOptions

Options d’une réponse en flux d’octets.

• status?: number — Statut de la réponse, entre 200 et 599.
• headers?: http.OutgoingHttpHeaders — En-têtes de la réponse, écrits au premier morceau.
• live?: boolean — Flux VIVANT (défaut true) : la sortie d’un processus, un relais — un proxy inverse ne doit pas le mettre en tampon, ni un cache le garder, d’où Cache-Control: no-cache, no-transform et `X-Accel-Bu …
• idleTimeout?: number — Délai maximal sans un octet de la source, en ms ; 0 le désarme.
• stallTimeout?: number | false — Délai maximal pendant lequel une écriture peut rester bloquée — le client ne lit plus —, en ms ; au-delà, la connexion est coupée.
• maxDuration?: number | false — Durée de vie maximale du flux, en ms.
• onClose?: (reason: ByteStreamEndReason) => void — Appelé une fois à la fin du flux, avec sa raison — AVANT la fin de la requête et la résolution de la promesse.

IByteStreamResult#

interface IByteStreamResult

Ce que rend la fin d’un flux d’octets.

• reason: ByteStreamEndReason — Pourquoi le flux s’est terminé.
• bytes: number — Octets écrits sur la réponse.

IFrameRateWindow#

interface IFrameRateWindow

Fenêtre de comptage d’une connexion, créée à la PREMIÈRE trame reçue borne activée.

• start: number — Début de la fenêtre courante (ms, Date.now()).
• count: number — Trames reçues dans la fenêtre courante.
• balance: number — Solde de refus (+1 par trame écartée, −1 par trame admise).

ISplitTarget#

interface ISplitTarget

Résultat d’une découpe acceptée : les deux composants, dans la même forme que URL.pathname / URL.search (le ? inclus, "" si query absente ou vide — /x? donne search === "" comme WHATWG).

• pathname: string
• search: string

ISseSendOptions#

interface ISseSendOptions<K extends string = string>

Ce qu’un événement porte en plus de ses données.

• event?: K — Type de l’événement (champ event:) — absent : message.
• id?: string — Identifiant (champ id:) que le client renverra en Last-Event-ID.

ISseStreamOptions#

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#

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.

IWsFrameRateOptions#

interface IWsFrameRateOptions

Options de la borne de débit ENTRANTE (client → serveur), lues dans wss.options.

• maxFramesPerSecond?: number — Trames reçues admises par seconde et par connexion ; 0/absent = désactivée.
• frameRateCloseAfterRejects?: number — Solde de trames écartées qui ferme la connexion (1008) ; 0 = jamais.

Types (11)#

ByteStreamEndReason#

type ByteStreamEndReason = "end" | "client" | "error" | "timeout" | "stall"

Raison de la fin d’un flux d’octets.

ByteStreamSource#

type ByteStreamSource = Readable | ReadableStream<Uint8Array>

Une source d’octets : flux Node, ou flux web (fetch().body).

Cookies#

type Cookies = Record<string, Cookie>

DomainPattern#

type DomainPattern = string | RegExp

Un pattern de domaine : string (exact ou *-wildcard) ou RegExp (libre).

HTTPMethod#

type HTTPMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE" | "PATCH" | "WEBSOCKET"

ITrustedHostsConfig#

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#

type WebSocketState = "handshake" | "connected" | "closed" | "error" | "message" | null

WsBackpressurePolicy#

type WsBackpressurePolicy = BackpressurePolicy

Politique appliquée quand le buffer d’envoi d’un client dépasse le seuil.

WsSendDecision#

type WsSendDecision = BackpressureVerdict

Décision pour une frame : l’émettre, la sauter, ou (socket fermée) ne rien faire.

contextRequest#

type contextRequest = HttpRequest | Http2Request | http.IncomingMessage | null

contextResponse#

type contextResponse = HttpResponse | Http2Response | WebsocketResponse | null

← Toutes les références d’API