@powerhousedao/switchboard 6.2.3-dev.11 → 6.2.3-dev.13

package/test/workflow/harness.ts

@@ -0,0 +1,237 @@
+// 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";
+
+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 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?: { blockType?: string; workflowId?: string },
+  ): Promise<{ token: string; url: string }>;
+  /** Publishes the same workflow as DISABLED, keeping its endpoint row. */
+  disarm(workflowId?: string): Promise<void>;
+  /** 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 } = {},
+): 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);
+  const { port } = server.address() as { port: number };
+  const url = `http://127.0.0.1:${port}`;
+
+  const webhooks = new WebhookService({ store: new MemoryWebhookStore() });
+  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: {
+      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,
+    blockType: string,
+    workflowId: string,
+  ) => {
+    await service.onOperations([
+      workflowOperation(
+        {
+          name: "Integration",
+          status,
+          version: ordinal + 1,
+          trigger: { id: "t1", blockType, config },
+          steps: [],
+          edges: [],
+          variables: [],
+        },
+        workflowId,
+      ),
+    ]);
+  };
+
+  return {
+    url,
+    fired,
+    service,
+    async arm(config, opts = {}) {
+      const workflowId = opts.workflowId ?? DEFAULT_WORKFLOW;
+      await publish(
+        config,
+        "ENABLED",
+        opts.blockType ?? "core#webhook",
+        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", "core#webhook", workflowId);
+    },
+    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;
+}

package/test/workflow/resolvers.test.ts

@@ -0,0 +1,105 @@
+// What the workflow subgraph does with the caller behind a request: every
+// workflow-scoped field hands it to the runtime, and secret writes are admins'.
+import type {
+  Context,
+  IAuthorizationService,
+} from "@powerhousedao/reactor-api";
+import type { WorkflowRuntimeService } from "@powerhousedao/reactor-workflow";
+import { describe, expect, it, vi } from "vitest";
+import { getResolvers } from "../../src/workflow/resolvers.js";
+
+const CTX = {
+  headers: {},
+  db: {},
+  user: { address: "0xadmin" },
+} as unknown as Context;
+
+type Resolver = (
+  parent: unknown,
+  args: unknown,
+  ctx: Context,
+) => Promise<unknown>;
+
+function fakeRuntime() {
+  return {
+    webhookEndpoint: vi.fn(() => Promise.resolve(null)),
+    triggerStates: vi.fn(() => Promise.resolve([])),
+    runs: vi.fn(() => Promise.resolve([])),
+    run: vi.fn(() => Promise.resolve(null)),
+    fire: vi.fn(() => Promise.resolve({})),
+    rerun: vi.fn(() => Promise.resolve({})),
+    secrets: vi.fn(() =>
+      Promise.resolve({
+        create: vi.fn(() => Promise.resolve({ ref: "secret://v1:00" })),
+        rotate: vi.fn(() => Promise.resolve({ ref: "secret://v1:00" })),
+        delete: vi.fn(() => Promise.resolve()),
+      }),
+    ),
+  };
+}
+
+function build(isAdmin: boolean) {
+  const runtime = fakeRuntime();
+  const authorizationService = {
+    isSupremeAdmin: vi.fn(() => isAdmin),
+  } as unknown as IAuthorizationService;
+  const resolvers = getResolvers(
+    runtime as unknown as WorkflowRuntimeService,
+    authorizationService,
+  ) as Record<string, Record<string, Resolver>>;
+  return {
+    runtime,
+    queries: resolvers.WorkflowRuntimeQueries,
+    mutations: resolvers.WorkflowRuntimeMutations,
+  };
+}
+
+describe("the workflow resolvers and the caller", () => {
+  it("hands the caller to every workflow-scoped field", async () => {
+    const { runtime, queries, mutations } = build(true);
+
+    await queries.webhookEndpoint({}, { workflowId: "wf-1" }, CTX);
+    await queries.triggerStates({}, {}, CTX);
+    await queries.runs({}, { driveId: "drive-1" }, CTX);
+    await queries.run({}, { id: "run-1" }, CTX);
+    await mutations.fire({}, { workflowId: "wf-1", payload: { a: 1 } }, CTX);
+    await mutations.rerun({}, { runId: "run-1" }, CTX);
+
+    expect(runtime.webhookEndpoint).toHaveBeenCalledWith("wf-1", CTX);
+    expect(runtime.triggerStates).toHaveBeenCalledWith(CTX);
+    expect(runtime.runs).toHaveBeenCalledWith({ driveId: "drive-1" }, CTX);
+    expect(runtime.run).toHaveBeenCalledWith("run-1", CTX);
+    expect(runtime.fire).toHaveBeenCalledWith(
+      "wf-1",
+      { a: 1 },
+      "manual",
+      undefined,
+      CTX,
+    );
+    expect(runtime.rerun).toHaveBeenCalledWith("run-1", CTX);
+  });
+
+  it("refuses secret writes to a caller who does not administer the reactor", async () => {
+    const { runtime, mutations } = build(false);
+
+    await expect(
+      mutations.createSecret({}, { value: "s3cret" }, CTX),
+    ).rejects.toThrow("Admin access required");
+    await expect(
+      mutations.rotateSecret({}, { ref: "secret://v1:00", value: "s" }, CTX),
+    ).rejects.toThrow("Admin access required");
+    await expect(
+      mutations.deleteSecret({}, { ref: "secret://v1:00" }, CTX),
+    ).rejects.toThrow("Admin access required");
+    // Refused before the store is ever opened.
+    expect(runtime.secrets).not.toHaveBeenCalled();
+  });
+
+  it("lets an administrator write secrets", async () => {
+    const { runtime, mutations } = build(true);
+
+    await mutations.createSecret({}, { value: "s3cret", label: "slack" }, CTX);
+
+    expect(runtime.secrets).toHaveBeenCalledTimes(1);
+  });
+});

package/test/workflow/webhook-dedupe.test.ts

@@ -0,0 +1,295 @@
+// Redelivery and the sender's verification round, over a real socket: both
+// are decided by the reactor from one config field, before the trigger runs.
+import { afterEach, describe, expect, it } from "vitest";
+import { startWebhookHost, waitForRuns, type WebhookHost } from "./harness.js";
+
+let host: WebhookHost | undefined;
+
+afterEach(async () => {
+  // Even on failure: a thrown expectation would leave the port open.
+  await host?.stop();
+  host = undefined;
+});
+
+const JSON_HEADERS = { "content-type": "application/json" };
+
+// Gives a run that should NOT exist time to appear: asserting the instant a
+// response lands wins the race whether the trigger fired or not.
+async function settle(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 50));
+}
+
+interface PolicyShape {
+  dedupe?: { field: unknown; ttlSeconds?: number };
+  challengeField?: unknown;
+}
+
+describe("core#webhook redelivery", () => {
+  it("dedupes on a bare field name found in the query string", async () => {
+    host = await startWebhookHost();
+    const { token } = await host.arm({
+      methods: "POST",
+      dedupeField: "eventId",
+      dedupeTtlSeconds: 60,
+    });
+    const send = () => host!.deliver(token, { query: { eventId: "evt-1" } });
+
+    expect((await send()).status).toBe(202);
+    await waitForRuns(host, 1);
+    // A redelivery is answered as a success so the provider stops retrying;
+    // 4xx here would make a well-behaved sender retry forever.
+    expect((await send()).status).toBe(200);
+    await settle();
+    expect(host.fired).toHaveLength(1);
+  });
+
+  it("dedupes on a bare field name found as a top-level body field", async () => {
+    host = await startWebhookHost();
+    const { token } = await host.arm({
+      methods: "POST",
+      dedupeField: "id",
+      dedupeTtlSeconds: 60,
+    });
+    const send = () =>
+      host!.deliver(token, {
+        headers: JSON_HEADERS,
+        body: '{"id":"evt_1","kind":"created"}',
+      });
+
+    expect((await send()).status).toBe(202);
+    await waitForRuns(host, 1);
+    expect((await send()).status).toBe(200);
+    await settle();
+    expect(host.fired).toHaveLength(1);
+  });
+
+  it("dedupes on a `header:`-sourced field", async () => {
+    host = await startWebhookHost();
+    const { token } = await host.arm({
+      methods: "POST",
+      dedupeField: "header:x-delivery-id",
+      dedupeTtlSeconds: 60,
+    });
+    const send = () =>
+      host!.deliver(token, {
+        headers: { ...JSON_HEADERS, "x-delivery-id": "abc-123" },
+        body: '{"a":1}',
+      });
+
+    expect((await send()).status).toBe(202);
+    await waitForRuns(host, 1);
+    expect((await send()).status).toBe(200);
+    await settle();
+    expect(host.fired).toHaveLength(1);
+  });
+
+  it("dedupes on a `body:` path nested inside the payload", async () => {
+    host = await startWebhookHost();
+    const { token } = await host.arm({
+      methods: "POST",
+      dedupeField: "body:data.object.id",
+      dedupeTtlSeconds: 60,
+    });
+    const send = () =>
+      host!.deliver(token, {
+        headers: JSON_HEADERS,
+        body: '{"data":{"object":{"id":"in_1"}}}',
+      });
+
+    expect((await send()).status).toBe(202);
+    await waitForRuns(host, 1);
+    expect((await send()).status).toBe(200);
+    await settle();
+    expect(host.fired).toHaveLength(1);
+  });
+
+  it("keys only on the named field, not on the URL or the body", async () => {
+    host = await startWebhookHost();
+    const { token } = await host.arm({
+      methods: "POST",
+      dedupeField: "header:x-delivery-id",
+      dedupeTtlSeconds: 60,
+    });
+
+    const first = await host.deliver(token, {
+      headers: { ...JSON_HEADERS, "x-delivery-id": "abc-123" },
+      query: { attempt: "1" },
+      body: '{"attempt":1}',
+    });
+    expect(first.status).toBe(202);
+    await waitForRuns(host, 1);
+
+    // A retry is rarely byte-identical, so anything keyed on the URL or the
+    // whole request would treat this as a new event and run twice.
+    const retry = await host.deliver(token, {
+      headers: { ...JSON_HEADERS, "x-delivery-id": "abc-123" },
+      query: { attempt: "2" },
+      body: '{"attempt":2}',
+    });
+    expect(retry.status).toBe(200);
+    await settle();
+    expect(host.fired).toHaveLength(1);
+  });
+
+  it("starts a second run when the named field carries a different value", async () => {
+    host = await startWebhookHost();
+    const { token } = await host.arm({
+      methods: "POST",
+      dedupeField: "header:x-delivery-id",
+      dedupeTtlSeconds: 60,
+    });
+    const send = (id: string) =>
+      host!.deliver(token, {
+        headers: { ...JSON_HEADERS, "x-delivery-id": id },
+        body: '{"a":1}',
+      });
+
+    expect((await send("abc-123")).status).toBe(202);
+    expect((await send("def-456")).status).toBe(202);
+    await waitForRuns(host, 2);
+    expect(host.fired).toHaveLength(2);
+  });
+
+  it("runs every delivery when no dedupe field is configured", async () => {
+    host = await startWebhookHost();
+    const { token } = await host.arm({ methods: "POST" });
+    const send = () =>
+      host!.deliver(token, { headers: JSON_HEADERS, body: '{"a":1}' });
+
+    expect((await send()).status).toBe(202);
+    expect((await send()).status).toBe(202);
+    // Without an id there is no key, and collapsing unrelated deliveries under
+    // a shared "no key" bucket would silently drop real events.
+    await waitForRuns(host, 2);
+    expect(host.fired).toHaveLength(2);
+  });
+
+  it("runs both deliveries when the configured field is absent from the request", async () => {
+    host = await startWebhookHost();
+    const { token } = await host.arm({
+      methods: "POST",
+      dedupeField: "header:x-delivery-id",
+      dedupeTtlSeconds: 60,
+    });
+    const send = (body: string) =>
+      host!.deliver(token, { headers: JSON_HEADERS, body });
+
+    expect((await send('{"a":1}')).status).toBe(202);
+    expect((await send('{"a":2}')).status).toBe(202);
+    // A missing field is not a key either: two senders that both omit it are
+    // not the same delivery, and treating them as one loses the second event.
+    await waitForRuns(host, 2);
+    expect(host.fired).toHaveLength(2);
+  });
+
+  it("drops everything after the first when the named field repeats across events", async () => {
+    host = await startWebhookHost();
+    const { token } = await host.arm({
+      methods: "POST",
+      // A subscription id is the same on every delivery for that subscription,
+      // so naming it here is a configuration mistake with no error to see.
+      dedupeField: "subscriptionId",
+      dedupeTtlSeconds: 60,
+    });
+    const send = (eventId: string) =>
+      host!.deliver(token, {
+        headers: JSON_HEADERS,
+        body: `{"subscriptionId":"sub_1","eventId":"${eventId}"}`,
+      });
+
+    expect((await send("evt_1")).status).toBe(202);
+    await waitForRuns(host, 1);
+    // Two different events, second silently discarded: the field has to
+    // identify the delivery, not the thing it is about.
+    expect((await send("evt_2")).status).toBe(200);
+    await settle();
+    expect(host.fired).toHaveLength(1);
+  });
+});
+
+describe("core#webhook endpoint verification", () => {
+  it("echoes a bare challenge field from the query string without running", async () => {
+    host = await startWebhookHost();
+    const { token } = await host.arm({
+      methods: "POST",
+      challengeField: "hub.challenge",
+    });
+
+    const response = await host.deliver(token, {
+      query: { "hub.challenge": "nonce-42" },
+    });
+    expect(response.status).toBe(200);
+    // Verbatim: providers compare the body byte for byte, so a JSON wrapper or
+    // a trailing newline fails the subscription with nothing to read.
+    expect(await response.text()).toBe("nonce-42");
+    await settle();
+    expect(host.fired).toHaveLength(0);
+  });
+
+  it("echoes a `header:`-sourced challenge field without running", async () => {
+    host = await startWebhookHost();
+    const { token } = await host.arm({
+      methods: "POST",
+      challengeField: "header:x-hook-challenge",
+    });
+
+    const response = await host.deliver(token, {
+      headers: { ...JSON_HEADERS, "x-hook-challenge": "nonce-99" },
+      body: '{"type":"url_verification"}',
+    });
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe("nonce-99");
+    await settle();
+    expect(host.fired).toHaveLength(0);
+  });
+
+  it("runs as usual when the challenge field is absent", async () => {
+    host = await startWebhookHost();
+    const { token } = await host.arm({
+      methods: "POST",
+      challengeField: "hub.challenge",
+    });
+
+    // The challenge round happens once; every delivery after it is a real
+    // event, so a configured challenge field must not swallow the endpoint.
+    const response = await host.deliver(token, {
+      headers: JSON_HEADERS,
+      body: '{"id":"evt_1"}',
+    });
+    expect(response.status).toBe(202);
+    const [run] = await waitForRuns(host, 1);
+    expect(run.kind).toBe("webhook");
+  });
+});
+
+describe("core#webhook field policy", () => {
+  it("hands the reactor a source-tagged field for a prefixed config", async () => {
+    host = await startWebhookHost();
+    await host.arm({
+      methods: "POST",
+      dedupeField: "header:X-Delivery-ID",
+      challengeField: "body:challenge.value",
+      dedupeTtlSeconds: 60,
+    });
+
+    const policy = (await host.policyFor()) as PolicyShape;
+    // Lowercased for the reactor's header record; the prefix must survive
+    // parsing or the reactor reads the query string and finds no id.
+    expect(policy.dedupe?.field).toEqual({ header: "x-delivery-id" });
+    expect(policy.dedupe?.ttlSeconds).toBe(60);
+    expect(policy.challengeField).toEqual({ body: "challenge.value" });
+  });
+
+  it("leaves a bare field name bare, so the reactor tries query then body", async () => {
+    host = await startWebhookHost();
+    await host.arm({
+      methods: "POST",
+      dedupeField: "eventId",
+      challengeField: "hub.challenge",
+    });
+
+    const policy = (await host.policyFor()) as PolicyShape;
+    expect(policy.dedupe?.field).toBe("eventId");
+    expect(policy.challengeField).toBe("hub.challenge");
+  });
+});