yinzerflow 0.7.0 → 0.8.0

package/index.d.ts

@@ -1456,6 +1456,156 @@ export interface Context<T extends HandlerCallbackGenerics = HandlerCallbackGene
  * @see {@link HandlerCallbackGenerics} for custom typing options
  */
 export type HandlerCallback<T extends HandlerCallbackGenerics = HandlerCallbackGenerics> = (ctx: Context<T>, error?: unknown) => Promise<T["response"] | void> | T["response"] | void;
+/**
+ * User-facing WebSocket types for YinzerFlow.
+ *
+ * These types define the public API surface for WebSocket support:
+ * route handlers, the per-connection `ws` object, upgrade requests,
+ * route options, and backpressure configuration.
+ */
+// ============================================
+// WebSocket Connection Object
+// ============================================
+/**
+ * A live WebSocket connection exposed to route handlers.
+ *
+ * @template T - Shape of per-socket data attached during upgrade
+ *
+ * @example
+ * ```typescript
+ * app.ws<{ userId: string }>('/feed', {
+ *   message(ws, data) {
+ *     ws.send(`Echo: ${data}`);
+ *     ws.publish('updates', data as string);
+ *     console.log(ws.data.userId, ws.readyState);
+ *   }
+ * });
+ * ```
+ */
+interface WebSocket$1<T = unknown> {
+	/** Send a text or binary message to this client. */
+	send: (data: Buffer | string) => void;
+	/** Write a pre-encoded WebSocket frame directly (used internally by pub/sub broadcast). */
+	sendRaw: (encodedFrame: Buffer) => void;
+	/** Initiate a graceful close handshake. */
+	close: (code?: number, reason?: string) => void;
+	/** Send a ping frame (payload must be ≤125 bytes per RFC 6455 §5.5). */
+	ping: (data?: Buffer) => void;
+	/** Subscribe this connection to a named channel for pub/sub. */
+	subscribe: (channel: string) => void;
+	/** Unsubscribe this connection from a named channel. */
+	unsubscribe: (channel: string) => void;
+	/** Publish a message to all subscribers of a channel (excluding this connection). Returns recipient count. */
+	publish: (channel: string, data: Buffer | string) => number;
+	/** Check if this connection is subscribed to a channel. */
+	isSubscribed: (channel: string) => boolean;
+	/** Per-socket data attached during the upgrade handler. */
+	readonly data: T;
+	/** Current connection state (use wsReadyState constants for comparison). */
+	readonly readyState: number;
+	/** Remote IP address of the connected client. */
+	readonly remoteAddress: string;
+	/** Number of bytes queued in the socket's write buffer. */
+	readonly bufferedAmount: number;
+}
+// ============================================
+// Upgrade Request
+// ============================================
+/**
+ * Parsed HTTP upgrade request passed to the `upgrade` handler.
+ * Contains everything needed to decide whether to accept the connection
+ * and what per-socket data to attach.
+ */
+export interface WebSocketUpgradeRequest {
+	/** HTTP headers from the upgrade request (lowercased keys). */
+	headers: Record<string, string>;
+	/** URL path of the upgrade request. */
+	path: string;
+	/** Parsed query string parameters. */
+	query: Record<string, string>;
+	/** Route parameters extracted from parameterized paths (e.g., `/ws/:room` → `{ room: 'lobby' }`). */
+	params: Record<string, string>;
+	/** Remote IP address of the client. */
+	remoteAddress: string;
+}
+// ============================================
+// Route Handlers
+// ============================================
+/**
+ * Handler functions for a WebSocket route.
+ *
+ * @template T - Shape of per-socket data returned from `upgrade`
+ *
+ * @example
+ * ```typescript
+ * app.ws<{ username: string }>('/chat', {
+ *   upgrade(req) {
+ *     const user = validateToken(req.headers.authorization);
+ *     return user ? { username: user.name } : false;
+ *   },
+ *   open(ws) {
+ *     ws.subscribe('chat');
+ *   },
+ *   message(ws, data, isBinary) {
+ *     ws.publish('chat', data as string);
+ *   },
+ *   close(ws, code, reason) {
+ *     // cleanup — unsubscribe is automatic
+ *   }
+ * });
+ * ```
+ */
+export interface WebSocketHandlers<T = unknown> {
+	/**
+	 * Called before the handshake completes. Return per-socket data to accept,
+	 * or `false` to reject the connection with a 403 response.
+	 * If omitted, the connection is accepted with `undefined` as data.
+	 */
+	upgrade?: (request: WebSocketUpgradeRequest) => Promise<T | false> | T | false;
+	/** Called when the connection is established and ready. */
+	open?: (ws: WebSocket$1<T>) => void;
+	/** Called when a complete message (text or binary) is received. */
+	message?: (ws: WebSocket$1<T>, data: Buffer | string, isBinary: boolean) => void;
+	/** Called when the connection is closed (after close handshake or on error). */
+	close?: (ws: WebSocket$1<T>, code: number, reason: string) => void;
+	/** Called when a socket error occurs. */
+	error?: (ws: WebSocket$1<T>, error: Error) => void;
+	/** Called when a backpressured socket's write buffer drains. */
+	drain?: (ws: WebSocket$1<T>) => void;
+}
+// ============================================
+// Route Options
+// ============================================
+/**
+ * Per-route WebSocket options that override global websocket configuration.
+ */
+export interface WebSocketRouteOptions {
+	/** Maximum incoming message payload in bytes (default: global `websocket.maxPayloadLength`). */
+	maxPayloadLength?: number;
+	/** Seconds of inactivity before closing the connection (default: global `websocket.idleTimeout`). 0 = no timeout. */
+	idleTimeout?: number;
+	/** Backpressure handling for this route. */
+	backpressure?: WebSocketBackpressureOptions;
+}
+/**
+ * Backpressure configuration for WebSocket connections.
+ */
+export interface WebSocketBackpressureOptions {
+	/**
+	 * Strategy when the client can't keep up with outgoing data:
+	 * - `'buffer'`: Queue messages up to `limit` bytes, then close the connection (safe default)
+	 * - `'drop'`: Silently discard messages (ideal for real-time data like trading quotes)
+	 * @default 'buffer'
+	 */
+	strategy: "buffer" | "drop";
+	/** Maximum buffered bytes before the connection is closed (only applies to 'buffer' strategy). @default 1048576 (1MB) */
+	limit?: number;
+}
+/**
+ * WebSocket message hook handler signature.
+ * Used for `wsBeforeMessage` and `wsAfterMessage` global hooks.
+ */
+export type WebSocketMessageHook = (ws: WebSocket$1, data: Buffer | string, isBinary: boolean) => Promise<void> | void;
 export type InternalGlobalHookOptions = {
 	routesToExclude: Array<string>;
 } & {
@@ -1474,11 +1624,19 @@ export interface InternalHookRegistryImpl {
 		handler: HandlerCallback;
 		options?: InternalGlobalHookOptions;
 	}>;
+	readonly _wsBeforeMessage: Set<{
+		handler: WebSocketMessageHook;
+	}>;
+	readonly _wsAfterMessage: Set<{
+		handler: WebSocketMessageHook;
+	}>;
 	_onError: HandlerCallback;
 	_onNotFound: HandlerCallback;
 	_addBeforeRoutingHooks: (handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions) => void;
 	_addBeforeHooks: (handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions) => void;
 	_addAfterHooks: (handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions) => void;
+	_addWsBeforeMessageHooks: (handlers: Array<WebSocketMessageHook>) => void;
+	_addWsAfterMessageHooks: (handlers: Array<WebSocketMessageHook>) => void;
 	_addOnError: (handler: HandlerCallback) => void;
 	_addOnNotFound: (handler: HandlerCallback) => void;
 	setLogger: (logger: {
@@ -2449,6 +2607,31 @@ export interface InternalServerOptions {
 	 * @default true
 	 */
 	gracefulShutdownTimeout: TimeString | number;
+	/**
+	 * WebSocket configuration — controls max payload, idle timeout, connection limits, and backpressure.
+	 * Only takes effect when `app.ws()` routes are registered (zero overhead otherwise).
+	 */
+	websocket: InternalWebSocketOptions;
+}
+/**
+ * Internal WebSocket Configuration
+ */
+export interface InternalWebSocketOptions {
+	/** Maximum incoming message payload in bytes. @default 16777216 (16MB) */
+	maxPayloadLength: number;
+	/** Seconds of inactivity before closing. 0 = no timeout. @default 120 */
+	idleTimeout: number;
+	/** Maximum concurrent WebSocket connections per IP. @default 50 */
+	maxConnectionsPerIp: number;
+	/** Allowed origins for upgrade requests. Empty = allow all. @default [] */
+	allowedOrigins: Array<string>;
+	/** Backpressure handling when clients can't keep up. */
+	backpressure: {
+		/** 'buffer' (queue up to limit, safe default) or 'drop' (discard, for real-time data). @default 'buffer' */
+		strategy: "buffer" | "drop";
+		/** Max queued bytes before closing connection (buffer strategy only). @default 1048576 (1MB) */
+		limit: number;
+	};
 }
 /**
  * Internal Logging Configuration
@@ -2866,6 +3049,19 @@ export interface Setup extends HttpMethodHandlers {
 	 * @see {@link HandlerCallback} for not-found handler function signature
 	 */
 	onNotFound: (handler: HandlerCallback) => void;
+	/**
+	 * Register a WebSocket route.
+	 *
+	 * @template T - Per-socket data shape returned from the upgrade handler
+	 * @param path - URL path for WebSocket connections (e.g., '/ws', '/chat/:room')
+	 * @param handlers - Lifecycle handlers (upgrade, open, message, close, error, drain)
+	 * @param options - Per-route options that override global websocket config
+	 */
+	ws: <T = unknown>(path: string, handlers: WebSocketHandlers<T>, options?: WebSocketRouteOptions) => void;
+	/** Register global hooks that run before each WebSocket message handler. */
+	wsBeforeMessage: (handlers: Array<WebSocketMessageHook>) => void;
+	/** Register global hooks that run after each WebSocket message handler. */
+	wsAfterMessage: (handlers: Array<WebSocketMessageHook>) => void;
 }
 export type InternalSetupMethod = (path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions) => void;
 export interface InternalSetupImpl extends Setup {
@@ -2894,6 +3090,12 @@ declare class HookRegistryImpl implements InternalHookRegistryImpl {
 		handler: HandlerCallback;
 		options?: InternalGlobalHookOptions;
 	}>;
+	readonly _wsBeforeMessage: Set<{
+		handler: WebSocketMessageHook;
+	}>;
+	readonly _wsAfterMessage: Set<{
+		handler: WebSocketMessageHook;
+	}>;
 	_onError: HandlerCallback;
 	_onNotFound: HandlerCallback;
 	private _logger;
@@ -2906,6 +3108,8 @@ declare class HookRegistryImpl implements InternalHookRegistryImpl {
 	_addBeforeRoutingHooks(handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions): void;
 	_addBeforeHooks(handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions): void;
 	_addAfterHooks(handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions): void;
+	_addWsBeforeMessageHooks(handlers: Array<WebSocketMessageHook>): void;
+	_addWsAfterMessageHooks(handlers: Array<WebSocketMessageHook>): void;
 	private _validateHandlersArray;
 	_addOnError(handler: HandlerCallback): void;
 	_addOnNotFound(handler: HandlerCallback): void;
@@ -3095,10 +3299,23 @@ declare const log: {
 		personality: boolean;
 	};
 };
+export interface WsRouteMatch {
+	handlers: WebSocketHandlers;
+	options: WebSocketRouteOptions | undefined;
+	params: Record<string, string>;
+}
+declare class WebSocketRouter {
+	private readonly _exactRoutes;
+	private readonly _parameterizedRoutes;
+	_register(path: string, handlers: WebSocketHandlers, options?: WebSocketRouteOptions): void;
+	_match(path: string): WsRouteMatch | undefined;
+	_hasRoutes(): boolean;
+}
 declare class SetupImpl implements InternalSetupImpl {
 	readonly _configuration: InternalServerOptions;
 	readonly _routeRegistry: RouteRegistryImpl;
 	readonly _hooks: HookRegistryImpl;
+	readonly _wsRouter: WebSocketRouter;
 	_log: typeof log;
 	constructor(customConfiguration?: ServerOptions);
 	get(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
@@ -3114,6 +3331,9 @@ declare class SetupImpl implements InternalSetupImpl {
 	afterAll(handlers: Array<HandlerCallback<any>>, options?: InternalGlobalHookOptions): void;
 	onError(handler: HandlerCallback<any>): void;
 	onNotFound(handler: HandlerCallback<any>): void;
+	ws<T = unknown>(path: string, handlers: WebSocketHandlers<T>, options?: WebSocketRouteOptions): void;
+	wsBeforeMessage(handlers: Array<WebSocketMessageHook>): void;
+	wsAfterMessage(handlers: Array<WebSocketMessageHook>): void;
 }
 export declare class YinzerFlow extends SetupImpl {
 	private _isListening;
@@ -3123,6 +3343,9 @@ export declare class YinzerFlow extends SetupImpl {
 	private readonly _maxBufferSize;
 	private _accessLog?;
 	private _accessLogEnabled;
+	private _wsConnections?;
+	private _wsChannelManager?;
+	private _wsSecurity?;
 	constructor(configuration?: ServerOptions);
 	get log(): typeof YinzerFlow._log;
 	private _configureLogging;
@@ -3134,6 +3357,17 @@ export declare class YinzerFlow extends SetupImpl {
 	private _looksLikeHttp;
 	private _parseContentLength;
 	private _handleConnection;
+	private _handleConnectionData;
+	private _handleHeaderPhase;
+	private _handleWebSocketUpgrade;
+	private _handleWebSocketUpgradeAsync;
+	private _setupWsConnection;
+	private _mergeWsConnectionOptions;
+	private _wrapWsHandlers;
+	private _parseHeadersMap;
+	private _sendHttpError;
+	publish(channel: string, data: Buffer | string): number;
+	subscriberCount(channel: string): number;
 	listen(): Promise<void>;
 	close(): Promise<void>;
 	status(): {
@@ -3154,5 +3388,40 @@ export declare const colors: {
 	readonly magenta: "\u001B[95m";
 	readonly gray: "\u001B[90m";
 };
+export declare const wsOpcode: {
+	readonly continuation: 0;
+	readonly text: 1;
+	readonly binary: 2;
+	readonly close: 8;
+	readonly ping: 9;
+	readonly pong: 10;
+};
+export declare const wsCloseCode: {
+	readonly normal: 1000;
+	readonly goingAway: 1001;
+	readonly protocolError: 1002;
+	readonly unsupported: 1003;
+	readonly noStatus: 1005;
+	readonly abnormal: 1006;
+	readonly invalidPayload: 1007;
+	readonly policyViolation: 1008;
+	readonly tooLarge: 1009;
+	readonly missingExtension: 1010;
+	readonly internalError: 1011;
+};
+export declare const wsReadyState: {
+	readonly connecting: 0;
+	readonly open: 1;
+	readonly closing: 2;
+	readonly closed: 3;
+};
+export declare const wsBackpressureStrategy: {
+	readonly buffer: "buffer";
+	readonly drop: "drop";
+};
+
+export {
+	WebSocket$1 as WebSocket,
+};
 
 export {};