---
title: "Référence d'API — @nodefony/http — service"
source: docs/api/http/service.md
url: https://nodefony.github.io/nodefony-core/docs/api/http/service/
---


[Documentation](../../../) › [Référence d'API](../../) › [`@nodefony/http`](../) › service

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

## `@nodefony/http`

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

### Classes (7)

#### `DefaultErrorRenderer`

```ts
class DefaultErrorRenderer implements IErrorRenderer
```

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

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

#### `DefaultRequestLogger`

```ts
class DefaultRequestLogger implements IRequestLogger
```

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

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

#### `HttpKernel`

```ts
class HttpKernel extends Service implements IHttpKernelInterface
```

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

#### `JsonAuditLogger`

```ts
class JsonAuditLogger implements IRequestLogger
```

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

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

#### `PrettyRequestLogger`

```ts
class PrettyRequestLogger implements IRequestLogger
```

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

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

#### `ReverseProxy`

```ts
class ReverseProxy extends Service
```

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

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

#### `SessionsService`

```ts
class SessionsService extends Service
```

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

### Fonctions (2)

#### `schemaMismatchOf`

```ts
function schemaMismatchOf(error: unknown): SchemaMismatchConfidence | null
```

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

#### `toValidationFields`

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

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

### Interfaces (4)

#### `AuditErrorEntry`

```ts
interface AuditErrorEntry
```

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

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

#### `AuditLogEntry`

```ts
interface AuditLogEntry
```

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

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

#### `IValidationField`

```ts
interface IValidationField
```

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

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

#### `JsonAuditLoggerOptions`

```ts
interface JsonAuditLoggerOptions
```

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

### Types (5)

#### `ContextType`

```ts
type ContextType = WebsocketContext | HttpContext | Context
```

#### `ProtocolType`

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

#### `SchemaMismatchConfidence`

```ts
type SchemaMismatchConfidence = "certain" | "probable"
```

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

#### `httpRequest`

```ts
type httpRequest = http.IncomingMessage | http2.Http2ServerRequest
```

#### `httpResponse`

```ts
type httpResponse = http.ServerResponse | http2.Http2ServerResponse
```

---

[← Toutes les références d'API](../../)