pi-harness-runtime 1.1.375 → 1.1.377

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);
 }

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/dist/ws-server.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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!
+ */
+export interface RelayMessage {
+    type: "callback" | "ping" | "pong" | "auth";
+    payload: unknown;
+}
+export interface CallbackPayload {
+    type: "telegram_callback" | "line_callback";
+    action: string;
+    targetId: string;
+    userId: number;
+    username?: string;
+    messageId?: number;
+    timestamp: string;
+}
+/**
+ * WebSocket Relay Server
+ */
+export declare class WsRelayServer {
+    private server;
+    private wss;
+    private clients;
+    private port;
+    private running;
+    constructor(port?: number);
+    /**
+     * Start the WebSocket server
+     */
+    start(): Promise<void>;
+    private handleMessage;
+    /**
+     * Broadcast callback to all connected clients
+     */
+    broadcastCallback(callback: CallbackPayload): void;
+    /**
+     * Stop the server
+     */
+    stop(): Promise<void>;
+    isRunning(): boolean;
+    getClientCount(): number;
+}
+export declare function getRelayServer(): WsRelayServer;