@nodefony/http 10.0.0-alpha.1

package/dist/types/nodefony/config/defineModuleConfig.d.ts

@@ -0,0 +1,39 @@
+import type { IHttpConfig, IHttpConfigInput } from "../interfaces/IHttpConfig.js";
+/**
+ * Sous-ensemble structurel du kernel nécessaire aux défauts dérivés — découple
+ * le builder du type `Kernel`/`IKernel` (testable sans kernel complet). Tous les
+ * champs sont optionnels : un kernel absent ou minimal retombe sur les fallbacks.
+ */
+export interface IKernelConfigDefaults {
+    tmpDir?: {
+        path?: unknown;
+    } | null;
+    domain?: string;
+    projectName?: string;
+    /** Environnement courant — pilote les défauts secure-by-default (ex. `Server:`). */
+    environment?: string;
+}
+/**
+ * Builder type-safe de la configuration de `@nodefony/http`.
+ *
+ * ⭐ TL;DR : MACHINERIE DE BOOT — on n'édite (presque) jamais ce fichier. Même
+ * pattern que `nodefony.config.ts` ↔ `defineConfig()` du core : `config.ts` PORTE
+ * la config (schéma + défauts), `define<X>Config()` la VALIDE au boot (parse +
+ * env + freeze) et publie le JSON Schema Studio.
+ *
+ * Aligné sur `defineRedisConfig` / `defineSecurityConfig` : source unique =
+ * `./config.ts` (Zod) ; le builder VALIDE puis complète les défauts kernel.
+ *
+ * @param config - configuration brute (sections omises = défauts sûrs).
+ * @param kernel - kernel courant, pour les défauts dérivés (tmpDir, domain).
+ * @returns config validée et complétée (NON gelée — les services la mutent).
+ * @throws BootConfigurationError si un champ est invalide ou une clé inconnue —
+ *   `parseModuleConfig` (cœur) porte le message ET le type d'erreur, pour que le
+ *   refus interrompe le boot en développement comme en production.
+ */
+export declare function defineHttpConfig(config?: IHttpConfigInput, kernel?: IKernelConfigDefaults | null): IHttpConfig;
+/**
+ * JSON Schema introspectable de la config HTTP — destiné au formulaire
+ * d'édition Studio (futur) et à la documentation générée.
+ */
+export declare function httpConfigJsonSchema(): unknown;

package/dist/types/nodefony/interfaces/IContext.d.ts

