@hot-updater/server 1.0.0-rc.18 → 1.0.0-rc.21

package/src/assembly/assembly.types.spec.ts

@@ -1,203 +0,0 @@
-import { describe, expectTypeOf, it } from "vitest";
-
-import {
-  type ClientAccessPolicy,
-  type ClientAccessRule,
-  createHotUpdater,
-  type CreateHotUpdaterOptions,
-  type RemovedClientAccess,
-} from "../createHotUpdaterCore";
-import { defineTable } from "../database/schema";
-import { definePlugin } from "../plugins/definePlugin";
-
-const keys = definePlugin({
-  id: "keys",
-  provides: { clientAuth: true },
-  schemaVersion: "1",
-  schema: {},
-  init: () => ({
-    api: { ping: () => "pong" as const },
-    clientAuth: { varyHeaders: ["x-key"], authenticate: async () => true },
-  }),
-});
-
-const sso = definePlugin({
-  id: "sso",
-  provides: { clientAuth: true },
-  schemaVersion: "1",
-  schema: {},
-  init: () => ({
-    api: {},
-    clientAuth: { varyHeaders: [], authenticate: async () => true },
-  }),
-});
-
-const notes = definePlugin({
-  id: "notes",
-  schemaVersion: "1",
-  schema: {
-    notes: defineTable({ id: { type: "string" } }, { key: ["id"] }),
-  },
-  init: ({ db }) => ({
-    api: { read: (id: string) => db.findOne("notes", { id }) },
-  }),
-});
-
-type Database = CreateHotUpdaterOptions["database"];
-
-/** The callback is type-checked and never runs. */
-const typeOnly = (check: (database: Database) => void) => void check;
-
-describe("createHotUpdater types", () => {
-  it("counts clientAuth plugins in a tuple and names the fix", () => {
-    expectTypeOf<ClientAccessRule<readonly []>>().toEqualTypeOf<{
-      readonly clientAccess: ClientAccessPolicy;
-    }>();
-    expectTypeOf<ClientAccessRule<readonly [typeof notes]>>().toEqualTypeOf<{
-      readonly clientAccess: ClientAccessPolicy;
-    }>();
-    expectTypeOf<ClientAccessRule<readonly [typeof keys]>>().toEqualTypeOf<{
-      readonly clientAccess?: 'Remove clientAccess: plugin "keys" provides clientAuth';
-    }>();
-    expectTypeOf<
-      ClientAccessRule<readonly [typeof keys, typeof notes, typeof sso]>
-    >().toEqualTypeOf<{
-      readonly clientAuth: 'Keep one clientAuth plugin: "keys", "sso" all provide it';
-    }>();
-    expectTypeOf<
-      ClientAccessRule<readonly (typeof keys | typeof notes)[]>
-    >().toEqualTypeOf<{
-      readonly clientAccess?: "Remove clientAccess: a plugin in this list may provide clientAuth";
-    }>();
-  });
-
-  it("accepts exactly one policy source", () => {
-    typeOnly((database) => {
-      createHotUpdater({ database, plugins: [notes, keys] });
-      createHotUpdater({ database, plugins: [notes], clientAccess: "public" });
-      createHotUpdater({ database, clientAccess: "public" });
-      // @ts-expect-error Neither a clientAuth plugin nor "public".
-      createHotUpdater({ database, plugins: [notes] });
-      createHotUpdater({
-        database,
-        plugins: [keys],
-        // @ts-expect-error clientAuth and "public" together.
-        clientAccess: "public",
-      });
-      // @ts-expect-error Two plugins provide clientAuth.
-      createHotUpdater({ database, plugins: [keys, sso] });
-    });
-  });
-
-  it("says what replaced a clientAccess object from before 1.0 where it is written", () => {
-    expectTypeOf<ClientAccessPolicy>().toEqualTypeOf<
-      "public" | RemovedClientAccess
-    >();
-    expectTypeOf<
-      RemovedClientAccess["type"]
-    >().toEqualTypeOf<'clientAccess objects were removed in 1.0: set clientAccess: "public", or add a plugin that provides clientAuth'>();
-    typeOnly((database) => {
-      // @ts-expect-error clientAccess objects were removed in 1.0.
-      createHotUpdater({ database, clientAccess: { type: "public" } });
-      createHotUpdater({
-        database,
-        // @ts-expect-error clientAccess objects were removed in 1.0.
-        clientAccess: { type: "api-key", headerName: "x-client-key" },
-      });
-    });
-  });
-
-  it("rejects core passed as a plugin and a clientAuth the plugin did not declare", () => {
-    const core = {
-      kind: "core",
-      id: "core",
-      schemaVersion: "1",
-      schema: {},
-      init: () => ({ api: {} }),
-    } as const;
-    typeOnly((database) => {
-      createHotUpdater({
-        database,
-        // @ts-expect-error Core is built in; it is not a plugin.
-        plugins: [core],
-      });
-    });
-    definePlugin({
-      id: "sneaky",
-      schemaVersion: "1",
-      schema: {},
-      init: () => ({
-        api: {},
-        // @ts-expect-error Declare provides: { clientAuth: true } to return clientAuth.
-        clientAuth: { varyHeaders: [], authenticate: async () => true },
-      }),
-    });
-    definePlugin({
-      id: "promised",
-      provides: { clientAuth: true },
-      schemaVersion: "1",
-      schema: {},
-      // @ts-expect-error A plugin that provides clientAuth must return it.
-      init: () => ({ api: {} }),
-    });
-  });
-
-  it("types CLI commands by the plugin's API and gates clientCredential on clientAuth", () => {
-    definePlugin({
-      id: "counter",
-      schemaVersion: "1",
-      schema: {},
-      init: () => ({ api: { count: () => 1 } }),
-      cli: {
-        commands: [
-          {
-            name: "count",
-            description: "Count",
-            async run({ api, ui }) {
-              expectTypeOf(api.count()).toEqualTypeOf<1>();
-              ui.print(String(api.count()));
-            },
-          },
-        ],
-        // @ts-expect-error Declare provides: { clientAuth: true } to add clientCredential.
-        clientCredential: {
-          label: "Key",
-          header: "x-key",
-          env: "KEY",
-          generate: () => "key",
-          provision: async () => "key",
-        },
-      },
-    });
-    definePlugin({
-      id: "keyed",
-      provides: { clientAuth: true },
-      schemaVersion: "1",
-      schema: {},
-      init: () => ({
-        api: { issue: async () => "key" },
-        clientAuth: { varyHeaders: ["x-key"], authenticate: async () => true },
-      }),
-      cli: {
-        clientCredential: {
-          label: "Key",
-          header: "x-key",
-          env: "KEY",
-          generate: () => "key",
-          provision: (api) => api.issue(),
-        },
-      },
-    });
-  });
-
-  it("types each plugin's API by id", () => {
-    type Api = ReturnType<
-      typeof createHotUpdater<readonly [typeof keys, typeof notes]>
-    >["api"];
-    expectTypeOf<keyof Api>().toEqualTypeOf<"keys" | "notes">();
-    expectTypeOf<ReturnType<Api["keys"]["ping"]>>().toEqualTypeOf<"pong">();
-    expectTypeOf<Parameters<Api["notes"]["read"]>>().toEqualTypeOf<
-      [id: string]
-    >();
-  });
-});

