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

package/src/assembly/pluginCli.spec.ts

@@ -1,254 +0,0 @@
-import { createMemoryAdapter } from "@hot-updater/plugin-core/internal";
-import { describe, expect, it } from "vitest";
-
-import { apiKeys } from "../plugins/api-keys";
-import { definePlugin } from "../plugins/definePlugin";
-import { insights } from "../plugins/insights";
-import {
-  clientAuthOf,
-  clientPluginsOf,
-  generateClientCredential,
-  pluginCommandsOf,
-  provisionClientCredential,
-} from "./pluginCli";
-
-const run = async () => {};
-
-const withCommands = (id: string, commands: readonly unknown[]) =>
-  ({
-    id,
-    schemaVersion: "1",
-    schema: {},
-    init: () => ({ api: {} }),
-    cli: { commands },
-  }) as never;
-
-const notes = definePlugin({
-  id: "notes",
-  schemaVersion: "1",
-  schema: {},
-  init: () => ({ api: { count: () => 0 } }),
-  cli: {
-    commands: [
-      {
-        name: "notes",
-        description: "Manage notes",
-        commands: [
-          {
-            name: "count",
-            description: "Count notes",
-            async run({ api, ui }) {
-              ui.print(String(api.count()));
-            },
-          },
-        ],
-      },
-    ],
-  },
-});
-
-describe("pluginCommandsOf", () => {
-  it("lists each plugin's top-level commands with its plugin", () => {
-    const entries = pluginCommandsOf([notes, apiKeys()]);
-    expect(
-      entries.map(({ plugin, command }) => [plugin, command.name]),
-    ).toEqual([
-      ["notes", "notes"],
-      ["apiKeys", "api-key"],
-    ]);
-    expect(pluginCommandsOf([])).toEqual([]);
-  });
-
-  it.each([
-    [
-      [{ name: "Notes", description: "x", run }],
-      'command "Notes" needs a name of lowercase words joined by hyphens',
-    ],
-    [[{ name: "notes", run }], "and a description"],
-    [
-      [{ name: "notes", description: "x" }],
-      "needs either subcommands or run, not both",
-    ],
-    [
-      [{ name: "notes", description: "x", run, commands: [] }],
-      "needs either subcommands or run, not both",
-    ],
-    [[{ name: "notes", description: "x", commands: [] }], "at least one"],
-    [
-      [
-        {
-          name: "notes",
-          description: "x",
-          commands: [
-            { name: "add", description: "x", run },
-            { name: "add", description: "y", run },
-          ],
-        },
-      ],
-      'has two subcommands named "add"',
-    ],
-    [
-      [
-        {
-          name: "notes",
-          description: "x",
-          arguments: [{ name: "configPath", description: "x" }],
-          run,
-        },
-      ],
-      'other than "configPath"',
-    ],
-    [
-      [
-        {
-          name: "notes",
-          description: "x",
-          options: [{ flags: "-y", description: "x" }],
-          run,
-        },
-      ],
-      "needs --flags and a description",
-    ],
-  ])("refuses a malformed command (%#)", (commands, message) => {
-    expect(() => pluginCommandsOf([withCommands("notes", commands)])).toThrow(
-      message,
-    );
-  });
-
-  it("refuses two plugins that add the same command", () => {
-    expect(() =>
-      pluginCommandsOf([
-        notes,
-        withCommands("other", [{ name: "notes", description: "x", run }]),
-      ]),
-    ).toThrow(
-      'Plugins "notes" and "other" both add the command "notes"; keep one.',
-    );
-  });
-});
-
-describe("clientAuthOf", () => {
-  it("is undefined when no plugin provides clientAuth", () => {
-    expect(clientAuthOf([notes])).toBeUndefined();
-    expect(generateClientCredential([notes])).toBeUndefined();
-  });
-
-  it("reads the policy's headers and the credential an app sends", () => {
-    expect(clientAuthOf([notes, apiKeys({ headerName: "X-Key" })])).toEqual({
-      plugin: "apiKeys",
-      varyHeaders: ["x-key"],
-      credential: {
-        label: "API key",
-        header: "x-key",
-        env: "HOT_UPDATER_API_KEY",
-      },
-    });
-    expect(generateClientCredential([apiKeys()])).toMatch(
-      /^[A-Za-z0-9_-]{43}$/u,
-    );
-  });
-
-  it("refuses a clientAuth plugin that gives init no credential", () => {
-    const sso = definePlugin({
-      id: "sso",
-      provides: { clientAuth: true },
-      schemaVersion: "1",
-      schema: {},
-      init: () => ({
-        api: {},
-        clientAuth: { varyHeaders: [], authenticate: async () => true },
-      }),
-    });
-    expect(() => clientAuthOf([sso])).toThrow(
-      'Plugin "sso" provides clientAuth but no cli.clientCredential',
-    );
-  });
-});
-
-describe("provisionClientCredential", () => {
-  const database = () => ({ name: "memory", adapter: createMemoryAdapter() });
-
-  it("is undefined when client routes are public", async () => {
-    await expect(
-      provisionClientCredential(database(), [notes], {
-        env: {},
-        name: "Init",
-      }),
-    ).resolves.toBeUndefined();
-  });
-
-  it("registers a saved credential again, and creates one otherwise", async () => {
-    const plugins = [apiKeys()];
-    const target = database();
-    const created = await provisionClientCredential(target, plugins, {
-      env: {},
-      name: "Init",
-    });
-    expect(created).toMatchObject({
-      label: "API key",
-      header: "x-api-key",
-      env: "HOT_UPDATER_API_KEY",
-      value: expect.stringMatching(/^[A-Za-z0-9_-]{43}$/u),
-    });
-    const again = await provisionClientCredential(target, plugins, {
-      env: { HOT_UPDATER_API_KEY: ` ${created!.value}\n` },
-      name: "Init again",
-    });
-    expect(again?.value).toBe(created!.value);
-  });
-});
-
-describe("clientPluginsOf", () => {
-  const withClientPlugin = (id: string, clientPlugin: unknown) =>
-    ({
-      id,
-      schemaVersion: "1",
-      schema: {},
-      init: () => ({ api: {} }),
-      cli: { clientPlugin },
-    }) as never;
-
-  it("lists each client plugin once, in plugin order", () => {
-    expect(clientPluginsOf([notes, apiKeys()])).toEqual([]);
-    expect(
-      clientPluginsOf([
-        withClientPlugin("feedback", { module: "feedback-rn", name: "fb" }),
-        insights(),
-        apiKeys(),
-        withClientPlugin("again", { module: "feedback-rn", name: "fb" }),
-      ]),
-    ).toEqual([
-      { module: "feedback-rn", name: "fb" },
-      {
-        module: "@hot-updater/react-native/plugins/insights",
-        name: "insights",
-      },
-    ]);
-  });
-
-  it.each([
-    [{ module: "", name: "fb" }],
-    [{ module: "feedback-rn", name: "fb()" }],
-    [{ module: "feedback-rn", name: "default" }],
-    [{ module: "feedback-rn", name: "HotUpdater" }],
-    [{ module: "feedback-rn", name: "App" }],
-    ["feedback-rn"],
-  ])("refuses a client plugin the app cannot import (%j)", (value) => {
-    expect(() =>
-      clientPluginsOf([withClientPlugin("feedback", value)]),
-    ).toThrow(
-      'Plugin "feedback" cli.clientPlugin needs a module and an export name the app can import',
-    );
-  });
-
-  it("refuses two client plugins with one name from different modules", () => {
-    expect(() =>
-      clientPluginsOf([
-        withClientPlugin("a", { module: "a-rn", name: "fb" }),
-        withClientPlugin("b", { module: "b-rn", name: "fb" }),
-      ]),
-    ).toThrow(
-      'Plugin "b" names the client plugin "fb" from b-rn, but another plugin names it from a-rn.',
-    );
-  });
-});