@@ -0,0 +1,138 @@
+import type { URL } from "node:url";
+import type { ICookie } from "./ICookie.js";
+import type { ISession } from "./ISession.js";
+import type { HTTPMethodType } from "./IRequest.js";
+export type ServerType = "http" | "https" | "http2" | "http3" | "websocket" | "websocket-secure";
+export type SchemeType = "http" | "https" | "ws" | "wss";
+export type WebSocketStateType = "handshake" | "connected" | "closed" | "error" | "message" | null;
+export type CookiesMap = Record<string, ICookie>;
+export type PhaseName = "parse" | "resolve" | "firewall" | "initialize" | "action" | "render" | "send" | (string & {});
+export interface PhaseTiming {
+    name: PhaseName;
+    startMs: number;
+    endMs?: number;
+    durationMs?: number;
+}
+/** Issue de la traversée d'une zone firewall. */
+export type SecurityOutcome = 
+/** Identité authentifiée (un authenticator a résolu un token). */
+"granted"
+/** Anonyme EXPLICITE (authenticator `anonymous` listé par la zone). */
+ | "anonymous"
+/** Refus par POLITIQUE (aucune preuve présentée en zone fermée → 401). */
+ | "denied"
+/** Preuve PRÉSENTÉE mais invalide (l'acteur a échoué une preuve → 401). */
+ | "failure"
+/** Backoff NIST actif (429). */
+ | "throttled"
+/** Route exemptée (`bypassFirewall`) — la zone est traversée sans auth. */
+ | "bypass";
+/**
+ * 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é.
+ *
+ * Le contrat vit ici (et non dans `@nodefony/security`) parce que
+ * `@nodefony/http` ne peut pas importer le module de sécurité (cycle) : http
+ * porte le champ, security le REMPLIT — exactement le pattern de
+ * `profilerQueries` (buffer porté par http, rempli par les adapters ORM).
+ *
+ * **Dev-only** : alloué par le firewall UNIQUEMENT si `context.profiling` est
+ * vrai (profiler actif → jamais en production). Le chemin nominal de succès
+ * n'émet aucun événement d'audit (le volume n'est pas un signal) : sans cette
+ * trace, une requête qui PASSE ne laisse aucune empreinte de sa zone.
+ */
+export interface ISecurityTrace {
+    /** Authenticator qui a résolu le token — `null` si aucun n'a abouti. */
+    authenticator: string | null;
+    /** Ce qui s'est passé. */
+    outcome: SecurityOutcome;
+    /** Motif du refus (`no_credentials`, `invalid_credentials`…), `null` si succès. */
+    reason: string | null;
+    /**
+     * Identité résolue par le firewall. Le token vit dans l'ALS (pas sur
+     * `context.user`) : sans ce champ, une requête authentifiée s'affiche
+     * « anonyme » alors qu'elle porte des rôles.
+     */
+    user: string | null;
+    /** Rôles portés par le token résolu, `null` hors succès. */
+    roles: string[] | null;
+}
+export type AfterResponseHandler = (ctx: IContext) => void | Promise<void>;
+export interface IContext {
+    requestId: string;
+    readonly cspNonce: string;
+    cspDirectives: Record<string, readonly string[]> | null;
+    csrfProtect: boolean;
+    csrfExempt: boolean;
+    csrfToken: string | null;
+    type: ServerType;
+    scheme: SchemeType;
+    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 | undefined;
+    originUrl: URL | null | undefined;
+    session: ISession | null | undefined;
+    cookieSession: ICookie | null | undefined;
+    cookies: CookiesMap;
+    user: unknown;
+    error: Error | null | undefined;
+    metaData: object;
+    readonly phases: PhaseTiming[];
+    phaseStart(name: PhaseName): void;
+    phaseEnd(name: PhaseName): void;
+    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<ISession | null>;
+    hasSession(): boolean;
+    getCookieSession(name: string): ICookie | null;
+    getSessionCookieName(): string;
+    setMetaData(obj?: Record<string, unknown>): object;
+}
+export interface IHttpContext extends IContext {
+    proxy: object | null;
+    isRedirect: boolean;
+    handle(): Promise<object>;
+    render(chunk: unknown, encoding?: BufferEncoding, status?: string | number, headers?: Record<string, string | number>): Promise<object>;
+    send(chunk?: unknown, encoding?: BufferEncoding): Promise<object>;
+    end(): Promise<object>;
+    redirect(url: string, status?: number | string, headers?: Record<string, string | number>): unknown;
+    getHostName(): string | undefined;
+    getRemoteAddress(): string | null | undefined;
+    getHost(): string | undefined;
+    getUserAgent(): string | undefined;
+}
+export interface IWebsocketContext extends IContext {
+    acceptedProtocol?: string;
+    connection: unknown | null;
+    rejected: boolean;
+    port: number | string;
+    wsUrl: URL | null;
+    queryGet: Record<string, string>;
+    connect(): Promise<unknown>;
+    handle(data?: unknown[]): Promise<object>;
+    close(reasonCode: number, description: string): unknown;
+    send(data?: Buffer | string | null, encoding?: BufferEncoding): Promise<object>;
+    broadcast(data: Buffer | string): void;
+    getRemoteAddress(): string | null | undefined;
+    getHost(): string | undefined;
+    getUserAgent(): string | undefined;
+}

package/dist/types/nodefony/interfaces/ICookie.d.ts

