@hot-updater/server 1.0.0-rc.1 → 1.0.0-rc.16

package/src/assembly/assemblePlugins.ts

@@ -0,0 +1,269 @@
+import type { DatabaseAdapter } from "@hot-updater/plugin-core/internal";
+
+import { createCoreApi, type CoreApi } from "../core/api";
+import { createCoreReads, type CoreStorage } from "../core/reads";
+import { coreModule } from "../core/schema";
+import { createDatabaseEngine } from "../database/database";
+import type { ReadMeasurement } from "../database/engine";
+import { fencedName, withSchemaFence } from "../database/fence";
+import {
+  resolveSchema,
+  validateSchema,
+  type SchemaModule,
+} from "../database/resolveSchema";
+import type { ModuleSchema } from "../database/schema";
+import { addedSettings, builtInModules } from "../db/builtInDatabase";
+import { builtInPlugin } from "../plugins/builtIn";
+import type {
+  ClientAuth,
+  PluginEndpoint,
+  PluginInstance,
+} from "../plugins/definePlugin";
+
+/** A misconfigured `createHotUpdater` call, reported at startup. */
+export class HotUpdaterConfigError extends Error {
+  readonly name = "HotUpdaterConfigError";
+}
+
+export interface MountedEndpoint extends PluginEndpoint {
+  readonly plugin: string;
+}
+
+export interface AssembledPlugins {
+  /** Core's reads and typed writes, on the same engine as the plugins, which get only the reads. */
+  readonly core: CoreApi;
+  readonly api: Readonly<Record<string, unknown>>;
+  readonly endpoints: readonly MountedEndpoint[];
+  readonly clientAuth?: ClientAuth & { readonly plugin: string };
+  /** With `verify`: runs `read` and reports what it read at both boundaries. */
+  readonly measureReads?: <T>(
+    read: () => Promise<T>,
+  ) => Promise<ReadMeasurement<T>>;
+}
+
+interface PluginShape {
+  readonly id: string;
+  readonly provides?: { readonly clientAuth?: true };
+  readonly schemaVersion: string;
+  readonly schema: ModuleSchema;
+  init(context: unknown): PluginInstance;
+  readonly [builtInPlugin]?: true;
+}
+
+const PLUGIN_KEYS = new Set([
+  "id",
+  "provides",
+  "schemaVersion",
+  "schema",
+  "init",
+]);
+const INSTANCE_KEYS = new Set(["api", "endpoints", "clientAuth"]);
+const METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+const BUILT_IN_ID = /^[a-z][A-Za-z0-9]*$/u;
+const PLUGIN_ID = /^[a-z][a-z0-9_]*$/u;
+const PATH = /^(\/(:?[A-Za-z0-9_.~-]+))+$/u;
+
+const fail = (message: string): never => {
+  throw new HotUpdaterConfigError(message);
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const checkPlugin = (value: unknown, at: string): PluginShape => {
+  if (!isRecord(value)) return fail(`${at} is not a plugin.`);
+  if ("kind" in value) {
+    fail(`${at} has a kind; core is built in and is never passed as a plugin.`);
+  }
+  const unknown = Object.keys(value).find((key) => !PLUGIN_KEYS.has(key));
+  if (unknown !== undefined) fail(`${at} has an unknown key "${unknown}".`);
+  const plugin = value as unknown as PluginShape;
+  const pattern = plugin[builtInPlugin] ? BUILT_IN_ID : PLUGIN_ID;
+  if (typeof plugin.id !== "string" || !pattern.test(plugin.id)) {
+    fail(`${at} needs an id matching ${pattern.source}.`);
+  }
+  if (plugin.id === coreModule.id) {
+    fail(`${at} uses the id "core", which is core's own.`);
+  }
+  if (
+    typeof plugin.schemaVersion !== "string" ||
+    !isRecord(plugin.schema) ||
+    typeof plugin.init !== "function"
+  ) {
+    fail(`Plugin "${plugin.id}" needs a schemaVersion, a schema, and init.`);
+  }
+  const provides = plugin.provides as unknown;
+  if (
+    provides !== undefined &&
+    (!isRecord(provides) ||
+      Object.entries(provides).some(
+        ([key, flag]) => key !== "clientAuth" || flag !== true,
+      ))
+  ) {
+    fail(
+      `Plugin "${plugin.id}" may only declare provides: { clientAuth: true }.`,
+    );
+  }
+  return plugin;
+};
+
+const checkEndpoint = (id: string, value: unknown): MountedEndpoint => {
+  const endpoint = (isRecord(value) ? value : {}) as Partial<PluginEndpoint>;
+  if (
+    !METHODS.has(endpoint.method as string) ||
+    typeof endpoint.path !== "string" ||
+    !PATH.test(endpoint.path) ||
+    (endpoint.access !== "client" && endpoint.access !== "admin") ||
+    typeof endpoint.handler !== "function"
+  ) {
+    fail(
+      `Plugin "${id}" has an endpoint that needs a method, a path like /name/:param, access "client" or "admin", and a handler.`,
+    );
+  }
+  return { ...(endpoint as PluginEndpoint), plugin: id };
+};
+
+const checkInstance = (plugin: PluginShape, instance: unknown) => {
+  const { id } = plugin;
+  if (!isRecord(instance))
+    return fail(`Plugin "${id}" init returned no instance.`);
+  if (typeof instance.then === "function") {
+    fail(`Plugin "${id}" init returned a promise; init must be synchronous.`);
+  }
+  const unknown = Object.keys(instance).find((key) => !INSTANCE_KEYS.has(key));
+  if (unknown !== undefined || !("api" in instance)) {
+    fail(
+      `Plugin "${id}" init must return { api, endpoints?, clientAuth? }${unknown === undefined ? "" : `, not "${unknown}"`}.`,
+    );
+  }
+  const declared = plugin.provides?.clientAuth === true;
+  const clientAuth = instance.clientAuth as ClientAuth | undefined;
+  if (declared !== (clientAuth !== undefined)) {
+    fail(
+      declared
+        ? `Plugin "${id}" declares provides: { clientAuth: true } but its instance has no clientAuth.`
+        : `Plugin "${id}" returns clientAuth without declaring provides: { clientAuth: true }.`,
+    );
+  }
+  if (
+    clientAuth !== undefined &&
+    (typeof clientAuth.authenticate !== "function" ||
+      !Array.isArray(clientAuth.varyHeaders) ||
+      !clientAuth.varyHeaders.every((header) => typeof header === "string"))
+  ) {
+    fail(`Plugin "${id}" clientAuth needs varyHeaders and authenticate.`);
+  }
+  const endpoints = instance.endpoints ?? [];
+  if (!Array.isArray(endpoints))
+    fail(`Plugin "${id}" endpoints must be an array.`);
+  return {
+    api: instance.api,
+    clientAuth,
+    endpoints: (endpoints as unknown[]).map((endpoint) =>
+      checkEndpoint(id, endpoint),
+    ),
+  };
+};
+
+/**
+ * Checks every plugin, runs each `init` once against one engine over the
+ * database's storage adapter, and collects APIs, endpoints, and clientAuth.
+ * Core's reads run on the same engine, so plugins read core through `ctx.core`.
+ */
+export const assemblePlugins = (
+  value: unknown,
+  adapter: DatabaseAdapter,
+  {
+    now = Date.now,
+    storage = { resolveFileUrl: async () => null },
+    verify = false,
+    onCachedRoutesChange,
+  }: {
+    readonly now?: () => number;
+    readonly storage?: CoreStorage;
+    /** Runs the engine in verify mode, which meters reads for `measureReads`. */
+    readonly verify?: boolean;
+    /** The database's CDN purge, which core calls after a catalog write. */
+    readonly onCachedRoutesChange?: () => Promise<void>;
+  } = {},
+): AssembledPlugins => {
+  if (!Array.isArray(value))
+    return fail("plugins must be an array of plugins.");
+  const plugins = value.map((plugin, position) =>
+    checkPlugin(plugin, `plugins[${position}]`),
+  );
+  const ids = new Set<string>();
+  for (const { id } of plugins) {
+    if (ids.has(id)) fail(`Plugin "${id}" is registered twice.`);
+    ids.add(id);
+  }
+  const modules: (SchemaModule & { readonly schema: ModuleSchema })[] =
+    plugins.map((plugin) => ({
+      id: plugin.id,
+      schema: plugin.schema,
+      ...(plugin[builtInPlugin] ? {} : { namespace: plugin.id }),
+    }));
+  const added = modules.filter(({ namespace }) => namespace !== undefined);
+  if (added.length > 0) {
+    // Tooling creates the built-in tables and settings rows whichever plugins
+    // a server runs, so a third-party plugin takes none of their names.
+    const taken = added.find(({ id }) =>
+      builtInModules.some((module) => module.id === id),
+    );
+    if (taken !== undefined) {
+      fail(`Plugin "${taken.id}" uses a built-in plugin's id.`);
+    }
+    validateSchema([...builtInModules, ...added]);
+  }
+  // A fenced database also waits for each third-party plugin's settings row.
+  const name = fencedName(adapter);
+  const engine = createDatabaseEngine({
+    adapter:
+      name === undefined || added.length === 0
+        ? adapter
+        : withSchemaFence(adapter, name, addedSettings(plugins)),
+    schema: resolveSchema([coreModule, ...modules]),
+    verify,
+  });
+  const coreDatabase = engine.database(coreModule);
+  const core = createCoreApi(coreDatabase, storage, {
+    now,
+    ...(onCachedRoutesChange === undefined ? {} : { onCachedRoutesChange }),
+  });
+  const reads = createCoreReads(coreDatabase, storage);
+  const api: Record<string, unknown> = {};
+  const endpoints: MountedEndpoint[] = [];
+  let clientAuth: AssembledPlugins["clientAuth"];
+  plugins.forEach((plugin, position) => {
+    const instance = checkInstance(
+      plugin,
+      plugin.init({
+        db: engine.database(modules[position]!),
+        core: reads,
+        now,
+      }),
+    );
+    if (instance.clientAuth !== undefined) {
+      if (clientAuth !== undefined) {
+        fail(
+          `Plugins "${clientAuth.plugin}" and "${plugin.id}" both provide clientAuth; keep one.`,
+        );
+      }
+      const provided = instance.clientAuth;
+      clientAuth = {
+        plugin: plugin.id,
+        varyHeaders: provided.varyHeaders,
+        authenticate: (headers) => provided.authenticate(headers),
+      };
+    }
+    endpoints.push(...instance.endpoints);
+    api[plugin.id] = instance.api;
+  });
+  return {
+    core,
+    api,
+    endpoints,
+    ...(clientAuth === undefined ? {} : { clientAuth }),
+    ...(verify ? { measureReads: engine.measureReads } : {}),
+  };
+};

package/src/assembly/assembly.spec.ts

@@ -0,0 +1,325 @@
+import { createMemoryAdapter } from "@hot-updater/plugin-core/internal";
+import { describe, expect, it, vi } from "vitest";
+
+import { createBundleFixture } from "../../../test-utils/src/databaseTestFixtures";
+import { createHotUpdater } from "../createHotUpdaterCore";
+import { defineTable } from "../database/schema";
+import { listHotUpdaterRoutes } from "../handler";
+import { definePlugin } from "../plugins/definePlugin";
+import { HotUpdaterConfigError } from "./assemblePlugins";
+
+const database = () => ({ name: "memory", adapter: createMemoryAdapter() });
+
+const notes = definePlugin({
+  id: "notes",
+  schemaVersion: "1",
+  schema: {
+    notes: defineTable(
+      { id: { type: "string" }, text: { type: "string" } },
+      { key: ["id"] },
+    ),
+  },
+  init: ({ db, now }) => ({
+    api: {
+      add: (id: string, text: string) =>
+        db.transaction(async (tx) => {
+          tx.create("notes", { id, text });
+        }),
+      read: (id: string) => db.findOne("notes", { id }),
+      now,
+    },
+    endpoints: [
+      {
+        method: "GET",
+        path: "/notes/:id",
+        access: "client",
+        handler: async (_request, params) =>
+          Response.json(await db.findOne("notes", { id: params.id! }), {
+            headers: { "cache-control": "public, max-age=60" },
+          }),
+      },
+      {
+        method: "DELETE",
+        path: "/notes/:id",
+        access: "admin",
+        handler: async () => new Response(null, { status: 204 }),
+      },
+    ],
+  }),
+});
+
+const keys = (
+  authenticate = async (headers: Headers) => headers.get("x-key") === "valid",
+) =>
+  definePlugin({
+    id: "keys",
+    provides: { clientAuth: true },
+    schemaVersion: "1",
+    schema: {},
+    init: () => ({
+      api: {},
+      clientAuth: { varyHeaders: ["X-Key"], authenticate },
+    }),
+  });
+
+const startup = (options: Record<string, unknown>) => () =>
+  createHotUpdater({ database: database(), ...options } as never);
+
+describe("createHotUpdater with plugins", () => {
+  it("gives each plugin its own tables on the engine and exposes its API by id", async () => {
+    const hotUpdater = createHotUpdater({
+      database: database(),
+      plugins: [notes],
+      clientAccess: "public",
+    });
+    await hotUpdater.api.notes.add("n1", "hello");
+    await expect(hotUpdater.api.notes.read("n1")).resolves.toEqual({
+      id: "n1",
+      text: "hello",
+    });
+    expect(hotUpdater.api.notes.now()).toBeTypeOf("number");
+  });
+
+  it("mounts endpoints by access and lists every route with its access", () => {
+    const { handlers } = createHotUpdater({
+      database: database(),
+      plugins: [notes, keys()],
+    });
+    expect(listHotUpdaterRoutes(handlers)).toEqual([
+      { method: "GET", path: "/version", access: "public" },
+      {
+        method: "GET",
+        path: "/release-catalogs/app-version/:platform/:channelKey/:appVersion",
+        access: "client",
+      },
+      {
+        method: "GET",
+        path: "/release-catalogs/fingerprint/:platform/:channelKey/:fingerprintHash",
+        access: "client",
+      },
+      {
+        method: "GET",
+        path: "/artifacts/v1/:targetBundleId/from/:currentBundleId",
+        access: "client",
+      },
+      { method: "POST", path: "/events", access: "client" },
+      { method: "GET", path: "/version", access: "admin" },
+      { method: "POST", path: "/releases", access: "admin" },
+      { method: "POST", path: "/releases/:id/promote", access: "admin" },
+      { method: "GET", path: "/releases/:id", access: "admin" },
+      { method: "GET", path: "/releases", access: "admin" },
+      { method: "PATCH", path: "/releases/:id", access: "admin" },
+      { method: "POST", path: "/releases/:id/preflight", access: "admin" },
+      { method: "DELETE", path: "/releases/:id", access: "admin" },
+      { method: "GET", path: "/release-catalogs/:scopeKey", access: "admin" },
+      { method: "GET", path: "/release-catalogs", access: "admin" },
+      {
+        method: "POST",
+        path: "/release-catalogs/:scopeKey/rebuild",
+        access: "admin",
+      },
+      {
+        method: "POST",
+        path: "/release-catalogs/:scopeKey/preflight",
+        access: "admin",
+      },
+      { method: "GET", path: "/channels", access: "admin" },
+      { method: "POST", path: "/channels", access: "admin" },
+      { method: "DELETE", path: "/channels/:id", access: "admin" },
+      { method: "GET", path: "/bundles/count", access: "admin" },
+      { method: "GET", path: "/bundles/child-counts", access: "admin" },
+      { method: "GET", path: "/bundles/:id", access: "admin" },
+      { method: "GET", path: "/bundles", access: "admin" },
+      { method: "PATCH", path: "/bundles/:id", access: "admin" },
+      { method: "POST", path: "/bundles/delete", access: "admin" },
+      { method: "GET", path: "/bundles/:id/children", access: "admin" },
+      {
+        method: "GET",
+        path: "/base-candidates/:candidateKey",
+        access: "admin",
+      },
+      { method: "GET", path: "/events", access: "admin" },
+      { method: "GET", path: "/overview", access: "admin" },
+      { method: "GET", path: "/installations", access: "admin" },
+      {
+        method: "GET",
+        path: "/installations/:installId/events",
+        access: "admin",
+      },
+      { method: "GET", path: "/installations/:installId", access: "admin" },
+      { method: "GET", path: "/notes/:id", access: "client" },
+      { method: "DELETE", path: "/notes/:id", access: "admin" },
+    ]);
+  });
+
+  it("puts client routes and client endpoints behind clientAuth, never /version, and varies cacheable answers", async () => {
+    const authenticate = vi.fn(async (headers: Headers) => {
+      if (headers.get("x-key") === "down") throw new Error("unavailable");
+      return headers.get("x-key") === "valid";
+    });
+    const hotUpdater = createHotUpdater({
+      database: database(),
+      plugins: [notes, keys(authenticate)],
+    });
+    await hotUpdater.api.notes.add("n1", "hello");
+    const client = (path: string, key?: string) =>
+      hotUpdater.handlers.client(
+        new Request(`https://updates.example.com${path}`, {
+          headers: key === undefined ? {} : { "x-key": key },
+        }),
+      );
+
+    expect((await client("/version")).status).toBe(200);
+    expect(authenticate).not.toHaveBeenCalled();
+    expect((await client("/notes/n1")).status).toBe(401);
+    expect((await client("/notes/n1", "down")).status).toBe(503);
+    const allowed = await client("/notes/n1", "valid");
+    expect(allowed.status).toBe(200);
+    await expect(allowed.json()).resolves.toMatchObject({ text: "hello" });
+    expect(allowed.headers.get("vary")).toBe("x-key");
+    expect(
+      (
+        await hotUpdater.handlers.admin(
+          new Request("https://updates.example.com/notes/n1", {
+            method: "DELETE",
+          }),
+        )
+      ).status,
+    ).toBe(204);
+  });
+
+  it("leaves client routes open with clientAccess: public", async () => {
+    const hotUpdater = createHotUpdater({
+      database: database(),
+      plugins: [notes],
+      clientAccess: "public",
+    });
+    await hotUpdater.api.notes.add("n1", "hello");
+    const response = await hotUpdater.handlers.client(
+      new Request("https://updates.example.com/notes/n1"),
+    );
+    expect(response.status).toBe(200);
+    expect(response.headers.get("vary")).toBeNull();
+  });
+
+  it("purges the database's cached client routes after core writes a Release Catalog, not after a plugin write", async () => {
+    const onCachedRoutesChange = vi.fn(async () => undefined);
+    const hotUpdater = createHotUpdater({
+      database: { ...database(), onCachedRoutesChange },
+      plugins: [notes],
+      clientAccess: "public",
+    });
+
+    await hotUpdater.api.notes.add("n1", "hello");
+    expect(onCachedRoutesChange).not.toHaveBeenCalled();
+    await hotUpdater.core.deploy([
+      {
+        bundle: createBundleFixture("801"),
+        release: {
+          channel: "production",
+          enabled: true,
+          fingerprintHash: null,
+          message: null,
+          shouldForceUpdate: false,
+          targetAppVersion: "1.0.0",
+        },
+      },
+    ]);
+
+    expect(onCachedRoutesChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects every misconfiguration at startup", () => {
+    const valid = {
+      id: "valid",
+      schemaVersion: "1",
+      schema: {},
+      init: () => ({ api: {} }),
+    };
+    const cases: [Record<string, unknown>, string][] = [
+      [{ plugins: [notes] }, 'Set clientAccess to "public"'],
+      [
+        { plugins: [keys()], clientAccess: "public" },
+        'Plugin "keys" provides clientAuth, so remove clientAccess.',
+      ],
+      [
+        {
+          plugins: [keys(), { ...keys(), id: "sso" }],
+        },
+        'Plugins "keys" and "sso" both provide clientAuth; keep one.',
+      ],
+      [
+        { plugins: [valid, valid], clientAccess: "public" },
+        'Plugin "valid" is registered twice.',
+      ],
+      [
+        { plugins: [{ ...valid, kind: "core" }], clientAccess: "public" },
+        "plugins[0] has a kind; core is built in and is never passed as a plugin.",
+      ],
+      [
+        { plugins: [{ ...valid, hooks: {} }], clientAccess: "public" },
+        'plugins[0] has an unknown key "hooks".',
+      ],
+      [
+        {
+          plugins: [{ ...valid, init: async () => ({ api: {} }) }],
+          clientAccess: "public",
+        },
+        'Plugin "valid" init returned a promise; init must be synchronous.',
+      ],
+      [
+        {
+          plugins: [{ ...valid, provides: { clientAuth: true } }],
+          clientAccess: "public",
+        },
+        'Plugin "valid" declares provides: { clientAuth: true } but its instance has no clientAuth.',
+      ],
+      [
+        {
+          plugins: [
+            {
+              ...valid,
+              init: () => ({
+                api: {},
+                clientAuth: { varyHeaders: [], authenticate: async () => true },
+              }),
+            },
+          ],
+          clientAccess: "public",
+        },
+        'Plugin "valid" returns clientAuth without declaring provides: { clientAuth: true }.',
+      ],
+      [
+        {
+          plugins: [
+            {
+              ...valid,
+              init: () => ({
+                api: {},
+                endpoints: [
+                  {
+                    method: "GET",
+                    path: "/version",
+                    access: "client",
+                    handler: async () => new Response(),
+                  },
+                ],
+              }),
+            },
+          ],
+          clientAccess: "public",
+        },
+        "plugin valid: GET /version (GET /version) collides with version on handlers.client.",
+      ],
+      [
+        { plugins: [{ ...valid, id: "Valid" }], clientAccess: "public" },
+        "plugins[0] needs an id matching ^[a-z][a-z0-9_]*$.",
+      ],
+    ];
+    for (const [options, message] of cases) {
+      const run = startup(options);
+      expect(run).toThrow(HotUpdaterConfigError);
+      expect(run).toThrow(message);
+    }
+  });
+});