shadow-claw 1.23.4 → 1.24.1

package/src/core/backup-controller.ts

@@ -0,0 +1,166 @@
+/**
+ * ShadowClaw — Client-Side Backup Controller
+ *
+ * Orchestrates workspace file backups from the browser client's OPFS / local storage
+ * to the server via the `/api/backup/*` REST endpoints.
+ */
+
+import { ulid } from "../utils/ulid.js";
+
+export interface BackupProgress {
+  current: number;
+  total: number;
+  file: string;
+}
+
+export interface BackupControllerOptions {
+  clientId: string;
+  token?: string;
+  serverBaseUrl?: string;
+  fileEnumerator?: () => Promise<string[]>;
+  fileReader?: (path: string) => Promise<string | Uint8Array | null>;
+  onProgress?: (progress: BackupProgress) => void;
+}
+
+export interface BackupInitiateResult {
+  success: boolean;
+  backupId: string;
+  fileCount: number;
+  totalBytes: number;
+}
+
+function getTargetAddressSpace(urlStr: string): string | undefined {
+  try {
+    const u = new URL(urlStr);
+    const host = u.hostname.toLowerCase();
+    if (
+      host === "localhost" ||
+      host === "127.0.0.1" ||
+      host === "::1" ||
+      host === "[::1]"
+    ) {
+      return "loopback";
+    }
+    if (/^(10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/.test(host)) {
+      return "private";
+    }
+  } catch {}
+  return undefined;
+}
+
+export class BackupController {
+  private _clientId: string;
+  private _token?: string;
+  private _serverBaseUrl: string;
+  private _fileEnumerator: () => Promise<string[]>;
+  private _fileReader: (path: string) => Promise<string | Uint8Array | null>;
+  private _onProgress?: (progress: BackupProgress) => void;
+
+  constructor(options: BackupControllerOptions) {
+    this._clientId = options.clientId;
+    this._token = options.token;
+    this._serverBaseUrl = options.serverBaseUrl || "";
+    this._fileEnumerator = options.fileEnumerator || (async () => []);
+    this._fileReader = options.fileReader || (async () => null);
+    this._onProgress = options.onProgress;
+  }
+
+  public async initiate(): Promise<BackupInitiateResult> {
+    const backupId = ulid();
+    const files = await this._fileEnumerator();
+    let totalBytes = 0;
+    let uploadedCount = 0;
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (this._token) {
+      headers["x-control-token"] = this._token;
+    }
+
+    for (let i = 0; i < files.length; i++) {
+      const filePath = files[i];
+      const data = await this._fileReader(filePath);
+
+      if (data === null || data === undefined) {
+        continue;
+      }
+
+      let contentStr: string;
+      let encoding = "utf-8";
+
+      if (typeof data === "string") {
+        contentStr = data;
+        totalBytes += Buffer.from(data, "utf-8").length;
+      } else {
+        contentStr = Buffer.from(data).toString("base64");
+        encoding = "base64";
+        totalBytes += data.byteLength || data.length || 0;
+      }
+
+      const uploadUrl = `${this._serverBaseUrl}/api/backup/upload`;
+      const uploadOpts: any = {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          clientId: this._clientId,
+          backupId,
+          path: filePath,
+          content: contentStr,
+          encoding,
+        }),
+      };
+      const uploadAddressSpace = getTargetAddressSpace(uploadUrl);
+      if (uploadAddressSpace) {
+        uploadOpts.targetAddressSpace = uploadAddressSpace;
+      }
+      const res = await fetch(uploadUrl, uploadOpts);
+
+      if (!res.ok) {
+        const errorText = await res.text().catch(() => res.statusText);
+        throw new Error(
+          `Upload failed for ${filePath} (${res.status}): ${errorText}`,
+        );
+      }
+
+      uploadedCount++;
+      this._onProgress?.({
+        current: uploadedCount,
+        total: files.length,
+        file: filePath,
+      });
+    }
+
+    // Finalize backup
+    const completeUrl = `${this._serverBaseUrl}/api/backup/complete`;
+    const completeOpts: any = {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        clientId: this._clientId,
+        backupId,
+        fileCount: uploadedCount,
+        totalBytes,
+      }),
+    };
+    const completeAddressSpace = getTargetAddressSpace(completeUrl);
+    if (completeAddressSpace) {
+      completeOpts.targetAddressSpace = completeAddressSpace;
+    }
+    const completeRes = await fetch(completeUrl, completeOpts);
+
+    if (!completeRes.ok) {
+      const errorText = await completeRes
+        .text()
+        .catch(() => completeRes.statusText);
+      throw new Error(`Failed to complete backup: ${errorText}`);
+    }
+
+    return {
+      success: true,
+      backupId,
+      fileCount: uploadedCount,
+      totalBytes,
+    };
+  }
+}

