pi-harness-runtime 1.1.376 → 1.1.377

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

@@ -1,5 +1,5 @@
 /**
- * Relay Types
+ * Relay Types - Two-way Streaming Communication
  */
 export interface RelayConfig {
     /** Relay server URL */
@@ -27,6 +27,142 @@ export interface RelayTunnel {
     /** Error message if any */
     error?: string;
 }
+export type ConnectionState = {
+    state: 'disconnected';
+} | {
+    state: 'connecting';
+} | {
+    state: 'authenticating';
+} | {
+    state: 'connected';
+    sessionId: string;
+} | {
+    state: 'reconnecting';
+    attempt: number;
+} | {
+    state: 'error';
+    error: string;
+};
+export interface ConnectionStateChange {
+    previous: ConnectionState;
+    current: ConnectionState;
+    timestamp: string;
+}
+/**
+ * Protocol version for typed streaming
+ */
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * Generate a unique message ID
+ */
+export declare function generateMessageId(): string;
+/**
+ * Create a timestamp
+ */
+export declare function createTimestamp(): string;
+/**
+ * Base message interface
+ */
+export interface BaseMessage<T extends string, P = unknown> {
+    version: typeof PROTOCOL_VERSION;
+    type: T;
+    payload: P;
+    timestamp: string;
+    messageId?: string;
+}
+/**
+ * Server -> Client: Initial state snapshot sent on connect
+ */
+export interface SnapshotMessage extends BaseMessage<'snapshot'> {
+    payload: {
+        sessionId: string;
+        serverVersion: string;
+        connectedClients: number;
+        recentCallbacks: CallbackPayload[];
+    };
+}
+/**
+ * Server -> Client: Synchronization marker (indicates all initial state sent)
+ */
+export interface SynchronizedMessage extends BaseMessage<'synchronized'> {
+}
+/**
+ * Callback types from Telegram/LINE
+ */
+export interface CallbackPayload {
+    id: string;
+    type: 'telegram_callback' | 'line_callback';
+    action: string;
+    targetId: string;
+    userId: number;
+    username?: string;
+    messageId?: number;
+    timestamp: string;
+}
+/**
+ * Server -> Client: Live callback event (after synchronized)
+ */
+export interface CallbackMessage extends BaseMessage<'callback'> {
+    payload: CallbackPayload;
+}
+/**
+ * Server -> Client: Status update
+ */
+export type StatusKind = 'info' | 'warning' | 'error';
+export interface StatusMessage extends BaseMessage<'status'> {
+    payload: {
+        kind: StatusKind;
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Heartbeat messages
+ */
+export interface PingMessage extends BaseMessage<'ping'> {
+}
+export interface PongMessage extends BaseMessage<'pong'> {
+}
+/**
+ * Authentication messages
+ */
+export interface AuthRequestMessage extends BaseMessage<'auth'> {
+    payload: {
+        token: string;
+    };
+}
+export interface AuthResponseMessage extends BaseMessage<'auth'> {
+    payload: {
+        success: boolean;
+        sessionId?: string;
+        error?: string;
+    };
+}
+/**
+ * Client -> Server: Subscribe to specific event types
+ */
+export interface SubscribeMessage extends BaseMessage<'subscribe'> {
+    payload: {
+        events: ('callback' | 'status' | 'sync')[];
+    };
+}
+/**
+ * Connection acknowledged by server
+ */
+export interface ConnectedMessage extends BaseMessage<'connected'> {
+    payload: {
+        clientId: string;
+        serverTime: string;
+    };
+}
+/**
+ * Union type of all server -> client messages
+ */
+export type ServerMessage = SnapshotMessage | SynchronizedMessage | CallbackMessage | StatusMessage | PongMessage | ConnectedMessage | AuthResponseMessage;
+/**
+ * Union type of all client -> server messages
+ */
+export type ClientMessage = AuthRequestMessage | PingMessage | SubscribeMessage;
 export interface RelayMessage {
     type: 'connect' | 'disconnect' | 'data' | 'ping' | 'pong' | 'error';
     tunnelId?: string;

package/packages/relay/dist/types.js

@@ -1,4 +1,23 @@
 /**
- * Relay Types
+ * Relay Types - Two-way Streaming Communication
  */
-export {};
+import { randomUUID } from "node:crypto";
+// ============================================================================
+// Typed Streaming Protocol
+// ============================================================================
+/**
+ * Protocol version for typed streaming
+ */
+export const PROTOCOL_VERSION = 1;
+/**
+ * Generate a unique message ID
+ */
+export function generateMessageId() {
+    return randomUUID();
+}
+/**
+ * Create a timestamp
+ */
+export function createTimestamp() {
+    return new Date().toISOString();
+}

package/packages/relay/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/relay",
-  "version": "1.1.376",
+  "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;
   }
 }