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

package/dist/assembly/pluginCli.mjs

@@ -0,0 +1,121 @@
+import { HotUpdaterConfigError } from "./configError.mjs";
+import { clientPluginsOf } from "./clientPlugins.mjs";
+import { assemblePlugins } from "./assemblePlugins.mjs";
+import { createDatabasePluginApis } from "./databasePlugins.mjs";
+import { createMemoryAdapter } from "@hot-updater/plugin-core/internal";
+//#region src/assembly/pluginCli.ts
+const COMMAND_NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/u;
+const ARGUMENT_NAME = /^[A-Za-z][A-Za-z0-9]*$/u;
+const RESERVED_ARGUMENT = "configPath";
+const fail = (message) => {
+	throw new HotUpdaterConfigError(message);
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const pluginsOf = (value) => Array.isArray(value) ? value.filter(isRecord) : fail("plugins must be an array of plugins.");
+const checkCommand = (plugin, value, path) => {
+	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;
+	if (typeof command.run === "function" === (command.commands !== void 0)) fail(`${at} needs either subcommands or run, not both.`);
+	const names = /* @__PURE__ */ new Set();
+	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 !== void 0) {
+		if (!Array.isArray(command.commands) || command.commands.length === 0) fail(`${at} needs at least one subcommand.`);
+		const subcommands = /* @__PURE__ */ new Set();
+		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.
+*/
+const pluginCommandsOf = (plugins) => {
+	const entries = [];
+	for (const plugin of pluginsOf(plugins)) {
+		const commands = plugin.cli?.commands;
+		if (commands === void 0) continue;
+		const id = String(plugin.id);
+		if (!Array.isArray(commands)) fail(`Plugin "${id}" cli.commands must be an array.`);
+		for (const value of commands) {
+			const command = checkCommand(id, value, []);
+			const taken = entries.find((entry) => entry.command.name === command.name);
+			if (taken !== void 0) 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) => {
+	const plugin = pluginsOf(plugins).find(({ provides }) => provides?.clientAuth === true);
+	if (plugin === void 0) return void 0;
+	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
+	};
+};
+/**
+* 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.
+*/
+const clientAuthOf = (plugins) => {
+	const found = credentialOf(plugins);
+	if (found === void 0) return void 0;
+	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.
+*/
+const generateClientCredential = (plugins) => 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.
+*/
+const provisionClientCredential = async (database, plugins, input) => {
+	const found = credentialOf(plugins);
+	if (found === void 0) return void 0;
+	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
+	};
+};
+//#endregion
+export { clientAuthOf, clientPluginsOf, generateClientCredential, pluginCommandsOf, provisionClientCredential };

package/dist/createHotUpdaterCore.cjs

@@ -1,4 +1,5 @@
-const require_builtInDatabase = require("./db/builtInDatabase.cjs");
+const require_coreDatabase = require("./db/coreDatabase.cjs");
+const require_configError = require("./assembly/configError.cjs");
 const require_assemblePlugins = require("./assembly/assemblePlugins.cjs");
 const require_handler = require("./handler.cjs");
 const require_storageAccess = require("./storageAccess.cjs");
@@ -15,21 +16,15 @@ const isAdapter = (value) => isRecord(value) && [
 const databaseOf = (value) => {
 	if (isRecord(value) && typeof value.name === "string") {
 		if (isAdapter(value.adapter)) return value;
-		if ("core" in value && "fetchAdmin" in value) throw new require_assemblePlugins.HotUpdaterConfigError("standaloneRepository reaches a server's admin API from the CLI and console. createHotUpdater needs the server's own database, such as kyselyAdapter(...).");
+		if ("core" in value && "fetchAdmin" in value) throw new require_configError.HotUpdaterConfigError("standaloneRepository reaches a server's admin API from the CLI and console. createHotUpdater needs the server's own database, such as kyselyAdapter(...).");
 	}
-	throw new require_assemblePlugins.HotUpdaterConfigError("database must be a Hot Updater 1.0 database, such as kyselyAdapter(...) or postgres(...). Upgrade the provider package that created it.");
+	throw new require_configError.HotUpdaterConfigError("database must be a Hot Updater 1.0 database, such as kyselyAdapter(...) or postgres(...). Upgrade the provider package that created it.");
 };
-/** A release candidate's config moving to 1.0 also needs `insights()`. */
-const KEEP_INSIGHTS = "To keep Insights, which the release candidates ran by default, add insights() from @hot-updater/server/plugins/insights to plugins.";
-/** `"public"`, or nothing; a `clientAccess` object names what replaced it. */
+/** `"public"`, or nothing; a `clientAccess` object says what replaced it. */
 const isPublic = (value) => {
 	if (value === void 0) return false;
 	if (value === "public") return true;
-	if (isRecord(value)) {
-		const type = value.type;
-		throw new require_assemblePlugins.HotUpdaterConfigError(type === "api-key" ? `clientAccess: { type: "api-key" } was removed in 1.0. Remove it and add apiKeys(${value.headerName === void 0 ? "" : `{ headerName: ${JSON.stringify(value.headerName)} }`}) from @hot-updater/server/plugins/api-keys to plugins, which protects client routes the same way. ${KEEP_INSIGHTS}` : `clientAccess objects were removed in 1.0. Use clientAccess: "public", or add apiKeys() from @hot-updater/server/plugins/api-keys to plugins. ${KEEP_INSIGHTS}`);
-	}
-	throw new require_assemblePlugins.HotUpdaterConfigError("clientAccess must be \"public\"; to protect client routes, add apiKeys() from @hot-updater/server/plugins/api-keys to plugins.");
+	throw new require_configError.HotUpdaterConfigError(isRecord(value) ? "clientAccess objects were removed in 1.0. Set clientAccess: \"public\", or add a plugin that provides clientAuth to plugins." : "clientAccess must be \"public\"; to protect client routes, add a plugin that provides clientAuth to plugins.");
 };
 const hotUpdaterCoreMetadata = Symbol.for("@hot-updater/server/core-metadata");
 function getHotUpdaterCoreMetadata(hotUpdater) {
@@ -49,11 +44,12 @@ function createHotUpdater(options) {
 			readStorageText,
 			resolveFileUrl
 		},
-		...database.onCachedRoutesChange === void 0 ? {} : { onCachedRoutesChange: () => database.onCachedRoutesChange() }
+		...database.onCachedRoutesChange === void 0 ? {} : { onCachedRoutesChange: () => database.onCachedRoutesChange() },
+		...database.aggregateBatching === void 0 ? {} : { batching: database.aggregateBatching }
 	});
 	const clientAuth = plugins.clientAuth;
-	if (clientAuth !== void 0 && publicClients) throw new require_assemblePlugins.HotUpdaterConfigError(`Plugin "${clientAuth.plugin}" provides clientAuth, so remove clientAccess.`);
-	if (clientAuth === void 0 && !publicClients) throw new require_assemblePlugins.HotUpdaterConfigError("Set clientAccess to \"public\", or add a plugin that provides clientAuth.");
+	if (clientAuth !== void 0 && publicClients) throw new require_configError.HotUpdaterConfigError(`Plugin "${clientAuth.plugin}" provides clientAuth, so remove clientAccess.`);
+	if (clientAuth === void 0 && !publicClients) throw new require_configError.HotUpdaterConfigError("Set clientAccess to \"public\", or add a plugin that provides clientAuth.");
 	const clientPolicy = clientAuth === void 0 ? void 0 : {
 		varyHeaders: clientAuth.varyHeaders.map((header) => header.toLowerCase()),
 		authenticate: (request) => clientAuth.authenticate(request.headers)
@@ -69,13 +65,15 @@ function createHotUpdater(options) {
 		adapterName: database.name,
 		handlers,
 		core: plugins.core,
-		api: plugins.api
+		api: plugins.api,
+		flush: plugins.flush
 	};
 	Object.defineProperty(api, hotUpdaterCoreMetadata, {
 		enumerable: false,
 		value: {
 			database,
-			target: require_builtInDatabase.toolingTargetOf(options.plugins ?? [])
+			target: require_coreDatabase.toolingTargetOf(options.plugins ?? []),
+			plugins: options.plugins ?? []
 		}
 	});
 	return api;

package/dist/createHotUpdaterCore.d.cts

@@ -1,6 +1,6 @@
 import { ToolingDatabase } from "./db/types.cjs";
-import { CoreApi } from "./core/api.cjs";
 import { AnyHotUpdaterPlugin, PluginApis } from "./plugins/definePlugin.cjs";
+import { CoreApi } from "./core/api.cjs";
 import { HotUpdaterHandlers } from "./handlerTypes.cjs";
 import "./handler.cjs";
 import { StoragePlugin } from "@hot-updater/plugin-core";
@@ -13,9 +13,16 @@ type RuntimeHotUpdaterAPI<TPlugins extends readonly AnyHotUpdaterPlugin[] = read
   readonly api: PluginApis<TPlugins>;
   /** The database's name, which `hot-updater db` commands read. */
   readonly adapterName: string;
+  /**
+   * Applies aggregate changes the database batches that are still pending:
+   * this process's buffer, and the log rows no compaction has merged yet.
+   * A long-lived server with `aggregateBatching: { mode: "memory" }` calls
+   * it before it exits.
+   */
+  readonly flush: () => Promise<void>;
 };
 type HotUpdaterAPI = RuntimeHotUpdaterAPI;
-declare const REMOVED_CLIENT_ACCESS = "clientAccess objects were removed in 1.0: set clientAccess: \"public\", or add apiKeys() from @hot-updater/server/plugins/api-keys to plugins";
+declare const REMOVED_CLIENT_ACCESS = "clientAccess objects were removed in 1.0: set clientAccess: \"public\", or add a plugin that provides clientAuth";
 /**
  * A `clientAccess` object from before 1.0. Its `type` names the fix, so
  * TypeScript reports it where the object is written.
@@ -57,7 +64,7 @@ type CreateHotUpdaterOptions<TPlugins extends readonly AnyHotUpdaterPlugin[] = r
   readonly database: ToolingDatabase;
   /** Storage implementations used to read provider-specific storage URIs. */
   readonly storage?: readonly StoragePlugin[];
-  /** Built-in and third-party plugins; at most one provides clientAuth. Defaults to none. */
+  /** The plugins the server runs; at most one provides clientAuth. Defaults to none. */
   readonly plugins?: TPlugins;
 } & ClientAccessRule<TPlugins>;
 declare function createHotUpdater<const TPlugins extends readonly AnyHotUpdaterPlugin[] = readonly []>(options: CreateHotUpdaterOptions<TPlugins>): RuntimeHotUpdaterAPI<NoInfer<TPlugins>>;

package/dist/createHotUpdaterCore.d.mts

@@ -1,6 +1,6 @@
 import { ToolingDatabase } from "./db/types.mjs";
-import { CoreApi } from "./core/api.mjs";
 import { AnyHotUpdaterPlugin, PluginApis } from "./plugins/definePlugin.mjs";
+import { CoreApi } from "./core/api.mjs";
 import { HotUpdaterHandlers } from "./handlerTypes.mjs";
 import "./handler.mjs";
 import { StoragePlugin } from "@hot-updater/plugin-core";
@@ -13,9 +13,16 @@ type RuntimeHotUpdaterAPI<TPlugins extends readonly AnyHotUpdaterPlugin[] = read
   readonly api: PluginApis<TPlugins>;
   /** The database's name, which `hot-updater db` commands read. */
   readonly adapterName: string;
+  /**
+   * Applies aggregate changes the database batches that are still pending:
+   * this process's buffer, and the log rows no compaction has merged yet.
+   * A long-lived server with `aggregateBatching: { mode: "memory" }` calls
+   * it before it exits.
+   */
+  readonly flush: () => Promise<void>;
 };
 type HotUpdaterAPI = RuntimeHotUpdaterAPI;
-declare const REMOVED_CLIENT_ACCESS = "clientAccess objects were removed in 1.0: set clientAccess: \"public\", or add apiKeys() from @hot-updater/server/plugins/api-keys to plugins";
+declare const REMOVED_CLIENT_ACCESS = "clientAccess objects were removed in 1.0: set clientAccess: \"public\", or add a plugin that provides clientAuth";
 /**
  * A `clientAccess` object from before 1.0. Its `type` names the fix, so
  * TypeScript reports it where the object is written.
@@ -57,7 +64,7 @@ type CreateHotUpdaterOptions<TPlugins extends readonly AnyHotUpdaterPlugin[] = r
   readonly database: ToolingDatabase;
   /** Storage implementations used to read provider-specific storage URIs. */
   readonly storage?: readonly StoragePlugin[];
-  /** Built-in and third-party plugins; at most one provides clientAuth. Defaults to none. */
+  /** The plugins the server runs; at most one provides clientAuth. Defaults to none. */
   readonly plugins?: TPlugins;
 } & ClientAccessRule<TPlugins>;
 declare function createHotUpdater<const TPlugins extends readonly AnyHotUpdaterPlugin[] = readonly []>(options: CreateHotUpdaterOptions<TPlugins>): RuntimeHotUpdaterAPI<NoInfer<TPlugins>>;