package/src/core/control-plane-client.test.ts

@@ -0,0 +1,415 @@
+import { jest } from "@jest/globals";
+import {
+  ControlPlaneClient,
+  type CommandHandler,
+} from "./control-plane-client.js";
+import type {
+  ControlMessage,
+  CommandExecutePayload,
+  CommandResultPayload,
+} from "../server/control-plane-types.js";
+
+// Mock WebSocket implementation for client testing
+class MockClientWebSocket {
+  static readonly CONNECTING = 0;
+  static readonly OPEN = 1;
+  static readonly CLOSING = 2;
+  static readonly CLOSED = 3;
+
+  static instances: MockClientWebSocket[] = [];
+  url: string;
+  readyState: number = 0; // CONNECTING
+  sentMessages: string[] = [];
+  onopen: (() => void) | null = null;
+  onmessage: ((event: { data: string }) => void) | null = null;
+  onclose: (() => void) | null = null;
+  onerror: ((err: any) => void) | null = null;
+
+  constructor(url: string) {
+    this.url = url;
+    this.readyState = MockClientWebSocket.CONNECTING;
+    MockClientWebSocket.instances.push(this);
+    setTimeout(() => {
+      if (this.readyState === MockClientWebSocket.CONNECTING) {
+        this.readyState = MockClientWebSocket.OPEN;
+        this.onopen?.();
+      }
+    }, 10);
+  }
+
+  send(data: string) {
+    this.sentMessages.push(data);
+  }
+
+  close() {
+    this.readyState = MockClientWebSocket.CLOSED;
+    this.onclose?.();
+  }
+
+  // Helper for test to simulate server messages
+  receiveMessageFromServer(msg: ControlMessage) {
+    this.onmessage?.({ data: JSON.stringify(msg) });
+  }
+}
+
+// Mock EventSource implementation for SSE client testing
+class MockEventSource {
+  static instances: MockEventSource[] = [];
+  url: string;
+  onopen: (() => void) | null = null;
+  onmessage: ((event: { data: string }) => void) | null = null;
+  onerror: ((err: any) => void) | null = null;
+  listeners: Map<string, ((event: { data: string }) => void)[]> = new Map();
+  closed: boolean = false;
+
+  constructor(url: string) {
+    this.url = url;
+    MockEventSource.instances.push(this);
+    setTimeout(() => {
+      if (!this.closed) {
+        this.onopen?.();
+      }
+    }, 10);
+  }
+
+  addEventListener(event: string, handler: (e: { data: string }) => void) {
+    const list = this.listeners.get(event) || [];
+    list.push(handler);
+    this.listeners.set(event, list);
+  }
+
+  close() {
+    this.closed = true;
+  }
+
+  // Helper for test to simulate server event
+  receiveEvent(type: string, data: any) {
+    const dataStr = typeof data === "string" ? data : JSON.stringify(data);
+    const handlers = this.listeners.get(type) || [];
+    for (const h of handlers) {
+      h({ data: dataStr });
+    }
+    if (type === "message") {
+      this.onmessage?.({ data: dataStr });
+    }
+  }
+}
+
+describe("control-plane-client", () => {
+  let mockFetch: jest.Mock<any>;
+  let postedRequests: Array<{
+    url: string;
+    body: any;
+    headers: any;
+    targetAddressSpace?: string;
+  }>;
+
+  beforeEach(() => {
+    MockClientWebSocket.instances = [];
+    MockEventSource.instances = [];
+    postedRequests = [];
+    mockFetch = jest.fn(async (url: string, opts: any) => {
+      postedRequests.push({
+        url,
+        body: JSON.parse(opts.body),
+        headers: opts.headers,
+        targetAddressSpace: opts.targetAddressSpace,
+      });
+      return { ok: true, json: async () => ({ status: "received" }) };
+    }) as any;
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  describe("SSE Transport (Default)", () => {
+    it("connects via EventSource and sends registration over HTTP POST with targetAddressSpace", async () => {
+      const client = new ControlPlaneClient({
+        clientId: "sse-client-1",
+        deviceLabel: "SSE Device",
+        capabilities: ["opfs", "webmcp"],
+        EventSourceClass: MockEventSource as any,
+        fetchFn: mockFetch as any,
+      });
+
+      expect(client.transport).toBe("sse");
+      client.connect();
+
+      expect(MockEventSource.instances).toHaveLength(1);
+      const es = MockEventSource.instances[0];
+      expect(es.url).toContain("/api/control/events");
+      expect(es.url).toContain("clientId=sse-client-1");
+
+      // Advance timers to trigger onopen
+      jest.advanceTimersByTime(15);
+      expect(client.getState()).toBe("connected");
+
+      // Verify registration POST
+      expect(postedRequests).toHaveLength(1);
+      expect(postedRequests[0].body.type).toBe("client:register");
+      expect(postedRequests[0].body.payload.clientId).toBe("sse-client-1");
+      expect(postedRequests[0].body.payload.transport).toBe("sse");
+      expect(postedRequests[0].targetAddressSpace).toBe("loopback");
+
+      client.disconnect();
+      expect(client.getState()).toBe("disconnected");
+      expect(es.closed).toBe(true);
+    });
+
+    it("sends periodic heartbeats over HTTP POST in SSE mode", async () => {
+      const client = new ControlPlaneClient({
+        clientId: "sse-client-hb",
+        heartbeatIntervalMs: 10000,
+        EventSourceClass: MockEventSource as any,
+        fetchFn: mockFetch as any,
+      });
+
+      client.connect();
+      jest.advanceTimersByTime(15); // open -> register
+      expect(postedRequests).toHaveLength(1);
+
+      // Advance 10s
+      jest.advanceTimersByTime(10000);
+      expect(postedRequests).toHaveLength(2);
+      expect(postedRequests[1].body.type).toBe("client:heartbeat");
+
+      // Advance another 10s
+      jest.advanceTimersByTime(10000);
+      expect(postedRequests).toHaveLength(3);
+
+      client.disconnect();
+    });
+
+    it("executes command from SSE stream and posts result back", async () => {
+      const mockHandler = jest.fn(async (args: any) => ({
+        echo: args.input,
+      }));
+
+      const client = new ControlPlaneClient({
+        clientId: "sse-client-cmd",
+        EventSourceClass: MockEventSource as any,
+        fetchFn: mockFetch as any,
+        handlers: {
+          "echo-command": mockHandler,
+        },
+      });
+
+      client.connect();
+      const es = MockEventSource.instances[0];
+      jest.advanceTimersByTime(15);
+
+      const cmdMsg: ControlMessage = {
+        id: "cmd-msg-1",
+        type: "command:execute",
+        payload: {
+          commandId: "cmd-id-123",
+          action: "echo-command" as any,
+          args: { input: "hello sse" },
+        } as CommandExecutePayload,
+      };
+
+      es.receiveEvent("command:execute", cmdMsg);
+
+      await Promise.resolve();
+
+      expect(mockHandler).toHaveBeenCalledWith({ input: "hello sse" });
+      expect(postedRequests).toHaveLength(2); // register + result
+      const resultPost = postedRequests[1];
+      expect(resultPost.body.type).toBe("command:result");
+      expect(resultPost.body.replyTo).toBe("cmd-msg-1");
+      expect(resultPost.body.payload.commandId).toBe("cmd-id-123");
+      expect(resultPost.body.payload.success).toBe(true);
+      expect(resultPost.body.payload.data).toEqual({ echo: "hello sse" });
+
+      client.disconnect();
+    });
+  });
+
+  describe("WebSocket Transport (Opt-in)", () => {
+    it("connects and registers client with server", async () => {
+      const client = new ControlPlaneClient({
+        transport: "websocket",
+        url: "ws://127.0.0.1:8888/ws/control",
+        token: "secret-token",
+        clientId: "client-test-1",
+        deviceLabel: "Test Device",
+        capabilities: ["webmcp", "opfs"],
+        WebSocketClass: MockClientWebSocket as any,
+      });
+
+      expect(client.transport).toBe("websocket");
+      client.connect();
+      expect(MockClientWebSocket.instances).toHaveLength(1);
+      const ws = MockClientWebSocket.instances[0];
+
+      // Trigger onopen
+      jest.advanceTimersByTime(15);
+      expect(client.getState()).toBe("connected");
+
+      // Verify client:register was sent
+      expect(ws.sentMessages).toHaveLength(1);
+      const regMsg: ControlMessage = JSON.parse(ws.sentMessages[0]);
+      expect(regMsg.type).toBe("client:register");
+      expect(regMsg.payload).toEqual({
+        clientId: "client-test-1",
+        deviceLabel: "Test Device",
+        capabilities: ["webmcp", "opfs"],
+        version: "1.23.4",
+        transport: "websocket",
+      });
+
+      client.disconnect();
+      expect(client.getState()).toBe("disconnected");
+    });
+
+    it("sends periodic heartbeats while connected in WebSocket mode", async () => {
+      const client = new ControlPlaneClient({
+        transport: "websocket",
+        url: "ws://127.0.0.1:8888/ws/control",
+        clientId: "client-test-hb",
+        heartbeatIntervalMs: 10000,
+        WebSocketClass: MockClientWebSocket as any,
+      });
+
+      client.connect();
+      const ws = MockClientWebSocket.instances[0];
+      jest.advanceTimersByTime(15); // open
+
+      expect(ws.sentMessages).toHaveLength(1); // register
+
+      // Advance 10s -> heartbeat 1
+      jest.advanceTimersByTime(10000);
+      expect(ws.sentMessages).toHaveLength(2);
+      const hb1: ControlMessage = JSON.parse(ws.sentMessages[1]);
+      expect(hb1.type).toBe("client:heartbeat");
+
+      // Advance another 10s -> heartbeat 2
+      jest.advanceTimersByTime(10000);
+      expect(ws.sentMessages).toHaveLength(3);
+
+      client.disconnect();
+    });
+
+    it("executes registered command handlers and returns result over WebSocket", async () => {
+      const mockHandler: CommandHandler = jest.fn(async (_args: any) => ({
+        tasks: [{ id: "t1" }],
+      }));
+
+      const client = new ControlPlaneClient({
+        transport: "websocket",
+        url: "ws://127.0.0.1:8888/ws/control",
+        clientId: "client-test-cmd",
+        WebSocketClass: MockClientWebSocket as any,
+        handlers: {
+          "list-tasks": mockHandler,
+        },
+      });
+
+      client.connect();
+      const ws = MockClientWebSocket.instances[0];
+      jest.advanceTimersByTime(15);
+
+      // Simulate server sending command:execute
+      const cmdMsg: ControlMessage = {
+        id: "srv-cmd-1",
+        type: "command:execute",
+        payload: {
+          commandId: "cmd-ulid-1",
+          action: "list-tasks",
+          args: { filter: "enabled" },
+        } as CommandExecutePayload,
+      };
+
+      ws.receiveMessageFromServer(cmdMsg);
+
+      // Allow handler promise to resolve
+      await Promise.resolve();
+
+      expect(mockHandler).toHaveBeenCalledWith({ filter: "enabled" });
+
+      // Client sends command:result
+      expect(ws.sentMessages).toHaveLength(2); // register + result
+      const resultMsg: ControlMessage = JSON.parse(ws.sentMessages[1]);
+      expect(resultMsg.type).toBe("command:result");
+      expect(resultMsg.replyTo).toBe("srv-cmd-1");
+      const payload = resultMsg.payload as CommandResultPayload;
+      expect(payload.commandId).toBe("cmd-ulid-1");
+      expect(payload.success).toBe(true);
+      expect(payload.data).toEqual({ tasks: [{ id: "t1" }] });
+
+      client.disconnect();
+    });
+
+    it("returns error result when handler throws in WebSocket mode", async () => {
+      const client = new ControlPlaneClient({
+        transport: "websocket",
+        url: "ws://127.0.0.1:8888/ws/control",
+        clientId: "client-test-err",
+        WebSocketClass: MockClientWebSocket as any,
+        handlers: {
+          "failing-action": async () => {
+            throw new Error("Something went wrong");
+          },
+        },
+      });
+
+      client.connect();
+      const ws = MockClientWebSocket.instances[0];
+      jest.advanceTimersByTime(15);
+
+      ws.receiveMessageFromServer({
+        id: "srv-cmd-2",
+        type: "command:execute",
+        payload: {
+          commandId: "cmd-ulid-2",
+          action: "failing-action" as any,
+          args: {},
+        } as unknown as CommandExecutePayload,
+      });
+
+      await Promise.resolve();
+
+      const resultMsg: ControlMessage = JSON.parse(ws.sentMessages[1]);
+      expect(resultMsg.type).toBe("command:result");
+      const payload = resultMsg.payload as CommandResultPayload;
+      expect(payload.success).toBe(false);
+      expect(payload.error).toContain("Something went wrong");
+
+      client.disconnect();
+    });
+
+    it("auto-reconnects when connection is lost", async () => {
+      const client = new ControlPlaneClient({
+        transport: "websocket",
+        url: "ws://127.0.0.1:8888/ws/control",
+        clientId: "client-test-reconnect",
+        reconnectDelayMs: 500,
+        WebSocketClass: MockClientWebSocket as any,
+      });
+
+      client.connect();
+      expect(MockClientWebSocket.instances).toHaveLength(1);
+      const ws1 = MockClientWebSocket.instances[0];
+      jest.advanceTimersByTime(15); // open
+      expect(client.getState()).toBe("connected");
+
+      // Simulate unexpected disconnect
+      ws1.close();
+      expect(client.getState()).toBe("disconnected");
+
+      // Advance reconnect timer
+      jest.advanceTimersByTime(500);
+
+      // New WebSocket instance created
+      expect(MockClientWebSocket.instances).toHaveLength(2);
+      jest.advanceTimersByTime(15); // open ws2
+      expect(client.getState()).toBe("connected");
+      const ws2 = MockClientWebSocket.instances[1];
+      expect(ws2.sentMessages).toHaveLength(1); // Re-registers on connect
+
+      client.disconnect();
+    });
+  });
+});