@powerhousedao/switchboard 6.2.3-dev.5 → 6.2.3-dev.51

package/test/snapshot-writer.ts

@@ -0,0 +1,94 @@
+// Test-only v1 snapshot.bin writer over a loose on-disk tree.
+import { promises as fs } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import path from "node:path";
+
+const MAGIC = new Uint8Array([0x50, 0x47, 0x4c, 0x41]);
+const FORMAT_VERSION = 1;
+const HEADER_SIZE = 12;
+const ENTRY_PREFIX_SIZE = 9;
+const DEFAULT_SKIP = ["snapshot.bin", "snapshot.bin.tmp"];
+
+export interface SnapshotEntry {
+  type: 0 | 1;
+  mode: number;
+  relPath: string;
+  data?: Buffer;
+}
+
+export interface WriteSnapshotOptions {
+  /** Root-level names to leave out. Defaults to the snapshot files. */
+  skip?: string[];
+}
+
+export async function collectDiskEntries(
+  dataDir: string,
+  options: WriteSnapshotOptions = {},
+): Promise<SnapshotEntry[]> {
+  const skip = new Set(options.skip ?? DEFAULT_SKIP);
+  const entries: SnapshotEntry[] = [];
+  const walk = async (dir: string, rel: string) => {
+    const names = (await fs.readdir(dir)).sort();
+    for (const name of names) {
+      if (rel === "" && skip.has(name)) continue;
+      const full = path.join(dir, name);
+      const relPath = rel === "" ? name : `${rel}/${name}`;
+      const stat = await fs.lstat(full);
+      if (stat.isDirectory()) {
+        entries.push({ type: 0, mode: stat.mode & 0o7777, relPath });
+        await walk(full, relPath);
+      } else if (stat.isFile()) {
+        entries.push({
+          type: 1,
+          mode: stat.mode & 0o7777,
+          relPath,
+          data: await fs.readFile(full),
+        });
+      }
+    }
+  };
+  await walk(dataDir, "");
+  return entries;
+}
+
+export function encodeSnapshot(entries: SnapshotEntry[]): Buffer {
+  const encoder = new TextEncoder();
+  const parts: Buffer[] = [];
+  const header = Buffer.alloc(HEADER_SIZE);
+  header.set(MAGIC, 0);
+  header.writeUInt32LE(FORMAT_VERSION, 4);
+  header.writeUInt32LE(entries.length, 8);
+  parts.push(header);
+  for (const entry of entries) {
+    const pathBytes = encoder.encode(entry.relPath);
+    const dataLen = entry.data?.byteLength ?? 0;
+    const prefix = Buffer.alloc(ENTRY_PREFIX_SIZE + pathBytes.byteLength + 4);
+    prefix.writeUInt8(entry.type, 0);
+    prefix.writeUInt32LE(entry.mode, 1);
+    prefix.writeUInt32LE(pathBytes.byteLength, 5);
+    prefix.set(pathBytes, ENTRY_PREFIX_SIZE);
+    prefix.writeUInt32LE(dataLen, ENTRY_PREFIX_SIZE + pathBytes.byteLength);
+    parts.push(prefix);
+    if (entry.data && dataLen > 0) parts.push(entry.data);
+  }
+  return Buffer.concat(parts);
+}
+
+/** Serializes `dataDir` into `snapshotPath`. Returns the entry count and size. */
+export async function writeSnapshotFromDir(
+  dataDir: string,
+  snapshotPath: string,
+  options: WriteSnapshotOptions = {},
+): Promise<{ entries: number; bytes: number }> {
+  const entries = await collectDiskEntries(dataDir, options);
+  const bytes = encodeSnapshot(entries);
+  let fh: FileHandle | undefined;
+  try {
+    fh = await fs.open(snapshotPath, "w");
+    await fh.writeFile(bytes);
+    await fh.sync();
+  } finally {
+    await fh?.close();
+  }
+  return { entries: entries.length, bytes: bytes.byteLength };
+}

package/test/unsupported-stored-documents.test.ts

