crewly 1.2.3 → 1.2.6

package/dist/backend/backend/src/services/cloud/relay-server.service.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Relay Server Service
+ *
+ * WebSocket server that accepts connections from Crewly instances,
+ * assigns session IDs, pairs nodes by pairing code, and relays
+ * encrypted messages between paired instances.
+ *
+ * The server never inspects or decrypts message payloads (E2EE).
+ * It only reads the wire protocol envelope to route messages.
+ *
+ * @module services/cloud/relay-server.service
+ */
+import type { Server as HttpServer } from 'http';
+import { type RelaySession } from './relay.types.js';
+/**
+ * RelayServerService singleton.
+ *
+ * Manages the WebSocket server lifecycle, client connections, pairing,
+ * and message forwarding between paired Crewly instances.
+ */
+export declare class RelayServerService {
+    private static instance;
+    private readonly logger;
+    /** WebSocket server instance */
+    private wss;
+    /** Map of session ID → connected client */
+    private clients;
+    /** Map of pairing code → array of session IDs waiting to pair */
+    private pairingQueue;
+    /** Whether the server is running */
+    private running;
+    private constructor();
+    /**
+     * Get the singleton instance.
+     *
+     * @returns RelayServerService instance
+     */
+    static getInstance(): RelayServerService;
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance(): void;
+    /**
+     * Start the relay WebSocket server.
+     *
+     * Can attach to an existing HTTP server or listen on a standalone port.
+     *
+     * @param options - Server options: either an httpServer or a port number
+     *
+     * @example
+     * ```ts
+     * const relay = RelayServerService.getInstance();
+     * relay.start({ port: 8787 });
+     * ```
+     */
+    start(options: {
+        httpServer?: HttpServer;
+        port?: number;
+        path?: string;
+    }): void;
+    /**
+     * Stop the relay server and close all connections.
+     *
+     * @returns Promise that resolves when the server is fully closed
+     */
+    stop(): Promise<void>;
+    /**
+     * Check whether the relay server is currently running.
+     *
+     * @returns true if running
+     */
+    isRunning(): boolean;
+    /**
+     * Get the number of currently connected clients.
+     *
+     * @returns Client count
+     */
+    getClientCount(): number;
+    /**
+     * Get a snapshot of all active sessions.
+     *
+     * @returns Array of relay session metadata
+     */
+    getSessions(): RelaySession[];
+    /**
+     * Handle a new WebSocket connection.
+     *
+     * Sets up message, close, and error handlers. The client must send
+     * a `register` message within the handshake timeout or be disconnected.
+     *
+     * @param ws - Incoming WebSocket connection
+     */
+    private handleConnection;
+    /**
+     * Handle a register message from a client.
+     *
+     * Assigns a session ID, stores the client, and attempts pairing
+     * if another client with the same pairing code is waiting.
+     *
+     * @param ws - Client WebSocket
+     * @param msg - Registration message
+     */
+    private handleRegister;
+    /**
+     * Attempt to pair a newly registered client with an existing one.
+     *
+     * Two clients are paired when they share the same pairing code and
+     * have complementary roles (orchestrator + agent).
+     *
+     * @param sessionId - Session ID of the newly registered client
+     * @param pairingCode - Pairing code to match
+     */
+    private attemptPairing;
+    /**
+     * Complete pairing between two sessions.
+     *
+     * Updates both sessions to 'paired' state and sends paired messages
+     * to both clients.
+     *
+     * @param idA - First session ID
+     * @param idB - Second session ID
+     */
+    private completePairing;
+    /**
+     * Forward a relay message from one peer to its paired counterpart.
+     *
+     * The payload is forwarded unchanged — the server never decrypts it.
+     *
+     * @param senderSessionId - Session ID of the sending client
+     * @param msg - Relay data message with encrypted payload
+     */
+    private handleRelay;
+    /**
+     * Handle a heartbeat from a client by resetting its timeout timer.
+     *
+     * @param sessionId - Session ID of the heartbeating client
+     */
+    private handleHeartbeat;
+    /**
+     * Handle a client disconnection.
+     *
+     * Cleans up the session, removes from pairing queue, and notifies
+     * the paired peer if applicable.
+     *
+     * @param sessionId - Session ID of the disconnected client
+     */
+    private handleDisconnect;
+    /**
+     * Find the session ID associated with a WebSocket connection.
+     *
+     * @param ws - WebSocket to look up
+     * @returns Session ID or undefined
+     */
+    private findSessionIdByWs;
+    /**
+     * Start a heartbeat timeout timer for a session.
+     *
+     * If no heartbeat is received within the timeout window, the client
+     * is disconnected.
+     *
+     * @param sessionId - Session ID to monitor
+     * @returns Timer handle
+     */
+    private startHeartbeatTimer;
+    /**
+     * Send a typed relay message to a WebSocket.
+     *
+     * @param ws - Target WebSocket
+     * @param message - Relay message to send
+     */
+    private send;
+    /**
+     * Send an error message to a WebSocket.
+     *
+     * @param ws - Target WebSocket (or null if unavailable)
+     * @param code - Machine-readable error code
+     * @param message - Human-readable error description
+     */
+    private sendError;
+}
+//# sourceMappingURL=relay-server.service.d.ts.map

