pi-harness-runtime 1.1.376 → 1.1.378

package/packages/relay/dist/server.d.ts

@@ -1,58 +1,96 @@
 /**
- * Relay Server - Cloud relay server for tunnels
- */
-import type { RelayTunnel, RelayMessage } from './types.js';
-/**
- * Relay Server options
+ * Relay Server - Two-way streaming WebSocket relay
+ *
+ * Implements t3code-style streaming with:
+ * - Snapshot + Live event pattern
+ * - Typed message protocol
+ * - Connection state machine
+ * - Stream coalescing
  */
+import { type RelayTunnel, type RelayMessage, type ConnectionState, type ConnectionStateChange, type CallbackPayload } from './types.js';
 export interface RelayServerOptions {
     /** Port to listen on */
     port?: number;
     /** Host to bind */
     host?: string;
+    /** Authentication token */
+    authToken?: string;
+    /** Server version string */
+    serverVersion?: string;
     /** Called when a tunnel connects */
     onTunnelConnect?: (tunnel: RelayTunnel) => void;
     /** Called when a tunnel disconnects */
     onTunnelDisconnect?: (tunnelId: string) => void;
     /** Called when a message is received */
     onMessage?: (tunnelId: string, message: RelayMessage) => void;
+    /** Called on state change */
+    onStateChange?: (change: ConnectionStateChange) => void;
 }
-/**
- * Relay Server
- *
- * Manages tunnels and relays messages between clients.
- */
 export declare class RelayServer {
+    private server;
+    private wss;
+    private clients;
     private tunnels;
     private options;
     private running;
+    private serverSessionId;
+    private eventBuffer;
+    private recentCallbacks;
     constructor(options?: RelayServerOptions);
     /**
-     * Start the relay server
+     * Start the WebSocket server
      */
     start(): Promise<void>;
     /**
      * Stop the relay server
      */
     stop(): Promise<void>;
+    private updateState;
+    private handleMessage;
+    private handleAuth;
+    private handlePing;
+    private handleSubscribe;
+    /**
+     * Send initial snapshot followed by synchronized marker
+     * This is the t3code pattern: snapshot -> synchronized -> live events
+     */
+    private sendSnapshot;
+    /**
+     * Flush event buffer and send batched callbacks
+     */
+    private flushEventBuffer;
+    /**
+     * Broadcast callback to all connected clients
+     * Uses stream batching for high-frequency events
+     */
+    broadcastCallback(callback: CallbackPayload, batch?: boolean): void;
     /**
-     * Get all active tunnels
+     * Send status to all clients
      */
-    getTunnels(): RelayTunnel[];
+    broadcastStatus(kind: 'info' | 'warning' | 'error', code: string, message: string): void;
     /**
-     * Get tunnel by ID
+     * Broadcast to all subscribed clients
      */
-    getTunnel(id: string): RelayTunnel | undefined;
+    private broadcast;
     /**
-     * Create a tunnel
+     * Check if client is connected and authenticated
      */
-    createTunnel(localPort: number): RelayTunnel;
+    private isConnected;
     /**
-     * Remove a tunnel
+     * Send a typed message to a client
      */
-    removeTunnel(id: string): boolean;
+    private sendMessage;
     /**
-     * Check if server is running
+     * Send status to specific client
      */
+    private sendStatus;
     isRunning(): boolean;
+    getClientCount(): number;
+    getClients(): Array<{
+        id: string;
+        state: ConnectionState;
+        connectedAt: string;
+    }>;
+    getRecentCallbacks(limit?: number): CallbackPayload[];
 }
+export declare function createRelayServer(options?: RelayServerOptions): RelayServer;

package/packages/relay/dist/server.js

@@ -1,93 +1,388 @@
 /**
- * Relay Server - Cloud relay server for tunnels
- */
-/**
- * Generate a UUID v4
- */
-function generateUUID() {
-    // Use crypto.randomUUID if available
-    const crypto = globalThis;
-    if (crypto.crypto?.randomUUID) {
-        return crypto.crypto.randomUUID();
-    }
-    // Fallback
-    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
-        const r = (Math.random() * 16) | 0;
-        const v = c === 'x' ? r : (r & 0x3) | 0x8;
-        return v.toString(16);
-    });
-}
-/**
- * Relay Server
+ * Relay Server - Two-way streaming WebSocket relay
  *
- * Manages tunnels and relays messages between clients.
+ * Implements t3code-style streaming with:
+ * - Snapshot + Live event pattern
+ * - Typed message protocol
+ * - Connection state machine
+ * - Stream coalescing
  */