@@ -0,0 +1,72 @@
+import { UnsupportedStoredProtocolError } from "@powerhousedao/reactor";
+import { describe, expect, it } from "vitest";
+import {
+  StoredDocumentsRefusedError,
+  resolveUnsupportedStoredDocuments,
+} from "../src/unsupported-stored-documents.mjs";
+
+describe("resolveUnsupportedStoredDocuments", () => {
+  it("refuses by default", () => {
+    expect(resolveUnsupportedStoredDocuments(undefined, {})).toBe("refuse");
+    expect(
+      resolveUnsupportedStoredDocuments(undefined, {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: " ",
+      }),
+    ).toBe("refuse");
+  });
+
+  it("reads REACTOR_UNSUPPORTED_STORED_DOCUMENTS", () => {
+    expect(
+      resolveUnsupportedStoredDocuments(undefined, {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: " read-only ",
+      }),
+    ).toBe("read-only");
+    expect(
+      resolveUnsupportedStoredDocuments(undefined, {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: "refuse",
+      }),
+    ).toBe("refuse");
+  });
+
+  it("lets the option win over the env var", () => {
+    expect(
+      resolveUnsupportedStoredDocuments("refuse", {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: "read-only",
+      }),
+    ).toBe("refuse");
+  });
+
+  it("refuses an unknown value", () => {
+    expect(() =>
+      resolveUnsupportedStoredDocuments(undefined, {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: "readonly",
+      }),
+    ).toThrow(
+      'REACTOR_UNSUPPORTED_STORED_DOCUMENTS must be "refuse" or "read-only", got "readonly"',
+    );
+  });
+});
+
+describe("StoredDocumentsRefusedError", () => {
+  it("names the versions, the count and both ways forward", () => {
+    const cause = new UnsupportedStoredProtocolError(
+      [
+        { protocol: "base-reducer", version: 3 },
+        { protocol: "base-reducer", version: 7 },
+      ],
+      4,
+    );
+
+    const error = new StoredDocumentsRefusedError(cause);
+
+    expect(error.message).toBe(
+      "Refusing to start: 4 stored document(s) require base-reducer 3, base-reducer 7, which this switchboard does not run. " +
+        "Either start a switchboard build that runs base-reducer 3, base-reducer 7, or set REACTOR_UNSUPPORTED_STORED_DOCUMENTS=read-only to start with those documents read-only.",
+    );
+    expect(error.documents).toBe(4);
+    expect(error.versions).toBe(cause.versions);
+    expect(error.cause).toBe(cause);
+    expect(StoredDocumentsRefusedError.isError(error)).toBe(true);
+    expect(StoredDocumentsRefusedError.isError(cause)).toBe(false);
+  });
+});

package/test/worker-pool.test.ts

@@ -1,9 +1,12 @@
 import type { ILogger } from "document-model";