package/dist/backend/backend/src/services/cloud/relay-server.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-server.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/cloud/relay-server.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AAGjD,OAAO,EAEL,KAAK,YAAY,EAUlB,MAAM,kBAAkB,CAAC;AAgC1B;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,gCAAgC;IAChC,OAAO,CAAC,GAAG,CAAgC;IAC3C,2CAA2C;IAC3C,OAAO,CAAC,OAAO,CAAmD;IAClE,iEAAiE;IACjE,OAAO,CAAC,YAAY,CAA4C;IAChE,oCAAoC;IACpC,OAAO,CAAC,OAAO,CAAS;IAExB,OAAO;IAIP;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,kBAAkB;IAOxC;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAQ5B;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,OAAO,EAAE;QAAE,UAAU,CAAC,EAAE,UAAU,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IA6B/E;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B3B;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;OAIG;IACH,WAAW,IAAI,YAAY,EAAE;IAc7B;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IA0ExB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAgCtB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IA+BtB;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAiCvB;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IAkBnB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAgBvB;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IA6CxB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IAW3B;;;;;OAKG;IACH,OAAO,CAAC,IAAI;IAMZ;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;CAKlB"}

package/dist/backend/backend/src/services/cloud/relay-server.service.js

@@ -0,0 +1,494 @@
+/**
+ * Relay Server Service
+ *
+ * WebSocket server that accepts connections from Crewly instances,
+ * assigns session IDs, pairs nodes by pairing code, and relays
+ * encrypted messages between paired instances.
+ *
+ * The server never inspects or decrypts message payloads (E2EE).
+ * It only reads the wire protocol envelope to route messages.
+ *
+ * @module services/cloud/relay-server.service
+ */
+import { WebSocketServer, WebSocket } from 'ws';
+import { randomUUID } from 'crypto';
+import { LoggerService } from '../core/logger.service.js';
+import { CLOUD_CONSTANTS } from '../../constants.js';
+import { isRelayMessage, } from './relay.types.js';
+const RELAY = CLOUD_CONSTANTS.RELAY;
+/** Named WebSocket close codes used by the relay server. */
+const WS_CLOSE = {
+    /** Normal server shutdown */
+    SERVER_SHUTDOWN: 1001,
+    /** Client failed to register within the handshake window */
+    HANDSHAKE_TIMEOUT: 4001,
+    /** Client missed heartbeat deadline */
+    HEARTBEAT_TIMEOUT: 4002,
+};
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+/**
+ * RelayServerService singleton.
+ *
+ * Manages the WebSocket server lifecycle, client connections, pairing,
+ * and message forwarding between paired Crewly instances.
+ */
+export class RelayServerService {
+    static instance = null;
+    logger;
+    /** WebSocket server instance */
+    wss = null;
+    /** Map of session ID → connected client */
+    clients = new Map();
+    /** Map of pairing code → array of session IDs waiting to pair */
+    pairingQueue = new Map();
+    /** Whether the server is running */
+    running = false;
+    constructor() {
+        this.logger = LoggerService.getInstance().createComponentLogger('RelayServerService');
+    }
+    /**
+     * Get the singleton instance.
+     *
+     * @returns RelayServerService instance
+     */
+    static getInstance() {
+        if (!RelayServerService.instance) {
+            RelayServerService.instance = new RelayServerService();
+        }
+        return RelayServerService.instance;
+    }
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance() {
+        RelayServerService.instance = null;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Start the relay WebSocket server.
+     *
+     * Can attach to an existing HTTP server or listen on a standalone port.
+     *
+     * @param options - Server options: either an httpServer or a port number
+     *
+     * @example
+     * ```ts
+     * const relay = RelayServerService.getInstance();
+     * relay.start({ port: 8787 });
+     * ```
+     */
+    start(options) {
+        if (this.running) {
+            this.logger.warn('Relay server already running');
+            return;
+        }
+        const wssOptions = {
+            maxPayload: RELAY.MAX_PAYLOAD_BYTES,
+            path: options.path ?? '/relay',
+        };
+        if (options.httpServer) {
+            wssOptions['server'] = options.httpServer;
+        }
+        else {
+            wssOptions['port'] = options.port ?? RELAY.DEFAULT_PORT;
+        }
+        this.wss = new WebSocketServer(wssOptions);
+        this.running = true;
+        this.wss.on('connection', (ws) => {
+            this.handleConnection(ws);
+        });
+        this.logger.info('Relay server started', {
+            port: options.port ?? (options.httpServer ? 'attached' : RELAY.DEFAULT_PORT),
+        });
+    }
+    /**
+     * Stop the relay server and close all connections.
+     *
+     * @returns Promise that resolves when the server is fully closed
+     */
+    async stop() {
+        if (!this.running || !this.wss) {
+            return;
+        }
+        this.running = false;
+        // Clear all heartbeat timers
+        for (const client of this.clients.values()) {
+            if (client.heartbeatTimer) {
+                clearTimeout(client.heartbeatTimer);
+            }
+            client.ws.close(WS_CLOSE.SERVER_SHUTDOWN, 'Server shutting down');
+        }
+        this.clients.clear();
+        this.pairingQueue.clear();
+        return new Promise((resolve) => {
+            this.wss.close(() => {
+                this.wss = null;
+                this.logger.info('Relay server stopped');
+                resolve();
+            });
+        });
+    }
+    /**
+     * Check whether the relay server is currently running.
+     *
+     * @returns true if running
+     */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Get the number of currently connected clients.
+     *
+     * @returns Client count
+     */
+    getClientCount() {
+        return this.clients.size;
+    }
+    /**
+     * Get a snapshot of all active sessions.
+     *
+     * @returns Array of relay session metadata
+     */
+    getSessions() {
+        const sessions = [];
+        for (const client of this.clients.values()) {
+            if (client.session) {
+                sessions.push({ ...client.session });
+            }
+        }
+        return sessions;
+    }
+    // -------------------------------------------------------------------------
+    // Connection handling
+    // -------------------------------------------------------------------------
+    /**
+     * Handle a new WebSocket connection.
+     *
+     * Sets up message, close, and error handlers. The client must send
+     * a `register` message within the handshake timeout or be disconnected.
+     *
+     * @param ws - Incoming WebSocket connection
+     */
+    handleConnection(ws) {
+        const tempId = `pending-${randomUUID()}`;
+        this.logger.debug('New WebSocket connection', { tempId });
+        // Handshake timeout: client must register within the window
+        const handshakeTimer = setTimeout(() => {
+            this.sendError(ws, 'HANDSHAKE_TIMEOUT', 'Registration timeout — send a register message');
+            ws.close(WS_CLOSE.HANDSHAKE_TIMEOUT, 'Handshake timeout');
+        }, RELAY.HANDSHAKE_TIMEOUT_MS);
+        ws.on('message', (data) => {
+            const raw = typeof data === 'string' ? data : data.toString('utf8');
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                this.sendError(ws, 'INVALID_JSON', 'Message is not valid JSON');
+                return;
+            }
+            if (!isRelayMessage(parsed)) {
+                this.sendError(ws, 'INVALID_MESSAGE', 'Unknown or malformed relay message');
+                return;
+            }
+            const msg = parsed;
+            if (msg.type === 'register') {
+                clearTimeout(handshakeTimer);
+                this.handleRegister(ws, msg);
+                return;
+            }
+            // All other message types require a registered session
+            const sessionId = this.findSessionIdByWs(ws);
+            if (!sessionId) {
+                this.sendError(ws, 'NOT_REGISTERED', 'Send a register message first');
+                return;
+            }
+            switch (msg.type) {
+                case 'relay':
+                    this.handleRelay(sessionId, msg);
+                    break;
+                case 'heartbeat':
+                    this.handleHeartbeat(sessionId);
+                    break;
+                default:
+                    this.sendError(ws, 'UNEXPECTED_TYPE', `Unexpected message type: ${msg.type}`);
+            }
+        });
+        ws.on('close', () => {
+            clearTimeout(handshakeTimer);
+            const sessionId = this.findSessionIdByWs(ws);
+            if (sessionId) {
+                this.handleDisconnect(sessionId);
+            }
+        });
+        ws.on('error', (err) => {
+            this.logger.error('WebSocket error', { error: err.message });
+            const sessionId = this.findSessionIdByWs(ws);
+            if (sessionId) {
+                this.handleDisconnect(sessionId);
+            }
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Message handlers
+    // -------------------------------------------------------------------------
+    /**
+     * Handle a register message from a client.
+     *
+     * Assigns a session ID, stores the client, and attempts pairing
+     * if another client with the same pairing code is waiting.
+     *
+     * @param ws - Client WebSocket
+     * @param msg - Registration message
+     */
+    handleRegister(ws, msg) {
+        const sessionId = randomUUID();
+        const now = new Date().toISOString();
+        const session = {
+            sessionId,
+            role: msg.role,
+            pairingCode: msg.pairingCode,
+            state: 'waiting',
+            pairedWith: null,
+            registeredAt: now,
+            lastHeartbeatAt: now,
+        };
+        const client = {
+            ws,
+            session,
+            heartbeatTimer: this.startHeartbeatTimer(sessionId),
+        };
+        this.clients.set(sessionId, client);
+        // Send registration confirmation
+        const registered = { type: 'registered', sessionId };
+        this.send(ws, registered);
+        this.logger.info('Client registered', { sessionId, role: msg.role, pairingCode: msg.pairingCode });
+        // Attempt pairing
+        this.attemptPairing(sessionId, msg.pairingCode);
+    }
+    /**
+     * Attempt to pair a newly registered client with an existing one.
+     *
+     * Two clients are paired when they share the same pairing code and
+     * have complementary roles (orchestrator + agent).
+     *
+     * @param sessionId - Session ID of the newly registered client
+     * @param pairingCode - Pairing code to match
+     */
+    attemptPairing(sessionId, pairingCode) {
+        const queue = this.pairingQueue.get(pairingCode) ?? [];
+        // Look for a compatible peer in the queue
+        const newClient = this.clients.get(sessionId);
+        if (!newClient?.session)
+            return;
+        const peerIndex = queue.findIndex((peerId) => {
+            const peer = this.clients.get(peerId);
+            if (!peer?.session)
+                return false;
+            // Pair orchestrator with agent (different roles)
+            return peer.session.role !== newClient.session.role && peer.session.state === 'waiting';
+        });
+        if (peerIndex >= 0) {
+            const peerId = queue[peerIndex];
+            queue.splice(peerIndex, 1);
+            if (queue.length === 0) {
+                this.pairingQueue.delete(pairingCode);
+            }
+            else {
+                this.pairingQueue.set(pairingCode, queue);
+            }
+            this.completePairing(sessionId, peerId);
+        }
+        else {
+            // No peer yet — add to queue
+            queue.push(sessionId);
+            this.pairingQueue.set(pairingCode, queue);
+        }
+    }
+    /**
+     * Complete pairing between two sessions.
+     *
+     * Updates both sessions to 'paired' state and sends paired messages
+     * to both clients.
+     *
+     * @param idA - First session ID
+     * @param idB - Second session ID
+     */
+    completePairing(idA, idB) {
+        const clientA = this.clients.get(idA);
+        const clientB = this.clients.get(idB);
+        if (!clientA?.session || !clientB?.session)
+            return;
+        clientA.session.state = 'paired';
+        clientA.session.pairedWith = idB;
+        clientB.session.state = 'paired';
+        clientB.session.pairedWith = idA;
+        const pairedA = {
+            type: 'paired',
+            peerSessionId: idB,
+            peerRole: clientB.session.role,
+        };
+        const pairedB = {
+            type: 'paired',
+            peerSessionId: idA,
+            peerRole: clientA.session.role,
+        };
+        this.send(clientA.ws, pairedA);
+        this.send(clientB.ws, pairedB);
+        this.logger.info('Clients paired', {
+            sessionA: idA,
+            roleA: clientA.session.role,
+            sessionB: idB,
+            roleB: clientB.session.role,
+        });
+    }
+    /**
+     * Forward a relay message from one peer to its paired counterpart.
+     *
+     * The payload is forwarded unchanged — the server never decrypts it.
+     *
+     * @param senderSessionId - Session ID of the sending client
+     * @param msg - Relay data message with encrypted payload
+     */
+    handleRelay(senderSessionId, msg) {
+        const sender = this.clients.get(senderSessionId);
+        if (!sender?.session?.pairedWith) {
+            this.sendError(sender?.ws ?? null, 'NOT_PAIRED', 'Cannot relay — not paired with a peer');
+            return;
+        }
+        const peer = this.clients.get(sender.session.pairedWith);
+        if (!peer) {
+            this.sendError(sender.ws, 'PEER_UNAVAILABLE', 'Paired peer is no longer connected');
+            return;
+        }
+        // Forward the encrypted payload as-is
+        const forwarded = { type: 'relay', payload: msg.payload };
+        this.send(peer.ws, forwarded);
+    }
+    /**
+     * Handle a heartbeat from a client by resetting its timeout timer.
+     *
+     * @param sessionId - Session ID of the heartbeating client
+     */
+    handleHeartbeat(sessionId) {
+        const client = this.clients.get(sessionId);
+        if (!client?.session)
+            return;
+        client.session.lastHeartbeatAt = new Date().toISOString();
+        // Reset heartbeat timer
+        if (client.heartbeatTimer) {
+            clearTimeout(client.heartbeatTimer);
+        }
+        client.heartbeatTimer = this.startHeartbeatTimer(sessionId);
+        const ack = { type: 'heartbeat_ack' };
+        this.send(client.ws, ack);
+    }
+    /**
+     * Handle a client disconnection.
+     *
+     * Cleans up the session, removes from pairing queue, and notifies
+     * the paired peer if applicable.
+     *
+     * @param sessionId - Session ID of the disconnected client
+     */
+    handleDisconnect(sessionId) {
+        const client = this.clients.get(sessionId);
+        if (!client)
+            return;
+        if (client.heartbeatTimer) {
+            clearTimeout(client.heartbeatTimer);
+        }
+        // Notify peer of disconnection
+        if (client.session?.pairedWith) {
+            const peer = this.clients.get(client.session.pairedWith);
+            if (peer?.session) {
+                peer.session.state = 'waiting';
+                peer.session.pairedWith = null;
+                const disconnected = {
+                    type: 'peer_disconnected',
+                    peerSessionId: sessionId,
+                };
+                this.send(peer.ws, disconnected);
+            }
+        }
+        // Remove from pairing queue
+        if (client.session) {
+            const queue = this.pairingQueue.get(client.session.pairingCode);
+            if (queue) {
+                const idx = queue.indexOf(sessionId);
+                if (idx >= 0) {
+                    queue.splice(idx, 1);
+                    if (queue.length === 0) {
+                        this.pairingQueue.delete(client.session.pairingCode);
+                    }
+                }
+            }
+        }
+        this.clients.delete(sessionId);
+        this.logger.info('Client disconnected', { sessionId });
+    }
+    // -------------------------------------------------------------------------
+    // Helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Find the session ID associated with a WebSocket connection.
+     *
+     * @param ws - WebSocket to look up
+     * @returns Session ID or undefined
+     */
+    findSessionIdByWs(ws) {
+        for (const [sessionId, client] of this.clients.entries()) {
+            if (client.ws === ws)
+                return sessionId;
+        }
+        return undefined;
+    }
+    /**
+     * Start a heartbeat timeout timer for a session.
+     *
+     * If no heartbeat is received within the timeout window, the client
+     * is disconnected.
+     *
+     * @param sessionId - Session ID to monitor
+     * @returns Timer handle
+     */
+    startHeartbeatTimer(sessionId) {
+        return setTimeout(() => {
+            this.logger.warn('Heartbeat timeout', { sessionId });
+            const client = this.clients.get(sessionId);
+            if (client) {
+                client.ws.close(WS_CLOSE.HEARTBEAT_TIMEOUT, 'Heartbeat timeout');
+                this.handleDisconnect(sessionId);
+            }
+        }, RELAY.HEARTBEAT_TIMEOUT_MS);
+    }
+    /**
+     * Send a typed relay message to a WebSocket.
+     *
+     * @param ws - Target WebSocket
+     * @param message - Relay message to send
+     */
+    send(ws, message) {
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify(message));
+        }
+    }
+    /**
+     * Send an error message to a WebSocket.
+     *
+     * @param ws - Target WebSocket (or null if unavailable)
+     * @param code - Machine-readable error code
+     * @param message - Human-readable error description
+     */
+    sendError(ws, code, message) {
+        if (!ws || ws.readyState !== WebSocket.OPEN)
+            return;
+        const errorMsg = { type: 'error', code, message };
+        ws.send(JSON.stringify(errorMsg));
+    }
+}
+//# sourceMappingURL=relay-server.service.js.map