raffel 1.0.9 → 1.0.10-next.22f4d4e

package/dist/adapters/index.d.ts

@@ -11,7 +11,7 @@
  * @deprecated Import from 'adapters/inbound' or 'adapters/outbound' for hexagonal clarity.
  */
 export { createWebSocketAdapter } from './websocket.js';
-export type { WebSocketAdapter, WebSocketAdapterOptions } from './websocket.js';
+export type { WebSocketAdapter, WebSocketAdapterOptions, WebSocketClientInfo } from './websocket.js';
 export { createHttpAdapter } from './http.js';
 export type { HttpAdapter, HttpAdapterOptions, HttpMiddleware } from './http.js';
 export { createTcpAdapter, createTcpClient } from './tcp.js';

package/dist/adapters/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AACvD,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAG/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC7C,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAGhF,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC5D,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAG7D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC5D,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAG7D,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACtF,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,YAAY,GACb,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC7C,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAGhG,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC/D,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,cAAc,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAGjJ,OAAO,EAAE,qBAAqB,EAAE,8BAA8B,EAAE,MAAM,8BAA8B,CAAA;AACpG,YAAY,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AACvD,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAGpG,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC7C,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAGhF,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC5D,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAG7D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC5D,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAG7D,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACtF,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,YAAY,GACb,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC7C,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAGhG,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC/D,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,cAAc,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAGjJ,OAAO,EAAE,qBAAqB,EAAE,8BAA8B,EAAE,MAAM,8BAA8B,CAAA;AACpG,YAAY,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAA"}

package/dist/adapters/websocket.d.ts

@@ -8,7 +8,8 @@ import { WebSocket } from 'ws';
 import type { IncomingMessage, Server } from 'node:http';
 import type { Router } from '../core/router.js';
 import type { ContextSeed } from '../types/index.js';
-import { type ChannelOptions, type ChannelManager } from '../channels/index.js';
+import { type ChannelOptions, type ChannelManager, type WebSocketAuthConfig, type BackpressureConfig } from '../channels/index.js';
+import { type ConnectionRecoveryPort } from '../channels/recovery.js';
 import { type WebSocketConnectionFilter } from './utils/connection-filter.js';
 /**
  * WebSocket adapter configuration
@@ -54,6 +55,78 @@ export interface WebSocketAdapterOptions {
     channels?: ChannelOptions;
     /** Inbound connection filter — controls which source IPs/origins may connect */
     filter?: WebSocketConnectionFilter;
+    /** WebSocket authentication (ticket, bearer, or custom) */
+    auth?: WebSocketAuthConfig;
+    /** Backpressure handling for slow consumers */
+    backpressure?: BackpressureConfig;
+    /** Enable per-message compression (default: false) */
+    compression?: boolean | {
+        /** Minimum payload size in bytes to compress (default: 1024) */
+        threshold?: number;
+        /** zlib compression level 1-9 (default: 1) */
+        level?: number;
+    };
+    /** Connection state recovery (requires channels to be enabled) */
+    recovery?: {
+        /** Enable connection recovery (default: false) */
+        enabled: boolean;
+        /** TTL in ms for recovery sessions (default: 120000 = 2 minutes) */
+        ttl?: number;
+        /** Custom recovery store (default: in-memory) */
+        store?: ConnectionRecoveryPort;
+    };
+    /**
+     * Raw message handler — called BEFORE any Raffel processing.
+     * Return `true` to indicate the message was handled (skip default processing).
+     * Return `false` to let Raffel process it normally.
+     *
+     * Use this to implement your own protocol on top of WebSocket,
+     * or to intercept/modify messages before they reach the router.
+     *
+     * @example
+     * ```typescript
+     * onMessage: (socketId, raw, send) => {
+     *   const msg = JSON.parse(raw)
+     *   if (msg.type === 'my-custom-type') {
+     *     send({ type: 'my-response', data: 'handled' })
+     *     return true // Handled, skip Raffel
+     *   }
+     *   return false // Let Raffel handle it
+     * }
+     * ```
+     */
+    onMessage?: (socketId: string, raw: string | Buffer, send: (message: unknown) => void) => boolean | Promise<boolean>;
+    /**
+     * Called when a new client connects (after auth + filter).
+     * Receives the socket ID and a send function for the connection.
+     *
+     * @example
+     * ```typescript
+     * onConnection: (socketId, send, req) => {
+     *   send({ type: 'welcome', socketId })
+     * }
+     * ```
+     */
+    onConnection?: (socketId: string, send: (message: unknown) => void, req: IncomingMessage) => void | Promise<void>;
+    /**
+     * Called when a client disconnects.
+     */
+    onClose?: (socketId: string, code: number, reason: string) => void | Promise<void>;
+}
+/**
+ * Minimal client info exposed by the adapter
+ */
+export interface WebSocketClientInfo {
+    /** Unique socket ID */
+    id: string;
+    /** Remote IP address */
+    remoteAddress?: string;
+    /** Connection metadata (headers) */
+    metadata: Record<string, string>;
+    /** Auth context seed (if authenticated) */
+    authSeed?: ContextSeed;
+    /** When the client connected */
+    connectedAt: number;
 }
 /**
  * WebSocket Adapter
@@ -70,6 +143,32 @@ export interface WebSocketAdapter {
      * Only available when `channels` option is provided.
      */
     readonly channels: ChannelManager | null;