+import { createServer } from "node:http";
+import { WebSocketServer, WebSocket } from "ws";
+import { randomUUID } from "node:crypto";
+import { PROTOCOL_VERSION, generateMessageId, createTimestamp, } from './types.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_PORT = 8444;
+const DEFAULT_HOST = "0.0.0.0";
+const MAX_RECENT_CALLBACKS = 100;
+const STREAM_BATCH_SIZE = 50; // Batch events for coalescing
+const STREAM_BATCH_TIMEOUT_MS = 100; // Flush batch after this delay
+function createEventBuffer() {
+    return {
+        callbacks: [],
+        timer: null,
+    };
+}
+// ============================================================================
+// Relay Server - Two-way Streaming Implementation
+// ============================================================================
 export class RelayServer {
+    server = null;
+    wss = null;
+    clients = new Map();
     tunnels = new Map();
     options;
     running = false;
+    serverSessionId;
+    // Event stream buffering for coalescing
+    eventBuffer = createEventBuffer();
+    // Recent callbacks for snapshot
+    recentCallbacks = [];
     constructor(options = {}) {
+        this.serverSessionId = randomUUID();
         this.options = {
-            port: options.port ?? 3001,
-            host: options.host ?? '0.0.0.0',
+            port: options.port ?? DEFAULT_PORT,
+            host: options.host ?? DEFAULT_HOST,
+            authToken: options.authToken ?? "change-me-in-production",
+            serverVersion: options.serverVersion ?? "1.0.0",
             onTunnelConnect: options.onTunnelConnect ?? (() => { }),
             onTunnelDisconnect: options.onTunnelDisconnect ?? (() => { }),
             onMessage: options.onMessage ?? (() => { }),
+            onStateChange: options.onStateChange ?? (() => { }),
         };
     }
+    // ========================================================================
+    // Lifecycle
+    // ========================================================================
     /**
-     * Start the relay server
+     * Start the WebSocket server
      */
     async start() {
         if (this.running)
             return;
-        this.running = true;
-        // Note: Actual HTTP/WebSocket server would be implemented here
-        // For now, this is a stub that can be expanded with actual server code
+        this.server = createServer();
+        this.wss = new WebSocketServer({ server: this.server });
+        this.wss.on("connection", (ws, req) => {
+            const clientId = randomUUID();
+            const clientIp = req.socket.remoteAddress;
+            console.log(`[RelayServer] Client connecting: ${clientId} from ${clientIp}`);
+            // Create client session
+            const session = {
+                id: clientId,
+                ws,
+                state: { state: 'connecting' },
+                subscriptions: new Set(['callback', 'status', 'sync']),
+                connectedAt: createTimestamp(),
+                lastPing: createTimestamp(),
+                pendingSnapshot: true,
+            };
+            this.clients.set(clientId, session);
+            this.updateState(session, { state: 'connecting' });
+            // Handle incoming messages
+            ws.on("message", (data) => {
+                this.handleMessage(clientId, data);
+            });
+            ws.on("close", () => {
+                this.clients.delete(clientId);
+                console.log(`[RelayServer] Client disconnected: ${clientId}`);
+            });
+            ws.on("error", (err) => {
+                console.error(`[RelayServer] Client error: ${clientId}`, err.message);
+                this.clients.delete(clientId);
+            });
+            // Send initial connected message
+            this.sendMessage(session, {
+                version: PROTOCOL_VERSION,
+                type: 'connected',
+                payload: {
+                    clientId,
+                    serverTime: createTimestamp(),
+                },
+                timestamp: createTimestamp(),
+            });
+            // Auto-auth for now (can be changed to require explicit auth)
+            this.updateState(session, { state: 'authenticating' });
+            this.handleAuth(clientId, this.options.authToken);
+        });
+        return new Promise((resolve, reject) => {
+            this.server.listen(this.options.port, this.options.host, () => {
+                this.running = true;
+                console.log(`[RelayServer] Server started on ${this.options.host}:${this.options.port}`);
+                resolve();
+            });
+            this.server.on("error", (err) => {
+                console.error("[RelayServer] Server error:", err);
+                reject(err);
+            });
+        });
     }
     /**
      * Stop the relay server
      */
     async stop() {
-        this.running = false;
-        this.tunnels.clear();
+        if (!this.running)
+            return;
+        // Close all client connections
+        for (const session of this.clients.values()) {
+            session.ws.close();
+        }
+        this.clients.clear();
+        // Close event buffer timer
+        if (this.eventBuffer.timer) {
+            clearTimeout(this.eventBuffer.timer);
+        }
+        return new Promise((resolve) => {
+            this.server.close(() => {
+                this.running = false;
+                console.log("[RelayServer] Server stopped");
+                resolve();
+            });
+        });
+    }
+    // ========================================================================
+    // State Management
+    // ========================================================================
+    updateState(session, newState) {
+        const previous = session.state;
+        session.state = newState;
+        this.options.onStateChange({
+            previous,
+            current: newState,
+            timestamp: createTimestamp(),
+        });
+    }
+    // ========================================================================
+    // Message Handling
+    // ========================================================================
+    handleMessage(clientId, data) {
+        const session = this.clients.get(clientId);
+        if (!session)
+            return;
+        try {
+            const msg = JSON.parse(data.toString());
+            switch (msg.type) {
+                case 'auth':
+                    this.handleAuth(clientId, msg.payload.token);
+                    break;
+                case 'ping':
+                    this.handlePing(session);
+                    break;
+                case 'subscribe':
+                    this.handleSubscribe(session, msg);
+                    break;
+                default:
+                    const _msg = msg;
+                    console.warn(`[RelayServer] Unknown message type: ${_msg?.type}`);
+            }
+        }
+        catch (err) {
+            console.error("[RelayServer] Invalid message:", err);
+            this.sendStatus(session, 'error', 'INVALID_MESSAGE', 'Failed to parse message');
+        }
+    }
+    handleAuth(clientId, token) {
+        const session = this.clients.get(clientId);
+        if (!session)
+            return;
+        const success = token === this.options.authToken;
+        const response = {
+            version: PROTOCOL_VERSION,
+            type: 'auth',
+            payload: {
+                success,
+                sessionId: success ? this.serverSessionId : undefined,
+                error: success ? undefined : 'Invalid token',
+            },
+            timestamp: createTimestamp(),
+            messageId: generateMessageId(),
+        };
+        this.sendMessage(session, response);
+        if (success) {
+            this.updateState(session, { state: 'connected', sessionId: this.serverSessionId });
+            console.log(`[RelayServer] Client authenticated: ${clientId}`);
+            // Send snapshot + synchronized (t3code pattern)
+            this.sendSnapshot(session);
+        }
+        else {
+            this.updateState(session, { state: 'error', error: 'Authentication failed' });
+            session.ws.close();
+        }
+    }
+    handlePing(session) {
+        session.lastPing = createTimestamp();
+        this.sendMessage(session, {
+            version: PROTOCOL_VERSION,
+            type: 'pong',
+            payload: {},
+            timestamp: createTimestamp(),
+        });
+    }
+    handleSubscribe(session, msg) {
+        session.subscriptions = new Set(msg.payload.events);
+        console.log(`[RelayServer] Client ${session.id} subscribed to: ${Array.from(session.subscriptions).join(', ')}`);
+    }
+    // ========================================================================
+    // Snapshot + Live Streaming (t3code pattern)
+    // ========================================================================
+    /**
+     * Send initial snapshot followed by synchronized marker
+     * This is the t3code pattern: snapshot -> synchronized -> live events
+     */
+    async sendSnapshot(session) {
+        // Build snapshot message
+        const snapshot = {
+            version: PROTOCOL_VERSION,
+            type: 'snapshot',
+            payload: {
+                sessionId: this.serverSessionId,
+                serverVersion: this.options.serverVersion,
+                connectedClients: this.clients.size,
+                recentCallbacks: this.recentCallbacks.slice(-20), // Last 20 callbacks
+            },
+            timestamp: createTimestamp(),
+            messageId: generateMessageId(),
+        };
+        // Send snapshot
+        this.sendMessage(session, snapshot);
+        // Send synchronized marker (t3code pattern: indicates snapshot complete)
+        const synchronized = {
+            version: PROTOCOL_VERSION,
+            type: 'synchronized',
+            payload: {},
+            timestamp: createTimestamp(),
+            messageId: generateMessageId(),
+        };
+        this.sendMessage(session, synchronized);
+        session.pendingSnapshot = false;
+        console.log(`[RelayServer] Snapshot sent to ${session.id}`);
     }
     /**
-     * Get all active tunnels
+     * Flush event buffer and send batched callbacks
      */
-    getTunnels() {
-        return Array.from(this.tunnels.values());
+    flushEventBuffer() {
+        if (this.eventBuffer.callbacks.length === 0)
+            return;
+        const callbacks = this.eventBuffer.callbacks;
+        this.eventBuffer.callbacks = [];
+        this.eventBuffer.timer = null;
+        // Send each callback as a separate live event
+        for (const callback of callbacks) {
+            this.broadcastCallback(callback, false); // false = don't add to recent
+        }
     }
+    // ========================================================================
+    // Broadcasting
+    // ========================================================================
     /**
-     * Get tunnel by ID
+     * Broadcast callback to all connected clients
+     * Uses stream batching for high-frequency events
      */
-    getTunnel(id) {
-        return this.tunnels.get(id);
+    broadcastCallback(callback, batch = true) {
+        // Add to recent callbacks (circular buffer)
+        this.recentCallbacks.push(callback);
+        if (this.recentCallbacks.length > MAX_RECENT_CALLBACKS) {
+            this.recentCallbacks.shift();
+        }
+        const message = {
+            version: PROTOCOL_VERSION,
+            type: 'callback',
+            payload: callback,
+            timestamp: createTimestamp(),
+            messageId: generateMessageId(),
+        };
+        if (batch) {
+            // Add to buffer for coalescing
+            this.eventBuffer.callbacks.push(callback);
+            if (!this.eventBuffer.timer) {
+                this.eventBuffer.timer = setTimeout(() => {
+                    this.flushEventBuffer();
+                }, STREAM_BATCH_TIMEOUT_MS);
+            }
+        }
+        else {
+            // Send immediately
+            this.broadcast(message);
+        }
     }
     /**
-     * Create a tunnel
+     * Send status to all clients
      */
-    createTunnel(localPort) {
-        const tunnel = {
-            id: generateUUID(),
-            url: `https://tunnel-${Date.now()}.relay.example.com`,
-            localPort,
-            status: 'connecting',
-            createdAt: new Date().toISOString(),
+    broadcastStatus(kind, code, message) {
+        const msg = {
+            version: PROTOCOL_VERSION,
+            type: 'status',
+            payload: { kind, code, message },
+            timestamp: createTimestamp(),
+            messageId: generateMessageId(),
         };
-        this.tunnels.set(tunnel.id, tunnel);
-        return tunnel;
+        this.broadcast(msg);
     }
     /**
-     * Remove a tunnel
+     * Broadcast to all subscribed clients
      */
-    removeTunnel(id) {
-        return this.tunnels.delete(id);
+    broadcast(message) {
+        let count = 0;
+        for (const session of this.clients.values()) {
+            if (this.isConnected(session)) {
+                this.sendMessage(session, message);
+                count++;
+            }
+        }
+        console.log(`[RelayServer] Broadcast ${message.type} to ${count} client(s)`);
     }
     /**
-     * Check if server is running
+     * Check if client is connected and authenticated
      */
+    isConnected(session) {
+        return session.ws.readyState === WebSocket.OPEN &&
+            session.state.state === 'connected';
+    }
+    /**
+     * Send a typed message to a client
+     */
+    sendMessage(session, message) {
+        if (session.ws.readyState === WebSocket.OPEN) {
+            session.ws.send(JSON.stringify(message));
+        }
+    }
+    /**
+     * Send status to specific client
+     */
+    sendStatus(session, kind, code, message) {
+        const msg = {
+            version: PROTOCOL_VERSION,
+            type: 'status',
+            payload: { kind, code, message },
+            timestamp: createTimestamp(),
+            messageId: generateMessageId(),
+        };
+        this.sendMessage(session, msg);
+    }
+    // ========================================================================
+    // Public API
+    // ========================================================================
     isRunning() {
         return this.running;
     }
+    getClientCount() {
+        return this.clients.size;
+    }
+    getClients() {
+        return Array.from(this.clients.values()).map(s => ({
+            id: s.id,
+            state: s.state,
+            connectedAt: s.connectedAt,
+        }));
+    }
+    getRecentCallbacks(limit = 20) {
+        return this.recentCallbacks.slice(-limit);
+    }
+}
+// ============================================================================
+// Export for use in webhook server
+// ============================================================================
+export function createRelayServer(options) {
+    return new RelayServer(options);
 }