@wooksjs/event-http 0.6.6 → 0.7.1

package/dist/index.d.ts

@@ -1,15 +1,110 @@
 import * as _wooksjs_event_core from '@wooksjs/event-core';
-import { TEventOptions, TEmpty, TCtxHelpers, TGenericContextStore } from '@wooksjs/event-core';
-export { useEventLogger, useRouteParams } from '@wooksjs/event-core';
+import { EventContext, Logger, EventContextOptions } from '@wooksjs/event-core';
+export { EventContext, EventContextOptions, useLogger, useRouteParams } from '@wooksjs/event-core';
 import * as http from 'http';
-import { IncomingMessage, ServerResponse, IncomingHttpHeaders, Server } from 'http';
-import { URLSearchParams } from 'url';
+import { IncomingHttpHeaders, IncomingMessage, ServerResponse, Server } from 'http';
 import { Buffer as Buffer$1 } from 'buffer';
-import { TConsoleBase } from '@prostojs/logger';
+import { URLSearchParams } from 'url';
 import * as wooks from 'wooks';
-import { TWooksHandler, TWooksOptions, WooksAdapterBase, Wooks } from 'wooks';
+import { TWooksHandler, TWooksOptions, WooksAdapterBase, Wooks, WooksUpgradeHandler } from 'wooks';
+import { TConsoleBase } from '@prostojs/logger';
 import { ListenOptions } from 'net';
+import { Duplex } from 'stream';
+
+/**
+ * Provides access to parsed request cookies.
+ * @example
+ * ```ts
+ * const { getCookie, raw } = useCookies()
+ * const sessionId = getCookie('session_id')
+ * ```
+ */
+declare const useCookies: (ctx?: EventContext) => {
+    raw: string | undefined;
+    getCookie: (name: string) => string | null;
+};
+
+/** Short names for common Accept MIME types. */
+type KnownAcceptType = 'json' | 'html' | 'xml' | 'text';
+/** Provides helpers to check the request's Accept header for supported MIME types. */
+declare const useAccept: (ctx?: EventContext) => {
+    accept: string | undefined;
+    has: (type: KnownAcceptType | (string & {})) => boolean;
+};
+
+/** Short names for common Authorization schemes. */
+type KnownAuthType = 'basic' | 'bearer';
+/**
+ * Provides parsed access to the Authorization header (type, credentials, Basic decoding).
+ * @example
+ * ```ts
+ * const { is, credentials, basicCredentials } = useAuthorization()
+ * if (is('bearer')) { const token = credentials() }
+ * ```
+ */
+declare const useAuthorization: (ctx?: EventContext) => {
+    authorization: string | undefined;
+    type: () => string | null;
+    credentials: () => string | null;
+    is: (type: KnownAuthType | (string & {})) => boolean;
+    basicCredentials: () => {
+        username: string;
+        password: string;
+    } | null;
+};
+
+/**
+ * Returns the incoming request headers.
+ * @example
+ * ```ts
+ * const { host, authorization } = useHeaders()
+ * ```
+ */
+declare function useHeaders(ctx?: EventContext): IncomingHttpHeaders;
 