package/src/assembly/clientPlugins.ts

@@ -1,113 +0,0 @@
-import { HotUpdaterConfigError } from "./configError";
-
-/** A client plugin an app adds to `HotUpdater.init`'s `plugins`. */
-export interface ClientPluginSpec {
-  /** The module that exports it. */
-  readonly module: string;
-  /** The export, which the app calls with no arguments. */
-  readonly name: string;
-}
-
-const EXPORT_NAME = /^[A-Za-z_$][\w$]*$/u;
-
-/**
- * Names app code cannot import as they are: reserved words, and the names
- * the printed app code declares itself.
- */
-const UNAVAILABLE_NAMES = new Set([
-  "App",
-  "HotUpdater",
-  "arguments",
-  "await",
-  "break",
-  "case",
-  "catch",
-  "class",
-  "const",
-  "continue",
-  "debugger",
-  "default",
-  "delete",
-  "do",
-  "else",
-  "enum",
-  "eval",
-  "export",
-  "extends",
-  "false",
-  "finally",
-  "for",
-  "function",
-  "if",
-  "implements",
-  "import",
-  "in",
-  "instanceof",
-  "interface",
-  "let",
-  "new",
-  "null",
-  "package",
-  "private",
-  "protected",
-  "public",
-  "return",
-  "static",
-  "super",
-  "switch",
-  "this",
-  "throw",
-  "true",
-  "try",
-  "typeof",
-  "var",
-  "void",
-  "while",
-  "with",
-  "yield",
-]);
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
-/**
- * The client plugins an app adds for the plugins, each once, in plugin
- * order: what init prints in `HotUpdater.init`'s `plugins`. A malformed one,
- * or one name from two modules, throws `HotUpdaterConfigError`.
- */
-export const clientPluginsOf = (
-  plugins: readonly unknown[],
-): readonly ClientPluginSpec[] => {
-  if (!Array.isArray(plugins)) {
-    throw new HotUpdaterConfigError("plugins must be an array of plugins.");
-  }
-  const found: ClientPluginSpec[] = [];
-  for (const plugin of plugins) {
-    if (!isRecord(plugin) || !isRecord(plugin.cli)) continue;
-    const value = plugin.cli.clientPlugin;
-    if (value === undefined) continue;
-    const id = String(plugin.id);
-    if (
-      !isRecord(value) ||
-      typeof value.module !== "string" ||
-      value.module === "" ||
-      typeof value.name !== "string" ||
-      !EXPORT_NAME.test(value.name) ||
-      UNAVAILABLE_NAMES.has(value.name)
-    ) {
-      throw new HotUpdaterConfigError(
-        `Plugin "${id}" cli.clientPlugin needs a module and an export name the app can import: an identifier other than a reserved word, App, or HotUpdater.`,
-      );
-    }
-    const { module, name } = value as unknown as ClientPluginSpec;
-    const named = found.find((entry) => entry.name === name);
-    if (named === undefined) {
-      found.push({ module, name });
-    } else if (named.module !== module) {
-      throw new HotUpdaterConfigError(
-        `Plugin "${id}" names the client plugin "${name}" from ${module}, but another plugin names it from ${named.module}.`,
-      );
-    }
-  }
-  return found;
-};