package/src/assembly/pluginCli.ts

@@ -1,248 +0,0 @@
-import { createMemoryAdapter } from "@hot-updater/plugin-core/internal";
-
-import type {
-  PluginClientCredential,
-  PluginCommand,
-} from "../plugins/definePlugin";
-import { assemblePlugins, HotUpdaterConfigError } from "./assemblePlugins";
-import { createDatabasePluginApis } from "./databasePlugins";
-
-export { clientPluginsOf, type ClientPluginSpec } from "./clientPlugins";
-
-/** A top-level command a plugin adds to `hot-updater`. */
-export interface PluginCommandEntry {
-  /** The id of the plugin that adds it. */
-  readonly plugin: string;
-  readonly command: PluginCommand;
-}
-
-/** The credential an app sends to client routes. */
-export interface ClientCredentialSpec {
-  /** Its name in output, such as "API key". */
-  readonly label: string;
-  /** The request header that carries it, lowercase. */
-  readonly header: string;
-  /** The environment variable init stores it in. */
-  readonly env: string;
-}
-
-/** The client-route policy a server's plugins set, as tooling needs it. */
-export interface ClientAuthSpec {
-  /** The plugin that provides clientAuth. */
-  readonly plugin: string;
-  /** The request headers its decision reads, lowercase: what caches key on. */
-  readonly varyHeaders: readonly string[];
-  readonly credential: ClientCredentialSpec;
-}
-
-export interface ProvisionedClientCredential extends ClientCredentialSpec {
-  readonly value: string;
-}
-
-interface PluginLike {
-  readonly id?: unknown;
-  readonly provides?: { readonly clientAuth?: unknown };
-  readonly cli?: {
-    readonly commands?: unknown;
-    readonly clientCredential?: unknown;
-  };
-}
-
-const COMMAND_NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/u;
-const ARGUMENT_NAME = /^[A-Za-z][A-Za-z0-9]*$/u;
-// The CLI appends the server config's path to every command that runs.
-const RESERVED_ARGUMENT = "configPath";
-
-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 pluginsOf = (value: unknown): readonly PluginLike[] =>
-  Array.isArray(value)
-    ? value.filter(isRecord)
-    : fail("plugins must be an array of plugins.");
-
-const checkCommand = (
-  plugin: string,
-  value: unknown,
-  path: readonly string[],
-): PluginCommand => {
-  const at = `Plugin "${plugin}" command "${[...path, isRecord(value) ? String(value.name) : "?"].join(" ")}"`;
-  if (
-    !isRecord(value) ||
-    typeof value.name !== "string" ||
-    !COMMAND_NAME.test(value.name) ||
-    typeof value.description !== "string"
-  ) {
-    return fail(
-      `${at} needs a name of lowercase words joined by hyphens and a description.`,
-    );
-  }
-  const command = value as unknown as PluginCommand;
-  if (
-    (typeof command.run === "function") ===
-    (command.commands !== undefined)
-  ) {
-    fail(`${at} needs either subcommands or run, not both.`);
-  }
-  const names = new Set<string>();
-  for (const argument of command.arguments ?? []) {
-    if (
-      !isRecord(argument) ||
-      typeof argument.name !== "string" ||
-      !ARGUMENT_NAME.test(argument.name) ||
-      argument.name === RESERVED_ARGUMENT ||
-      names.has(argument.name) ||
-      typeof argument.description !== "string"
-    ) {
-      fail(
-        `${at} has an argument that needs a unique camelCase name other than "${RESERVED_ARGUMENT}" and a description.`,
-      );
-    }
-    names.add(argument.name);
-  }
-  for (const option of command.options ?? []) {
-    if (
-      !isRecord(option) ||
-      typeof option.flags !== "string" ||
-      !option.flags.includes("--") ||
-      typeof option.description !== "string"
-    ) {
-      fail(`${at} has an option that needs --flags and a description.`);
-    }
-  }
-  if (command.commands !== undefined) {
-    if (!Array.isArray(command.commands) || command.commands.length === 0) {
-      fail(`${at} needs at least one subcommand.`);
-    }
-    const subcommands = new Set<string>();
-    for (const subcommand of command.commands) {
-      const checked = checkCommand(plugin, subcommand, [...path, command.name]);
-      if (subcommands.has(checked.name)) {
-        fail(`${at} has two subcommands named "${checked.name}".`);
-      }
-      subcommands.add(checked.name);
-    }
-  }
-  return command;
-};
-
-/**
- * The top-level commands the plugins add, each checked. Two plugins may not
- * add the same command.
- */
-export const pluginCommandsOf = (
-  plugins: unknown,
-): readonly PluginCommandEntry[] => {
-  const entries: PluginCommandEntry[] = [];
-  for (const plugin of pluginsOf(plugins)) {
-    const commands = plugin.cli?.commands;
-    if (commands === undefined) continue;
-    const id = String(plugin.id);
-    if (!Array.isArray(commands)) {
-      fail(`Plugin "${id}" cli.commands must be an array.`);
-    }
-    for (const value of commands as unknown[]) {
-      const command = checkCommand(id, value, []);
-      const taken = entries.find(
-        (entry) => entry.command.name === command.name,
-      );
-      if (taken !== undefined) {
-        fail(
-          `Plugins "${taken.plugin}" and "${id}" both add the command "${command.name}"; keep one.`,
-        );
-      }
-      entries.push({ plugin: id, command });
-    }
-  }
-  return entries;
-};
-
-/** The clientAuth plugin's credential contribution, checked. */
-const credentialOf = (
-  plugins: unknown,
-):
-  | { readonly plugin: string; readonly credential: PluginClientCredential }
-  | undefined => {
-  const plugin = pluginsOf(plugins).find(
-    ({ provides }) => provides?.clientAuth === true,
-  );
-  if (plugin === undefined) return undefined;
-  const id = String(plugin.id);
-  const credential = plugin.cli?.clientCredential;
-  if (
-    !isRecord(credential) ||
-    typeof credential.label !== "string" ||
-    typeof credential.header !== "string" ||
-    typeof credential.env !== "string" ||
-    typeof credential.generate !== "function" ||
-    typeof credential.provision !== "function"
-  ) {
-    return fail(
-      `Plugin "${id}" provides clientAuth but no cli.clientCredential with a label, header, env, generate, and provision, so init cannot give an app its credential.`,
-    );
-  }
-  return {
-    plugin: id,
-    credential: credential as unknown as PluginClientCredential,
-  };
-};
-
-/**
- * The client-route policy the plugins set: the plugin that provides
- * clientAuth, the headers its decision reads, and the credential an app
- * sends. Undefined when client routes are public. The plugins initialize on
- * a throwaway in-memory database, since `varyHeaders` live on the instance.
- */
-export const clientAuthOf = (
-  plugins: readonly unknown[],
-): ClientAuthSpec | undefined => {
-  const found = credentialOf(plugins);
-  if (found === undefined) return undefined;
-  const { clientAuth } = assemblePlugins(plugins, createMemoryAdapter());
-  const { label, header, env } = found.credential;
-  return {
-    plugin: found.plugin,
-    varyHeaders: (clientAuth?.varyHeaders ?? []).map((name) =>
-      name.toLowerCase(),
-    ),
-    credential: { label, header: header.toLowerCase(), env },
-  };
-};
-
-/**
- * A new client credential, made without a database, so tooling can save it
- * before it registers it. Undefined when client routes are public.
- */
-export const generateClientCredential = (
-  plugins: readonly unknown[],
-): string | undefined => credentialOf(plugins)?.credential.generate();
-
-/**
- * Provisions the credential an app sends to client routes, through the
- * plugin that provides clientAuth, on the tables the server reads: a
- * credential saved in `env` is registered again rather than replaced.
- * Undefined when client routes are public.
- */
-export const provisionClientCredential = async (
-  database: unknown,
-  plugins: readonly unknown[],
-  input: {
-    readonly env: Readonly<Record<string, string | undefined>>;
-    /** Names the credential where the plugin stores one. */
-    readonly name: string;
-  },
-): Promise<ProvisionedClientCredential | undefined> => {
-  const found = credentialOf(plugins);
-  if (found === undefined) return undefined;
-  const { label, header, env, provision } = found.credential;
-  const existing = input.env[env]?.trim();
-  const value = await provision(
-    createDatabasePluginApis(database, plugins)[found.plugin],
-    { ...(existing ? { existing } : {}), name: input.name },
-  );
-  return { label, header: header.toLowerCase(), env, value };
-};