-import { existsSync } from "node:fs";
+import { existsSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import { describe, expect, it, vi } from "vitest";
 import {
   autoWorkerCount,
   buildWorkerDbConfig,
+  keepImportableSources,
   resolveHostPoolSize,
   resolveWorkerModelSources,
   resolveWorkerPoolOptions,
@@ -264,3 +267,26 @@ describe("resolveWorkerModelSources", () => {
     expect(logger.warn).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("keepImportableSources", () => {
+  it("keeps sources that export a model and drops one that throws or has none", async () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "ph-model-sources-"));
+    const good = path.join(dir, "good.mjs");
+    const broken = path.join(dir, "broken.mjs");
+    const empty = path.join(dir, "empty.mjs");
+    writeFileSync(
+      good,
+      'export const Model = { reducer: () => ({}), documentModel: { global: { id: "test/model" } } };',
+    );
+    writeFileSync(broken, 'throw new Error("stale dist");');
+    // What `ph init` builds for a project with no models yet.
+    writeFileSync(empty, "export {};");
+
+    const kept = await keepImportableSources(
+      [{ filePath: broken }, { filePath: good }, { filePath: empty }],
+      stubLogger(),
+    );
+
+    expect(kept).toEqual([{ filePath: good }]);
+  });
+});

package/test/workflow/harness.ts

@@ -0,0 +1,289 @@
+// Shared harness: the suites go over a real socket through the reactor's own
+// adapter, route service and webhook service, which the unit tests cannot.
+import {
+  createHttpAdapter,
+  getDbClient,
+  HttpRouteService,
+  MemoryWebhookStore,
+  WebhookService,
+} from "@powerhousedao/reactor-api";
+import {
+  createWorkflowRuntime,
+  type WorkflowRuntimeService,
+} from "@powerhousedao/reactor-workflow";
+import {
+  createRelationalDb,
+  type IRelationalDb,
+} from "@powerhousedao/shared/processors";
+import type { OperationWithContext } from "document-model";
+import type { Kysely } from "kysely";
+import { vi } from "vitest";
+import {
+  CORE_PIECE_NAME,
+  CORE_PIECE_VERSION,
+} from "@powerhousedao/reactor-workflow";
+
+export const WORKFLOW_TYPE = "powerhouse/workflow";
+export const PACKAGE_NAME = "@powerhousedao/workflow";
+/** A ref the harness's secret store resolves; anything else rejects. */
+export const SECRET_REF = "secret://v1:00112233445566778899aabbccddeeff";
+export const SECRET = "s3cret";
+// Minting an endpoint is a read of the workflow, so the harness asks as one.
+const CALLER = { headers: {}, db: {}, user: { address: "0xabc" } } as never;
+
+export interface FiredRun {
+  workflowId: string;
+  payload: unknown;
+  kind: string;
+}
+
+export interface TriggerFields {
+  pieceName: string;
+  pieceVersion: string;
+  triggerName: string;
+}
+
+// The core piece's webhook trigger, pinned to the installed core piece.
+export const WEBHOOK_TRIGGER: TriggerFields = {
+  pieceName: CORE_PIECE_NAME,
+  pieceVersion: CORE_PIECE_VERSION,
+  triggerName: "webhook",
+};
+
+export interface WebhookHost {
+  /** Origin the endpoint is served from, e.g. `http://127.0.0.1:53124`. */
+  readonly url: string;
+  /** Runs the trigger started, in order. Cleared by `arm`. */
+  readonly fired: FiredRun[];
+  readonly service: WorkflowRuntimeService;
+  /** Publishes an ENABLED workflow with `config`; returns its endpoint. */
+  arm(
+    config: Record<string, unknown>,
+    options?: { trigger?: TriggerFields; workflowId?: string },
+  ): Promise<{ token: string; url: string }>;
+  /** Publishes the same workflow as DISABLED, keeping its endpoint row. */
+  disarm(workflowId?: string): Promise<void>;
+  /** Deletes the workflow document, as the reactor reports it. */
+  remove(workflowId?: string): Promise<void>;
+  /** Whether the reactor's webhook store still holds this token. */
+  hasToken(token: string): Promise<boolean>;
+  /** The policy the service hands the reactor for one endpoint. */
+  policyFor(workflowId?: string): Promise<unknown>;
+  deliver(
+    token: string,
+    init?: {
+      method?: string;
+      headers?: Record<string, string>;
+      body?: string;
+      query?: Record<string, string>;
+    },
+  ): Promise<Response>;
+  stop(): Promise<void>;
+}
+
+export const DEFAULT_WORKFLOW = "wf-integration";
+
+// Module-scoped: the service ignores any ordinal at or below the highest it
+// has seen, so a per-host counter would make a file's second host see nothing.
+let ordinal = 0;
+
+export function workflowOperation(
+  state: Record<string, unknown>,
+  workflowId = DEFAULT_WORKFLOW,
+): OperationWithContext {
+  ordinal += 1;
+  return {
+    operation: {
+      index: ordinal,
+      timestampUtcMs: `${ordinal}`,
+      action: { type: "SET_WORKFLOW_NAME", input: {} },
+      resultingState: JSON.stringify(state),
+    },
+    context: {
+      documentId: workflowId,
+      documentType: WORKFLOW_TYPE,
+      scope: "global",
+      branch: "main",
+      ordinal,
+    },
+  } as unknown as OperationWithContext;
+}
+
+// `publicUrl` is known only after `listen`: a family registered against the
+// wrong origin advertises URLs no caller can reach.
+export async function startWebhookHost(
+  options: {
+    fire?: (run: FiredRun) => unknown;
+    // Reads and writes of the workflow documents; none by default.
+    reactorClient?: unknown;
+  } = {},
+): Promise<WebhookHost> {
+  // The public factory, not the adapter class: the class is internal, so
+  // constructing it would test a path no consumer can take.
+  const { adapter } = await createHttpAdapter("express");
+  adapter.setupMiddleware({});
+  const server = await adapter.listen(0, undefined, "127.0.0.1");
+  const { port } = server.address() as { port: number };
+  const url = `http://127.0.0.1:${port}`;
+
+  const webhookStore = new MemoryWebhookStore();
+  const webhooks = new WebhookService({ store: webhookStore });
+  const routes = new HttpRouteService({
+    httpAdapter: adapter,
+    webhooks,
+    publicUrl: url,
+  });
+  // Core serves the endpoint family from its own host scope, exactly as the
+  // reactor wires it: nothing here touches the adapter directly.
+  webhooks.attach(routes.hostScope("@powerhousedao/reactor-api", "/webhooks"));
+
+  const { db } = getDbClient();
+  const fired: FiredRun[] = [];
+
+  // Every host surface the runtime asks for, and nothing it does not: no run
+  // here reaches the reactor, and the secret store answers one fixed ref.
+  const service = createWorkflowRuntime({
+    relationalDb: createRelationalDb(
+      db as unknown as Kysely<unknown>,
+    ) as IRelationalDb,
+    reactorClient: options.reactorClient ?? {
+      get: () => Promise.reject(new Error("not used")),
+      find: () => Promise.resolve({ results: [] }),
+    },
+    assertCanRead: () => Promise.resolve(undefined),
+    assertCanWrite: () => Promise.resolve(undefined),
+    webhooks: routes.scopeFor(PACKAGE_NAME).webhooks,
+    secrets: {
+      get: (ref: string) =>
+        ref === SECRET_REF
+          ? Promise.resolve(SECRET)
+          : Promise.reject(new Error(`No secret found for ref "${ref}"`)),
+    },
+  } as never);
+  vi.spyOn(service, "fire").mockImplementation(
+    (workflowId: string, payload?: unknown, kind = "manual") => {
+      const run = { workflowId, payload, kind };
+      fired.push(run);
+      const outcome = options.fire?.(run);
+      return Promise.resolve(
+        (outcome ?? {
+          runId: `run-${fired.length}`,
+          status: "SUCCEEDED",
+          steps: [],
+        }) as never,
+      );
+    },
+  );
+
+  await service.registerWebhookEndpoint();
+
+  const publish = async (
+    config: Record<string, unknown>,
+    status: string,
+    trigger: TriggerFields,
+    workflowId: string,
+  ) => {
+    await service.onOperations([
+      workflowOperation(
+        {
+          name: "Integration",
+          status,
+          version: ordinal + 1,
+          trigger: { id: "t1", ...trigger, config },
+          steps: [],
+          edges: [],
+          variables: [],
+        },
+        workflowId,
+      ),
+    ]);
+  };
+
+  return {
+    url,
+    fired,
+    service,
+    async arm(config, opts = {}) {
+      const workflowId = opts.workflowId ?? DEFAULT_WORKFLOW;
+      // The runtime requires a scheme; an unsigned suite names "none".
+      await publish(
+        { scheme: "none", ...config },
+        "ENABLED",
+        opts.trigger ?? WEBHOOK_TRIGGER,
+        workflowId,
+      );
+      const endpoint = await service.webhookEndpoint(workflowId, CALLER);
+      if (!endpoint) throw new Error(`No endpoint minted for ${workflowId}`);
+      fired.length = 0;
+      return {
+        url: endpoint.url,
+        token: endpoint.url.slice(endpoint.url.lastIndexOf("/") + 1),
+      };
+    },
+    async disarm(workflowId = DEFAULT_WORKFLOW) {
+      await publish({}, "DISABLED", WEBHOOK_TRIGGER, workflowId);
+    },
+    async remove(workflowId = DEFAULT_WORKFLOW) {
+      ordinal += 1;
+      await service.onOperations([
+        {
+          operation: {
+            index: ordinal,
+            timestampUtcMs: `${ordinal}`,
+            action: {
+              type: "DELETE_DOCUMENT",
+              input: { documentId: workflowId },
+            },
+          },
+          context: {
+            documentId: workflowId,
+            documentType: WORKFLOW_TYPE,
+            scope: "document",
+            branch: "main",
+            ordinal,
+          },
+        } as unknown as OperationWithContext,
+      ]);
+    },
+    async hasToken(token) {
+      return (await webhookStore.find(token)) !== undefined;
+    },
+    policyFor(workflowId = DEFAULT_WORKFLOW) {
+      return service.webhookPolicy(workflowId);
+    },
+    deliver(token, init = {}) {
+      const query = init.query
+        ? `?${new URLSearchParams(init.query).toString()}`
+        : "";
+      return fetch(`${url}/webhooks/${token}${query}`, {
+        method: init.method ?? "POST",
+        headers: init.headers,
+        body: init.body,
+      });
+    },
+    stop() {
+      return new Promise<void>((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve())),
+      );
+    },
+  };
+}
+
+// A delivery is answered before its run starts, so asserting on `fired`
+// straight after a 202 is a race that passes for the wrong reason.
+export async function waitForRuns(
+  host: WebhookHost,
+  count: number,
+  timeoutMs = 2000,
+): Promise<FiredRun[]> {
+  const deadline = Date.now() + timeoutMs;
+  while (host.fired.length < count && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  if (host.fired.length < count) {
+    throw new Error(
+      `Expected ${count} run(s), saw ${host.fired.length} within ${timeoutMs}ms`,
+    );
+  }
+  return host.fired;
+}