@@ -0,0 +1,47 @@
+export type SameSiteType = "Strict" | "Lax" | "None";
+export type PriorityType = "High" | "Medium" | "Low" | undefined;
+export interface ICookieOptions {
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    expires?: Date | string | number;
+    sameSite?: SameSiteType;
+    httpOnly?: boolean;
+    signed?: boolean;
+    secret?: string;
+    priority?: PriorityType;
+}
+export interface IWsCookie {
+    name: string;
+    value: string;
+    maxage?: number;
+    domain?: string;
+    path?: string;
+    expires?: Date;
+    httponly?: boolean;
+    secure?: boolean;
+}
+export interface ICookie {
+    name: string;
+    value: unknown;
+    options: ICookieOptions;
+    signed?: boolean;
+    originalMaxAge?: number;
+    expires?: Date;
+    maxAge?: number;
+    path?: string;
+    domain?: string | undefined;
+    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 | undefined;
+}

package/dist/types/nodefony/interfaces/IErrorRenderer.d.ts

@@ -0,0 +1,55 @@
+import type { IHttpContext, IWebsocketContext } from "./IContext.js";
+/**
+ * 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).
+ */
+export interface IErrorHttpResult {
+    status: number;
+    message: string;
+    body: unknown;
+    headers?: Record<string, string | number>;
+}
+/**
+ * Aide jointe au corps d'erreur — ce que le développeur doit faire, en clair.
+ *
+ * **Jamais en production**, et ce n'est pas une précaution de confort : une
+ * aide nomme la table et la colonne en cause, c'est-à-dire de la cartographie
+ * de schéma offerte à qui frappe la porte. Le même parti-pris que le message
+ * opaque des pannes 5xx.
+ *
+ * Le champ est ADDITIONNEL, sur le modèle de `fields` en validation : un client
+ * qui l'ignore lit le corps exactement comme avant.
+ */
+export interface IErrorHint {
+    /** Famille d'aide — un seul cas aujourd'hui, la base en retard sur le code. */
+    readonly kind: "schema-mismatch";
+    /** Le fait, en français, sans jargon de pilote. */
+    readonly message: string;
+    /** Les gestes possibles, du plus probable au moins probable. Copiables tels quels. */
+    readonly actions: readonly string[];
+}
+/**
+ * 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).
+ */
+export interface IErrorWebsocketResult {
+    code: number;
+    reason: string;
+}
+/**
+ * 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 }
+ *
+ * Override via `httpKernel.setErrorRenderer(custom)` to customise:
+ *   - hide stack traces in prod
+ *   - emit RFC 7807 problem+json
+ *   - inject auth challenge headers
+ */
+export interface IErrorRenderer {
+    renderHttp(error: Error, context: IHttpContext): IErrorHttpResult;
+    renderWebsocket(error: Error, context: IWebsocketContext): IErrorWebsocketResult;
+}

package/dist/types/nodefony/interfaces/IHttpConfig.d.ts

@@ -0,0 +1,12 @@
+import type { HttpConfig, HttpConfigInput } from "../config/config.js";
+/**
+ * Configuration validée de `@nodefony/http` (sortie du parse Zod + défauts
+ * kernel appliqués par le builder). Source de vérité = `../config/config.ts`.
+ */
+export type IHttpConfig = HttpConfig;
+/**
+ * Configuration brute fournie par l'application (toutes sections optionnelles —
+ * les sections omises reçoivent leurs défauts). Entrée du builder
+ * {@link import("../config/defineModuleConfig").defineHttpConfig}.
+ */
+export type IHttpConfigInput = HttpConfigInput;

package/dist/types/nodefony/interfaces/IHttpKernel.d.ts

@@ -0,0 +1,10 @@
+import type { ServerType } from "./IContext.js";
+export interface IHttpKernel {
+    domain: string;
+    httpPort?: number;
+    httpsPort?: number;
+    handle(request: unknown, response: unknown, type: ServerType): Promise<unknown>;
+    handleFrontController(context: object, checkFirewall?: boolean): Promise<unknown>;
+    onError(error: unknown, context?: object, extraHeaders?: object): Promise<object>;
+    isValidDomain(context: object): boolean;
+}

package/dist/types/nodefony/interfaces/IRequest.d.ts