package/src/assembly/configError.ts

@@ -1,4 +0,0 @@
-/** A misconfigured `createHotUpdater` call, reported at startup. */
-export class HotUpdaterConfigError extends Error {
-  readonly name = "HotUpdaterConfigError";
-}

package/src/assembly/databasePlugins.spec.ts

@@ -1,71 +0,0 @@
-import { createMemoryAdapter } from "@hot-updater/plugin-core/internal";
-import { describe, expect, it } from "vitest";
-
-import { apiKeys } from "../plugins/api-keys";
-import { insights } from "../plugins/insights";
-import { HotUpdaterConfigError } from "./assemblePlugins";
-import {
-  createDatabasePluginApis,
-  createMeasuredDatabase,
-} from "./databasePlugins";
-
-describe("createDatabasePluginApis", () => {
-  it("assembles the listed plugins over the database's engine, on the server's tables", async () => {
-    const database = { name: "memory", adapter: createMemoryAdapter() };
-
-    const api = createDatabasePluginApis(database, [insights(), apiKeys()]);
-    const created = await api.apiKeys.create({ name: "Console" });
-
-    expect(Object.keys(api).sort()).toEqual(["apiKeys", "insights"]);
-    // Another assembly over the same database reads the same table.
-    await expect(
-      createDatabasePluginApis(database, [apiKeys()]).apiKeys.list(),
-    ).resolves.toEqual([expect.objectContaining({ id: created.record.id })]);
-  });
-
-  it("gives no APIs for an empty plugin list", () => {
-    const database = { name: "memory", adapter: createMemoryAdapter() };
-
-    expect(createDatabasePluginApis(database, [])).toEqual({});
-  });
-
-  it("refuses a database off the storage engine, and a malformed list", () => {
-    expect(() =>
-      createDatabasePluginApis({ name: "old", models: {} }, [insights()]),
-    ).toThrow("Upgrade its provider package to 1.0.");
-    expect(() =>
-      createDatabasePluginApis(
-        { name: "memory", adapter: createMemoryAdapter() },
-        [insights(), insights()],
-      ),
-    ).toThrow(HotUpdaterConfigError);
-  });
-});
-
-describe("createMeasuredDatabase", () => {
-  it("runs core and the plugins on one engine in verify mode, over the adapter as given", async () => {
-    // A bare adapter without settings rows, which the schema fence would refuse.
-    const { core, api, clientAuth, measureReads } = createMeasuredDatabase(
-      createMemoryAdapter(),
-      [insights(), apiKeys()],
-    );
-    const { apiKey } = await api.apiKeys.create({ name: "Console" });
-    await core.ensureChannel("production");
-
-    const measured = await measureReads(async () => ({
-      authenticated: await clientAuth!.authenticate(
-        new Headers({ "x-api-key": apiKey }),
-      ),
-      channel: await core.findChannelByName("production"),
-    }));
-
-    expect(measured).toEqual({
-      result: {
-        authenticated: true,
-        channel: { id: expect.any(String), name: "production" },
-      },
-      adapter: { gets: 0, keys: 0, queries: 2, rows: 2 },
-      engine: { calls: 2, rows: 2 },
-    });
-  });
-});