package/dist/createHotUpdaterCore.mjs

@@ -1,5 +1,6 @@
-import { toolingTargetOf } from "./db/builtInDatabase.mjs";
-import { HotUpdaterConfigError, assemblePlugins } from "./assembly/assemblePlugins.mjs";
+import { toolingTargetOf } from "./db/coreDatabase.mjs";
+import { HotUpdaterConfigError } from "./assembly/configError.mjs";
+import { assemblePlugins } from "./assembly/assemblePlugins.mjs";
 import { createHotUpdaterHandlers } from "./handler.mjs";
 import { createStorageAccess } from "./storageAccess.mjs";
 import { assertStorageOperations } from "@hot-updater/plugin-core";
@@ -19,17 +20,11 @@ const databaseOf = (value) => {
 	}
 	throw new HotUpdaterConfigError("database must be a Hot Updater 1.0 database, such as kyselyAdapter(...) or postgres(...). Upgrade the provider package that created it.");
 };
-/** A release candidate's config moving to 1.0 also needs `insights()`. */
-const KEEP_INSIGHTS = "To keep Insights, which the release candidates ran by default, add insights() from @hot-updater/server/plugins/insights to plugins.";
-/** `"public"`, or nothing; a `clientAccess` object names what replaced it. */
+/** `"public"`, or nothing; a `clientAccess` object says what replaced it. */
 const isPublic = (value) => {
 	if (value === void 0) return false;
 	if (value === "public") return true;
-	if (isRecord(value)) {
-		const type = value.type;
-		throw new HotUpdaterConfigError(type === "api-key" ? `clientAccess: { type: "api-key" } was removed in 1.0. Remove it and add apiKeys(${value.headerName === void 0 ? "" : `{ headerName: ${JSON.stringify(value.headerName)} }`}) from @hot-updater/server/plugins/api-keys to plugins, which protects client routes the same way. ${KEEP_INSIGHTS}` : `clientAccess objects were removed in 1.0. Use clientAccess: "public", or add apiKeys() from @hot-updater/server/plugins/api-keys to plugins. ${KEEP_INSIGHTS}`);
-	}
-	throw new HotUpdaterConfigError("clientAccess must be \"public\"; to protect client routes, add apiKeys() from @hot-updater/server/plugins/api-keys to plugins.");
+	throw new HotUpdaterConfigError(isRecord(value) ? "clientAccess objects were removed in 1.0. Set clientAccess: \"public\", or add a plugin that provides clientAuth to plugins." : "clientAccess must be \"public\"; to protect client routes, add a plugin that provides clientAuth to plugins.");
 };
 const hotUpdaterCoreMetadata = Symbol.for("@hot-updater/server/core-metadata");
 function getHotUpdaterCoreMetadata(hotUpdater) {
@@ -49,7 +44,8 @@ function createHotUpdater(options) {
 			readStorageText,
 			resolveFileUrl
 		},
-		...database.onCachedRoutesChange === void 0 ? {} : { onCachedRoutesChange: () => database.onCachedRoutesChange() }
+		...database.onCachedRoutesChange === void 0 ? {} : { onCachedRoutesChange: () => database.onCachedRoutesChange() },
+		...database.aggregateBatching === void 0 ? {} : { batching: database.aggregateBatching }
 	});
 	const clientAuth = plugins.clientAuth;
 	if (clientAuth !== void 0 && publicClients) throw new HotUpdaterConfigError(`Plugin "${clientAuth.plugin}" provides clientAuth, so remove clientAccess.`);
@@ -69,13 +65,15 @@ function createHotUpdater(options) {
 		adapterName: database.name,
 		handlers,
 		core: plugins.core,
-		api: plugins.api
+		api: plugins.api,
+		flush: plugins.flush
 	};
 	Object.defineProperty(api, hotUpdaterCoreMetadata, {
 		enumerable: false,
 		value: {
 			database,
-			target: toolingTargetOf(options.plugins ?? [])
+			target: toolingTargetOf(options.plugins ?? []),
+			plugins: options.plugins ?? []
 		}
 	});
 	return api;