pi-harness-runtime 1.1.375 → 1.1.377

package/packages/relay/dist/client.js

@@ -1,95 +1,302 @@
 /**
- * Relay Client - Connect to relay server for remote access
- */
-/**
- * Generate a UUID v4
- */
-function generateUUID() {
-    // Use crypto.randomUUID if available (Node.js 14.17+)
-    const crypto = globalThis;
-    if (crypto.crypto?.randomUUID) {
-        return crypto.crypto.randomUUID();
-    }
-    // Fallback: simple UUID generation
-    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 Client
+ * Relay Client - Two-way streaming WebSocket client
  *
- * Connects to a relay server and establishes tunnels for remote access.
+ * Implements t3code-style streaming with:
+ * - Connection state machine
+ * - Snapshot + live event handling
+ * - Typed message protocol
+ * - Automatic reconnection with backoff
  */
+import WebSocket from "ws";
+import { PROTOCOL_VERSION, createTimestamp, } from './types.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_RECONNECT_DELAY_MS = 1000;
+const MAX_RECONNECT_DELAY_MS = 30000;
+const HEARTBEAT_INTERVAL_MS = 30000;
+const CONNECT_TIMEOUT_MS = 10000;
+// ============================================================================
+// Relay Client - Two-way Streaming Implementation
+// ============================================================================
 export class RelayClient {
+    ws = null;
     config;
-    options;
-    connected = false;
-    tunnel;
-    constructor(config, options) {
+    callbacks;
+    // State machine
+    state = { state: 'disconnected' };
+    sessionId = null;
+    clientId = null;
+    // Reconnection
+    reconnectAttempt = 0;
+    reconnectDelay = DEFAULT_RECONNECT_DELAY_MS;
+    reconnectTimer = null;
+    connectTimeoutTimer = null;
+    // Heartbeat
+    heartbeatTimer = null;
+    // Snapshot tracking (t3code pattern)
+    snapshotReceived = false;
+    synchronizedReceived = false;
+    constructor(config, callbacks = {}) {
         this.config = config;
-        this.options = options;
+        this.callbacks = callbacks;
+    }
+    // ========================================================================
+    // Connection State Machine
+    // ========================================================================
+    setState(newState) {
+        const previous = this.state;
+        this.state = newState;
+        this.callbacks.onStateChange?.({
+            previous,
+            current: newState,
+            timestamp: createTimestamp(),
+        });
     }
+    isConnected() {
+        return this.ws?.readyState === WebSocket.OPEN &&
+            this.state.state === 'connected';
+    }
+    // ========================================================================
+    // Lifecycle
+    // ========================================================================
     /**
-     * Connect to relay server
+     * Connect to relay server with automatic authentication
      */
     async connect() {
-        if (this.connected)
+        if (this.isConnected())
             return;
-        try {
-            // In a real implementation, this would establish WebSocket connection
-            // to the relay server and authenticate
-            this.connected = true;
-            this.options.onConnected?.();
-        }
-        catch (error) {
-            this.options.onError?.(error);
-            throw error;
-        }
+        // Clear any existing connection
+        this.cleanup();
+        this.setState({ state: 'connecting' });
+        const url = this.config.serverUrl;
+        console.log(`[RelayClient] Connecting to ${url}...`);
+        return new Promise((resolve, reject) => {
+            // Set connect timeout
+            this.connectTimeoutTimer = setTimeout(() => {
+                if (this.state.state === 'connecting') {
+                    this.ws?.close();
+                    reject(new Error('Connection timeout'));
+                }
+            }, CONNECT_TIMEOUT_MS);
+            this.ws = new WebSocket(url);
+            this.ws.on("open", () => {
+                console.log("[RelayClient] WebSocket opened");
+                this.setState({ state: 'authenticating' });
+                // Send authentication
+                this.send({
+                    version: PROTOCOL_VERSION,
+                    type: 'auth',
+                    payload: { token: this.config.token || '' },
+                    timestamp: createTimestamp(),
+                });
+            });
+            this.ws.on("message", (data) => {
+                this.handleMessage(data.toString());
+            });
+            this.ws.on("close", () => {
+                console.log("[RelayClient] WebSocket closed");
+                this.handleDisconnect();
+            });
+            this.ws.on("error", (err) => {
+                console.error("[RelayClient] WebSocket error:", err.message);
+                this.callbacks.onError?.(err);
+                if (this.state.state === 'connecting' || this.state.state === 'authenticating') {
+                    clearTimeout(this.connectTimeoutTimer);
+                    reject(err);
+                }
+                this.handleDisconnect();
+            });
+        });
     }
     /**
      * Disconnect from relay server
      */
-    async disconnect() {
-        this.connected = false;
-        this.tunnel = undefined;
-        this.options.onDisconnected?.();
+    disconnect() {
+        console.log("[RelayClient] Disconnecting...");
+        this.cleanup();
+        this.setState({ state: 'disconnected' });
+        this.callbacks.onDisconnected?.();
     }
     /**
-     * Create a tunnel
+     * Send a message through the WebSocket
      */
-    async createTunnel(localPort) {
-        const tunnel = {
-            id: generateUUID(),
-            url: `${this.config.serverUrl}/tunnel/${localPort}`,
-            localPort,
-            status: this.connected ? 'connected' : 'disconnected',
-            createdAt: new Date().toISOString(),
-        };
-        this.tunnel = tunnel;
-        this.options.onTunnel?.(tunnel);
-        return tunnel;
+    send(message) {
+        if (this.isConnected()) {
+            this.ws.send(JSON.stringify(message));
+        }
     }
-    /**
-     * Send a message through the tunnel
-     */
-    async send(_message) {
-        if (!this.connected) {
-            throw new Error('Not connected to relay server');
+    // ========================================================================
+    // Message Handling
+    // ========================================================================
+    handleMessage(data) {
+        try {
+            const msg = JSON.parse(data);
+            switch (msg.type) {
+                case 'connected':
+                    this.handleConnected(msg);
+                    break;
+                case 'auth':
+                    this.handleAuth(msg);
+                    break;
+                case 'snapshot':
+                    this.handleSnapshot(msg);
+                    break;
+                case 'synchronized':
+                    this.handleSynchronized(msg);
+                    break;
+                case 'callback':
+                    this.handleCallback(msg);
+                    break;
+                case 'status':
+                    this.handleStatus(msg);
+                    break;
+                case 'pong':
+                    // Heartbeat response - connection is alive
+                    break;
+                default: {
+                    const unknownMsg = msg;
+                    console.warn(`[RelayClient] Unknown message type: ${unknownMsg.type}`);
+                }
+            }
+        }
+        catch (err) {
+            console.error("[RelayClient] Failed to parse message:", err);
+            this.callbacks.onError?.(err);
         }
-        // In a real implementation, this would send the message over WebSocket
     }
-    /**
-     * Check if connected
-     */
-    isConnected() {
-        return this.connected;
+    handleConnected(msg) {
+        this.clientId = msg.payload.clientId;
+        console.log(`[RelayClient] Connected, clientId: ${this.clientId}`);
     }
-    /**
-     * Get current tunnel
-     */
-    getTunnel() {
-        return this.tunnel;
+    handleAuth(msg) {
+        if (msg.payload.success) {
+            this.sessionId = msg.payload.sessionId || null;
+            this.setState({ state: 'connected', sessionId: this.sessionId || '' });
+            // Reset reconnection state
+            this.reconnectAttempt = 0;
+            this.reconnectDelay = DEFAULT_RECONNECT_DELAY_MS;
+            // Start heartbeat
+            this.startHeartbeat();
+            // Notify callback
+            this.callbacks.onConnected?.(this.sessionId || '');
+            console.log(`[RelayClient] Authenticated, sessionId: ${this.sessionId}`);
+        }
+        else {
+            console.error(`[RelayClient] Auth failed: ${msg.payload.error}`);
+            this.callbacks.onError?.(new Error(msg.payload.error || 'Authentication failed'));
+            this.disconnect();
+        }
+    }
+    handleSnapshot(msg) {
+        console.log(`[RelayClient] Snapshot received: ${msg.payload.recentCallbacks.length} recent callbacks`);
+        this.snapshotReceived = true;
+        // Notify callback
+        this.callbacks.onSnapshot?.(msg.payload);
+    }
+    handleSynchronized(_msg) {
+        console.log("[RelayClient] Synchronized - live events starting");
+        this.synchronizedReceived = true;
+        // Notify callback
+        this.callbacks.onSynchronized?.();
+    }
+    handleCallback(msg) {
+        // Only process callbacks after synchronized
+        if (!this.synchronizedReceived) {
+            console.warn("[RelayClient] Ignoring callback before synchronized");
+            return;
+        }
+        this.callbacks.onCallback?.(msg.payload);
+    }
+    handleStatus(msg) {
+        console.log(`[RelayClient] Status [${msg.payload.kind}]: ${msg.payload.code} - ${msg.payload.message}`);
+        this.callbacks.onStatus?.(msg.payload);
+    }
+    // ========================================================================
+    // Disconnect & Reconnect
+    // ========================================================================
+    handleDisconnect() {
+        this.stopHeartbeat();
+        const wasConnected = this.state.state === 'connected';
+        this.setState({ state: 'disconnected' });
+        if (wasConnected) {
+            this.callbacks.onDisconnected?.();
+            this.scheduleReconnect();
+        }
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        this.reconnectAttempt++;
+        this.setState({ state: 'reconnecting', attempt: this.reconnectAttempt });
+        console.log(`[RelayClient] Scheduling reconnect attempt ${this.reconnectAttempt} in ${this.reconnectDelay}ms`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect().catch((err) => {
+                console.error(`[RelayClient] Reconnect failed: ${err.message}`);
+            });
+        }, this.reconnectDelay);
+        // Exponential backoff
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, MAX_RECONNECT_DELAY_MS);
+    }
+    // ========================================================================
+    // Heartbeat
+    // ========================================================================
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            if (this.isConnected()) {
+                this.send({
+                    version: PROTOCOL_VERSION,
+                    type: 'ping',
+                    payload: {},
+                    timestamp: createTimestamp(),
+                });
+            }
+        }, HEARTBEAT_INTERVAL_MS);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    // ========================================================================
+    // Cleanup
+    // ========================================================================
+    cleanup() {
+        // Clear timers
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.connectTimeoutTimer) {
+            clearTimeout(this.connectTimeoutTimer);
+            this.connectTimeoutTimer = null;
+        }
+        this.stopHeartbeat();
+        // Reset snapshot state
+        this.snapshotReceived = false;
+        this.synchronizedReceived = false;
+        // Close WebSocket
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+    // ========================================================================
+    // Public API
+    // ========================================================================
+    getState() {
+        return this.state;
+    }
+    isReady() {
+        return this.isConnected() && this.synchronizedReceived;
+    }
+    getSessionId() {
+        return this.sessionId;
+    }
+    getClientId() {
+        return this.clientId;
     }
 }

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

@@ -1,9 +1,16 @@
 /**
- * Cloud Relay - T3 Connect Style
+ * Cloud Relay - Two-way Streaming Communication
  *
- * Enables remote access to pi-harness without router/port forwarding.
- * Based on T3Code's T3 Connect architecture.
+ * Enables real-time two-way communication with pi-harness without router/port forwarding.
+ * Based on T3Code's streaming architecture:
+ * - Snapshot + Live event pattern
+ * - Typed message protocol
+ * - Connection state machine
+ * - Stream coalescing
  */
-export { RelayServer } from './server.js';
+export { RelayServer, createRelayServer } from './server.js';
+export type { RelayServerOptions } from './server.js';
 export { RelayClient } from './client.js';
-export { RelayConfig, RelayTunnel } from './types.js';
+export type { RelayClientCallbacks } from './client.js';
+export { PROTOCOL_VERSION, generateMessageId, createTimestamp, } from './types.js';
+export type { RelayConfig, RelayTunnel, ConnectionState, ConnectionStateChange, BaseMessage, SnapshotMessage, SynchronizedMessage, CallbackPayload, CallbackMessage, StatusKind, StatusMessage, PingMessage, PongMessage, AuthRequestMessage, AuthResponseMessage, SubscribeMessage, ConnectedMessage, ServerMessage, ClientMessage, RelayMessage, } from './types.js';

package/packages/relay/dist/index.js

@@ -1,8 +1,16 @@
 /**
- * Cloud Relay - T3 Connect Style
+ * Cloud Relay - Two-way Streaming Communication
  *
- * Enables remote access to pi-harness without router/port forwarding.
- * Based on T3Code's T3 Connect architecture.
+ * Enables real-time two-way communication with pi-harness without router/port forwarding.
+ * Based on T3Code's streaming architecture:
+ * - Snapshot + Live event pattern
+ * - Typed message protocol
+ * - Connection state machine
+ * - Stream coalescing
  */
-export { RelayServer } from './server.js';
+// Server
+export { RelayServer, createRelayServer } from './server.js';
+// Client
 export { RelayClient } from './client.js';
+// Types
+export { PROTOCOL_VERSION, generateMessageId, createTimestamp, } from './types.js';

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;