pi-harness-runtime 1.1.375 → 1.1.377

package/packages/relay/dist/ws-server.js

@@ -0,0 +1,130 @@
+/**
+ * WebSocket Relay Server - Pushes callbacks to connected clients in real-time
+ *
+ * Architecture:
+ *   Telegram/LINE → Webhook → This Server → WebSocket → Local Client
+ *
+ * No file queue needed - real-time streaming!
+ */
+import { createServer } from "node:http";
+import { WebSocketServer, WebSocket } from "ws";
+import { randomUUID } from "node:crypto";
+const AUTH_TOKEN = process.env.RELAY_AUTH_TOKEN || "change-me-in-production";
+/**
+ * WebSocket Relay Server
+ */
+export class WsRelayServer {
+    server = null;
+    wss = null;
+    clients = new Map();
+    port;
+    running = false;
+    constructor(port = 8444) {
+        this.port = port;
+    }
+    /**
+     * Start the WebSocket server
+     */
+    async start() {
+        if (this.running)
+            return;
+        this.server = createServer();
+        this.wss = new WebSocketServer({ server: this.server });
+        this.wss.on("connection", (ws, req) => {
+            const clientId = randomUUID();
+            console.log(`[WsRelay] Client connected: ${clientId} from ${req.socket.remoteAddress}`);
+            // Don't auth yet - just accept connection
+            // Client will send auth message
+            ws.on("message", (data) => {
+                try {
+                    const msg = JSON.parse(data.toString());
+                    this.handleMessage(ws, clientId, msg);
+                }
+                catch (err) {
+                    console.error("[WsRelay] Invalid message:", err);
+                }
+            });
+            ws.on("close", () => {
+                this.clients.delete(clientId);
+                console.log(`[WsRelay] Client disconnected: ${clientId}`);
+            });
+            ws.on("error", (err) => {
+                console.error(`[WsRelay] Client error: ${clientId}`, err);
+                this.clients.delete(clientId);
+            });
+            // Send welcome
+            ws.send(JSON.stringify({ type: "connected", payload: { clientId } }));
+        });
+        return new Promise((resolve) => {
+            this.server.listen(this.port, () => {
+                this.running = true;
+                console.log(`[WsRelay] Server started on port ${this.port}`);
+                resolve();
+            });
+        });
+    }
+    handleMessage(ws, clientId, msg) {
+        switch (msg.type) {
+            case "auth":
+                if (msg.payload === AUTH_TOKEN) {
+                    this.clients.set(clientId, ws);
+                    ws.send(JSON.stringify({ type: "auth", payload: { success: true } }));
+                    console.log(`[WsRelay] Client authenticated: ${clientId}`);
+                }
+                else {
+                    ws.send(JSON.stringify({ type: "auth", payload: { success: false, error: "Invalid token" } }));
+                    ws.close();
+                }
+                break;
+            case "ping":
+                ws.send(JSON.stringify({ type: "pong", payload: {} }));
+                break;
+        }
+    }
+    /**
+     * Broadcast callback to all connected clients
+     */
+    broadcastCallback(callback) {
+        const msg = JSON.stringify({ type: "callback", payload: callback });
+        let count = 0;
+        for (const [clientId, ws] of this.clients) {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.send(msg);
+                count++;
+            }
+        }
+        console.log(`[WsRelay] Broadcast callback to ${count} client(s): ${callback.action} ${callback.targetId}`);
+    }
+    /**
+     * Stop the server
+     */
+    async stop() {
+        if (!this.running)
+            return;
+        for (const ws of this.clients.values()) {
+            ws.close();
+        }
+        this.clients.clear();
+        return new Promise((resolve) => {
+            this.server.close(() => {
+                this.running = false;
+                console.log("[WsRelay] Server stopped");
+                resolve();
+            });
+        });
+    }
+    isRunning() {
+        return this.running;
+    }
+    getClientCount() {
+        return this.clients.size;
+    }
+}
+// Export singleton for use in unified webhook server
+let singleton = null;
+export function getRelayServer() {
+    if (!singleton) {
+        singleton = new WsRelayServer();
+    }
+    return singleton;
+}

package/packages/relay/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/relay",
-  "version": "1.1.375",
+  "version": "1.1.377",
   "type": "module",
   "description": "Cloud relay for remote access - T3 Connect style for pi-harness",
   "main": "./dist/index.js",

package/packages/relay/src/client.ts

@@ -1,119 +1,413 @@
 /**
- * Relay Client - Connect to relay server for remote access
+ * Relay Client - Two-way streaming WebSocket client
+ * 
+ * Implements t3code-style streaming with:
+ * - Connection state machine
+ * - Snapshot + live event handling
+ * - Typed message protocol
+ * - Automatic reconnection with backoff
  */
 
