--- title: "Référence d'API — @nodefony/http — interfaces" source: docs/api/http/interfaces.md url: https://nodefony.github.io/nodefony-core/docs/api/http/interfaces/ --- [Documentation](../../../) › [Référence d'API](../../) › [`@nodefony/http`](../) › interfaces > 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"` — 56 symboles. ### Interfaces (39) #### `IContext` ```ts interface IContext ``` - `requestId: string` - `readonly cspNonce: string` - `cspDirectives: Record | null` - `csrfProtect: boolean` - `csrfExempt: boolean` - `csrfToken: string | null` - `type: ProtocolName` — Famille traitée : `"http"` ou `"websocket"` (union ouverte). - `scheme: SchemeType` — Schéma vu par le client — seul champ que lit une décision de sécurité. - `alpnProtocol: AlpnProtocol` — Protocole du saut local : `"http/1.1"`, `"h2"`, `"h2c"` (union ouverte). - `serverType: ServerType` — Serveur qui a reçu la requête — choisit la configuration par serveur. - `method: HTTPMethodType | null` - `url: string` - `domain: string` - `request: object | null` - `response: object | null` - `secure: boolean` - `finished: boolean` - `cleaned: boolean` - `webSocketState: WebSocketStateType` - `isJson: boolean` - `isHtml: boolean` - `remoteAddress: string | null` - `originUrl: URL | null` - `session: ISession | null` - `cookieSession: ICookie | null` - `cookies: CookiesMap` - `user: unknown` - `userIdentifier: string | null` — Identifiant de l'appelant authentifié (pare-feu), lisible au démontage. - `error: Error | null` - `metaData: object` - `readonly phases: PhaseTiming[]` - `phaseStart(name: PhaseName): void` - `phaseEnd(name: PhaseName): void` - `stopClock(): number | null` — Arrête l'horloge de la requête (au premier appel) et rend sa durée en ms — la SEULE durée de requête du framework, mesurée partout par défaut ; `null` seulement si `timing.enabled` vaut `false`. - `profiling: boolean` - `securityTrace: ISecurityTrace | null` - `onAfterResponse(fn: AfterResponseHandler): void` - `readonly signal: AbortSignal` - `addRequestCookie(cookie: ICookie): ICookie` - `getRequestCookies(name?: string): CookiesMap | ICookie | null` - `setCookie(cookie: ICookie): void` - `parseCookies(): void` - `getRequest(): object | null` - `getResponse(): object | null` - `isValidDomain(): boolean` - `saveSession(): Promise` - `hasSession(): boolean` - `getCookieSession(name: string): ICookie | null` - `getSessionCookieName(): string` - `setMetaData(obj?: Record): object` #### `ICookie` ```ts interface ICookie ``` - `name: string` - `value: unknown` - `options: ICookieOptions` - `signed?: boolean` - `originalMaxAge?: number` - `expires?: Date` - `maxAge?: number` - `path?: string` - `domain?: string` - `httpOnly?: boolean` - `secure?: boolean` - `sameSite?: SameSiteType` - `priority?: string` - `setValue(value: unknown): unknown` - `toString(): string` - `serialize(): string` - `serializeWebSocket(): IWsCookie` - `clearCookie(): void` - `sign(val: string, secret: string): string` - `unsign(val?: string, secret?: string): string | false` - `getMaxAge(): number` #### `ICookieOptions` ```ts interface ICookieOptions ``` - `maxAge?: number` - `path?: string` - `domain?: string` - `secure?: boolean` - `expires?: Date | string | number` - `sameSite?: SameSiteType` - `httpOnly?: boolean` - `signed?: boolean` - `secret?: string` - `priority?: PriorityType` #### `IErrorHttpResult` ```ts interface IErrorHttpResult ``` Result of rendering an error for an HTTP response. `body` will be passed verbatim to `context.render()` (which JSON-stringifies). `status` and `message` go into ServerResponse.writeHead(). `headers` are optional extra headers (e.g. Allow for 405, WWW-Authenticate for 401). - `status: number` - `message: string` - `body: unknown` - `headers?: Record` #### `IErrorRenderer` ```ts interface IErrorRenderer ``` Unified error rendering contract — HTTP + WebSocket. The default implementation preserves the legacy Nodefony JSON error shape: { code, message, error: HttpError.toJSON(), nodefony: { requestId, scheme, ... }, result } - `renderHttp(error: Error, context: IHttpContext): IErrorHttpResult` - `renderWebsocket(error: Error, context: IWebsocketContext): IErrorWebsocketResult` #### `IErrorWebsocketResult` ```ts interface IErrorWebsocketResult ``` Result of rendering an error for a WebSocket close frame. `code` MUST be a valid WS close code (1000-4999). RFC 6455 §7.4. `reason` is a UTF-8 string sent in the close frame (max 123 bytes). - `code: number` - `reason: string` #### `IFirewallGate` ```ts interface IFirewallGate ``` Ce que le noyau HTTP appelle du pare-feu, service `firewall` du conteneur. - `isSecure(context: ContextType): boolean` — Match rapide de zone : pose `context.security`, `true` si une zone capture. - `handleSecurity(context: ContextType): Promise` — Authentifie la requête d'une zone protégée ; rejette si elle est refusée. - `enforceCsrf(context: ContextType): void` — Refuse une requête qui ne présente pas le jeton CSRF attendu. - `handleCors(context: ContextType): number` — Répond au preflight CORS ; `204` quand la réponse est déjà envoyée. - `applySecurityHeaders(context: ContextType): void` — Pose les en-têtes de sécurité (CSP, HSTS…) de la réponse. - `currentRevalidator?(): (nowMs?: number) => Promise | null` — Le revalidateur de l'identité authentifiée de la requête courante, pour une connexion longue qui la gardera (flux SSE) : la même règle que les sockets WebSocket. #### `IHttp2Request` ```ts interface IHttp2Request extends IHttpRequest ``` - `stream: unknown` #### `IHttpContext` ```ts interface IHttpContext extends IContext ``` - `proxy: object | null` - `isRedirect: boolean` - `handle(): MaybePromise` — Sert la requête — synchrone quand l'action et son rendu le sont. - `render(chunk: unknown, encoding?: BufferEncoding, status?: string | number, headers?: Record): MaybePromise` — Sérialise puis envoie — synchrone quand l'envoi l'est. - `send(chunk?: unknown, encoding?: BufferEncoding): MaybePromise` — Envoie la réponse — synchrone sans session à sauver, sans hook `onSend`, pour une réponse unique. - `end(): Promise` - `redirect(url: string, status?: number | string, headers?: Record): unknown` - `getHostName(): string` - `getRemoteAddress(): string | null` - `getHost(): string` - `getUserAgent(): string` #### `IHttpKernel` ```ts interface IHttpKernel extends IServerKernel ``` - `domain: string` - `httpPort?: number` - `httpsPort?: number` - `handle(request: unknown, response: unknown, type: ServerType): MaybePromise` — Pipeline public d'une requête (appelé par les serveurs HTTP/HTTPS). - `handleFrontController(context: object, checkFirewall?: boolean): Promise` - `onError(error: unknown, context?: object, extraHeaders?: object): Promise` - `isValidDomain(context: object): boolean` #### `IHttpRequest` ```ts interface IHttpRequest extends IRequest ``` - `url: URL` - `query: Record` - `body: RequestBody` - `files: readonly unknown[]` - `remoteAddress: string | null` - `acceptHtml: boolean` - `getRemoteAddress(): string | null` - `getHost(): string` - `getHostName(): string` - `getUserAgent(): string` - `getOrigin(): string` - `getCookies(): Record` #### `IHttpResponse` ```ts interface IHttpResponse extends IResponse ``` - `headers: Record` - `contentType: string` - `setStatusCode(code: number | string, message?: string): { code: number; message: string; }` - `getStatusCode(): number` - `getStatusMessage(): string` - `isHeaderSent(): boolean` - `setHeader(name: string, value: string | number | string[]): void` - `getHeader(name: string): string | number | string[]` - `setHeaders(headers: Record): void` - `setContentType(type: string): void` - `setBody(data: unknown): void` - `redirect(url: string, code?: number): Promise` - `isHtml(): boolean` - `setTimeout(ms: number): void` - `deleteCookie(cookie: ICookie): void` - `setCookie(cookie: ICookie): void` #### `IParsedUploadFile` ```ts interface IParsedUploadFile ``` Forme neutre d'un fichier multipart parsé (temp écrit sur disque), découplée du parser sous-jacent. Remplace l'ex-couplage à `formidable.File` : le moteur de parsing (busboy) n'apparaît plus dans le contrat consommé par `UploadedFile`. Champs alignés sur ce que lit `UploadedFile.create`. - `filepath: string` — Chemin absolu du fichier temporaire écrit sur disque. - `newFilename: string` — Nom de fichier temporaire généré (UUID + extension). - `originalFilename: string | null` — Nom de fichier d'origine déclaré par le client (peut être null). - `mimetype: string | null` — Type MIME déclaré dans la part multipart. - `size: number` — Taille réellement écrite sur disque (octets). - `mtime: Date | null` — Date d'écriture du temporaire. - `hashAlgorithm: false | "sha1" | "md5" | "sha256"` — Algorithme de hash appliqué pendant le stream, ou `false` si aucun. - `hash: string | null` — Hash hexadécimal du contenu si `hashAlgorithm` configuré, sinon null. #### `IProxyMount` ```ts interface IProxyMount extends IProxyMountOptions ``` Un montage tel que le proxy le garde : préfixe normalisé + réglages. - `readonly prefix: string` — Préfixe d'URL normalisé (`/` en tête et en fin). #### `IProxyMountOptions` ```ts interface IProxyMountOptions ``` Réglages d'un montage du proxy inverse (`ReverseProxy.mount`). - `target: ProxyTarget` — Origine de l'amont (cf `ProxyTarget`). - `methods?: readonly string[]` — Méthodes relayées (majuscules). - `websocket?: boolean` — Relaie aussi l'upgrade WebSocket du préfixe. - `stripPrefix?: boolean` — Retire le préfixe avant de transmettre le chemin (`/svc/a` → `/a`). - `preserveHost?: boolean` — Garde l'en-tête `Host` du client au lieu de le réécrire sur la cible. - `stripHeaders?: readonly string[]` — En-têtes de requête à ne pas transmettre (insensible à la casse) — ce dont l'amont n'a pas l'usage ne doit pas lui parvenir (`cookie`, `authorization` vers un serveur de sources, par exemple). - `timeoutMs?: number` — Délai d'inactivité de l'échange avec l'amont, en ms. - `secure?: boolean` — Vérifie le certificat d'une cible `https:`. - `accessLog?: "all" | "errors"` — Ligne d'accès des requêtes relayées : `"all"` (défaut) les écrit toutes, `"errors"` seulement celles en échec (statut ≥ 400). #### `IRequestLogEntry` ```ts interface IRequestLogEntry ``` Result of rendering a request log entry. Returned by IRequestLogger and passed verbatim to `context.log(text, severity, msgid)`. - `text: string` - `severity: Severity` - `msgid: string` #### `IRequestLogger` ```ts interface IRequestLogger ``` Unified per-request logger contract — HTTP + WebSocket. - `renderHttp(context: IHttpContext, error?: Error | null): IRequestLogEntry` - `renderWebsocket(context: IWebsocketContext, error?: Error | null, acceptedProtocol?: string | null): IRequestLogEntry` - `shouldSample?(context: IHttpContext, error?: Error | null): boolean` — Optional audit-sampling gate, evaluated by `Context.logRequest()` BEFORE `renderHttp`. #### `IRequestRouter` ```ts interface IRequestRouter ``` Ce que le pipeline HTTP/WS attend du service `router` — implémenté par `Router` (`@nodefony/framework`). - `resolve(context: ContextType, cleanPathOverride?: string, methodOverride?: string): IRouteResolver` — Résout la route d'un contexte. - `servesWebsocket(pathname: string): boolean` — Dit si au moins une route déclare le transport `WEBSOCKET` pour ce chemin. - `getSingletonController(ctor: new (...args: never[]) => T, create: () => MaybePromise): MaybePromise` — Instance partagée d'un controller `scope: "singleton"`, créée une seule fois. #### `IRequestTrace` ```ts interface IRequestTrace ``` Message publié sur le `TracingChannel` `nodefony.http.request`, le même objet de `start` à `asyncEnd` pour une requête donnée. - `readonly requestId: string` — Identifiant de corrélation de la requête (`X-Request-Id` entrant, sinon généré). - `readonly protocol: RequestTraceProtocol` — `"http"` pour une requête, `"websocket"` pour un handshake. - `readonly method: HTTPMethodType | null` — Méthode de la requête (`"WEBSOCKET"` pour un handshake). - `readonly scheme: SchemeType` — Schéma vu par le client, proxy de confiance compris (`url.scheme` d'OpenTelemetry). - `readonly url: string` — URL complète de la requête, chaîne de requête comprise — l'abonné en tire `url.path` et `url.query`. - `readonly route: string | null` — Nom de la route qui a répondu, `null` sans route (statique, 404). - `readonly routePath: string | null` — Gabarit de la route, préfixe compris (`/users/{id}`) : faible cardinalité, c'est l'attribut `http.route` d'OpenTelemetry. - `readonly module: string | null` — Module qui a signé la réponse — le même que celui de la ligne d'accès. - `readonly statusCode: number | null` — Statut rendu au client : celui de l'amont pour une requête relayée, `101` pour un handshake accepté, le statut du refus sinon. - `readonly durationMs: number | null` — Durée de la requête en millisecondes, construction du contexte → dernier octet remis (fin du handshake en WebSocket). - `readonly error: unknown` — Exception attrapée par le pipeline, `null` sinon. #### `IResolvedRoute` ```ts interface IResolvedRoute ``` Ce que le pipeline HTTP/WS lit d'une route résolue — et rien de plus. - `readonly name: string` — Nom de la route (journalisation, diagnostic). - `readonly path?: string` — Gabarit de la route, préfixe compris (`/users/{id}`) — faible cardinalité, publié comme `routePath` sur le canal `nodefony.http.request`. - `readonly module?: { readonly name: string; }` — Module propriétaire — il signe la ligne d'accès de la requête. - `readonly bodyStream?: boolean` — Corps laissé en flux (`@Body({ stream: true })`) : le parse est sauté. #### `IRouteResolver` ```ts interface IRouteResolver ``` Ce que le pipeline HTTP/WS attend du résolveur d'une requête, posé sur `context.resolver` par le routeur. - `readonly route: IResolvedRoute | null` — Route matchée, `null` tant qu'aucune ne l'est. - `resolve: boolean` — `true` si une route a matché la requête. - `exception?: Error | null` — Erreur levée pendant la résolution, relue par le pipeline. - `readonly controller?: { readonly name: string; } | null` — Classe du controller résolu — seul son nom est lu (erreurs, journal). - `actionName?: string` — Nom de l'action résolue. - `readonly unrendered?: string | null` — Ce que l'action a rendu sans que rien ne soit envoyé (`"null"`, `"undefined"`, `"une instance de Book"`…), `null` sinon. - `match(route: IResolvedRoute, context: ContextType, cleanPath?: string): unknown` — Rejoue le match d'une route sur un contexte (WS : handshake puis frames). - `newController(context?: ContextType): MaybePromise` — Instancie le controller résolu — le pipeline ne fait que le transmettre. - `callController(data?: unknown[], reload?: boolean): MaybePromise` — Exécute l'action résolue, puis rend sa valeur sur le transport. - `authorizeAction(): Promise` — Juge les gardes de l'action résolue (`@IsGranted`, `@RequireScope`, step-up, rôle de la zone) SANS l'exécuter — le pipeline WebSocket l'appelle avant d'accepter le handshake, pour qu'un refus parte en … #### `ISecurityTrace` ```ts interface ISecurityTrace ``` Décision du firewall sur CETTE requête — matière de la « radiographie » (Studio / debug bar) : la zone dit ce qui était POSSIBLE (via `context.security`), cette trace dit ce qui s'est RÉELLEMENT passé. - `authenticator: string | null` — Authenticator qui a résolu le token — `null` si aucun n'a abouti. - `outcome: SecurityOutcome` — Ce qui s'est passé. - `reason: string | null` — Motif du refus (`no_credentials`, `invalid_credentials`…), `null` si succès. - `user: string | null` — Identité résolue par le firewall. - `roles: string[] | null` — Rôles portés par le token résolu, `null` hors succès. #### `ISecurityZone` ```ts interface ISecurityZone ``` Ce que le pipeline HTTP/WS — et le résolveur de framework — lit de la zone de sécurité posée sur `context.security` — et rien de plus. - `readonly name: string` — Nom de la zone (journalisation, profiler). - `readonly security: boolean` — `true` si la zone exige une authentification. - `readonly stateless: boolean` — Zone sans session : aucune session n'est ouverte ni lue. - `readonly mode: "first" | "all"` — Stratégie des authenticators : le premier qui répond, ou tous. - `readonly authenticators: readonly string[]` — Noms des authenticators candidats, dans l'ordre. - `readonly roles: readonly string[] | null` — Rôles exigés par la zone, en OU (un seul suffit) ; `null` = aucune exigence de rôle. #### `ISerializedSession` ```ts interface ISerializedSession ``` Données de session **sérialisées** échangées avec un `ISessionStorage` (blob opaque persisté/restauré). La forme métier riche (ProtoService/bags) est l'affaire de `Session` ; le storage ne manipule que cette projection JSON-safe. - `Attributes: Record` - `metaBag: Record` - `flashBag: Record` - `user: string` - `createdAt?: Date` - `updatedAt?: Date` #### `ISession` ```ts interface ISession ``` - `id: string` - `name: string` - `status: SessionStatusType` - `saved: boolean` - `dirty: boolean` — Vrai si la session a été mutée sans être encore persistée (dirty-tracking). - `readOnly: boolean` — Lecture seule : la session est reprise mais jamais persistée (0 write storage). - `migrated: boolean` - `cookieSession: ICookie | null` - `flashBag: FlashBagType` - `strategy: SessionStrategyType` - `created?: Date` - `updated?: Date` - `user?: string` - `lifetime?: number` - `storage: ISessionStorage` - `start(context: unknown): Promise` - `save(user?: string): Promise` - `invalidate(lifetime?: number, id?: string, options?: ICookieOptions): Promise` - `destroy(cookieDelete?: boolean): Promise` - `create(lifetime: number, id?: string, options?: ICookieOptions): ISession` - `regenerateId(): void` — Régénère un identifiant opaque CSPRNG en conservant l'état (anti session-fixation, appelée au login par `AuthFlow`). - `get(key: string): unknown` - `set(key: string, value: unknown): unknown` - `getAttributes(): unknown` - `getMetaBag(key: string): unknown` - `setMetaBag(key: string, value: unknown): unknown` - `getMetas(): MetaBagType` - `getFlashBag(key: string): unknown` - `setFlashBag(key: string, value: unknown): unknown` - `flashBags(): FlashBagType` - `clearFlashBag(key: string): void` - `clearFlashBags(): void` - `getName(): string` - `checkStatus(): "restart" | boolean` - `serialize(user?: string): ISerializedSession` - `deSerialize(data: ISerializedSession): void` #### `ISessionListFilter` ```ts interface ISessionListFilter ``` Filtre d'énumération admin de `ISessionStorage.listAll`. Tous les champs sont optionnels. Un store SQL peut honorer `user` (WHERE indexable) ; les autres peuvent l'ignorer — `SessionsService.listAllSessions` ré-applique le filtre de façon défensive. `tenantId` = slot multi-tenant (ignoré en mono-tenant). - `user?: string` — Restreint aux sessions d'un utilisateur (pour « déconnecter partout »). - `tenantId?: string | null` — Slot multi-tenant — non scopé aujourd'hui (réserve coût-0). #### `ISessionListQuery` ```ts interface ISessionListQuery extends IPageQuery, ISessionListFilter ``` Requête d'énumération **paginée** des sessions — le `IPageQuery` standard de Nodefony étendu des filtres propres au store de session. C'est la forme que consomme `ISessionStorage.listPage` ; `ISessionListFilter` reste la forme non paginée du dump `ISessionStorage.listAll`. - `authenticated?: boolean` — Restreint aux sessions **authentifiées** (`true` : `user` non vide) ou **anonymes** (`false`). #### `ISessionRecord` ```ts interface ISessionRecord ``` Entrée **brute** d'énumération renvoyée par `ISessionStorage.listAll` : l'id opaque RÉEL + le blob sérialisé. Usage strictement **interne au process** (le service en a besoin pour calculer le `ref` et révoquer par id) — n'est JAMAIS sérialisée vers une réponse HTTP : `SessionsService` la projette en `ISessionSummary` (redaction par construction). - `id: string` — Identifiant opaque réel de la session (interne — jamais exposé via l'API). - `data: ISerializedSession` #### `ISessionStorage` ```ts interface ISessionStorage extends ISortableSource ``` Contrat **unique** d'un backend de stockage de session (File, Redis, SQL/Drizzle…). Source de vérité unifiée — l'ex-doublon `sessionStorageInterface` (any) n'est plus qu'un alias transitionnel. Enregistré dans le registre IoC `SessionsService.registerStorage`. - `read(id: string): Promise` - `write(id: string, data: ISerializedSession): Promise` - `start(id: string): Promise` - `open(): Promise` - `close(): boolean` - `destroy(id: string): Promise` - `gc(idleSeconds?: number, absoluteSeconds?: number): Promise` — Purge les sessions expirées sur les **deux bornes** NIST/OWASP : idle (inactivité depuis `updatedAt`) ET absolute (âge depuis `createdAt`, jamais prolongé). - `touch?(id: string, idleSeconds?: number): Promise` — **Prolonge l'idle timeout** d'une session active (timeout glissant) SANS réécrire son blob — `UPDATE updatedAt` (SQL), `EXPIRE` (Redis TTL), `utimes` (fichier). - `listAll?(filter?: ISessionListFilter): Promise` — Énumère les sessions persistées — capacité d'**ADMINISTRATION** (gouvernance, « déconnecter partout »), **optionnelle**. - `listPage?(query: ISessionListQuery): Promise>` — Énumère **une page** de sessions — la capacité d'administration NORMALE (console, « mes appareils », révocation). - `countSessions?(query?: Partial): Promise` — Compte les sessions correspondant aux filtres, **sans les énumérer** (`COUNT` natif SQL/Mongo). - `countDistinctUsers?(query?: Partial): Promise` — Compte les utilisateurs **distincts** portant au moins une session active. #### `ISessionSummary` ```ts interface ISessionSummary ``` Projection **redactée** d'une session pour l'ADMINISTRATION (data plane Studio, `/nodefony/http/api/sessions`). Construite par allowlist — **jamais** par `delete` après coup — donc ne porte par construction ni `Attributes` ni `flashBag` (données métier potentiellement sensibles), ni l'**id de session brut** (= la valeur du cookie ; le posséder = être connecté). - `ref: string` — Pseudonyme `HMAC(secret, id)` tronqué (préfixe `sess_…`). - `user: string` — Identifiant de l'utilisateur porté par la session (chaîne vide = anonyme). - `authenticated: boolean` — Vrai si la session porte un utilisateur authentifié (`user` non vide). - `ip: string | null` — IP capturée au login (`metaBag.ip`), ou `null` si non capturée / anonyme. - `ua: string | null` — User-Agent capturé au login (`metaBag.ua`), ou `null` si non capturé. - `createdAt: number | null` — Création de la session (epoch ms), ou `null` si inconnue. - `updatedAt: number | null` — Dernière persistance (epoch ms), ou `null` si inconnue. - `tenantId: string | null` — Réserve multi-tenant (toujours `null` en mono-tenant — slot coût-0). - `current: boolean` — Vrai si cette entrée est **la session qui porte la requête en cours** — le « cet appareil » des consoles d'appareils connectés. #### `IUploadOptions` ```ts interface IUploadOptions ``` Options du sous-système d'upload (clé de config `upload`). Mappées sur les `limits` de busboy + la gestion temp/hash propre à Nodefony. - `uploadDir?: string` — Répertoire de dépôt des fichiers temporaires. - `maxFileSize?: number` — Taille max d'UN fichier (octets) — `limits.fileSize` busboy. - `maxTotalFileSize?: number` — Taille max CUMULÉE des fichiers d'une requête (octets) — appliquée par Nodefony. - `maxFiles?: number` — Nombre max de fichiers — `limits.files` busboy. - `maxFields?: number` — Nombre max de champs texte — `limits.fields` busboy. - `maxFieldsSize?: number` — Taille max d'un champ texte (octets) — `limits.fieldSize` busboy. - `hashAlgorithm?: false | "sha1" | "md5" | "sha256"` — Hash calculé pendant le stream (défaut `false` = aucun). - `encoding?: string` — Encodage par défaut des parts texte. #### `IUploadService` ```ts interface IUploadService ``` - `path?: unknown` - `createUploadFile(file: unknown, name: string): Promise` — Construit un `UploadedFile` en async (stat non bloquant). #### `IUploadedFile` ```ts interface IUploadedFile ``` - `filename: string` - `size: number` - `prettySize: string` - `mimeType: string | null` - `hash: string | null` - `hashAlgorithm: false | "sha1" | "md5" | "sha256"` - `lastModifiedDate: Date | null` - `move(target: string): IUploadedFile` - `moveAsync(target: string): Promise` — Variante non bloquante de `move()` (recommandée dans le pipeline). - `getMimeType(): string | null` - `getSize(): number` - `getPrettySize(): string` #### `IWebsocketConnectionState` ```ts interface IWebsocketConnectionState ``` Ce qu'un module attache à une connexion WebSocket pour toute sa durée — interface VIDE par construction, qu'un module AUGMENTE par fusion de déclarations. #### `IWebsocketContext` ```ts interface IWebsocketContext extends IContext, IWebsocketConnectionState ``` - `acceptedProtocol?: string` - `connection: unknown` - `rejected: boolean` - `port: number | string` - `wsUrl: URL | null` - `query: Record` - `connect(): Promise` - `handle(data?: unknown[]): Promise` - `close(reasonCode: number, description: string): unknown` - `send(data?: Buffer | string | null, encoding?: BufferEncoding): Promise` - `broadcast(data: Buffer | string): void` - `getRemoteAddress(): string | null` - `getHost(): string` - `getUserAgent(): string` #### `IWebsocketResponse` ```ts interface IWebsocketResponse extends IResponse ``` - `connection: unknown` - `webSocketVersion?: number` - `setConnection(connection: unknown): unknown` - `broadcast(data: Buffer | string): void` - `close(code?: number, message?: string): Promise` #### `IWsCookie` ```ts interface IWsCookie ``` - `name: string` - `value: string` - `maxage?: number` - `domain?: string` - `path?: string` - `expires?: Date` - `httponly?: boolean` - `secure?: boolean` #### `IWsRequest` ```ts interface IWsRequest extends IRequest ``` - `url: URL` - `query: Record` - `path: string` - `cookies?: Record` #### `SessionIntent` ```ts interface SessionIntent ``` Intent d'activation de session déclaré par une route (décorateur `@UseSession` de `@nodefony/framework`, ou présence d'un paramètre `@Session`). Lu au point d'activation **unique** du pipeline (HTTP comme WS) : c'est lui — et non plus un `sessionAutoStart` global « démarre partout » — qui décide d'ouvrir une session. - `readOnly?: boolean` ### Types (17) #### `AlpnProtocol` ```ts type AlpnProtocol = "http/1.1" | "h2" | "h2c" ``` Protocole du saut qui atteint CE processus, nommé par le registre IANA des identifiants ALPN — la valeur même que Node expose (`TLSSocket.alpnProtocol`, `Http2Session.alpnProtocol`, qui vaut `"h2c"` sur une session en clair). #### `CookiesMap` ```ts type CookiesMap = Record ``` #### `FlashBagType` ```ts type FlashBagType = Record ``` #### `HTTPMethodType` ```ts type HTTPMethodType = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE" | "PATCH" | "WEBSOCKET" ``` #### `MetaBagType` ```ts type MetaBagType = Record ``` #### `PriorityType` ```ts type PriorityType = "High" | "Medium" | "Low" ``` #### `ProtocolName` ```ts type ProtocolName = "http" | "websocket" ``` Famille du protocole que le contrôleur traite, nommée comme l'attribut OpenTelemetry `network.protocol.name`. #### `ProxyTarget` ```ts type ProxyTarget = string | () => string ``` Origine d'un amont relayé : `scheme://hôte[:port]`, sans chemin. #### `RequestBody` ```ts type RequestBody = Record | string | Uint8Array ``` Le corps DÉCODÉ d'une requête : un objet (JSON, formulaire, champs multipart, XML), une chaîne (`text/*`), ou des octets (`Uint8Array` — tout autre type, et un corps sans `Content-Type`). Le même type d'octets que la socket temps réel : un schéma de route valide l'un comme l'autre. #### `RequestTraceProtocol` ```ts type RequestTraceProtocol = "http" | "websocket" ``` Nature de l'opération tracée : une requête HTTP, ou le handshake d'une connexion WebSocket. #### `SameSiteType` ```ts type SameSiteType = "Strict" | "Lax" | "None" ``` #### `SchemeType` ```ts type SchemeType = "http" | "https" | "ws" | "wss" ``` Schéma d'URI vu par le CLIENT (RFC 9110 §4.2, RFC 6455 §3) : derrière un proxy de confiance, c'est le schéma qu'il a annoncé (`Forwarded`), pas celui du saut local. Toute décision de sécurité lit ce champ. #### `SecurityOutcome` ```ts type SecurityOutcome = "granted" | "anonymous" | "denied" | "failure" | "throttled" | "bypass" ``` Issue de la traversée d'une zone firewall. #### `ServerType` ```ts type ServerType = "http" | "https" | "ws" | "wss" ``` Identité du serveur qui a reçu la requête, nommée par le schéma d'URI qu'il sert en LOCAL (RFC 9110 §4.2, RFC 6455 §3) : elle choisit la section de configuration du serveur (`http`, `https`, `websocket`, `websocketSecure`). Ce n'est PAS un protocole — `https` sert HTTP/1.1 et h2 sur le même port ; le protocole du saut se lit dans `AlpnProtocol`. #### `SessionStatusType` ```ts type SessionStatusType = "none" | "active" | "disabled" ``` #### `SessionStrategyType` ```ts type SessionStrategyType = "none" | "migrate" | "invalidate" ``` #### `WebSocketStateType` ```ts type WebSocketStateType = "handshake" | "connected" | "closed" | "error" | "message" | null ``` --- [← Toutes les références d'API](../../)