@powerhousedao/switchboard 6.2.3-dev.32 → 6.2.3-dev.33

package/dist/server.d.mts

@@ -1,5 +1,5 @@
 import { ILogger } from "document-model";
-import { ChannelScheme, IDocumentModelLoader, IReactorClient, InProcessReactorClientModule, JwtHandler, ReactorBuilder, ReactorClientBuilder, ReactorFeatureFlags, SignerConfig } from "@powerhousedao/reactor";
+import { ChannelScheme, IDocumentModelLoader, IReactorClient, InProcessReactorClientModule, JwtHandler, ReactorBuilder, ReactorClientBuilder, ReactorFeatureFlags, SignerConfig, UnsupportedStoredDocuments, UnsupportedStoredProtocolError } from "@powerhousedao/reactor";
 import { AttachmentReferenceProjectionCapability } from "@powerhousedao/reactor-api";
 import { IAttachmentService } from "@powerhousedao/reactor-attachments";
 import { IRenown } from "@renown/sdk/node";
@@ -170,6 +170,14 @@ export type StartServerOptions = {
     enabled?: boolean;
     dbPoolSize?: number;
   };
+  /**
+   * Stored documents at protocol versions this build does not run: "refuse"
+   * (the default) fails the boot with a StoredDocumentsRefusedError;
+   * "read-only" starts with a warning and keeps those documents read-only.
+   * Unset falls back to the REACTOR_UNSUPPORTED_STORED_DOCUMENTS env var.
+   * Ignored when `reactor` is passed.
+   */
+  unsupportedStoredDocuments?: UnsupportedStoredDocuments;
 };
 export type SwitchboardReactor = {
   defaultDriveUrl: string | undefined;
@@ -244,6 +252,20 @@ type SwitchboardReactorDefaultsOptions = {
 };
 export declare function applySwitchboardReactorDefaults(reactorBuilder: ReactorBuilder, clientBuilder: ReactorClientBuilder, options?: SwitchboardReactorDefaultsOptions): void;
 //#endregion
+//#region src/unsupported-stored-documents.d.mts
+/** From REACTOR_UNSUPPORTED_STORED_DOCUMENTS; `input` wins when defined. */
+export declare function resolveUnsupportedStoredDocuments(input: UnsupportedStoredDocuments | undefined, env: NodeJS.ProcessEnv): UnsupportedStoredDocuments;
+/** The reactor refused to start over documents this build does not run. */
+export declare class StoredDocumentsRefusedError extends Error {
+  readonly versions: readonly {
+    protocol: string;
+    version: number;
+  }[];
+  readonly documents: number;
+  constructor(cause: UnsupportedStoredProtocolError);
+  static isError(error: unknown): error is StoredDocumentsRefusedError;
+}
+//#endregion
 //#region src/server.d.mts
 /**
  * Attempt to bind a throwaway TCP server to the given port. Resolves true if

package/dist/server.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.mts","names":[],"sources":["../src/workflow-runtime.mts","../src/types.ts","../src/builder-defaults.mts","../src/server.mts"],"mappings":";;;;;;;;;;;;;KA2DY;EACN;;EAEA;EACA;;;;;;;;;;YC7CM;;YAKA,wBAAwB;EAClC,eAAe;;YAGL;EACV;EACA;EACA;;YAGU;;EAEV;;;;;EAKA;;EAGA;;YAGU;;;;;;;;;;;;;;;;;;;;;EAqBV,UAAU;;;;;;;;EAQV;;;;;;;EAOA;EACA;EACA;;;;;;EAMA;EACA;EACA;EACA,QAAQ;EACR;EACA;EACA;IAEM;IACA;;;;;;;EASN,WAAW;;EAEX;EACA;;;EAGA;IACE;;EAEF,kBAAkB;EAClB;EACA;;;;;;EAMA;EACA,SAAS;;;;;;;;;;EAUT;;;;;;;;;;EAUA;;;;;;;;;EASA;IACE;IACA;IACA;;;;;;;;;;;EAWF;IACE;IACA;;;YAIQ;EACV;EACA,SAAS;;EAET,mBAAmB;;EAEnB,+BAA+B;;;EAG/B,mBAAmB;;EAEnB;;EAEA,QAAQ;;;;;EAKR;;;;;;;;;;;;;EAaA,gBAAgB;;;;KCzLN;EAIV,iBAAiB;;EAEjB,mBAAmB;;EAEnB;;;;;;EAMA,gBAAgB;;EAEhB;;EAEA;IACE;IACA,eAAe,QAAQ;;;EAGzB,sBAAsB;EACtB,SAAS;;;;;;EAMT,SAAS;;;;;EAKT,cAAc,KAAK;;EAEnB,wBAAwB;;wBAsBV,gCACd,gBAAgB,gBAChB,eAAe,sBACf,UAAS;;;;;;;;wBC6DK,gBAAgB,eAAe;;wBAoI/B,8BACd,SAAS,KAAK,uDACd,oBACA,QAAQ;EACL;EAAmB,YAAY;;;;;;;;;;;;;;;;;;;qBAu5BvB,mBAAgB,UAClB,uBACR,QAAQ"}
+{"version":3,"file":"server.d.mts","names":[],"sources":["../src/workflow-runtime.mts","../src/types.ts","../src/builder-defaults.mts","../src/unsupported-stored-documents.mts","../src/server.mts"],"mappings":";;;;;;;;;;;;;KA2DY;EACN;;EAEA;EACA;;;;;;;;;;YC5CM;;YAKA,wBAAwB;EAClC,eAAe;;YAGL;EACV;EACA;EACA;;YAGU;;EAEV;;;;;EAKA;;EAGA;;YAGU;;;;;;;;;;;;;;;;;;;;;EAqBV,UAAU;;;;;;;;EAQV;;;;;;;EAOA;EACA;EACA;;;;;;EAMA;EACA;EACA;EACA,QAAQ;EACR;EACA;EACA;IAEM;IACA;;;;;;;EASN,WAAW;;EAEX;EACA;;;EAGA;IACE;;EAEF,kBAAkB;EAClB;EACA;;;;;;EAMA;EACA,SAAS;;;;;;;;;;EAUT;;;;;;;;;;EAUA;;;;;;;;;EASA;IACE;IACA;IACA;;;;;;;;;;;EAWF;IACE;IACA;;;;;;;;;EASF,6BAA6B;;YAGnB;EACV;EACA,SAAS;;EAET,mBAAmB;;EAEnB,+BAA+B;;;EAG/B,mBAAmB;;EAEnB;;EAEA,QAAQ;;;;;EAKR;;;;;;;;;;;;;EAaA,gBAAgB;;;;KClMN;EAIV,iBAAiB;;EAEjB,mBAAmB;;EAEnB;;;;;;EAMA,gBAAgB;;EAEhB;;EAEA;IACE;IACA,eAAe,QAAQ;;;EAGzB,sBAAsB;EACtB,SAAS;;;;;;EAMT,SAAS;;;;;EAKT,cAAc,KAAK;;EAEnB,wBAAwB;;wBAsBV,gCACd,gBAAgB,gBAChB,eAAe,sBACf,UAAS;;;;wBC3EK,kCACd,OAAO,wCACP,KAAK,OAAO,aACX;;qBAaU,oCAAoC;WACtC;IAAqB;IAAkB;;WACvC;EAET,YAAY,OAAO;SAcZ,QAAQ,iBAAiB,SAAS;;;;;;;;;wBC2G3B,gBAAgB,eAAe;;wBAoI/B,8BACd,SAAS,KAAK,uDACd,oBACA,QAAQ;EACL;EAAmB,YAAY;;;;;;;;;;;;;;;;;;;qBAi7BvB,mBAAgB,UAClB,uBACR,QAAQ"}

package/dist/server.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as applySwitchboardReactorDefaults, n as isPortAvailable, r as startSwitchboard, t as deriveAttachmentServiceConfig } from "./server-CKKn0aXV.mjs";
-export { applySwitchboardReactorDefaults, deriveAttachmentServiceConfig, isPortAvailable, startSwitchboard };
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fe3a107a-4dd4-530b-b8d9-ef36656e688e")}catch(e){}}();
-//# debugId=fe3a107a-4dd4-530b-b8d9-ef36656e688e
+import { a as resolveUnsupportedStoredDocuments, i as StoredDocumentsRefusedError, n as isPortAvailable, o as applySwitchboardReactorDefaults, r as startSwitchboard, t as deriveAttachmentServiceConfig } from "./server-DAgJkmvH.mjs";
+export { StoredDocumentsRefusedError, applySwitchboardReactorDefaults, deriveAttachmentServiceConfig, isPortAvailable, resolveUnsupportedStoredDocuments, startSwitchboard };
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="631cf56c-74d8-5495-a51e-94daa58b7193")}catch(e){}}();
+//# debugId=631cf56c-74d8-5495-a51e-94daa58b7193

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@powerhousedao/switchboard",
   "type": "module",
-  "version": "6.2.3-dev.32",
+  "version": "6.2.3-dev.33",
   "main": "dist/index.mjs",
   "exports": {
     ".": {
@@ -41,7 +41,7 @@
     "@openfeature/core": "1.9.1",
     "@openfeature/env-var-provider": "0.3.1",
     "@openfeature/server-sdk": "1.19.0",
-    "@powerhousedao/config": "6.2.3-dev.32",
+    "@powerhousedao/config": "6.2.3-dev.33",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
@@ -55,22 +55,22 @@
     "@opentelemetry/sdk-node": "^0.218.0",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.41.1",
-    "@powerhousedao/opentelemetry-instrumentation-reactor": "6.2.3-dev.32",
-    "@powerhousedao/reactor": "6.2.3-dev.32",
-    "@powerhousedao/shared": "6.2.3-dev.32",
-    "@powerhousedao/vetra": "6.2.3-dev.32",
-    "@powerhousedao/reactor-api": "6.2.3-dev.32",
-    "@powerhousedao/reactor-attachments": "6.2.3-dev.32",
-    "@powerhousedao/reactor-drive": "6.2.3-dev.32",
-    "@powerhousedao/reactor-group": "6.2.3-dev.32",
-    "@powerhousedao/reactor-workflow": "6.2.3-dev.32",
-    "@powerhousedao/workflow": "6.2.3-dev.32",
-    "@powerhousedao/pglite-fs": "6.2.3-dev.32",
+    "@powerhousedao/opentelemetry-instrumentation-reactor": "6.2.3-dev.33",
+    "@powerhousedao/reactor": "6.2.3-dev.33",
+    "@powerhousedao/shared": "6.2.3-dev.33",
+    "@powerhousedao/vetra": "6.2.3-dev.33",
+    "@powerhousedao/reactor-api": "6.2.3-dev.33",
+    "@powerhousedao/reactor-attachments": "6.2.3-dev.33",
+    "@powerhousedao/reactor-drive": "6.2.3-dev.33",
+    "@powerhousedao/reactor-group": "6.2.3-dev.33",
+    "@powerhousedao/reactor-workflow": "6.2.3-dev.33",
+    "@powerhousedao/workflow": "6.2.3-dev.33",
+    "@powerhousedao/pglite-fs": "6.2.3-dev.33",
     "@pyroscope/nodejs": "^0.4.5",
-    "@renown/sdk": "6.2.3-dev.32",
+    "@renown/sdk": "6.2.3-dev.33",
     "@sentry/node": "^10.53.1",
     "@sentry/opentelemetry": "^10.53.1",
-    "document-model": "6.2.3-dev.32",
+    "document-model": "6.2.3-dev.33",
     "dotenv": "^16.4.7",
     "express": "^4.22.1",
     "graphql": "^16",

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

@@ -0,0 +1,210 @@
+import { PGlite } from "@electric-sql/pglite";
+import { AtomicNodeFs } from "@powerhousedao/pglite-fs";
+import {
+  JobStatus,
+  ReactorBuilder,
+  type Database,
+} from "@powerhousedao/reactor";
+import { driveDocumentModelModule } from "@powerhousedao/shared/document-drive";
+import {
+  withSignaturePolicy,
+  type PeerCapability,
+} from "@powerhousedao/shared/document-model";
+import type { ILogger } from "document-model";
+import { Kysely } from "kysely";
+import { cp, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+import { ClosablePGliteDialect } from "../src/pglite-dialect.js";
+import { startSwitchboard } from "../src/server.mjs";
+import { StoredDocumentsRefusedError } from "../src/unsupported-stored-documents.mjs";
+
+const ENV_KEYS = [
+  "PH_REACTOR_DATABASE_URL",
+  "DATABASE_URL",
+  "REACTOR_UNSUPPORTED_STORED_DOCUMENTS",
+] as const;
+
+const BASE_REDUCER_7: PeerCapability = {
+  kind: "protocol",
+  name: "base-reducer",
+  baseline: [1, 2],
+  supported: () => [1, 2, 7],
+  preferred: () => 2,
+  optional: false,
+};
+
+type StubLogger = ILogger & {
+  warn: ReturnType<typeof vi.fn>;
+  error: ReturnType<typeof vi.fn>;
+};
+
+function stubLogger(): StubLogger {
+  const logger = {
+    verbose: vi.fn(),
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    child: vi.fn(),
+  };
+  logger.child.mockReturnValue(logger);
+  return logger as unknown as StubLogger;
+}
+
+/** A reactor store holding one drive created at base-reducer 7. */
+async function seedStore(dir: string): Promise<void> {
+  const db = new Kysely<Database>({
+    dialect: new ClosablePGliteDialect(
+      new PGlite({ fs: new AtomicNodeFs(dir) }),
+    ),
+  });
+  const module = await new ReactorBuilder()
+    .withKysely(db)
+    .withDocumentModelSources([driveDocumentModelModule as never])
+    .withPeerCapabilities([BASE_REDUCER_7])
+    .buildModule();
+  const created = await module.reactor.create(
+    withSignaturePolicy(
+      driveDocumentModelModule.utils.createDocument(),
+      "legacy",
+      {
+        id: "br7-stored",
+        protocolVersions: { "base-reducer": 7 },
+      },
+    ),
+  );
+  await vi.waitUntil(
+    async () => {
+      const { status } = await module.reactor.getJobStatus(created.id);
+      return status === JobStatus.READ_READY || status === JobStatus.FAILED;
+    },
+    { timeout: 10_000, interval: 5 },
+  );
+  expect((await module.reactor.getJobStatus(created.id)).status).toBe(
+    JobStatus.READ_READY,
+  );
+  await module.reactor.kill().completed;
+  await db.destroy();
+}
+
+// PGlite boots are several times slower on Windows runners.
+const BOOT_TIMEOUT = 120_000;
+
+describe("booting over documents this build does not run", () => {
+  let seeded: string;
+  let tempRoot: string;
+  let previous: Partial<Record<(typeof ENV_KEYS)[number], string>>;
+
+  beforeAll(async () => {
+    seeded = await mkdtemp(join(tmpdir(), "switchboard-stored-protocol-seed-"));
+    await seedStore(join(seeded, "reactor-storage"));
+  }, BOOT_TIMEOUT);
+
+  afterAll(async () => {
+    await rm(seeded, { recursive: true, force: true });
+  });
+
+  beforeEach(async () => {
+    tempRoot = await mkdtemp(join(tmpdir(), "switchboard-stored-protocol-"));
+    previous = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+    process.env.PH_REACTOR_DATABASE_URL = join(tempRoot, "reactor-storage");
+    process.env.DATABASE_URL = join(tempRoot, "read-model");
+    delete process.env.REACTOR_UNSUPPORTED_STORED_DOCUMENTS;
+    await cp(
+      join(seeded, "reactor-storage"),
+      process.env.PH_REACTOR_DATABASE_URL,
+      { recursive: true },
+    );
+  });
+
+  afterEach(async () => {
+    for (const key of ENV_KEYS) {
+      if (previous[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = previous[key];
+      }
+    }
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  function boot(logger: ILogger) {
+    return startSwitchboard({
+      workflows: { enabled: false },
+      port: 0,
+      mcp: false,
+      disableLocalPackages: true,
+      identity: { keypairPath: join(tempRoot, "identity.json") },
+      logger,
+    });
+  }
+
+  it(
+    "refuses by default and tells the operator both ways forward",
+    async () => {
+      const logger = stubLogger();
+
+      const booted = boot(logger);
+
+      await expect(booted).rejects.toSatisfy(
+        (error) =>
+          StoredDocumentsRefusedError.isError(error) &&
+          error.documents === 1 &&
+          error.versions.some(
+            ({ protocol, version }) =>
+              protocol === "base-reducer" && version === 7,
+          ),
+      );
+      const message = (await booted.catch((error: Error) => error)) as Error;
+      expect(message.message).toMatch(
+        /1 stored document\(s\) require base-reducer 7/,
+      );
+      expect(message.message).toMatch(
+        /switchboard build that runs base-reducer 7/,
+      );
+      expect(message.message).toMatch(
+        /REACTOR_UNSUPPORTED_STORED_DOCUMENTS=read-only/,
+      );
+      expect(logger.error).toHaveBeenCalledWith(message.message);
+      expect(logger.error).not.toHaveBeenCalledWith(
+        "App crashed: @error",
+        expect.anything(),
+      );
+    },
+    BOOT_TIMEOUT,
+  );
+
+  it(
+    "starts read-only when REACTOR_UNSUPPORTED_STORED_DOCUMENTS says so",
+    async () => {
+      process.env.REACTOR_UNSUPPORTED_STORED_DOCUMENTS = "read-only";
+      const logger = stubLogger();
+
+      const switchboard = await boot(logger);
+      try {
+        expect(logger.warn).toHaveBeenCalledWith(
+          expect.stringContaining("read-only"),
+          expect.stringContaining(
+            "1 stored document(s) require base-reducer 7",
+          ),
+        );
+        const stored = await switchboard.reactor.get("br7-stored");
+        expect(stored.header.id).toBe("br7-stored");
+      } finally {
+        await switchboard.shutdown();
+      }
+    },
+    BOOT_TIMEOUT,
+  );
+});

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);
+  });
+});