-import type { RelayConfig, RelayTunnel, RelayMessage } from './types.js';
+import WebSocket from "ws";
+import {
+  type RelayConfig,
+  type RelayTunnel,
+  type RelayMessage,
+  type ConnectionState,
+  type ConnectionStateChange,
+  type CallbackPayload,
+  type ServerMessage,
+  type ClientMessage,
+  type SnapshotMessage,
+  type SynchronizedMessage,
+  type CallbackMessage,
+  type StatusMessage,
+  type AuthResponseMessage,
+  type ConnectedMessage,
+  PROTOCOL_VERSION,
+  generateMessageId,
+  createTimestamp,
+} from './types.js';
 
-/**
- * Generate a UUID v4
- */
-function generateUUID(): string {
-  // Use crypto.randomUUID if available (Node.js 14.17+)
-  const crypto = globalThis as { crypto?: { randomUUID?: () => string } };
-  if (crypto.crypto?.randomUUID) {
-    return crypto.crypto.randomUUID();
-  }
-  // Fallback: simple UUID generation
-  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c: string) => {
-    const r = (Math.random() * 16) | 0;
-    const v = c === 'x' ? r : (r & 0x3) | 0x8;
-    return v.toString(16);
-  });
-}
+// ============================================================================
+// Constants
+// ============================================================================
 