+    /**
+     * Send a raw message to a specific client by socket ID.
+     * Works regardless of channel subscriptions.
+     */
+    send(socketId: string, message: unknown): void;
+    /**
+     * Send raw data (string or Buffer) to a specific client.
+     * Bypasses JSON serialization — use for binary or custom protocols.
+     */
+    sendRaw(socketId: string, data: string | Buffer): void;
+    /**
+     * Broadcast a message to ALL connected clients.
+     */
+    broadcast(message: unknown, except?: string): void;
+    /**
+     * Get info about a specific connected client.
+     */
+    getClient(socketId: string): WebSocketClientInfo | undefined;
+    /**
+     * Get all connected clients.
+     */
+    getClients(): WebSocketClientInfo[];
+    /**
+     * Disconnect a specific client.
+     */
+    disconnect(socketId: string, code?: number, reason?: string): void;
 }
 /**
  * Create a WebSocket adapter

package/dist/adapters/websocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/adapters/websocket.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAmB,SAAS,EAAE,MAAM,IAAI,CAAA;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAExD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAqB,WAAW,EAAE,MAAM,mBAAmB,CAAA;AASvE,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,cAAc,EAIpB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,8BAA8B,CAAA;AAIrC;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B,mDAAmD;IACnD,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,eAAe,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAE5F;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAA;IAEzB,gFAAgF;IAChF,MAAM,CAAC,EAAE,yBAAyB,CAAA;CACnC;AAeD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtB,sBAAsB;IACtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAErB,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAA;CACzC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,uBAAuB,GAC/B,gBAAgB,CA0hBlB"}
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/adapters/websocket.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAmB,SAAS,EAAE,MAAM,IAAI,CAAA;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAExD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAqB,WAAW,EAAE,MAAM,mBAAmB,CAAA;AASvE,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,cAAc,EAOnB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAGL,KAAK,sBAAsB,EAE5B,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,8BAA8B,CAAA;AAIrC;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B,mDAAmD;IACnD,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,eAAe,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAE5F;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAA;IAEzB,gFAAgF;IAChF,MAAM,CAAC,EAAE,yBAAyB,CAAA;IAElC,2DAA2D;IAC3D,IAAI,CAAC,EAAE,mBAAmB,CAAA;IAE1B,+CAA+C;IAC/C,YAAY,CAAC,EAAE,kBAAkB,CAAA;IAEjC,sDAAsD;IACtD,WAAW,CAAC,EAAE,OAAO,GAAG;QACtB,gEAAgE;QAChE,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,8CAA8C;QAC9C,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,CAAA;IAED,kEAAkE;IAClE,QAAQ,CAAC,EAAE;QACT,kDAAkD;QAClD,OAAO,EAAE,OAAO,CAAA;QAChB,oEAAoE;QACpE,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,iDAAiD;QACjD,KAAK,CAAC,EAAE,sBAAsB,CAAA;KAC/B,CAAA;IAID;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,CACV,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,KAC7B,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE/B;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,CACb,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,EAChC,GAAG,EAAE,eAAe,KACjB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzB;;OAEG;IACH,OAAO,CAAC,EAAE,CACR,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,KACX,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAmBD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,wBAAwB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,WAAW,CAAA;IACtB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtB,sBAAsB;IACtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAErB,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAA;IAIxC;;;OAGG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAE9C;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IAEtD;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAElD;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAA;IAE5D;;OAEG;IACH,UAAU,IAAI,mBAAmB,EAAE,CAAA;IAEnC;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACnE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,uBAAuB,GAC/B,gBAAgB,CA8+BlB"}