@frockbot/plugin-computer 0.0.0 → 0.1.0

package/src/backend.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ComputerBotNotFoundError,
+  createComputerBackendContribution,
+} from "./backend.js";
+import type {
+  ComputerCommandReceiptV1,
+  ComputerProjectionV1,
+} from "./protocol.js";
+
+const projection: ComputerProjectionV1 = {
+  version: 1,
+  botId: "scout",
+  providerLabel: "Fake Computer",
+  phase: "idle",
+  message: "Persistent Computer available",
+  screenshots: [],
+};
+
+function request(body: unknown): Request {
+  return new Request("https://app.test/api/bots/scout/computer/commands", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+describe("Computer gateway Contribution", () => {
+  test("rejects malformed exact DTOs before the host or storage is touched", async () => {
+    let calls = 0;
+    const contribution = createComputerBackendContribution({
+      readComputer: () => Promise.resolve(projection),
+      executeComputerCommand: () => {
+        calls += 1;
+        throw new Error("must not execute");
+      },
+    });
+    const response = await contribution.route(
+      request({
+        version: 1,
+        commandId: "command-1",
+        botId: "scout",
+        type: "connect",
+        unexpected: true,
+      }),
+      new URL("https://app.test/api/bots/scout/computer/commands"),
+      { userId: "user-1", client: "browser" },
+    );
+    expect(response?.status).toBe(400);
+    expect(calls).toBe(0);
+  });
+
+  test("answers 404 for a foreign Bot without writing its storage", async () => {
+    let writes = 0;
+    const contribution = createComputerBackendContribution({
+      readComputer: () => {
+        throw new ComputerBotNotFoundError("scout");
+      },
+      executeComputerCommand: () => {
+        writes += 1;
+        throw new Error("must not execute");
+      },
+    });
+    const response = await contribution.route(
+      new Request("https://app.test/api/bots/scout/computer"),
+      new URL("https://app.test/api/bots/scout/computer"),
+      { userId: "another-user", client: "browser" },
+    );
+    expect(response?.status).toBe(404);
+    expect(writes).toBe(0);
+  });
+
+  test("returns the authority's first receipt for a duplicate command replay", async () => {
+    const first: ComputerCommandReceiptV1 = {
+      version: 1,
+      commandId: "command-1",
+      type: "connect",
+      status: "applied",
+      completedAt: "2026-09-02T00:00:00.000Z",
+    };
+    const receipts = new Map<string, ComputerCommandReceiptV1>();
+    let effects = 0;
+    const contribution = createComputerBackendContribution({
+      readComputer: () => Promise.resolve(projection),
+      executeComputerCommand: (_userId, _botId, command) => {
+        const stored = receipts.get(command.commandId);
+        if (stored) return Promise.resolve(stored);
+        effects += 1;
+        receipts.set(command.commandId, first);
+        return Promise.resolve(first);
+      },
+    });
+    const command = {
+      version: 1,
+      commandId: "command-1",
+      botId: "scout",
+      type: "connect",
+    };
+    const execute = () =>
+      contribution.route(
+        request(command),
+        new URL("https://app.test/api/bots/scout/computer/commands"),
+        { userId: "user-1", client: "browser" },
+      );
+    const one = await execute();
+    const two = await execute();
+    expect(await one?.json()).toEqual(await two?.json());
+    expect(effects).toBe(1);
+  });
+
+  test("decodes refreshViewer and returns the authority's replayed receipt", async () => {
+    let effects = 0;
+    const receipts = new Map<string, ComputerCommandReceiptV1>();
+    const contribution = createComputerBackendContribution({
+      readComputer: () => Promise.resolve(projection),
+      executeComputerCommand: (_userId, _botId, decoded) => {
+        const replay = receipts.get(decoded.commandId);
+        if (replay) return Promise.resolve(replay);
+        effects += 1;
+        const receipt: ComputerCommandReceiptV1 = {
+          version: 1,
+          commandId: decoded.commandId,
+          type: decoded.type,
+          status: "applied",
+          completedAt: "2026-09-02T00:00:00.000Z",
+        };
+        receipts.set(decoded.commandId, receipt);
+        return Promise.resolve(receipt);
+      },
+    });
+    const execute = () =>
+      contribution.route(
+        request({
+          version: 1,
+          commandId: "viewer-renew-1",
+          botId: "scout",
+          type: "refreshViewer",
+        }),
+        new URL("https://app.test/api/bots/scout/computer/commands"),
+        { userId: "user-1", client: "browser" },
+      );
+
+    const first = await execute();
+    const duplicate = await execute();
+
+    expect(await first?.json()).toEqual(await duplicate?.json());
+    expect(effects).toBe(1);
+  });
+});

package/src/backend.ts

@@ -0,0 +1,163 @@
+// The authenticated Computer presence routes. The gateway owns no Computer
+// state: it decodes one exact DTO, proves User-to-Bot membership through its
+// host, and forwards to the Bot Durable Object that owns the records.
+import type { Plugin } from "cordis";
+import {
+  ComputerProtocolDecodeError,
+  decodeComputerCommandReceiptV1,
+  decodeComputerCommandV1,
+  decodeComputerProjectionV1,
+  type ComputerCommandReceiptV1,
+  type ComputerCommandV1,
+  type ComputerProjectionV1,
+} from "./protocol.js";
+
+export interface ComputerGatewayHost {
+  readComputer(userId: string, botId: string): Promise<ComputerProjectionV1>;
+  executeComputerCommand(
+    userId: string,
+    botId: string,
+    command: ComputerCommandV1,
+  ): Promise<ComputerCommandReceiptV1>;
+}
+
+export interface ComputerBackendRouteContribution {
+  packageId: string;
+  route(
+    request: Request,
+    url: URL,
+    context: { userId?: string; client: "browser" | "desktop" },
+  ): Promise<Response | undefined>;
+}
+
+export class ComputerBotNotFoundError extends Error {
+  override readonly name = "ComputerBotNotFoundError";
+}
+
+function missingBot(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    (error.name === "ComputerBotNotFoundError" ||
+      error.name === "BotNotFoundError")
+  );
+}
+
+function errorResponse(error: unknown): Response {
+  if (missingBot(error)) {
+    return Response.json(
+      { error: "Computer not found", code: "bot-not-found", definitive: true },
+      { status: 404 },
+    );
+  }
+  if (
+    error instanceof ComputerProtocolDecodeError ||
+    error instanceof SyntaxError ||
+    (typeof error === "object" &&
+      error !== null &&
+      "name" in error &&
+      error.name === "ComputerProtocolDecodeError")
+  ) {
+    return Response.json(
+      {
+        error:
+          error instanceof Error
+            ? error.message
+            : "Computer request is invalid",
+        code: "invalid-request",
+        definitive: true,
+      },
+      { status: 400 },
+    );
+  }
+  return Response.json(
+    {
+      error: error instanceof Error ? error.message : "Computer request failed",
+    },
+    { status: 500 },
+  );
+}
+
+function pathId(value: string): string {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    throw new ComputerProtocolDecodeError("Computer botId is invalid");
+  }
+  if (!decoded.trim() || decoded.length > 200) {
+    throw new ComputerProtocolDecodeError("Computer botId is invalid");
+  }
+  return decoded;
+}
+
+export function createComputerBackendContribution(
+  host: ComputerGatewayHost,
+): ComputerBackendRouteContribution {
+  return {
+    packageId: "computer",
+    async route(request, url, context) {
+      if (!context.userId) return undefined;
+      const read = /^\/api\/bots\/([^/]+)\/computer$/.exec(url.pathname);
+      const command = /^\/api\/bots\/([^/]+)\/computer\/commands$/.exec(
+        url.pathname,
+      );
+      const match = read ?? command;
+      if (!match) return undefined;
+      if ([...url.searchParams.keys()].length > 0) {
+        return errorResponse(
+          new ComputerProtocolDecodeError(
+            "Computer routes take no query parameters",
+          ),
+        );
+      }
+      try {
+        const encodedBotId = match[1];
+        if (encodedBotId === undefined) {
+          throw new ComputerProtocolDecodeError("Computer botId is invalid");
+        }
+        const botId = pathId(encodedBotId);
+        if (read) {
+          if (request.method !== "GET") {
+            return Response.json(
+              { error: "method not allowed" },
+              { status: 405 },
+            );
+          }
+          return Response.json(
+            decodeComputerProjectionV1(
+              await host.readComputer(context.userId, botId),
+            ),
+          );
+        }
+        if (request.method !== "POST") {
+          return Response.json(
+            { error: "method not allowed" },
+            { status: 405 },
+          );
+        }
+        const decoded = decodeComputerCommandV1(await request.json());
+        if (decoded.botId !== botId) {
+          throw new ComputerProtocolDecodeError(
+            "Computer command does not match the request path",
+          );
+        }
+        return Response.json(
+          decodeComputerCommandReceiptV1(
+            await host.executeComputerCommand(context.userId, botId, decoded),
+          ),
+        );
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  };
+}
+
+export function createComputerBackendPlugin(
+  host: ComputerGatewayHost,
+  lifecycle: { mount(value: ComputerBackendRouteContribution): () => void },
+): Plugin {
+  return () => lifecycle.mount(createComputerBackendContribution(host));
+}