package/src/assembly/databasePlugins.ts

@@ -1,102 +0,0 @@
-import type { EngineDatabase } from "@hot-updater/plugin-core";
-import type { DatabaseAdapter } from "@hot-updater/plugin-core/internal";
-
-import {
-  engineAdapterOf,
-  OFF_ENGINE_DATABASE,
-  type CoreApi,
-} from "../core/api";
-import type { CoreStorage } from "../core/reads";
-import type { ReadMeasurement } from "../database/engine";
-import type {
-  AnyHotUpdaterPlugin,
-  ClientAuth,
-  PluginApis,
-} from "../plugins/definePlugin";
-import { assemblePlugins } from "./assemblePlugins";
-
-/**
- * The plugins' APIs by plugin id over a configured database, assembled as
- * `createHotUpdater` assembles them: how the console and the CLI run a
- * plugin in process, on the tables the server uses. A database off the
- * storage engine, `standaloneRepository` included, is refused: its server
- * runs the plugins.
- */
-export function createDatabasePluginApis<
-  const TPlugins extends readonly AnyHotUpdaterPlugin[],
->(
-  database: unknown,
-  plugins: TPlugins,
-  options?: { readonly now?: () => number },
-): PluginApis<TPlugins>;
-export function createDatabasePluginApis(
-  database: unknown,
-  plugins: readonly unknown[],
-  options?: { readonly now?: () => number },
-): Readonly<Record<string, unknown>>;
-export function createDatabasePluginApis(
-  database: unknown,
-  plugins: readonly unknown[],
-  options: { readonly now?: () => number } = {},
-): Readonly<Record<string, unknown>> {
-  const adapter = engineAdapterOf(database);
-  if (adapter === undefined) throw new Error(OFF_ENGINE_DATABASE);
-  // Batched aggregates compact before they are read, as on the server.
-  const { aggregateBatching } = database as Partial<EngineDatabase>;
-  return assemblePlugins(plugins, adapter, {
-    ...options,
-    ...(aggregateBatching === undefined ? {} : { batching: aggregateBatching }),
-  }).api;
-}
-
-export interface MeasuredDatabaseOptions {
-  readonly now?: () => number;
-  /** How core reads bundle manifests and resolves file URLs, for artifact resolution. */
-  readonly storage?: CoreStorage;
-}
-
-/** Core and the plugins' APIs on one engine in verify mode, and its read meter. */
-export interface MeasuredDatabase<TApi = Readonly<Record<string, unknown>>> {
-  readonly core: CoreApi;
-  readonly api: TApi;
-  /** The client-route policy, when a plugin provides one. */
-  readonly clientAuth?: ClientAuth;
-  /** Runs `read` and reports what it read at both boundaries. */
-  measureReads<T>(read: () => Promise<T>): Promise<ReadMeasurement<T>>;
-}
-
-/**
- * Core and the plugins over a storage adapter, assembled as
- * `createHotUpdater` assembles them but on an engine in verify mode, with
- * that engine's `measureReads`: what read-budget suites measure. The adapter
- * runs as given, without the schema fence.
- */
-export function createMeasuredDatabase<
-  const TPlugins extends readonly AnyHotUpdaterPlugin[],
->(
-  adapter: DatabaseAdapter,
-  plugins: TPlugins,
-  options?: MeasuredDatabaseOptions,
-): MeasuredDatabase<PluginApis<TPlugins>>;
-export function createMeasuredDatabase(
-  adapter: DatabaseAdapter,
-  plugins: readonly unknown[],
-  options?: MeasuredDatabaseOptions,
-): MeasuredDatabase;
-export function createMeasuredDatabase(
-  adapter: DatabaseAdapter,
-  plugins: readonly unknown[],
-  options: MeasuredDatabaseOptions = {},
-): MeasuredDatabase {
-  const { core, api, clientAuth, measureReads } = assemblePlugins(
-    plugins,
-    adapter,
-    { ...options, verify: true },
-  );
-  return {
-    core,
-    api,
-    ...(clientAuth === undefined ? {} : { clientAuth }),
-    measureReads: measureReads!,
-  };
-}