raffel 1.0.9 → 1.0.10-next.22f4d4e

package/dist/adapters/websocket.js

@@ -10,7 +10,9 @@ import { mergeContextSeeds } from '../types/index.js';
 import { createAbortableContextAsync } from '../utils/context-utils.js';
 import { createLogger } from '../utils/logger.js';
 import { extractMetadataFromHeaders, mergeMetadata, sanitizeMetadataRecord, } from '../utils/header-metadata.js';
-import { createChannelManager, isChannelMessage, } from '../channels/index.js';
+import { createChannelManager, isChannelMessage, isRecoverMessage, } from '../channels/index.js';
+import { createMemoryRecoveryStore, generateRecoveryToken, } from '../channels/recovery.js';
+import { createMemoryTicketStore } from '../channels/ticket-store.js';
 import { checkWebSocketConnectionFilter, } from './utils/connection-filter.js';
 const logger = createLogger('ws-adapter');
 /**
@@ -25,11 +27,50 @@ export function createWebSocketAdapter(router, options) {
     let wss = null;
     let heartbeatTimer = null;
     const clients = new Map();
+    // Backpressure config
+    const bpMaxBuffered = options.backpressure?.maxBufferedAmount ?? 1024 * 1024;
+    const bpStrategy = options.backpressure?.strategy ?? 'drop';
+    // Compression config
+    const perMessageDeflate = (() => {
+        if (!options.compression)
+            return false;
+        if (options.compression === true) {
+            return { threshold: 1024, zlibDeflateOptions: { level: 1 } };
+        }
+        return {
+            threshold: options.compression.threshold ?? 1024,
+            zlibDeflateOptions: { level: options.compression.level ?? 1 },
+        };
+    })();
+    // Auth config
+    const authConfig = options.auth;
+    // Ensure ticket store exists for ticket mode
+    if (authConfig?.mode === 'ticket' && !authConfig.ticketStore) {
+        authConfig.ticketStore = createMemoryTicketStore();
+    }
+    // Recovery store (only when channels + recovery are enabled)
+    const recoveryStore = options.channels && options.recovery?.enabled
+        ? options.recovery.store ?? createMemoryRecoveryStore({ ttl: options.recovery.ttl })
+        : null;
+    /** Map socketId → recoveryToken (sent to client on connect) */
+    const clientRecoveryTokens = new Map();
     // Create channel manager if channels are enabled
     const channelManager = options.channels
         ? createChannelManager(options.channels, (socketId, message) => {
             const client = clients.get(socketId);
             if (client && client.ws.readyState === WebSocket.OPEN) {
+                // Backpressure check on channel sends
+                if (options.backpressure && client.ws.bufferedAmount > bpMaxBuffered) {
+                    if (bpStrategy === 'disconnect') {
+                        options.backpressure.onSlowConsumer?.(socketId, client.ws.bufferedAmount);
+                        client.ws.close(1008, 'Slow consumer');
+                    }
+                    else {
+                        options.backpressure.onSlowConsumer?.(socketId, client.ws.bufferedAmount);
+                        // Drop silently
+                    }
+                    return;
+                }
                 client.ws.send(JSON.stringify(message));
             }
         })
@@ -50,12 +91,31 @@ export function createWebSocketAdapter(router, options) {
             },
         };
     }