+/** Default safety limits for request body reading (size, ratio, timeout). */
+declare const DEFAULT_LIMITS: {
+    readonly maxCompressed: number;
+    readonly maxInflated: number;
+    readonly maxRatio: 100;
+    readonly readTimeoutMs: 10000;
+};
+/** @internal Exported for test pre-seeding via `ctx.set(rawBodySlot, ...)`. */
+declare const rawBodySlot: _wooksjs_event_core.Cached<Promise<Buffer$1<ArrayBufferLike>>>;
+/**
+ * Provides access to the incoming HTTP request (method, url, headers, body, IP).
+ * @example
+ * ```ts
+ * const { method, url, raw, rawBody, getIp } = useRequest()
+ * const body = await rawBody()
+ * ```
+ */
+declare const useRequest: (ctx?: EventContext) => {
+    raw: http.IncomingMessage;
+    url: string | undefined;
+    method: string | undefined;
+    headers: http.IncomingHttpHeaders;
+    rawBody: () => Promise<Buffer$1<ArrayBufferLike>>;
+    reqId: () => string;
+    getIp: (options?: {
+        trustProxy: boolean;
+    }) => string;
+    getIpList: () => {
+        remoteIp: string;
+        forwarded: string[];
+    };
+    isCompressed: () => boolean;
+    getMaxCompressed: () => number;
+    setMaxCompressed: (limit: number) => void;
+    getReadTimeoutMs: () => number;
+    setReadTimeoutMs: (limit: number) => void;
+    getMaxInflated: () => number;
+    setMaxInflated: (limit: number) => void;
+    getMaxRatio: () => number;
+    setMaxRatio: (limit: number) => void;
+};
+
+/** Maps numeric HTTP status codes to their human-readable descriptions. */
 declare const httpStatusCodes: {
     100: string;
     101: string;
@@ -75,6 +170,7 @@ declare const httpStatusCodes: {
     510: string;
     511: string;
 };
+/** Enum of all standard HTTP status codes (100–511). */
 declare enum EHttpStatusCode {
     Continue = 100,
     SwitchingProtocols = 101,
@@ -140,63 +236,66 @@ declare enum EHttpStatusCode {
     NotExtended = 510,
     NetworkAuthenticationRequired = 511
 }
+/** Union of HTTP 4xx client error status codes. */
 type THttpBadRequestCodes = 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451;
+/** Union of HTTP 5xx server error status codes. */
 type THttpServerErrorCodes = 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511;
+/** Union of all HTTP error status codes (4xx + 5xx). */
 type THttpErrorCodes = THttpBadRequestCodes | THttpServerErrorCodes;
 
+/** Represents an HTTP error with a status code and optional structured body. */
+declare class HttpError<T extends TWooksErrorBody = TWooksErrorBody> extends Error {
+    protected code: THttpErrorCodes;
+    protected _body: string | T;
+    name: string;
+    constructor(code?: THttpErrorCodes, _body?: string | T);
+    get body(): TWooksErrorBodyExt;
+}
+/** Base shape for an HTTP error response body. */
+interface TWooksErrorBody {
+    message: string;
+    statusCode: EHttpStatusCode;
+    error?: string;
+}
+/** Extended error body that always includes the error description string. */
+interface TWooksErrorBodyExt extends TWooksErrorBody {
+    error: string;
+}
+
 type TTimeUnit = 'ms' | 's' | 'm' | 'h' | 'd' | 'w' | 'M' | 'Y';
 type TTimeSingleString = `${number}${TTimeUnit}`;
 type TTimeMultiString = `${TTimeSingleString}${TTimeSingleString | ''}${TTimeSingleString | ''}${TTimeSingleString | ''}`;
 
-declare class WooksURLSearchParams extends URLSearchParams {
-    toJson<T = unknown>(): T;
-}
-
+/** Raw HTTP event data attached to the event context. */
 interface THttpEventData {
     req: IncomingMessage;
     res: ServerResponse;
     requestLimits?: TRequestLimits;
 }
-interface THttpEvent {
-    type: 'HTTP';
-}
-interface THttpContextStore {
-    searchParams?: TSearchParamsCache;
-    cookies?: Record<string, string | null>;
-    setCookies?: Record<string, TSetCookieData>;
-    accept?: Record<string, boolean>;
-    authorization?: TAuthCache;
-    setHeader?: Record<string, string | string[]>;
-    request?: TRequestCache;
-    response?: {
-        responded: boolean;
-    };
-    status?: {
-        code: EHttpStatusCode;
-    };
-}
+/** Data for a pending outgoing `Set-Cookie` header (name is stored as the key in `HttpResponse._cookies`). */
 interface TSetCookieData {
     value: string;
     attrs: TCookieAttributesInput;
 }
+/** Partial cookie attributes — all fields are optional. */
 type TCookieAttributesInput = Partial<TCookieAttributes>;
+/** Full set of attributes for a `Set-Cookie` header (RFC 6265 §4.1). */
 interface TCookieAttributes {
+    /** Cookie expiration date. */
     expires: Date | string | number;
+    /** Max age in seconds, or a time string (e.g. `'1h'`). */
     maxAge: number | TTimeMultiString;
+    /** Cookie domain. */
     domain: string;
+    /** Cookie path. */
     path: string;
+    /** Secure flag — cookie only sent over HTTPS. */
     secure: boolean;
+    /** HttpOnly flag — cookie not accessible via JavaScript. */
     httpOnly: boolean;
+    /** SameSite policy. */
     sameSite: boolean | 'Lax' | 'None' | 'Strict';
 }
-interface TAuthCache {
-    type: string | null;
-    credentials: string | null;
-    basicCredentials: {
-        username: string;
-        password: string;
-    } | null;
-}
 /** App-level request body limits (all optional, defaults apply when omitted). */
 interface TRequestLimits {
     /** Max compressed body size in bytes (default: 1 MB). */
@@ -210,81 +309,8 @@ interface TRequestLimits {
     /** Internal flag: true when this object is a per-request clone (copy-on-write). */
     perRequest?: boolean;
 }
-interface TRequestCache {
-    rawBody: Promise<Buffer>;
-    parsed: unknown;
-    forwardedIp?: string;
-    remoteIp?: string;
-    ipList?: {
-        remoteIp: string;
-        forwarded: string[];
-    };
-    contentEncodings?: string[];
-    isCompressed?: boolean;
-}
-interface TSearchParamsCache {
-    raw?: string;
-    urlSearchParams?: WooksURLSearchParams;
-}
-
-/**
- * Provides access to parsed request cookies.
- * @example
- * ```ts
- * const { getCookie, rawCookies } = useCookies()
- * const sessionId = getCookie('session_id')
- * ```
- */
-declare function useCookies(): {
-    rawCookies: string | undefined;
-    getCookie: (name: string) => string | null;
-};
-/** Provides methods to set, get, remove, and clear outgoing response cookies. */
-declare function useSetCookies(): {
-    setCookie: (name: string, value: string, attrs?: Partial<TCookieAttributes>) => void;
-    getCookie: <K2 extends string>(key2: K2) => TSetCookieData | undefined;
-    removeCookie: <K2 extends string>(key2: K2) => void;
-    clearCookies: () => void;
-    cookies: () => string[];
-};
-/** Returns a hookable accessor for a single outgoing cookie by name. */
-declare function useSetCookie(name: string): {
-    name: string;
-    type: string;
-} & _wooksjs_event_core.THook<string, "value"> & _wooksjs_event_core.THook<TCookieAttributes, "attrs">;
-/** Hook type returned by {@link useSetCookie}. */
-type TCookieHook = ReturnType<typeof useSetCookie>;
-
-/** Provides helpers to check the request's Accept header for supported MIME types. */
-declare function useAccept(): {
-    accept: string | undefined;
-    accepts: (mime: string) => unknown;
-    acceptsJson: () => unknown;
-    acceptsXml: () => unknown;
-    acceptsText: () => unknown;
-    acceptsHtml: () => unknown;
-};
-
-/**
- * Provides parsed access to the Authorization header (type, credentials, Basic decoding).
- * @example
- * ```ts
- * const { isBearer, authRawCredentials, basicCredentials } = useAuthorization()
- * if (isBearer()) { const token = authRawCredentials() }
- * ```
- */
-declare function useAuthorization(): {
-    authorization: string | undefined;
-    authType: () => string | null;
-    authRawCredentials: () => string | null;
-    isBasic: () => boolean;
-    isBearer: () => boolean;
-    basicCredentials: () => {
-        username: string;
-        password: string;
-    } | null;
-};
 
+/** Cache-Control directive object (RFC 7234 §5.2.2). All fields are optional. */
 interface TCacheControl {
     mustRevalidate?: boolean;
     noCache?: boolean | string;
@@ -293,245 +319,196 @@ interface TCacheControl {
     public?: boolean;
     private?: boolean | string;
     proxyRevalidate?: boolean;
+    /** Max age in seconds, or a time string (e.g. `'3h 30m'`). */
     maxAge?: number | TTimeMultiString;
+    /** Shared cache max age in seconds, or a time string. */
     sMaxage?: number | TTimeMultiString;
 }
+/** Renders a `TCacheControl` object into a `Cache-Control` header string. */
 declare function renderCacheControl(data: TCacheControl): string;
 
-/** Provides helpers to set cache-related response headers (Cache-Control, Expires, Age, Pragma). */
-declare function useSetCacheControl(): {
-    setExpires: (value: Date | string | number) => void;
-    setAge: (value: number | TTimeMultiString) => void;
-    setPragmaNoCache: (value?: boolean) => void;
-    setCacheControl: (data: TCacheControl) => void;
-};
-
-/**
- * Returns the incoming request headers.
- * @example
- * ```ts
- * const { host, authorization } = useHeaders()
- * ```
- */
-declare function useHeaders(): IncomingHttpHeaders;
 /**
- * Provides methods to set, get, and remove outgoing response headers.
+ * Manages response status, headers, cookies, cache control, and body for an HTTP request.
+ *
+ * All header mutations are accumulated in memory and flushed in a single `writeHead()` call
+ * when `send()` is invoked. Setter methods are chainable.
+ *
  * @example
  * ```ts
- * const { setHeader, setContentType, enableCors } = useSetHeaders()
- * setHeader('x-request-id', '123')
+ * const response = useResponse()
+ * response.setStatus(200).setHeader('x-custom', 'value')
+ * response.setCookie('session', 'abc', { httpOnly: true })
  * ```
  */
-declare function useSetHeaders(): {
-    setHeader: (name: string, value: string | number) => void;
-    getHeader: <K2 extends string>(key2: K2) => string | string[] | undefined;
-    removeHeader: <K2 extends string>(key2: K2) => void;
-    setContentType: (value: string) => void;
-    headers: () => Record<string, string | string[]>;
-    enableCors: (origin?: string) => void;
-};
-/** Returns a hookable accessor for a single outgoing response header by name. */
-declare function useSetHeader(name: string): {
-    value: string | string[];
-    isDefined: boolean;
-};
-/** Hook type returned by {@link useSetHeader}. */
-type THeaderHook = ReturnType<typeof useSetHeader>;
+declare class HttpResponse {
+    protected readonly _res: ServerResponse;
+    protected readonly _req: IncomingMessage;
+    protected readonly _logger: Logger;
+    /**
+     * @param _res - The underlying Node.js `ServerResponse`.
+     * @param _req - The underlying Node.js `IncomingMessage`.
+     * @param _logger - Logger instance for error reporting.
+     * @param defaultHeaders - Optional headers to pre-populate on this response (e.g. from `securityHeaders()`).
+     */
+    constructor(_res: ServerResponse, _req: IncomingMessage, _logger: Logger, defaultHeaders?: Record<string, string | string[]>);
+    protected _status: EHttpStatusCode;
+    protected _body: unknown;
+    protected _headers: Record<string, string | string[]>;
+    protected _cookies: Record<string, TSetCookieData>;
+    protected _rawCookies: string[];
+    protected _hasCookies: boolean;
+    protected _responded: boolean;
+    /** The HTTP status code. If not set, it is inferred automatically when `send()` is called. */
+    get status(): EHttpStatusCode;
+    set status(value: EHttpStatusCode);
+    /** Sets the HTTP status code (chainable). */
+    setStatus(value: EHttpStatusCode): this;
+    /** The response body. Automatically serialized by `send()` (objects → JSON, strings → text). */
+    get body(): unknown;
+    set body(value: unknown);
+    /** Sets the response body (chainable). */
+    setBody(value: unknown): this;
+    /** Sets a single response header (chainable). Arrays produce multi-value headers. */
+    setHeader(name: string, value: string | number | string[]): this;
+    /** Batch-sets multiple response headers from a record (chainable). Existing keys are overwritten. */
+    setHeaders(headers: Record<string, string | string[]>): this;
+    /** Returns the value of a response header, or `undefined` if not set. */
+    getHeader(name: string): string | string[] | undefined;
+    /** Removes a response header (chainable). */
+    removeHeader(name: string): this;
+    /** Returns a read-only snapshot of all response headers. */
+    headers(): Readonly<Record<string, string | string[]>>;
+    /** Sets the `Content-Type` response header (chainable). */
+    setContentType(value: string): this;
+    /** Returns the current `Content-Type` header value. */
+    getContentType(): string | string[] | undefined;
+    /** Sets the `Access-Control-Allow-Origin` header (chainable). Defaults to `'*'`. */
+    enableCors(origin?: string): this;
+    /** Sets an outgoing `Set-Cookie` header with optional attributes (chainable). */
+    setCookie(name: string, value: string, attrs?: Partial<TCookieAttributes>): this;
+    /** Returns a previously set cookie's data, or `undefined` if not set. */
+    getCookie(name: string): TSetCookieData | undefined;
+    /** Removes a cookie from the outgoing set list (chainable). */
+    removeCookie(name: string): this;
+    /** Removes all outgoing cookies (chainable). */
+    clearCookies(): this;
+    /** Appends a raw `Set-Cookie` header string (chainable). Use when you need full control over the cookie format. */
+    setCookieRaw(rawValue: string): this;
+    /** Sets the `Cache-Control` header from a directive object (chainable). */
+    setCacheControl(data: TCacheControl): this;
+    /** Sets the `Age` header in seconds (chainable). Accepts a number or time string (e.g. `'2h 15m'`). */
+    setAge(value: number | TTimeMultiString): this;
+    /** Sets the `Expires` header (chainable). Accepts a `Date`, date string, or timestamp. */
+    setExpires(value: Date | string | number): this;
+    /** Sets or clears the `Pragma: no-cache` header (chainable). */
+    setPragmaNoCache(value?: boolean): this;
+    /**
+     * Returns the underlying Node.js `ServerResponse`.
+     * @param passthrough - If `true`, the framework still manages the response lifecycle. If `false` (default), the response is marked as "responded" and the framework will not touch it.
+     */
+    getRawRes(passthrough?: boolean): ServerResponse;
+    /** Whether the response has already been sent (or the underlying stream is no longer writable). */
+    get responded(): boolean;
+    protected renderBody(): string | Uint8Array;
+    protected renderError(data: TWooksErrorBodyExt, _ctx: EventContext): void;
+    /** Renders and sends an HTTP error response. Called automatically by the framework when a handler throws an `HttpError`. */
+    sendError(error: HttpError, ctx: EventContext): void | Promise<void>;
+    /**
+     * Finalizes and sends the response.
+     *
+     * Flushes all accumulated headers (including cookies) in a single `writeHead()` call,
+     * then writes the body. Supports `Readable` streams, `fetch` `Response` objects, and regular values.
+     *
+     * @throws Error if the response was already sent.
+     */
+    send(): void | Promise<void>;
+    private finalizeCookies;
+    private autoStatus;
+    private sendStream;
+    private sendFetchResponse;
+    private sendRegular;
+}
 
-/** Default safety limits for request body reading (size, ratio, timeout). */
-declare const DEFAULT_LIMITS: {
-    readonly maxCompressed: number;
-    readonly maxInflated: number;
-    readonly maxRatio: 100;
-    readonly readTimeoutMs: 10000;
-};
 /**
- * Provides access to the incoming HTTP request (method, url, headers, body, IP).
+ * Returns the HttpResponse instance for the current request.
+ * All response operations (status, headers, cookies, cache control, sending)
+ * are methods on the returned object.
+ *
  * @example
  * ```ts
- * const { method, url, rawBody, getIp } = useRequest()
- * const body = await rawBody()
+ * const response = useResponse()
+ * response.status = 200
+ * response.setHeader('x-custom', 'value')
+ * response.setCookie('session', 'abc', { httpOnly: true })
  * ```
  */
-declare function useRequest(): {
-    rawRequest: http.IncomingMessage;
-    url: string | undefined;
-    method: string | undefined;
-    headers: http.IncomingHttpHeaders;
-    rawBody: () => Promise<Buffer$1<ArrayBufferLike>>;
-    reqId: () => string;
-    getIp: (options?: {
-        trustProxy: boolean;
-    }) => string;
-    getIpList: () => {
-        remoteIp: string;
-        forwarded: string[];
-    };
-    isCompressed: () => boolean;
-    getMaxCompressed: () => number;
-    setMaxCompressed: (limit: number) => void;
-    getReadTimeoutMs: () => number;
-    setReadTimeoutMs: (limit: number) => void;
-    getMaxInflated: () => number;
-    setMaxInflated: (limit: number) => void;
-    getMaxRatio: () => number;
-    setMaxRatio: (limit: number) => void;
-};
+declare function useResponse(ctx?: EventContext): HttpResponse;
 
-interface TUseResponseOptions {
-    passthrough: boolean;
-}
 /**
- * Provides access to the raw HTTP response and status code management.
- * @example
- * ```ts
- * const { status, rawResponse, hasResponded } = useResponse()
- * status(200)
- * ```
+ * Extended `URLSearchParams` with safe JSON conversion.
+ *
+ * Rejects prototype-pollution keys (`__proto__`, `constructor`, `prototype`) and duplicate non-array keys.
+ * Array parameters are detected by a trailing `[]` in the key name (e.g. `tags[]=a&tags[]=b`).
  */
-declare function useResponse(): {
-    rawResponse: (options?: TUseResponseOptions) => http.ServerResponse<http.IncomingMessage>;
-    hasResponded: () => boolean;
-    status: ((code?: EHttpStatusCode) => EHttpStatusCode) & _wooksjs_event_core.THook<EHttpStatusCode, "value">;
-};
-/** Returns a hookable accessor for the response status code. */
-declare function useStatus(): {
-    value: EHttpStatusCode;
-    isDefined: boolean;
-};
-/** Hook type returned by {@link useStatus}. */
-type TStatusHook = ReturnType<typeof useStatus>;
+declare class WooksURLSearchParams extends URLSearchParams {
+    /** Converts query parameters to a plain object. Array params (keys ending with `[]`) become `string[]`. */
+    toJson<T = unknown>(): T;
+}
 
 /**
  * Provides access to URL search (query) parameters from the request.
  * @example
  * ```ts
- * const { urlSearchParams, jsonSearchParams } = useSearchParams()
- * const page = urlSearchParams().get('page')
+ * const { params, toJson } = useUrlParams()
+ * const page = params().get('page')
  * ```
  */
-declare function useSearchParams(): {
-    rawSearchParams: () => string;
-    urlSearchParams: () => WooksURLSearchParams;
-    jsonSearchParams: () => unknown;
+declare const useUrlParams: (ctx?: EventContext) => {
+    raw: () => string;
+    params: () => WooksURLSearchParams;
+    toJson: () => unknown;
 };
 
-declare class BaseHttpResponseRenderer<T = unknown> implements TWooksResponseRenderer<T> {
-    render(response: BaseHttpResponse<T>): string | Uint8Array;
-}
-interface TWooksResponseRenderer<T = unknown> {
-    render: (response: BaseHttpResponse<T>) => string | Uint8Array;
-}
-
-declare class BaseHttpResponse<BodyType = unknown> {
-    protected renderer: BaseHttpResponseRenderer;
-    constructor(renderer?: BaseHttpResponseRenderer);
-    protected _status: EHttpStatusCode;
-    protected _body?: BodyType;
-    protected _headers: Record<string, string | string[]>;
-    get status(): EHttpStatusCode;
-    set status(value: EHttpStatusCode);
-    get body(): BodyType | undefined;
-    set body(value: BodyType | undefined);
-    setStatus(value: EHttpStatusCode): this;
-    setBody(value: BodyType): this;
-    getContentType(): string | string[];
-    setContentType(value: string): this;
-    enableCors(origin?: string): this;
-    setCookie(name: string, value: string, attrs?: Partial<TCookieAttributes>): this;
-    setCacheControl(data: TCacheControl): void;
-    setCookieRaw(rawValue: string): this;
-    header(name: string, value: string): this;
-    setHeader(name: string, value: string): this;
-    getHeader(name: string): string | string[];
-    protected mergeHeaders(): this;
-    protected mergeStatus(renderedBody: string | Uint8Array | boolean): this;
-    protected mergeFetchStatus(fetchStatus: number): void;
-    protected panic(text: string, logger: TConsoleBase): void;
-    respond(): Promise<unknown>;
-}
-
-/** Represents an HTTP error with a status code and optional structured body. */
-declare class HttpError<T extends TWooksErrorBody = TWooksErrorBody> extends Error {
-    protected code: THttpErrorCodes;
-    protected _body: string | T;
-    name: string;
-    constructor(code?: THttpErrorCodes, _body?: string | T);
-    get body(): TWooksErrorBodyExt;
-    protected renderer?: HttpErrorRenderer;
-    attachRenderer(renderer: HttpErrorRenderer): void;
-    getRenderer(): HttpErrorRenderer | undefined;
-}
-/** Base shape for an HTTP error response body. */
-interface TWooksErrorBody {
-    message: string;
-    statusCode: EHttpStatusCode;
-    error?: string;
-}
-/** Extended error body that always includes the error description string. */
-interface TWooksErrorBodyExt extends TWooksErrorBody {
-    error: string;
-}
+/** Creates an async event context for an incoming HTTP request/response pair. */
+declare function createHttpContext(data: THttpEventData, options: EventContextOptions, ResponseClass?: typeof HttpResponse): <R>(fn: () => R) => R;
+/** Returns the current HTTP event context. */
+declare function useHttpContext(ctx?: EventContext): EventContext;
 
-/** Renders HTTP error responses in HTML, JSON, or plain text based on the Accept header. */
-declare class HttpErrorRenderer extends BaseHttpResponseRenderer<TWooksErrorBodyExt> {
-    protected opts?: {
-        version: string;
-        poweredBy: string;
-        link: string;
-        image: string;
-    } | undefined;
-    constructor(opts?: {
-        version: string;
-        poweredBy: string;
-        link: string;
-        image: string;
-    } | undefined);
-    protected icons: {
-        401: string;
-        403: string;
-        404: string;
-        500: string;
-    };
+/**
+ * Default `HttpResponse` subclass used by `createHttpApp`.
+ *
+ * Overrides error rendering to produce content-negotiated responses (JSON, HTML, or plain text)
+ * based on the request's `Accept` header. HTML error pages include SVG icons and framework branding.
+ */
+declare class WooksHttpResponse extends HttpResponse {
+    /** Registers framework metadata (name, version, link, logo) used in HTML error pages. */
     static registerFramework(opts: {
         version: string;
         poweredBy: string;
         link: string;
         image: string;
     }): void;
-    renderHtml(response: BaseHttpResponse<TWooksErrorBodyExt>): string;
-    renderText(response: BaseHttpResponse<TWooksErrorBodyExt>): string;
-    renderJson(response: BaseHttpResponse<TWooksErrorBodyExt>): string;
-    render(response: BaseHttpResponse<TWooksErrorBodyExt>): string;
+    protected renderError(data: TWooksErrorBodyExt, ctx: EventContext): void;
 }
 
-/** Creates an async event context for an incoming HTTP request/response pair. */
-declare function createHttpContext(data: THttpEventData, options: TEventOptions): <T>(cb: (...a: unknown[]) => T) => T;
-/**
- * Wrapper on useEventContext with HTTP event types
- * @returns set of hooks { getCtx, restoreCtx, clearCtx, hookStore, getStore, setStore }
- */
-declare function useHttpContext<T extends TEmpty>(): TCtxHelpers<THttpContextStore & T & TGenericContextStore<THttpEventData>>;
-
-declare function createWooksResponder(renderer?: TWooksResponseRenderer<any>, errorRenderer?: TWooksResponseRenderer<any>): {
-    createResponse: <T = unknown>(data: T) => BaseHttpResponse<T | TWooksErrorBodyExt> | null;
-    respond: (data: unknown) => Promise<unknown> | undefined;
-};
-
 /** Configuration options for the WooksHttp adapter. */
 interface TWooksHttpOptions {
     logger?: TConsoleBase;
-    eventOptions?: TEventOptions;
     onNotFound?: TWooksHandler;
     router?: TWooksOptions['router'];
     /** Default request body limits applied to every request (overridable per-request via `useRequest()`). */
     requestLimits?: Omit<TRequestLimits, 'perRequest'>;
+    /** Custom HttpResponse subclass. Defaults to WooksHttpResponse (HTML/JSON/text error rendering). */
+    responseClass?: typeof WooksHttpResponse;
+    /** Default headers applied to every response. Use `securityHeaders()` for recommended security headers. */
+    defaultHeaders?: Record<string, string | string[]>;
 }
 /** HTTP adapter for Wooks that provides route registration, server lifecycle, and request handling. */
 declare class WooksHttp extends WooksAdapterBase {
     protected opts?: TWooksHttpOptions | undefined;
     protected logger: TConsoleBase;
-    protected _cachedEventOptions: TEventOptions;
+    protected ResponseClass: typeof WooksHttpResponse;
+    protected eventContextOptions: EventContextOptions;
     constructor(opts?: TWooksHttpOptions | undefined, wooks?: Wooks | WooksAdapterBase);
     /** Registers a handler for all HTTP methods on the given path. */
     all<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
@@ -549,6 +526,11 @@ declare class WooksHttp extends WooksAdapterBase {
     head<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
     /** Registers an OPTIONS route handler. */
     options<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
+    /** Registers an UPGRADE route handler for WebSocket upgrade requests. */
+    upgrade<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
+    private wsHandler?;
+    /** Register a WebSocket upgrade handler that implements the WooksUpgradeHandler contract. */
+    ws(handler: WooksUpgradeHandler): void;
     protected server?: Server;
     /**
      * Starts the http(s) server.
@@ -584,11 +566,7 @@ declare class WooksHttp extends WooksAdapterBase {
      * @param server Server
      */
     attachServer(server?: Server): void;
-    protected responder: {
-        createResponse: <T = unknown>(data: T) => BaseHttpResponse<T | TWooksErrorBodyExt> | null;
-        respond: (data: unknown) => Promise<unknown> | undefined;
-    };
-    protected respond(data: unknown): Promise<unknown> | undefined;
+    protected respond(data: unknown, response: HttpResponse, ctx: EventContext): void | Promise<void>;
     /**
      * Returns server callback function
      * that can be passed to any node server:
@@ -602,7 +580,14 @@ declare class WooksHttp extends WooksAdapterBase {
      * ```
      */
     getServerCb(): (req: IncomingMessage, res: ServerResponse) => void;
-    protected processHandlers(handlers: TWooksHandler[]): Promise<unknown>;
+    /**
+     * Returns upgrade callback function for the HTTP server's 'upgrade' event.
+     * Creates an HTTP context, seeds it with upgrade data, and routes as method 'UPGRADE'.
+     */
+    getUpgradeCb(): (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+    protected processUpgradeHandlers(handlers: TWooksHandler[], ctx: EventContext, socket: Duplex): void | Promise<unknown>;
+    protected processHandlers(handlers: TWooksHandler[], ctx: EventContext, response: HttpResponse): void | Promise<unknown>;
+    private processAsyncResult;
 }
 /**
  * Creates a new WooksHttp application instance.
@@ -615,5 +600,76 @@ declare class WooksHttp extends WooksAdapterBase {
  */
 declare function createHttpApp(opts?: TWooksHttpOptions, wooks?: Wooks | WooksAdapterBase): WooksHttp;
 
-export { BaseHttpResponse, BaseHttpResponseRenderer, DEFAULT_LIMITS, EHttpStatusCode, HttpError, HttpErrorRenderer, WooksHttp, WooksURLSearchParams, createHttpApp, createHttpContext, createWooksResponder, httpStatusCodes, renderCacheControl, useAccept, useAuthorization, useCookies, useHeaders, useHttpContext, useRequest, useResponse, useSearchParams, useSetCacheControl, useSetCookie, useSetCookies, useSetHeader, useSetHeaders, useStatus };
-export type { TAuthCache, TCacheControl, TCookieAttributes, TCookieAttributesInput, TCookieHook, THeaderHook, THttpContextStore, THttpEvent, THttpEventData, TRequestCache, TRequestLimits, TSearchParamsCache, TSetCookieData, TStatusHook, TWooksErrorBody, TWooksErrorBodyExt, TWooksHttpOptions, TWooksResponseRenderer };
+/** Event kind definition for HTTP requests. Provides typed context slots for `req`, `response`, and `requestLimits`. */
+declare const httpKind: _wooksjs_event_core.EventKind<{
+    req: _wooksjs_event_core.SlotMarker<IncomingMessage>;
+    response: _wooksjs_event_core.SlotMarker<HttpResponse>;
+    requestLimits: _wooksjs_event_core.SlotMarker<TRequestLimits | undefined>;
+}>;
+
+/**
+ * Configuration for `securityHeaders()`. Each option accepts a `string` (override value),
+ * `false` (disable), or `undefined` (use default). `strictTransportSecurity` has no default (opt-in only).
+ */
+interface SecurityHeadersOptions {
+    /** `Content-Security-Policy` header. Default: `"default-src 'self'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'"`. */
+    contentSecurityPolicy?: string | false;
+    /** `Cross-Origin-Opener-Policy` header. Default: `'same-origin'`. */
+    crossOriginOpenerPolicy?: string | false;
+    /** `Cross-Origin-Resource-Policy` header. Default: `'same-origin'`. */
+    crossOriginResourcePolicy?: string | false;
+    /** `Referrer-Policy` header. Default: `'no-referrer'`. */
+    referrerPolicy?: string | false;
+    /** `Strict-Transport-Security` header. No default (opt-in only — HSTS is dangerous if not on HTTPS). */
+    strictTransportSecurity?: string | false;
+    /** `X-Content-Type-Options` header. Default: `'nosniff'`. */
+    xContentTypeOptions?: string | false;
+    /** `X-Frame-Options` header. Default: `'SAMEORIGIN'`. */
+    xFrameOptions?: string | false;
+}
+/**
+ * Returns a record of recommended HTTP security headers.
+ *
+ * Each option accepts a `string` (override value) or `false` (disable).
+ * Omitting an option uses the default value.
+ *
+ * `strictTransportSecurity` is opt-in only (no default) — HSTS is dangerous if not on HTTPS.
+ */
+declare function securityHeaders(opts?: SecurityHeadersOptions): Record<string, string>;
+
+/** Options for creating a test HTTP event context. */
+interface TTestHttpContext {
+    /** Pre-set route parameters (e.g. `{ id: '42' }`). */
+    params?: Record<string, string | string[]>;
+    /** Request URL (e.g. `/api/users?page=1`). */
+    url: string;
+    /** Request headers. */
+    headers?: Record<string, string>;
+    /** HTTP method (default: `'GET'`). */
+    method?: string;
+    /** Custom request body limits. */
+    requestLimits?: TRequestLimits;
+    /** Pre-seed the raw body for body-parsing tests. */
+    rawBody?: string | Buffer$1;
+    /** Default headers to pre-populate on the response (e.g. from `securityHeaders()`). */
+    defaultHeaders?: Record<string, string | string[]>;
+}
+/**
+ * Creates a fully initialized HTTP event context for testing.
+ *
+ * Sets up an `EventContext` with a fake `IncomingMessage`, `HttpResponse`, route params,
+ * and optional pre-seeded body. Returns a runner function that executes callbacks inside the context scope.
+ *
+ * @example
+ * ```ts
+ * const run = prepareTestHttpContext({ url: '/users/42', params: { id: '42' } })
+ * run(() => {
+ *   const { params } = useRouteParams()
+ *   expect(params.id).toBe('42')
+ * })
+ * ```
+ */
+declare function prepareTestHttpContext(options: TTestHttpContext): <T>(cb: (...a: any[]) => T) => T;
+
+export { DEFAULT_LIMITS, EHttpStatusCode, HttpError, HttpResponse, WooksHttp, WooksHttpResponse, WooksURLSearchParams, createHttpApp, createHttpContext, httpKind, httpStatusCodes, prepareTestHttpContext, rawBodySlot, renderCacheControl, securityHeaders, useAccept, useAuthorization, useCookies, useHeaders, useHttpContext, useRequest, useResponse, useUrlParams };
+export type { KnownAcceptType, KnownAuthType, SecurityHeadersOptions, TCacheControl, TCookieAttributes, TCookieAttributesInput, THttpEventData, TRequestLimits, TSetCookieData, TTestHttpContext, TWooksErrorBody, TWooksErrorBodyExt, TWooksHttpOptions };