raffel 0.1.2

package/dist/adapters/websocket.js

@@ -0,0 +1,393 @@
+/**
+ * WebSocket Adapter
+ *
+ * Exposes Raffel services over WebSocket with JSON envelopes.
+ * Supports procedures, streams, events, and Pusher-like channels.
+ */
+import { WebSocketServer, WebSocket } from 'ws';
+import { sid } from '../utils/id/index.js';
+import { createContext } from '../types/context.js';
+import { createLogger } from '../utils/logger.js';
+import { extractMetadataFromHeaders, mergeMetadata, sanitizeMetadataRecord, } from '../utils/header-metadata.js';
+import { createChannelManager, isChannelMessage, } from '../channels/index.js';
+const logger = createLogger('ws-adapter');
+/**
+ * Create a WebSocket adapter
+ */
+export function createWebSocketAdapter(router, options) {
+    const { port, host = '0.0.0.0', path = '/', maxPayloadSize = 1024 * 1024, // 1MB
+    heartbeatInterval = 30000, server: sharedServer, } = options;
+    if (!sharedServer && port === undefined) {
+        throw new Error('WebSocket adapter requires a port when no server is provided');
+    }
+    let wss = null;
+    let heartbeatTimer = null;
+    const clients = 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) {
+                client.ws.send(JSON.stringify(message));
+            }
+        })
+        : null;
+    function createAbortableContext(requestId, overrides, abortController) {
+        const { signal: upstreamSignal, ...rest } = overrides ?? {};
+        if (upstreamSignal) {
+            if (upstreamSignal.aborted) {
+                abortController.abort(upstreamSignal.reason);
+            }
+            else {
+                upstreamSignal.addEventListener('abort', () => {
+                    abortController.abort(upstreamSignal.reason);
+                }, { once: true });
+            }
+        }
+        return createContext(requestId, { ...rest, signal: abortController.signal });
+    }
+    /**
+     * Send a raw message to client (for channel responses)
+     */
+    function sendRawMessage(client, message) {
+        if (client.ws.readyState !== WebSocket.OPEN)
+            return;
+        client.ws.send(JSON.stringify(message));
+    }
+    /**
+     * Handle channel message (subscribe/unsubscribe/publish)
+     */
+    async function handleChannelMessage(client, parsed) {
+        if (!channelManager)
+            return false;
+        if (!isChannelMessage(parsed))
+            return false;
+        const messageType = parsed.type;
+        // Build context for authorization
+        const ctx = createContext(sid(), options.contextFactory?.(client.ws, client.request));
+        if (messageType === 'subscribe') {
+            const msg = parsed;
+            const result = await channelManager.subscribe(client.id, msg.channel, ctx);
+            if (result.success) {
+                sendRawMessage(client, {
+                    id: msg.id,
+                    type: 'subscribed',
+                    channel: msg.channel,
+                    members: result.members,
+                });
+            }
+            else {
+                sendRawMessage(client, {
+                    id: msg.id,
+                    type: 'error',
+                    code: result.error.code,
+                    status: result.error.status,
+                    message: result.error.message,
+                });
+            }
+            return true;
+        }
+        if (messageType === 'unsubscribe') {
+            const msg = parsed;
+            channelManager.unsubscribe(client.id, msg.channel);
+            sendRawMessage(client, {
+                id: msg.id,
+                type: 'unsubscribed',
+                channel: msg.channel,
+            });
+            return true;
+        }
+        if (messageType === 'publish') {
+            const msg = parsed;
+            // Check if user is subscribed to the channel
+            if (!channelManager.isSubscribed(client.id, msg.channel)) {
+                sendRawMessage(client, {
+                    id: msg.id,
+                    type: 'error',
+                    code: 'PERMISSION_DENIED',
+                    status: 403,
+                    message: `Must be subscribed to publish to ${msg.channel}`,
+                });
+                return true;
+            }
+            // Check onPublish hook if provided
+            if (options.channels?.onPublish) {
+                const allowed = await options.channels.onPublish(client.id, msg.channel, msg.event, msg.data, ctx);
+                if (!allowed) {
+                    sendRawMessage(client, {
+                        id: msg.id,
+                        type: 'error',
+                        code: 'PERMISSION_DENIED',
+                        status: 403,
+                        message: `Not allowed to publish to ${msg.channel}`,
+                    });
+                    return true;
+                }
+            }
+            // Broadcast to all subscribers except sender
+            channelManager.broadcast(msg.channel, msg.event, msg.data, client.id);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Handle incoming message from client
+     */
+    async function handleMessage(client, data) {
+        let envelope;
+        try {
+            // Parse JSON
+            const raw = typeof data === 'string' ? data : data.toString('utf-8');
+            const parsed = JSON.parse(raw);
+            if (handleCancelMessage(client, parsed)) {
+                return;
+            }
+            // Check if this is a channel message
+            if (await handleChannelMessage(client, parsed)) {
+                return;
+            }
+            // Validate envelope structure
+            if (!parsed.procedure || !parsed.type) {
+                sendError(client, 'INVALID_ENVELOPE', 'Missing procedure or type', parsed.id);
+                return;
+            }
+            const requestId = parsed.id !== undefined ? String(parsed.id) : sid();
+            const abortController = new AbortController();
+            // Build context
+            const ctx = createAbortableContext(requestId, options.contextFactory?.(client.ws, client.request), abortController);
+            envelope = {
+                id: requestId,
+                procedure: parsed.procedure,
+                type: parsed.type,
+                payload: parsed.payload ?? {},
+                metadata: mergeMetadata(client.connectionMetadata, sanitizeMetadataRecord(parsed.metadata)),
+                context: ctx,
+            };
+            client.activeRequests.set(requestId, abortController);
+        }
+        catch (err) {
+            sendError(client, 'PARSE_ERROR', 'Invalid JSON', undefined);
+            return;
+        }
+        logger.debug({ procedure: envelope.procedure, type: envelope.type }, 'Handling message');
+        try {
+            // Route the envelope
+            const result = await router.handle(envelope);
+            const requestAbortController = client.activeRequests.get(envelope.id);
+            if (requestAbortController?.signal.aborted) {
+                return;
+            }
+            // Check if result is a stream (async iterable)
+            if (result && typeof result === 'object' && Symbol.asyncIterator in result) {
+                // Stream response
+                const streamId = envelope.id;
+                const streamAbortController = client.activeRequests.get(streamId);
+                if (!streamAbortController) {
+                    throw new Error(`Missing abort controller for stream ${streamId}`);
+                }
+                client.activeRequests.delete(streamId);
+                client.activeStreams.set(streamId, streamAbortController);
+                try {
+                    for await (const chunk of result) {
+                        if (streamAbortController.signal.aborted)
+                            break;
+                        if (client.ws.readyState !== WebSocket.OPEN)
+                            break;
+                        sendEnvelope(client, chunk);
+                    }
+                }
+                finally {
+                    client.activeStreams.delete(streamId);
+                }
+            }
+            else {
+                // Single response
+                sendEnvelope(client, result);
+            }
+        }
+        catch (err) {
+            const error = err;
+            logger.error({ err: error, procedure: envelope.procedure }, 'Handler error');
+            sendError(client, 'INTERNAL_ERROR', error.message, envelope.id);
+        }
+        finally {
+            client.activeRequests.delete(envelope.id);
+        }
+    }
+    /**
+     * Send envelope to client
+     */
+    function sendEnvelope(client, envelope) {
+        if (client.ws.readyState !== WebSocket.OPEN)
+            return;
+        const message = JSON.stringify({
+            id: envelope.id,
+            procedure: envelope.procedure,
+            type: envelope.type,
+            payload: envelope.payload,
+            metadata: envelope.metadata,
+        });
+        client.ws.send(message);
+    }
+    /**
+     * Send error to client
+     */
+    function sendError(client, code, message, requestId, envelopeType = 'error') {
+        if (client.ws.readyState !== WebSocket.OPEN)
+            return;
+        const envelope = {
+            id: requestId ? `${requestId}:${envelopeType}` : sid(),
+            procedure: '',
+            type: envelopeType,
+            payload: { code, message },
+            metadata: {},
+        };
+        client.ws.send(JSON.stringify(envelope));
+    }
+    function handleCancelMessage(client, parsed) {
+        if (parsed.type !== 'cancel')
+            return false;
+        const requestId = parsed.id !== undefined ? String(parsed.id) : undefined;
+        if (!requestId)
+            return true;
+        const streamController = client.activeStreams.get(requestId);
+        if (streamController) {
+            streamController.abort('Client cancelled');
+            client.activeStreams.delete(requestId);
+            sendError(client, 'CANCELLED', 'Stream cancelled', requestId, 'stream:error');
+            return true;
+        }
+        const requestController = client.activeRequests.get(requestId);
+        if (requestController) {
+            requestController.abort('Client cancelled');
+            client.activeRequests.delete(requestId);
+            sendError(client, 'CANCELLED', 'Request cancelled', requestId);
+            return true;
+        }
+        return true;
+    }
+    /**
+     * Handle new client connection
+     */
+    function handleConnection(ws, req) {
+        const clientId = sid();
+        const client = {
+            id: clientId,
+            ws,
+            alive: true,
+            request: req,
+            connectionMetadata: extractMetadataFromHeaders(req.headers),
+            activeStreams: new Map(),
+            activeRequests: new Map(),
+        };
+        clients.set(clientId, client);
+        logger.info({ clientId, remoteAddress: req.socket.remoteAddress }, 'Client connected');
+        // Message handler
+        ws.on('message', (data) => {
+            handleMessage(client, data).catch((err) => {
+                logger.error({ err, clientId }, 'Unhandled message error');
+            });
+        });
+        // Pong handler (heartbeat response)
+        ws.on('pong', () => {
+            client.alive = true;
+        });
+        // Close handler
+        ws.on('close', (code, reason) => {
+            logger.info({ clientId, code, reason: reason.toString() }, 'Client disconnected');
+            // Unsubscribe from all channels
+            channelManager?.unsubscribeAll(clientId);
+            // Cancel active streams
+            for (const controller of client.activeStreams.values()) {
+                controller.abort('Client disconnected');
+            }
+            client.activeStreams.clear();
+            for (const controller of client.activeRequests.values()) {
+                controller.abort('Client disconnected');
+            }
+            client.activeRequests.clear();
+            clients.delete(clientId);
+        });
+        // Error handler
+        ws.on('error', (err) => {
+            logger.error({ err, clientId }, 'WebSocket error');
+        });
+    }
+    /**
+     * Heartbeat check
+     */
+    function heartbeat() {
+        for (const [clientId, client] of clients) {
+            if (!client.alive) {
+                logger.warn({ clientId }, 'Client heartbeat timeout, terminating');
+                client.ws.terminate();
+                clients.delete(clientId);
+                continue;
+            }
+            client.alive = false;
+            client.ws.ping();
+        }
+    }
+    return {
+        async start() {
+            return new Promise((resolve, reject) => {
+                wss = new WebSocketServer(sharedServer
+                    ? { server: sharedServer, path, maxPayload: maxPayloadSize }
+                    : { port: port, host, path, maxPayload: maxPayloadSize });
+                wss.on('connection', handleConnection);
+                wss.on('error', (err) => {
+                    logger.error({ err }, 'WebSocket server error');
+                    reject(err);
+                });
+                if (sharedServer) {
+                    logger.info({ path }, 'WebSocket server attached');
+                    if (heartbeatInterval > 0) {
+                        heartbeatTimer = setInterval(heartbeat, heartbeatInterval);
+                    }
+                    resolve();
+                    return;
+                }
+                wss.on('listening', () => {
+                    logger.info({ port, host, path }, 'WebSocket server listening');
+                    // Start heartbeat
+                    if (heartbeatInterval > 0) {
+                        heartbeatTimer = setInterval(heartbeat, heartbeatInterval);
+                    }
+                    resolve();
+                });
+            });
+        },
+        async stop() {
+            return new Promise((resolve) => {
+                // Stop heartbeat
+                if (heartbeatTimer) {
+                    clearInterval(heartbeatTimer);
+                    heartbeatTimer = null;
+                }
+                // Close all client connections
+                for (const [_, client] of clients) {
+                    client.ws.close(1001, 'Server shutting down');
+                }
+                clients.clear();
+                // Close server
+                if (wss) {
+                    wss.close(() => {
+                        logger.info('WebSocket server stopped');
+                        wss = null;
+                        resolve();
+                    });
+                }
+                else {
+                    resolve();
+                }
+            });
+        },
+        get clientCount() {
+            return clients.size;
+        },
+        get channels() {
+            return channelManager;
+        },
+    };
+}
+//# sourceMappingURL=websocket.js.map

package/dist/adapters/websocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.js","sourceRoot":"","sources":["../../src/adapters/websocket.ts"],"names":[],"mappings":"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"}

package/dist/cache/drivers/file.d.ts

@@ -0,0 +1,77 @@
+/**
+ * File Cache Driver
+ *
+ * File-system based cache for persistent storage across restarts.
+ *
+ * Features:
+ * - Persists cache to disk
+ * - Automatic cleanup of expired entries
+ * - Optional compression
+ * - Size limits (by file count or total bytes)
+ */
+import type { CacheDriver, CacheGetResult, CacheStats, FileDriverOptions } from '../types.js';
+/**
+ * File Cache Driver
+ *
+ * @example Basic usage
+ * ```typescript
+ * const cache = new FileDriver({ directory: '.cache' })
+ * await cache.set('key', { data: 'value' }, 60000)
+ * const result = await cache.get('key')
+ * ```
+ */
+export declare class FileDriver implements CacheDriver {
+    readonly name = "file";
+    private readonly directory;
+    private readonly maxFiles;
+    private readonly maxSizeBytes;
+    private readonly compressionEnabled;
+    private cleanupHandle;
+    private _stats;
+    constructor(options?: FileDriverOptions);
+    /**
+     * Get a cached entry
+     */
+    get(key: string): Promise<CacheGetResult | undefined>;
+    /**
+     * Set a cached entry
+     */
+    set(key: string, value: unknown, ttlMs: number, tags?: string[]): Promise<void>;
+    /**
+     * Delete a cached entry
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all cached entries, or those matching a prefix
+     */
+    clear(prefix?: string): Promise<void>;
+    /**
+     * Check if a key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Get all keys
+     */
+    keys(pattern?: string): Promise<string[]>;
+    /**
+     * Get cache statistics
+     */
+    stats(): CacheStats;
+    /**
+     * Shutdown the cache
+     */
+    shutdown(): Promise<void>;
+    private ensureDirectory;
+    private getFilePath;
+    private deleteFile;
+    private countFiles;
+    private getTotalSize;
+    private enforceFileLimits;
+    private evictOldest;
+    private cleanupExpired;
+}
+/**
+ * Create a file cache driver
+ */
+export declare function createFileDriver(options?: FileDriverOptions): CacheDriver;
+//# sourceMappingURL=file.d.ts.map

package/dist/cache/drivers/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../../src/cache/drivers/file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,KAAK,EACV,WAAW,EAEX,cAAc,EACd,UAAU,EACV,iBAAiB,EAClB,MAAM,aAAa,CAAA;AAapB;;;;;;;;;GASG;AACH,qBAAa,UAAW,YAAW,WAAW;IAC5C,QAAQ,CAAC,IAAI,UAAS;IAEtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,aAAa,CAA8C;IAGnE,OAAO,CAAC,MAAM,CAMb;gBAEW,OAAO,GAAE,iBAAsB;IAiB3C;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IA2C3D;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCrF;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC;;OAEG;IACG,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB3C;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBxC;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAW/C;;OAEG;IACH,KAAK,IAAI,UAAU;IAYnB;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAW/B,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,YAAY;YAgBN,iBAAiB;YAYjB,WAAW;IAyBzB,OAAO,CAAC,cAAc;CA+BvB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,WAAW,CAEzE"}