@hellcoder/companion 0.96.0

package/server/relay-client.test.ts

@@ -0,0 +1,337 @@
+import { vi, describe, it, expect, beforeEach, afterEach } from "vitest";
+import { RelayClient } from "./relay-client.js";
+
+// ─── Mock WebSocket ─────────────────────────────────────────────────────────
+
+/** Minimal mock WebSocket with event listener support for testing. */
+class MockWebSocket {
+  static OPEN = 1;
+  static CLOSED = 3;
+
+  readyState = MockWebSocket.OPEN;
+  private listeners = new Map<string, Set<Function>>();
+
+  sent: string[] = [];
+
+  constructor(public url: string) {
+    // Auto-fire "open" on next tick so tests can add listeners first
+    setTimeout(() => this.fireEvent("open", {}), 0);
+  }
+
+  addEventListener(event: string, fn: Function) {
+    if (!this.listeners.has(event)) this.listeners.set(event, new Set());
+    this.listeners.get(event)!.add(fn);
+  }
+
+  removeEventListener(event: string, fn: Function) {
+    this.listeners.get(event)?.delete(fn);
+  }
+
+  send(data: string) {
+    this.sent.push(data);
+  }
+
+  close(_code?: number, _reason?: string) {
+    this.readyState = MockWebSocket.CLOSED;
+    this.fireEvent("close", { code: _code || 1000, reason: _reason || "" });
+  }
+
+  /** Helper: simulate receiving a message from the relay. */
+  simulateMessage(data: string) {
+    this.fireEvent("message", { data });
+  }
+
+  /** Helper: simulate the connection closing. */
+  simulateClose(code = 1006, reason = "") {
+    this.readyState = MockWebSocket.CLOSED;
+    this.fireEvent("close", { code, reason });
+  }
+
+  private fireEvent(event: string, detail: Record<string, unknown>) {
+    this.listeners.get(event)?.forEach((fn) => fn(detail));
+  }
+}
+
+// Replace global WebSocket with mock
+let capturedWs: MockWebSocket | null = null;
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  capturedWs = null;
+
+  // Capture the WebSocket constructor call so we can interact with the instance
+  vi.stubGlobal("WebSocket", class extends MockWebSocket {
+    constructor(url: string) {
+      super(url);
+      capturedWs = this;
+    }
+    static OPEN = 1;
+    static CLOSED = 3;
+  });
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function createMockRouter() {
+  return {
+    webhooks: {} as Record<string, (req: Request, opts?: { waitUntil?: (task: Promise<unknown>) => void }) => Promise<Response>>,
+  };
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe("RelayClient", () => {
+  describe("connect()", () => {
+    it("builds the correct WebSocket URL from an HTTPS relay URL", () => {
+      const router = createMockRouter();
+      const client = new RelayClient(
+        "https://relay.example.com",
+        "my-secret",
+        router as any,
+      );
+
+      client.connect();
+
+      // The WebSocket should be constructed with wss:// and the secret in the query param
+      expect(capturedWs).not.toBeNull();
+      expect(capturedWs!.url).toBe("wss://relay.example.com/ws/relay?secret=my-secret");
+    });
+
+    it("converts HTTP relay URL to WS (not WSS)", () => {
+      const router = createMockRouter();
+      const client = new RelayClient(
+        "http://localhost:8787",
+        "dev-secret",
+        router as any,
+      );
+
+      client.connect();
+
+      expect(capturedWs!.url).toBe("ws://localhost:8787/ws/relay?secret=dev-secret");
+    });
+
+    it("redacts the secret from log output", () => {
+      const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const router = createMockRouter();
+      const client = new RelayClient(
+        "https://relay.example.com",
+        "super-secret-value",
+        router as any,
+      );
+
+      client.connect();
+
+      // The log message should contain the URL but with the secret redacted
+      const logCall = logSpy.mock.calls.find((args) =>
+        typeof args[0] === "string" && args[0].includes("[relay-client] Connecting to"),
+      );
+      expect(logCall).toBeDefined();
+      expect(logCall![0]).not.toContain("super-secret-value");
+      expect(logCall![0]).toContain("secret=***");
+
+      logSpy.mockRestore();
+    });
+
+    it("strips trailing slashes from the relay URL", () => {
+      const router = createMockRouter();
+      const client = new RelayClient(
+        "https://relay.example.com///",
+        "s",
+        router as any,
+      );
+
+      client.connect();
+
+      expect(capturedWs!.url).toBe("wss://relay.example.com/ws/relay?secret=s");
+    });
+  });
+
+  describe("disconnect()", () => {
+    it("closes the WebSocket and prevents reconnection", async () => {
+      const router = createMockRouter();
+      const client = new RelayClient("https://relay.example.com", "s", router as any);
+
+      client.connect();
+      await vi.advanceTimersByTimeAsync(0); // let "open" event fire
+
+      expect(capturedWs!.readyState).toBe(MockWebSocket.OPEN);
+
+      client.disconnect();
+
+      // After disconnect, the WebSocket should be closed
+      expect(capturedWs!.readyState).toBe(MockWebSocket.CLOSED);
+    });
+  });
+
+  describe("handleWebhookRequest()", () => {
+    it("forwards a webhook request to the handler and sends back the response", async () => {
+      const router = createMockRouter();
+      router.webhooks = {
+        github: vi.fn(async () => new Response("OK", { status: 200 })),
+      };
+
+      const client = new RelayClient("https://relay.example.com", "s", router as any);
+      client.connect();
+      await vi.advanceTimersByTimeAsync(0);
+
+      // handleWebhookRequest is private, but we can trigger it via a message
+      capturedWs!.simulateMessage(JSON.stringify({
+        type: "webhook_request",
+        requestId: "req-1",
+        platform: "github",
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: '{"event":"test"}',
+      }));
+
+      // Wait for async processing
+      await vi.advanceTimersByTimeAsync(10);
+
+      // The webhook handler should have been called
+      expect(router.webhooks.github).toHaveBeenCalledTimes(1);
+
+      // The relay client should have sent a webhook_response back
+      expect(capturedWs!.sent).toHaveLength(1);
+      const response = JSON.parse(capturedWs!.sent[0]);
+      expect(response.type).toBe("webhook_response");
+      expect(response.requestId).toBe("req-1");
+      expect(response.status).toBe(200);
+    });
+
+    it("returns 404 when no handler exists for the requested platform", async () => {
+      const router = createMockRouter();
+      router.webhooks = {}; // No handlers
+
+      const client = new RelayClient("https://relay.example.com", "s", router as any);
+      client.connect();
+      await vi.advanceTimersByTimeAsync(0);
+
+      capturedWs!.simulateMessage(JSON.stringify({
+        type: "webhook_request",
+        requestId: "req-2",
+        platform: "unknown-platform",
+        method: "POST",
+        headers: {},
+        body: "",
+      }));
+
+      await vi.advanceTimersByTimeAsync(10);
+
+      expect(capturedWs!.sent).toHaveLength(1);
+      const response = JSON.parse(capturedWs!.sent[0]);
+      expect(response.type).toBe("webhook_response");
+      expect(response.requestId).toBe("req-2");
+      expect(response.status).toBe(404);
+    });
+
+    it("returns 500 when the webhook handler throws", async () => {
+      const router = createMockRouter();
+      router.webhooks = {
+        github: vi.fn(async () => { throw new Error("boom"); }),
+      };
+
+      const client = new RelayClient("https://relay.example.com", "s", router as any);
+      client.connect();
+      await vi.advanceTimersByTimeAsync(0);
+
+      capturedWs!.simulateMessage(JSON.stringify({
+        type: "webhook_request",
+        requestId: "req-3",
+        platform: "github",
+        method: "POST",
+        headers: {},
+        body: "test",
+      }));
+
+      await vi.advanceTimersByTimeAsync(10);
+
+      expect(capturedWs!.sent).toHaveLength(1);
+      const response = JSON.parse(capturedWs!.sent[0]);
+      expect(response.status).toBe(500);
+    });
+  });
+
+  describe("message handling", () => {
+    it("ignores unknown message types", async () => {
+      const router = createMockRouter();
+      const client = new RelayClient("https://relay.example.com", "s", router as any);
+      client.connect();
+      await vi.advanceTimersByTimeAsync(0);
+
+      // Should not throw or send any response
+      capturedWs!.simulateMessage(JSON.stringify({ type: "unknown_type" }));
+      await vi.advanceTimersByTimeAsync(10);
+
+      expect(capturedWs!.sent).toHaveLength(0);
+    });
+
+    it("ignores malformed JSON messages", async () => {
+      const router = createMockRouter();
+      const client = new RelayClient("https://relay.example.com", "s", router as any);
+      client.connect();
+      await vi.advanceTimersByTimeAsync(0);
+
+      // Should not throw
+      capturedWs!.simulateMessage("not valid json {{{");
+      await vi.advanceTimersByTimeAsync(10);
+
+      expect(capturedWs!.sent).toHaveLength(0);
+    });
+
+    it("ignores malformed webhook_request (missing required fields)", async () => {
+      const router = createMockRouter();
+      const client = new RelayClient("https://relay.example.com", "s", router as any);
+      client.connect();
+      await vi.advanceTimersByTimeAsync(0);
+
+      // Missing platform, method, headers, body
+      capturedWs!.simulateMessage(JSON.stringify({ type: "webhook_request", requestId: "r" }));
+      await vi.advanceTimersByTimeAsync(10);
+
+      expect(capturedWs!.sent).toHaveLength(0);
+    });
+  });
+
+  describe("reconnection", () => {
+    it("schedules a reconnection when the WebSocket closes unexpectedly", async () => {
+      const router = createMockRouter();
+      const client = new RelayClient("https://relay.example.com", "s", router as any);
+
+      client.connect();
+      await vi.advanceTimersByTimeAsync(0);
+
+      const firstWs = capturedWs!;
+      firstWs.simulateClose(1006, "abnormal");
+
+      // After 1s (initial backoff), a new connection attempt should be made
+      await vi.advanceTimersByTimeAsync(1000);
+
+      // A new WebSocket should have been created
+      expect(capturedWs).not.toBe(firstWs);
+    });
+
+    it("does not reconnect after an intentional disconnect", async () => {
+      const router = createMockRouter();
+      const client = new RelayClient("https://relay.example.com", "s", router as any);
+
+      client.connect();
+      await vi.advanceTimersByTimeAsync(0);
+
+      const firstWs = capturedWs!;
+      client.disconnect();
+
+      // Advance well past the reconnect delay
+      await vi.advanceTimersByTimeAsync(60000);
+
+      // Should still be the same (closed) WebSocket — no new connection created
+      // (capturedWs may be a new reference from disconnect's close(), but no connect() should follow)
+      // The key test: no new open event or connection attempt
+      expect(capturedWs!.readyState).toBe(MockWebSocket.CLOSED);
+    });
+  });
+});

package/server/relay-client.ts

@@ -0,0 +1,320 @@
+// ─── Relay Client ────────────────────────────────────────────────────────────
+// Connects The Companion to a cloud relay worker via outbound WebSocket.
+// This allows a Companion instance running behind a firewall (NAT, no public IP)
+// to receive external webhooks relayed through a cloud worker.
+//
+// Flow:
+//   Companion --[outbound WS]--> Relay Worker <--[HTTPS webhooks]-- External platforms
+//   Companion receives webhook_request messages, processes them locally,
+//   and sends webhook_response messages back through the same WebSocket.
+
+type WebhookHandler = (req: Request, opts?: { waitUntil?: (task: Promise<unknown>) => void }) => Promise<Response>;
+
+/** Generic interface for webhook routing in the relay client */
+export interface RelayWebhookRouter {
+  /** Global webhook handlers keyed by platform name */
+  webhooks: Record<string, WebhookHandler>;
+  /** Get a webhook handler for a specific agent + platform combination */
+  getWebhookHandler?: (agentId: string, platform: string) => WebhookHandler | null;
+}
+
+/** Inbound message from the relay worker containing a webhook to process */
+interface WebhookRequestMessage {
+  type: "webhook_request";
+  requestId: string;
+  platform: string;
+  /** Optional agent ID for agent-scoped webhook routing */
+  agentId?: string;
+  method: string;
+  headers: Record<string, string>;
+  body: string;
+}
+
+/** Outbound message sent back to the relay worker with the webhook response */
+interface WebhookResponseMessage {
+  type: "webhook_response";
+  requestId: string;
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+}
+
+/** Any message that may arrive from the relay worker */
+type RelayIncomingMessage = WebhookRequestMessage | { type: string; [key: string]: unknown };
+
+const MIN_RECONNECT_DELAY_MS = 1_000;
+const MAX_RECONNECT_DELAY_MS = 30_000;
+
+export class RelayClient {
+  private relayUrl: string;
+  private relaySecret: string;
+  private router: RelayWebhookRouter;
+
+  private ws: WebSocket | null = null;
+  private reconnectDelay = MIN_RECONNECT_DELAY_MS;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private intentionalDisconnect = false;
+
+  constructor(relayUrl: string, relaySecret: string, router: RelayWebhookRouter) {
+    this.relayUrl = relayUrl;
+    this.relaySecret = relaySecret;
+    this.router = router;
+  }
+
+  /**
+   * Open a WebSocket connection to the relay worker.
+   * Automatically reconnects with exponential backoff on disconnection.
+   */
+  connect(): void {
+    this.intentionalDisconnect = false;
+    this.clearReconnectTimer();
+
+    // Convert http(s) URL to ws(s) URL
+    const wsUrl = this.buildWsUrl();
+    const displayUrl = wsUrl.replace(/([?&])(secret)=[^&]*/gi, "$1$2=***");
+    console.log(`[relay-client] Connecting to ${displayUrl}`);
+
+    try {
+      this.ws = new WebSocket(wsUrl);
+    } catch (err) {
+      console.log(`[relay-client] Failed to create WebSocket: ${err instanceof Error ? err.message : String(err)}`);
+      this.scheduleReconnect();
+      return;
+    }
+
+    this.ws.addEventListener("open", () => {
+      console.log("[relay-client] Connected to relay worker");
+      this.resetBackoff();
+    });
+
+    this.ws.addEventListener("message", (event: MessageEvent) => {
+      this.handleRawMessage(event.data);
+    });
+
+    this.ws.addEventListener("close", (event: CloseEvent) => {
+      console.log(`[relay-client] Connection closed (code=${event.code}, reason=${event.reason || "none"})`);
+      this.ws = null;
+
+      if (!this.intentionalDisconnect) {
+        this.scheduleReconnect();
+      }
+    });
+
+    this.ws.addEventListener("error", (event: Event) => {
+      // The error event does not carry much detail in browser-style WebSocket API;
+      // the subsequent close event will trigger reconnection.
+      console.log(`[relay-client] WebSocket error: ${String(event)}`);
+    });
+  }
+
+  /**
+   * Gracefully close the connection and stop reconnection attempts.
+   */
+  disconnect(): void {
+    this.intentionalDisconnect = true;
+    this.clearReconnectTimer();
+
+    if (this.ws) {
+      console.log("[relay-client] Disconnecting from relay worker");
+      try {
+        this.ws.close(1000, "Client shutting down");
+      } catch {
+        // Ignore errors on close — socket may already be closed
+      }
+      this.ws = null;
+    }
+  }
+
+  /**
+   * Handle a parsed webhook_request message by forwarding it to the webhook router
+   * and sending the response back to the relay worker.
+   */
+  async handleWebhookRequest(msg: WebhookRequestMessage): Promise<void> {
+    const { requestId, platform, agentId, method, headers, body } = msg;
+
+    // Route to agent-scoped handler if agentId is provided, otherwise use global handler
+    const webhookHandler = agentId
+      ? this.router.getWebhookHandler?.(agentId, platform) ?? null
+      : this.router.webhooks[platform];
+
+    if (!webhookHandler) {
+      const target = agentId ? `agent "${agentId}" / platform "${platform}"` : `platform "${platform}"`;
+      console.log(`[relay-client] No webhook handler for ${target}, returning 404`);
+      this.sendWebhookResponse({
+        type: "webhook_response",
+        requestId,
+        status: 404,
+        headers: {},
+        body: `No webhook handler for ${target}`,
+      });
+      return;
+    }
+
+    try {
+      // Construct a Request object from the relayed data
+      const hasBody = method !== "GET" && method !== "HEAD" && body;
+      const request = new Request(`https://relay-proxy/${platform}`, {
+        method,
+        headers: new Headers(headers),
+        body: hasBody ? body : undefined,
+      });
+
+      // Execute the webhook handler
+      const response = await webhookHandler(request, {
+        waitUntil: (task: Promise<unknown>) => {
+          task.catch((err) => console.error("[relay-client] Background task error:", err));
+        },
+      });
+
+      // Extract response details
+      const responseBody = await response.text();
+      const responseHeaders: Record<string, string> = {};
+      response.headers.forEach((value, key) => {
+        responseHeaders[key] = value;
+      });
+
+      this.sendWebhookResponse({
+        type: "webhook_response",
+        requestId,
+        status: response.status,
+        headers: responseHeaders,
+        body: responseBody,
+      });
+    } catch (err) {
+      console.log(`[relay-client] Error processing webhook for platform "${platform}": ${err instanceof Error ? err.message : String(err)}`);
+      this.sendWebhookResponse({
+        type: "webhook_response",
+        requestId,
+        status: 500,
+        headers: {},
+        body: "Internal error",
+      });
+    }
+  }
+
+  // ─── Private helpers ─────────────────────────────────────────────────────────
+
+  /**
+   * Build the WebSocket URL from the relay HTTP URL.
+   * Converts https:// to wss:// and http:// to ws://.
+   */
+  private buildWsUrl(): string {
+    let url = this.relayUrl;
+
+    if (url.startsWith("https://")) {
+      url = "wss://" + url.slice("https://".length);
+    } else if (url.startsWith("http://")) {
+      url = "ws://" + url.slice("http://".length);
+    }
+
+    // Remove trailing slash if present before appending path
+    url = url.replace(/\/+$/, "");
+
+    // NOTE: The secret is passed as a query param for simplicity. This means
+    // it may appear in relay-side HTTP access logs. For higher security, migrate
+    // to an auth-frame approach (send secret as the first WebSocket message after
+    // connection opens). Rotate the secret regularly if using this approach.
+    return `${url}/ws/relay?secret=${encodeURIComponent(this.relaySecret)}`;
+  }
+
+  /**
+   * Parse and route an incoming raw WebSocket message.
+   */
+  private handleRawMessage(data: unknown): void {
+    let parsed: RelayIncomingMessage;
+
+    try {
+      const text = typeof data === "string" ? data : String(data);
+      parsed = JSON.parse(text) as RelayIncomingMessage;
+    } catch (err) {
+      console.log(`[relay-client] Failed to parse message: ${err instanceof Error ? err.message : String(err)}`);
+      return;
+    }
+
+    if (!parsed || typeof parsed.type !== "string") {
+      console.log("[relay-client] Received message without a valid type field, ignoring");
+      return;
+    }
+
+    switch (parsed.type) {
+      case "webhook_request":
+        // Validate required fields before processing
+        if (!this.isValidWebhookRequest(parsed)) {
+          console.log("[relay-client] Received malformed webhook_request, ignoring");
+          return;
+        }
+        // Fire-and-forget: errors are caught inside handleWebhookRequest
+        void this.handleWebhookRequest(parsed as WebhookRequestMessage);
+        break;
+
+      default:
+        console.log(`[relay-client] Received unknown message type: ${parsed.type}`);
+        break;
+    }
+  }
+
+  /**
+   * Validate that a parsed message has all required webhook_request fields.
+   */
+  private isValidWebhookRequest(msg: RelayIncomingMessage): msg is WebhookRequestMessage {
+    return (
+      msg.type === "webhook_request" &&
+      typeof (msg as WebhookRequestMessage).requestId === "string" &&
+      typeof (msg as WebhookRequestMessage).platform === "string" &&
+      typeof (msg as WebhookRequestMessage).method === "string" &&
+      typeof (msg as WebhookRequestMessage).headers === "object" &&
+      (msg as WebhookRequestMessage).headers !== null &&
+      typeof (msg as WebhookRequestMessage).body === "string"
+    );
+  }
+
+  /**
+   * Send a webhook response message back through the WebSocket.
+   */
+  private sendWebhookResponse(response: WebhookResponseMessage): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      console.log(`[relay-client] Cannot send response for ${response.requestId}: WebSocket not open`);
+      return;
+    }
+
+    try {
+      this.ws.send(JSON.stringify(response));
+    } catch (err) {
+      console.log(`[relay-client] Failed to send response for ${response.requestId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  /**
+   * Schedule a reconnection attempt with exponential backoff.
+   */
+  private scheduleReconnect(): void {
+    if (this.intentionalDisconnect) return;
+
+    const delay = this.reconnectDelay;
+    console.log(`[relay-client] Reconnecting in ${delay}ms`);
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      // Double the delay for next time, capped at max
+      this.reconnectDelay = Math.min(this.reconnectDelay * 2, MAX_RECONNECT_DELAY_MS);
+      this.connect();
+    }, delay);
+  }
+
+  /**
+   * Reset backoff delay to the minimum after a successful connection.
+   */
+  private resetBackoff(): void {
+    this.reconnectDelay = MIN_RECONNECT_DELAY_MS;
+  }
+
+  /**
+   * Clear any pending reconnection timer.
+   */
+  private clearReconnectTimer(): void {
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+}