+    /**
+     * Check backpressure before sending
+     */
+    function checkBackpressure(client) {
+        if (!options.backpressure)
+            return true;
+        if (client.ws.bufferedAmount <= bpMaxBuffered)
+            return true;
+        if (bpStrategy === 'disconnect') {
+            options.backpressure.onSlowConsumer?.(client.id, client.ws.bufferedAmount);
+            client.ws.close(1008, 'Slow consumer');
+        }
+        else {
+            options.backpressure.onSlowConsumer?.(client.id, client.ws.bufferedAmount);
+        }
+        return false;
+    }
     /**
      * Send a raw message to client (for channel responses)
      */
     function sendRawMessage(client, message) {
         if (client.ws.readyState !== WebSocket.OPEN)
             return;
+        if (!checkBackpressure(client))
+            return;
         client.ws.send(JSON.stringify(message));
     }
     /**
@@ -68,10 +128,10 @@ export function createWebSocketAdapter(router, options) {
             return false;
         const messageType = parsed.type;
         const metadata = mergeMetadata(client.connectionMetadata, sanitizeMetadataRecord(parsed.metadata));
-        const ctx = await createAbortableContextAsync(sid(), mergeContextSeeds(buildWebSocketSeed(client, metadata, parsed), await options.contextFactory?.(client.ws, client.request)), new AbortController());
+        const ctx = await createAbortableContextAsync(sid(), mergeContextSeeds(mergeContextSeeds(buildWebSocketSeed(client, metadata, parsed), client.authSeed), await options.contextFactory?.(client.ws, client.request)), new AbortController());
         if (messageType === 'subscribe') {
             const msg = parsed;
-            const result = await channelManager.subscribe(client.id, msg.channel, ctx);
+            const result = await channelManager.subscribe(client.id, msg.channel, ctx, msg.since);
             if (result.success) {
                 sendRawMessage(client, {
                     id: msg.id,
@@ -79,6 +139,10 @@ export function createWebSocketAdapter(router, options) {
                     channel: msg.channel,
                     members: result.members,
                 });
+                // Replay history after subscribed response (if since is provided)
+                if (msg.since) {
+                    channelManager.replayHistory(client.id, msg.channel, msg.since.seq, msg.since.epoch);
+                }
             }
             else {
                 sendRawMessage(client, {
@@ -114,7 +178,7 @@ export function createWebSocketAdapter(router, options) {
                 });
                 return true;
             }
-            // Check onPublish hook if provided
+            // Check onPublish hook if provided (ChannelOptions.onPublish — authorization)
             if (options.channels?.onPublish) {
                 const allowed = await options.channels.onPublish(client.id, msg.channel, msg.event, msg.data, ctx);
                 if (!allowed) {
@@ -128,8 +192,75 @@ export function createWebSocketAdapter(router, options) {
                     return true;
                 }
             }
+            // Apply transform if configured
+            let finalData = msg.data;
+            if (options.channels?.transform) {
+                const clientInfo = channelManager.getClient(client.id);
+                const transformed = await options.channels.transform(msg.channel, msg.event, msg.data, { socketId: client.id, userId: clientInfo?.userId });
+                if (transformed === null) {
+                    // Message dropped by transform
+                    return true;
+                }
+                finalData = transformed;
+            }
             // Broadcast to all subscribers except sender
-            channelManager.broadcast(msg.channel, msg.event, msg.data, client.id);
+            channelManager.broadcast(msg.channel, msg.event, finalData, client.id);
+            // Lifecycle hook: onPublish (notification, not authorization)
+            if (options.channels?.hooks?.onPublish) {
+                Promise.resolve(options.channels.hooks.onPublish(client.id, msg.channel, msg.event, finalData)).catch(() => { });
+            }
+            return true;
+        }
+        // ─── Batch Subscribe ─────────────────────────────────────────────────────
+        if (messageType === 'subscribe:batch') {
+            const msg = parsed;
+            const results = {};
+            for (const entry of msg.channels) {
+                const result = await channelManager.subscribe(client.id, entry.channel, ctx, entry.since);
+                results[entry.channel] = result;
+                if (result.success && entry.since) {
+                    channelManager.replayHistory(client.id, entry.channel, entry.since.seq, entry.since.epoch);
+                }
+            }
+            sendRawMessage(client, {
+                id: msg.id,
+                type: 'subscribed:batch',
+                results,
+            });
+            return true;
+        }
+        // ─── Batch Publish ───────────────────────────────────────────────────────
+        if (messageType === 'publish:batch') {
+            const msg = parsed;
+            for (const entry of msg.messages) {
+                if (!channelManager.isSubscribed(client.id, entry.channel))
+                    continue;
+                // Check onPublish hook
+                if (options.channels?.onPublish) {
+                    const allowed = await options.channels.onPublish(client.id, entry.channel, entry.event, entry.data, ctx);
+                    if (!allowed)
+                        continue;
+                }
+                // Apply transform
+                let finalData = entry.data;
+                if (options.channels?.transform) {
+                    const clientInfo = channelManager.getClient(client.id);
+                    const transformed = await options.channels.transform(entry.channel, entry.event, entry.data, { socketId: client.id, userId: clientInfo?.userId });
+                    if (transformed === null)
+                        continue;
+                    finalData = transformed;
+                }
+                channelManager.broadcast(entry.channel, entry.event, finalData, client.id);
+                if (options.channels?.hooks?.onPublish) {
+                    Promise.resolve(options.channels.hooks.onPublish(client.id, entry.channel, entry.event, finalData)).catch(() => { });
+                }
+            }
+            return true;
+        }
+        // ─── Typing Indicators ───────────────────────────────────────────────────
+        if (messageType === 'typing') {
+            const msg = parsed;
+            channelManager.handleTyping(client.id, msg.channel, msg.isTyping);
             return true;
         }
         return false;
@@ -138,6 +269,18 @@ export function createWebSocketAdapter(router, options) {
      * Handle incoming message from client
      */
     async function handleMessage(client, data) {
+        // Custom protocol hook — intercept before any Raffel processing
+        if (options.onMessage) {
+            const sendFn = (msg) => sendRawMessage(client, msg);
+            try {
+                const handled = await options.onMessage(client.id, data, sendFn);
+                if (handled)
+                    return;
+            }
+            catch (err) {
+                logger.error({ err, clientId: client.id }, 'onMessage hook error');
+            }
+        }
         let envelope;
         try {
             // Parse JSON
@@ -146,6 +289,52 @@ export function createWebSocketAdapter(router, options) {
             if (handleCancelMessage(client, parsed)) {
                 return;
             }
+            // Handle auth:refresh
+            if (parsed.type === 'auth:refresh') {
+                await handleAuthRefresh(client, parsed);
+                return;
+            }
+            // Handle recovery message
+            if (recoveryStore && channelManager && isRecoverMessage(parsed)) {
+                const session = recoveryStore.get(parsed.recoveryToken);
+                if (session) {
+                    recoveryStore.delete(parsed.recoveryToken);
+                    // Re-register with previous user info
+                    const existingClient = channelManager.getClient(client.id);
+                    if (!existingClient) {
+                        channelManager.registerClient(client.id, {
+                            userId: session.userId,
+                            data: session.metadata,
+                        });
+                    }
+                    // Recover channel subscriptions
+                    channelManager.recoverClient(session.socketId, client.id, session.channels);
+                    // Re-join groups
+                    for (const groupName of session.groups) {
+                        channelManager.joinGroup(groupName, client.id);
+                    }
+                    // Generate new recovery token for this session
+                    const newToken = generateRecoveryToken();
+                    clientRecoveryTokens.set(client.id, newToken);
+                    sendRawMessage(client, {
+                        type: 'connection:recovered',
+                        socketId: client.id,
+                        recoveryToken: newToken,
+                        channels: session.channels.map((c) => c.name),
+                        groups: session.groups,
+                    });
+                    logger.info({ clientId: client.id, oldSocketId: session.socketId }, 'Client recovered');
+                }
+                else {
+                    sendRawMessage(client, {
+                        type: 'error',
+                        code: 'RECOVERY_FAILED',
+                        status: 404,
+                        message: 'Recovery token not found or expired',
+                    });
+                }
+                return;
+            }
             // Check if this is a channel message
             if (await handleChannelMessage(client, parsed)) {
                 return;
@@ -159,8 +348,8 @@ export function createWebSocketAdapter(router, options) {
             const messageId = parsed.id !== undefined ? String(parsed.id) : sid();
             const requestId = incomingMetadata['x-request-id'] ?? messageId;
             const abortController = new AbortController();
-            // Build context
-            const ctx = await createAbortableContextAsync(requestId, mergeContextSeeds(buildWebSocketSeed(client, incomingMetadata, parsed.payload ?? {}), await options.contextFactory?.(client.ws, client.request)), abortController);
+            // Build context (merge: ws seed → auth seed → contextFactory)
+            const ctx = await createAbortableContextAsync(requestId, mergeContextSeeds(mergeContextSeeds(buildWebSocketSeed(client, incomingMetadata, parsed.payload ?? {}), client.authSeed), await options.contextFactory?.(client.ws, client.request)), abortController);
             const deadline = incomingMetadata['x-deadline']
                 ? Number.parseInt(incomingMetadata['x-deadline'], 10)
                 : NaN;
@@ -232,6 +421,8 @@ export function createWebSocketAdapter(router, options) {
     function sendEnvelope(client, envelope) {
         if (client.ws.readyState !== WebSocket.OPEN)
             return;
+        if (!checkBackpressure(client))
+            return;
         const message = JSON.stringify({
             id: envelope.id,
             procedure: envelope.procedure,
@@ -278,10 +469,96 @@ export function createWebSocketAdapter(router, options) {
         }
         return true;
     }
+    /**
+     * Handle auth:refresh message — update auth context mid-connection
+     */
+    async function handleAuthRefresh(client, parsed) {
+        const token = parsed.token;
+        const msgId = parsed.id;
+        if (!token) {
+            sendRawMessage(client, { id: msgId, type: 'error', code: 'INVALID_TOKEN', status: 400, message: 'Token required' });
+            return;
+        }
+        if (!authConfig?.refreshToken) {
+            sendRawMessage(client, { id: msgId, type: 'error', code: 'NOT_SUPPORTED', status: 501, message: 'Token refresh not configured' });
+            return;
+        }
+        try {
+            const newSeed = await authConfig.refreshToken(token);
+            if (!newSeed) {
+                sendRawMessage(client, { id: msgId, type: 'error', code: 'AUTH_FAILED', status: 401, message: 'Invalid refresh token' });
+                return;
+            }
+            // Update connection metadata with new auth info
+            if (newSeed.input?.metadata) {
+                client.connectionMetadata = { ...client.connectionMetadata, ...newSeed.input.metadata };
+            }
+            logger.info({ clientId: client.id }, 'Auth token refreshed');
+            sendRawMessage(client, { id: msgId, type: 'auth:refreshed' });
+        }
+        catch (err) {
+            logger.error({ err, clientId: client.id }, 'Auth refresh error');
+            sendRawMessage(client, { id: msgId, type: 'error', code: 'AUTH_FAILED', status: 401, message: 'Token refresh failed' });
+        }
+    }
+    /**
+     * Extract auth token from upgrade request
+     */
+    function extractAuthToken(req) {
+        // Custom extractor
+        if (authConfig?.extractToken) {
+            return authConfig.extractToken(req);
+        }
+        // Default: ?ticket=xxx or ?token=xxx from query string
+        const url = new URL(req.url || '/', 'http://localhost');
+        const ticket = url.searchParams.get('ticket');
+        if (ticket)
+            return ticket;
+        const token = url.searchParams.get('token');
+        if (token)
+            return token;
+        // Authorization: Bearer xxx header
+        const authHeader = req.headers['authorization'];
+        if (authHeader?.startsWith('Bearer ')) {
+            return authHeader.slice(7);
+        }
+        return undefined;
+    }
+    /**
+     * Validate connection auth — returns context seed or null (reject)
+     */
+    async function validateConnectionAuth(req) {
+        if (!authConfig)
+            return {}; // No auth configured → allow all
+        const token = extractAuthToken(req);
+        if (!token)
+            return null; // No token → reject
+        if (authConfig.mode === 'ticket') {
+            const store = authConfig.ticketStore;
+            const ticket = await store.consume(token);
+            if (!ticket)
+                return null; // Invalid/expired/used ticket
+            return {
+                auth: {
+                    authenticated: true,
+                    principal: ticket.userId,
+                    principalId: ticket.userId,
+                    claims: ticket.metadata,
+                },
+            };
+        }
+        if (authConfig.mode === 'bearer' || authConfig.mode === 'custom') {
+            if (!authConfig.validateToken)
+                return null;
+            return await authConfig.validateToken(token);
+        }
+        return {};
+    }
     /**
      * Handle new client connection
      */
     function handleConnection(ws, req) {
+        // Connection filter
         if (options.filter) {
             const filter = options.filter;
             const host = req.socket.remoteAddress ?? '';
@@ -293,16 +570,36 @@ export function createWebSocketAdapter(router, options) {
                     ws.close(1008, 'Policy Violation');
                     return;
                 }
-                _doConnect(ws, req);
+                authenticateAndConnect(ws, req);
             }).catch(() => { ws.close(1008, 'Policy Violation'); });
             return;
         }
-        _doConnect(ws, req);
+        authenticateAndConnect(ws, req);
+    }
+    /**
+     * Authenticate and then connect
+     */
+    function authenticateAndConnect(ws, req) {
+        if (!authConfig) {
+            _doConnect(ws, req);
+            return;
+        }
+        validateConnectionAuth(req).then((seed) => {
+            if (!seed) {
+                logger.warn({ remoteAddress: req.socket.remoteAddress }, 'WebSocket auth rejected');
+                ws.close(1008, 'Authentication required');
+                return;
+            }
+            _doConnect(ws, req, seed);
+        }).catch((err) => {
+            logger.error({ err }, 'WebSocket auth error');
+            ws.close(1011, 'Authentication error');
+        });
     }
     /**
-     * Perform the actual client connection setup (after filter passes).
+     * Perform the actual client connection setup (after filter + auth passes).
      */
-    function _doConnect(ws, req) {
+    function _doConnect(ws, req, authSeed) {
         const clientId = sid();
         const client = {
             id: clientId,
@@ -312,12 +609,29 @@ export function createWebSocketAdapter(router, options) {
             connectionMetadata: extractMetadataFromHeaders(req.headers),
             activeStreams: new Map(),
             activeRequests: new Map(),
+            connectedAt: Date.now(),
         };
+        // Store auth seed for context building
+        if (authSeed) {
+            client.authSeed = authSeed;
+        }
         clients.set(clientId, client);
         logger.info({ clientId, remoteAddress: req.socket.remoteAddress }, 'Client connected');
         // Register client in channel manager inventory
         if (channelManager) {
-            channelManager.registerClient(clientId);
+            const userId = authSeed?.auth?.principalId
+                ?? (typeof authSeed?.auth?.principal === 'string' ? authSeed.auth.principal : undefined);
+            channelManager.registerClient(clientId, { userId: userId ?? undefined });
+            // Send recovery token if recovery is enabled
+            if (recoveryStore) {
+                const token = generateRecoveryToken();
+                clientRecoveryTokens.set(clientId, token);
+                sendRawMessage(client, {
+                    type: 'connection:established',
+                    socketId: clientId,
+                    recoveryToken: token,
+                });
+            }
             // Lifecycle hook: onConnect
             if (options.channels?.hooks?.onConnect) {
                 const headers = client.connectionMetadata;
@@ -330,6 +644,13 @@ export function createWebSocketAdapter(router, options) {
                 });
             }
         }
+        // Custom protocol: onConnection hook
+        if (options.onConnection) {
+            const sendFn = (msg) => sendRawMessage(client, msg);
+            Promise.resolve(options.onConnection(clientId, sendFn, req)).catch((err) => {
+                logger.warn({ err, clientId }, 'onConnection hook error');
+            });
+        }
         // Message handler
         ws.on('message', (data) => {
             handleMessage(client, data).catch((err) => {
@@ -344,6 +665,33 @@ export function createWebSocketAdapter(router, options) {
         ws.on('close', (code, reason) => {
             const reasonStr = reason.toString();
             logger.info({ clientId, code, reason: reasonStr }, 'Client disconnected');
+            // Save recovery session before removing client
+            if (recoveryStore && channelManager) {
+                const token = clientRecoveryTokens.get(clientId);
+                if (token) {
+                    const subs = channelManager.getSubscriptions(clientId);
+                    const clientInfo = channelManager.getClient(clientId);
+                    const groups = channelManager.getClientGroups(clientId).map((g) => g.name);
+                    // Build channel list with last seen seq (from channel state)
+                    const channelSeqs = subs.map((name) => {
+                        // We can't access internal channel state from outside, so we use 0
+                        // The channel manager's recoverClient will replay from the stored seq
+                        return { name, lastSeq: 0 };
+                    });
+                    const ttl = options.recovery?.ttl ?? 120_000;
+                    const session = {
+                        recoveryToken: token,
+                        socketId: clientId,
+                        userId: clientInfo?.userId,
+                        channels: channelSeqs,
+                        groups,
+                        metadata: clientInfo?.data ?? {},
+                        expiresAt: Date.now() + ttl,
+                    };
+                    recoveryStore.save(session);
+                    clientRecoveryTokens.delete(clientId);
+                }
+            }
             // Remove client from inventory (also unsubscribes, cleans rooms/groups)
             if (channelManager) {
                 channelManager.removeClient(clientId);
@@ -361,6 +709,12 @@ export function createWebSocketAdapter(router, options) {
             else {
                 // No channel manager — still unsubscribe
             }
+            // Custom protocol: onClose hook
+            if (options.onClose) {
+                Promise.resolve(options.onClose(clientId, code, reasonStr)).catch((err) => {
+                    logger.warn({ err, clientId }, 'onClose hook error');
+                });
+            }
             // Cancel active streams
             for (const controller of client.activeStreams.values()) {
                 controller.abort('Client disconnected');
@@ -396,8 +750,8 @@ export function createWebSocketAdapter(router, options) {
         async start() {
             return new Promise((resolve, reject) => {
                 wss = new WebSocketServer(sharedServer
-                    ? { server: sharedServer, path, maxPayload: maxPayloadSize }
-                    : { port: port, host, path, maxPayload: maxPayloadSize });
+                    ? { server: sharedServer, path, maxPayload: maxPayloadSize, perMessageDeflate }
+                    : { port: port, host, path, maxPayload: maxPayloadSize, perMessageDeflate });
                 wss.on('connection', handleConnection);
                 wss.on('error', (err) => {
                     logger.error({ err }, 'WebSocket server error');
@@ -452,6 +806,66 @@ export function createWebSocketAdapter(router, options) {
         get channels() {
             return channelManager;
         },
+        // ─── Low-Level API ─────────────────────────────────────────────
+        send(socketId, message) {
+            const client = clients.get(socketId);
+            if (!client || client.ws.readyState !== WebSocket.OPEN)
+                return;
+            if (!checkBackpressure(client))
+                return;
+            client.ws.send(JSON.stringify(message));
+        },
+        sendRaw(socketId, data) {
+            const client = clients.get(socketId);
+            if (!client || client.ws.readyState !== WebSocket.OPEN)
+                return;
+            if (!checkBackpressure(client))
+                return;
+            client.ws.send(data);
+        },
+        broadcast(message, except) {
+            const json = JSON.stringify(message);
+            for (const [id, client] of clients) {
+                if (id === except)
+                    continue;
+                if (client.ws.readyState !== WebSocket.OPEN)
+                    continue;
+                if (!checkBackpressure(client))
+                    continue;
+                client.ws.send(json);
+            }
+        },
+        getClient(socketId) {
+            const client = clients.get(socketId);
+            if (!client)
+                return undefined;
+            return {
+                id: client.id,
+                remoteAddress: client.request.socket.remoteAddress,
+                metadata: { ...client.connectionMetadata },
+                authSeed: client.authSeed,
+                connectedAt: client.connectedAt,
+            };
+        },
+        getClients() {
+            const result = [];
+            for (const client of clients.values()) {
+                result.push({
+                    id: client.id,
+                    remoteAddress: client.request.socket.remoteAddress,
+                    metadata: { ...client.connectionMetadata },
+                    authSeed: client.authSeed,
+                    connectedAt: Date.now(),
+                });
+            }
+            return result;
+        },
+        disconnect(socketId, code, reason) {
+            const client = clients.get(socketId);
+            if (!client)
+                return;
+            client.ws.close(code ?? 1000, reason ?? 'Disconnected by server');
+        },
     };
 }
 //# sourceMappingURL=websocket.js.map