-/**
- * Relay Client options
- */
-export interface RelayClientOptions {
-  /** Called when connected */
-  onConnected?: () => void;
+const DEFAULT_RECONNECT_DELAY_MS = 1000;
+const MAX_RECONNECT_DELAY_MS = 30000;
+const HEARTBEAT_INTERVAL_MS = 30000;
+const CONNECT_TIMEOUT_MS = 10000;
+
+// ============================================================================
+// Client Callbacks
+// ============================================================================
+
+export interface RelayClientCallbacks {
+  /** Called when connected and authenticated */
+  onConnected?: (sessionId: string) => void;
   /** Called when disconnected */
   onDisconnected?: () => void;
-  /** Called when tunnel is established */
-  onTunnel?: (tunnel: RelayTunnel) => void;
+  /** Called when snapshot is received (initial state) */
+  onSnapshot?: (snapshot: SnapshotMessage['payload']) => void;
+  /** Called when synchronized marker received (live events start) */
+  onSynchronized?: () => void;
+  /** Called when a callback event is received */
+  onCallback?: (callback: CallbackPayload) => void;
+  /** Called when a status message is received */
+  onStatus?: (status: StatusMessage['payload']) => void;
   /** Called on error */
   onError?: (error: Error) => void;
+  /** Called when connection state changes */
+  onStateChange?: (change: ConnectionStateChange) => void;
 }
 
-/**
- * Relay Client
- * 
- * Connects to a relay server and establishes tunnels for remote access.
- */
+// ============================================================================
+// Relay Client - Two-way Streaming Implementation
+// ============================================================================
+
 export class RelayClient {
+  private ws: WebSocket | null = null;
   private config: RelayConfig;
-  private options: RelayClientOptions;
-  private connected = false;
-  private tunnel?: RelayTunnel;
+  private callbacks: RelayClientCallbacks;
+  
+  // State machine
+  private state: ConnectionState = { state: 'disconnected' };
+  private sessionId: string | null = null;
+  private clientId: string | null = null;
+  
+  // Reconnection
+  private reconnectAttempt = 0;
+  private reconnectDelay = DEFAULT_RECONNECT_DELAY_MS;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private connectTimeoutTimer: ReturnType<typeof setTimeout> | null = null;
+  
+  // Heartbeat
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  
+  // Snapshot tracking (t3code pattern)
+  private snapshotReceived = false;
+  private synchronizedReceived = false;
 
-  constructor(config: RelayConfig, options: RelayClientOptions) {
+  constructor(config: RelayConfig, callbacks: RelayClientCallbacks = {}) {
     this.config = config;
-    this.options = options;
+    this.callbacks = callbacks;
+  }
+
+  // ========================================================================
+  // Connection State Machine
+  // ========================================================================
+
+  private setState(newState: ConnectionState): void {
+    const previous = this.state;
+    this.state = newState;
+    
+    this.callbacks.onStateChange?.({
+      previous,
+      current: newState,
+      timestamp: createTimestamp(),
+    });
   }
 
+  private isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN && 
+           this.state.state === 'connected';
+  }
+
+  // ========================================================================
+  // Lifecycle
+  // ========================================================================
+
   /**
-   * Connect to relay server
+   * Connect to relay server with automatic authentication
    */
   async connect(): Promise<void> {
-    if (this.connected) 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 as Error);
-      throw error;
-    }
+    if (this.isConnected()) return;
+    
+    // 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(): Promise<void> {
-    this.connected = false;
-    this.tunnel = undefined;
-    this.options.onDisconnected?.();
+  disconnect(): void {
+    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: number): Promise<RelayTunnel> {
-    const tunnel: RelayTunnel = {
-      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: ClientMessage): void {
+    if (this.isConnected()) {
+      this.ws!.send(JSON.stringify(message));
+    }
   }
 
-  /**
-   * Send a message through the tunnel
-   */
-  async send(_message: RelayMessage): Promise<void> {
-    if (!this.connected) {
-      throw new Error('Not connected to relay server');
+  // ========================================================================
+  // Message Handling
+  // ========================================================================
+
+  private handleMessage(data: string): void {
+    try {
+      const msg = JSON.parse(data) as ServerMessage & { type: string };
+      
+      switch (msg.type) {
+        case 'connected':
+          this.handleConnected(msg as ConnectedMessage);
+          break;
+
+        case 'auth':
+          this.handleAuth(msg as AuthResponseMessage);
+          break;
+
+        case 'snapshot':
+          this.handleSnapshot(msg as SnapshotMessage);
+          break;
+
+        case 'synchronized':
+          this.handleSynchronized(msg as SynchronizedMessage);
+          break;
+
+        case 'callback':
+          this.handleCallback(msg as CallbackMessage);
+          break;
+
+        case 'status':
+          this.handleStatus(msg as StatusMessage);
+          break;
+
+        case 'pong':
+          // Heartbeat response - connection is alive
+          break;
+
+        default: {
+          const unknownMsg = msg as { type: string };
+          console.warn(`[RelayClient] Unknown message type: ${unknownMsg.type}`);
+        }
+      }
+    } catch (err) {
+      console.error("[RelayClient] Failed to parse message:", err);
+      this.callbacks.onError?.(err as Error);
     }
-    // In a real implementation, this would send the message over WebSocket
   }
 
-  /**
-   * Check if connected
-   */
-  isConnected(): boolean {
-    return this.connected;
+  private handleConnected(msg: ConnectedMessage): void {
+    this.clientId = msg.payload.clientId;
+    console.log(`[RelayClient] Connected, clientId: ${this.clientId}`);
   }
 
-  /**
-   * Get current tunnel
-   */
-  getTunnel(): RelayTunnel | undefined {
-    return this.tunnel;
+  private handleAuth(msg: AuthResponseMessage): void {
+    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();
+    }
+  }
+
+  private handleSnapshot(msg: SnapshotMessage): void {
+    console.log(`[RelayClient] Snapshot received: ${msg.payload.recentCallbacks.length} recent callbacks`);
+    this.snapshotReceived = true;
+    
+    // Notify callback
+    this.callbacks.onSnapshot?.(msg.payload);
+  }
+
+  private handleSynchronized(_msg: SynchronizedMessage): void {
+    console.log("[RelayClient] Synchronized - live events starting");
+    this.synchronizedReceived = true;
+    
+    // Notify callback
+    this.callbacks.onSynchronized?.();
+  }
+
+  private handleCallback(msg: CallbackMessage): void {
+    // Only process callbacks after synchronized
+    if (!this.synchronizedReceived) {
+      console.warn("[RelayClient] Ignoring callback before synchronized");
+      return;
+    }
+    
+    this.callbacks.onCallback?.(msg.payload);
+  }
+
+  private handleStatus(msg: StatusMessage): void {
+    console.log(`[RelayClient] Status [${msg.payload.kind}]: ${msg.payload.code} - ${msg.payload.message}`);
+    this.callbacks.onStatus?.(msg.payload);
+  }
+
+  // ========================================================================
+  // Disconnect & Reconnect
+  // ========================================================================
+
+  private handleDisconnect(): void {
+    this.stopHeartbeat();
+    
+    const wasConnected = this.state.state === 'connected';
+    this.setState({ state: 'disconnected' });
+    
+    if (wasConnected) {
+      this.callbacks.onDisconnected?.();
+      this.scheduleReconnect();
+    }
+  }
+
+  private scheduleReconnect(): void {
+    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
+  // ========================================================================
+
+  private startHeartbeat(): void {
+    this.stopHeartbeat();
+    
+    this.heartbeatTimer = setInterval(() => {
+      if (this.isConnected()) {
+        this.send({
+          version: PROTOCOL_VERSION,
+          type: 'ping',
+          payload: {},
+          timestamp: createTimestamp(),
+        });
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  // ========================================================================
+  // Cleanup
+  // ========================================================================
+
+  private cleanup(): void {
+    // 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(): ConnectionState {
+    return this.state;
+  }
+
+  isReady(): boolean {
+    return this.isConnected() && this.synchronizedReceived;
+  }
+
+  getSessionId(): string | null {
+    return this.sessionId;
+  }
+
+  getClientId(): string | null {
+    return this.clientId;
   }
 }

package/packages/relay/src/index.ts

@@ -1,10 +1,47 @@
 /**
- * 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';
+export type { RelayServerOptions } from './server.js';
+
+// Client
 export { RelayClient } from './client.js';
-export { RelayConfig, RelayTunnel } from './types.js';
+export type { RelayClientCallbacks } from './client.js';
+
+// Types
+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';