@@ -0,0 +1,35 @@
+import type { URL } from "node:url";
+import type { ICookie } from "./ICookie.js";
+export type HTTPMethodType = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE" | "PATCH" | "WEBSOCKET";
+export interface IRequest {
+    url: URL | string;
+    method: HTTPMethodType | null | undefined;
+    getMethod(): HTTPMethodType | null | undefined;
+    getHeader(name: string): string | string[] | undefined;
+    getHeaders(): Record<string, string | string[] | undefined>;
+}
+export interface IHttpRequest extends IRequest {
+    url: URL;
+    query: Record<string, unknown>;
+    queryGet: Record<string, unknown>;
+    queryPost: Record<string, unknown>;
+    queryFile: unknown[];
+    remoteAddress: string | null | undefined;
+    acceptHtml: boolean;
+    getRemoteAddress(): string | null | undefined;
+    getHost(): string | undefined;
+    getHostName(): string | undefined;
+    getUserAgent(): string | undefined;
+    getOrigin(): string | undefined;
+    getCookies(): Record<string, ICookie>;
+}
+export interface IHttp2Request extends IHttpRequest {
+    stream: unknown;
+}
+export interface IWsRequest extends IRequest {
+    url: URL;
+    query: Record<string, string>;
+    queryGet: Record<string, string>;
+    path: string;
+    cookies?: Record<string, ICookie>;
+}

package/dist/types/nodefony/interfaces/IRequestLogger.d.ts

@@ -0,0 +1,31 @@
+import type { Severity } from "nodefony";
+import type { IHttpContext, IWebsocketContext } from "./IContext.js";
+/**
+ * Result of rendering a request log entry. Returned by IRequestLogger and
+ * passed verbatim to `context.log(text, severity, msgid)`.
+ */
+export interface IRequestLogEntry {
+    text: string;
+    severity: Severity;
+    msgid: string;
+}
+/**
+ * Unified per-request logger contract — HTTP + WebSocket.
+ *
+ * The default implementation preserves the legacy Nodefony "URL : ... FROM : ...
+ * ORIGIN : ... ID : <uuid>" colored format. Swap via
+ * `httpKernel.setRequestLogger(custom)` to:
+ *   - emit JSON access logs (audit / P3.1)
+ *   - render NCSA Common Log Format
+ *   - pretty-format with one colored line per request (P3.2)
+ */
+export interface IRequestLogger {
+    renderHttp(context: IHttpContext, error?: Error | null): IRequestLogEntry;
+    renderWebsocket(context: IWebsocketContext, error?: Error | null, acceptedProtocol?: string | null): IRequestLogEntry;
+    /**
+     * Optional audit-sampling gate, evaluated by `Context.logRequest()` BEFORE
+     * `renderHttp`. Return `false` to skip the log entirely (no object alloc, no
+     * `JSON.stringify`). Absent ⇒ always log (loggers without sampling).
+     */
+    shouldSample?(context: IHttpContext, error?: Error | null): boolean;
+}

package/dist/types/nodefony/interfaces/IResponse.d.ts

@@ -0,0 +1,39 @@
+import type { ICookie } from "./ICookie.js";
+export interface IResponse {
+    statusCode: number;
+    statusMessage: string;
+    encoding: BufferEncoding;
+    body: Buffer | null;
+    cookies: Record<string, ICookie>;
+    addCookie(cookie: ICookie): ICookie;
+    send(data?: Buffer | string | null, encoding?: BufferEncoding): Promise<unknown>;
+    clean(): void;
+}
+export interface IHttpResponse extends IResponse {
+    headers: Record<string, unknown>;
+    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[] | undefined;
+    setHeaders(headers: Record<string, string | number>): void;
+    setContentType(type: string): void;
+    setBody(data: unknown): void;
+    redirect(url: string, code?: number): Promise<IHttpResponse>;
+    isHtml(): boolean;
+    setTimeout(ms: number): void;
+    deleteCookie(cookie: ICookie): void;
+    setCookie(cookie: ICookie): void;
+}
+export interface IWebsocketResponse extends IResponse {
+    connection: unknown | null;
+    webSocketVersion?: number;
+    setConnection(connection: unknown): unknown;
+    broadcast(data: Buffer | string): void;
+    close(code?: number, message?: string): Promise<void>;
+}