package/src/assembly/pluginRoutes.spec.ts

@@ -1,186 +0,0 @@
-import { createMemoryAdapter } from "@hot-updater/plugin-core/internal";
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-import { createHotUpdater } from "../createHotUpdaterCore";
-import { type HotUpdaterHandlers, listHotUpdaterRoutes } from "../handler";
-import { apiKeys } from "../plugins/api-keys";
-import { definePlugin } from "../plugins/definePlugin";
-import { insights } from "../plugins/insights";
-import { INSIGHTS_ROUTES } from "../plugins/insights/routes";
-import { HotUpdaterConfigError } from "./assemblePlugins";
-
-const database = () => ({ name: "memory", adapter: createMemoryAdapter() });
-
-const event = {
-  appVersion: "1.0.0",
-  channel: "production",
-  cohort: "default",
-  fingerprintHash: null,
-  fromBundleId: null,
-  fromReleaseId: null,
-  installId: "install-1",
-  platform: "ios",
-  toBundleId: "bundle-1",
-  toReleaseId: null,
-  type: "UNCHANGED",
-  updateStrategy: null,
-  userId: "user-1",
-  sdkVersion: "2.0.0",
-} as const;
-
-const request = (path: string, init: RequestInit = {}) =>
-  new Request(`https://updates.example.com${path}`, init);
-
-const insightsRoutes = INSIGHTS_ROUTES.map(({ method, path, access }) => ({
-  method,
-  path,
-  access,
-}));
-
-describe("Insights routes with plugins", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it("come from the insights plugin when plugins hold it", async () => {
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const hotUpdater = createHotUpdater({
-      database: database(),
-      plugins: [insights()],
-      clientAccess: "public",
-    });
-
-    const ingested = await hotUpdater.handlers.client(
-      request("/events", {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify(event),
-      }),
-    );
-    expect(ingested.status).toBe(204);
-    const installation = await hotUpdater.handlers.admin(
-      request("/installations/install-1"),
-    );
-    await expect(installation.json()).resolves.toMatchObject({
-      latestStatus: "UNCHANGED",
-      lastKnownBundleId: "bundle-1",
-    });
-    expect(listHotUpdaterRoutes(hotUpdater.handlers)).toEqual(
-      expect.arrayContaining(insightsRoutes),
-    );
-    expect(warn).not.toHaveBeenCalled();
-  });
-
-  it("are not mounted when plugins leave it out: core serves no Insights route", async () => {
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const hotUpdater = createHotUpdater({
-      database: database(),
-      plugins: [],
-      clientAccess: "public",
-    });
-
-    for (const { access, method, path } of INSIGHTS_ROUTES) {
-      const response = await hotUpdater.handlers[access](
-        request(path.replace(":installId", "install-1"), {
-          method,
-          ...(method === "POST" ? { body: JSON.stringify(event) } : {}),
-        }),
-      );
-      expect(response.status, `${method} ${path}`).toBe(404);
-    }
-    expect(listHotUpdaterRoutes(hotUpdater.handlers)).not.toEqual(
-      expect.arrayContaining([insightsRoutes[0]]),
-    );
-    expect(warn).not.toHaveBeenCalled();
-  });
-});
-
-describe("admin /version", () => {
-  const plugins = async (hotUpdater: { handlers: HotUpdaterHandlers }) =>
-    (
-      (await (await hotUpdater.handlers.admin(request("/version"))).json()) as {
-        plugins: unknown;
-      }
-    ).plugins;
-
-  it("lists the plugins the server runs, sorted by id", async () => {
-    await expect(
-      plugins(
-        createHotUpdater({
-          database: database(),
-          plugins: [insights(), apiKeys()],
-        }),
-      ),
-    ).resolves.toEqual(["apiKeys", "insights"]);
-    await expect(
-      plugins(
-        createHotUpdater({
-          database: database(),
-          plugins: [insights()],
-          clientAccess: "public",
-        }),
-      ),
-    ).resolves.toEqual(["insights"]);
-  });
-
-  it("lists none for a server without plugins, which serves no Insights route", async () => {
-    const hotUpdater = createHotUpdater({
-      database: database(),
-      clientAccess: "public",
-    });
-
-    await expect(plugins(hotUpdater)).resolves.toEqual([]);
-    expect((await hotUpdater.handlers.admin(request("/events"))).status).toBe(
-      404,
-    );
-  });
-});
-
-describe("core reads", () => {
-  it("reads core through hotUpdater.core and a plugin's ctx.core", async () => {
-    const channels = definePlugin({
-      id: "channel_names",
-      schemaVersion: "1",
-      schema: {},
-      init: ({ core }) => ({
-        api: {
-          names: async () =>
-            (await core.listChannels()).map((channel) => channel.name),
-        },
-      }),
-    });
-    const hotUpdater = createHotUpdater({
-      database: database(),
-      plugins: [channels],
-      clientAccess: "public",
-    });
-    const channel = await hotUpdater.core.ensureChannel("production");
-
-    await expect(
-      hotUpdater.core.findChannelByName("production"),
-    ).resolves.toEqual(channel);
-    await expect(hotUpdater.api.channel_names.names()).resolves.toEqual([
-      "production",
-    ]);
-  });
-
-  it('keeps the plugin id "core" for core', () => {
-    const impostor = definePlugin({
-      id: "core",
-      schemaVersion: "1",
-      schema: {},
-      init: () => ({ api: {} }),
-    });
-    const start = () =>
-      createHotUpdater({
-        database: database(),
-        plugins: [impostor],
-        clientAccess: "public",
-      });
-
-    expect(start).toThrow(HotUpdaterConfigError);
-    expect(start).toThrow(
-      'plugins[0] uses the id "core", which is core\'s own.',
-    );
-  });
-});