@shykaruu/jarvis-brain 0.4.0

package/src/sidecar/connection.ts

@@ -0,0 +1,179 @@
+/**
+ * Sidecar Connection — Per-Sidecar WebSocket Wrapper
+ *
+ * Manages a single sidecar's WebSocket connection, including message
+ * parsing, validation, binary frame correlation, and heartbeat.
+ */
+
+import type { ServerWebSocket } from 'bun';
+import type { RPCRequest, SidecarEvent } from './protocol.ts';
+import type { EventScheduler } from './scheduler.ts';
+import { validateEvent, validateBinaryFrame, MAX_JSON_SIZE } from './validator.ts';
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const MAX_MISSED_PONGS = 3;
+const BINARY_WAIT_TIMEOUT_MS = 5_000;
+
+interface PendingBinary {
+  resolve: (payload: Buffer) => void;
+  reject: (error: Error) => void;
+  timer: Timer;
+}
+
+export class SidecarConnection {
+  readonly sidecarId: string;
+  private ws: ServerWebSocket<unknown>;
+  private scheduler: EventScheduler;
+  private pendingBinary = new Map<string, PendingBinary>();
+  private heartbeatTimer: Timer | null = null;
+  private missedPongs = 0;
+  private alive = true;
+  private onDisconnect: () => void;
+
+  constructor(
+    sidecarId: string,
+    ws: ServerWebSocket<unknown>,
+    scheduler: EventScheduler,
+    onDisconnect: () => void,
+  ) {
+    this.sidecarId = sidecarId;
+    this.ws = ws;
+    this.scheduler = scheduler;
+    this.onDisconnect = onDisconnect;
+  }
+
+  /** Send an RPC request to the sidecar */
+  sendRPC(request: RPCRequest): void {
+    try {
+      this.ws.send(JSON.stringify(request));
+    } catch (err) {
+      console.error(`[SidecarConnection:${this.sidecarId}] Failed to send RPC:`, err);
+    }
+  }
+
+  /** Handle an inbound text (JSON) message */
+  async handleMessage(raw: string): Promise<void> {
+    if (raw.length > MAX_JSON_SIZE) {
+      console.warn(`[SidecarConnection:${this.sidecarId}] Message too large: ${raw.length} bytes`);
+      return;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      console.warn(`[SidecarConnection:${this.sidecarId}] Invalid JSON`);
+      return;
+    }
+
+    const result = validateEvent(parsed);
+    if (!result.valid || !result.event) {
+      console.warn(`[SidecarConnection:${this.sidecarId}] Validation failed: ${result.error}`);
+      return;
+    }
+
+    const event = result.event;
+
+    // If event references binary data via ref, wait for the binary frame
+    if (event.binary?.type === 'ref') {
+      const refId = event.binary.ref_id;
+      try {
+        const binaryPayload = await this.waitForBinary(refId);
+        // Attach resolved binary data to the event payload
+        (event.payload as Record<string, unknown>)._binary = binaryPayload;
+      } catch (err) {
+        console.warn(`[SidecarConnection:${this.sidecarId}] Binary wait failed for ${refId}:`, err);
+        return;
+      }
+    }
+
+    this.scheduler.enqueue(this.sidecarId, event, event.priority);
+  }
+
+  /** Handle an inbound binary frame */
+  handleBinary(data: Buffer): void {
+    const result = validateBinaryFrame(data);
+    if (!result.valid || !result.refId) {
+      console.warn(`[SidecarConnection:${this.sidecarId}] Invalid binary frame: ${result.error}`);
+      return;
+    }
+
+    const pending = this.pendingBinary.get(result.refId);
+    if (pending) {
+      clearTimeout(pending.timer);
+      this.pendingBinary.delete(result.refId);
+      pending.resolve(result.payload!);
+    } else {
+      console.warn(`[SidecarConnection:${this.sidecarId}] Unexpected binary ref: ${result.refId}`);
+    }
+  }
+
+  /** Start heartbeat ping/pong */
+  startHeartbeat(): void {
+    this.missedPongs = 0;
+    this.alive = true;
+
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.alive) {
+        this.missedPongs++;
+        if (this.missedPongs >= MAX_MISSED_PONGS) {
+          console.warn(`[SidecarConnection:${this.sidecarId}] ${MAX_MISSED_PONGS} missed pongs, disconnecting`);
+          this.close();
+          this.onDisconnect();
+          return;
+        }
+      }
+
+      this.alive = false;
+      try {
+        this.ws.ping();
+      } catch {
+        this.close();
+        this.onDisconnect();
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  /** Called when a pong is received */
+  handlePong(): void {
+    this.alive = true;
+    this.missedPongs = 0;
+  }
+
+  /** Stop heartbeat */
+  stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  /** Close connection and clean up */
+  close(): void {
+    this.stopHeartbeat();
+
+    // Reject all pending binary waits
+    for (const [refId, pending] of this.pendingBinary) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error('Connection closed'));
+    }
+    this.pendingBinary.clear();
+
+    try {
+      this.ws.close();
+    } catch {
+      // Already closed
+    }
+  }
+
+  private waitForBinary(refId: string): Promise<Buffer> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingBinary.delete(refId);
+        reject(new Error(`Binary frame timeout for ref ${refId}`));
+      }, BINARY_WAIT_TIMEOUT_MS);
+
+      this.pendingBinary.set(refId, { resolve, reject, timer });
+    });
+  }
+}

package/src/sidecar/index.ts

@@ -0,0 +1,6 @@
+export { SidecarManager } from './manager.ts';
+export { EventScheduler } from './scheduler.ts';
+export { RPCTracker } from './rpc.ts';
+export { SidecarConnection } from './connection.ts';
+export type * from './types.ts';
+export type * from './protocol.ts';