@hot-updater/firebase 1.2.0-rc.11 → 1.2.0-rc.13

package/dist/firebase/functions/index.cjs

@@ -2102,7 +2102,10 @@ const CHANNEL_ID = {
 * every database's migrator creates missing tables and then records the
 * version, and none of them changes an existing table, so changing one
 * needs a migration step of its own first. The schema fence answers 503 on
-* a database whose row differs, until it runs.
+* a database whose row differs, until it runs. Before a version is released,
+* its tables change in place in its own migration, and a database one of its
+* prereleases migrated takes the same change by hand: the fence compares this
+* row, not columns, so nothing reports it.
 */
 const HOT_UPDATER_SCHEMA_VERSION = "1.2.0";
 const bundles = defineTable({
@@ -2366,6 +2369,10 @@ const channels = defineTable({
 * or `versionCode`. `submitted_to`, `submitted_at_ms` and
 * `submitted_version` record the store track a build went to, when, and
 * the store's label of the build; they stay null for a build no store took.
+* `store_build` is true on the build a person or a job says the store sells,
+* and null on every other: deploys patch from it over the scope's newest build.
+* It is never false, so `byStoreBuild` holds one entry per scope at most, on
+* every store, and an unmarked row, older than the column or not, holds none.
 */
 const nativeBuilds = defineTable({
 	id: {
@@ -2442,6 +2449,10 @@ const nativeBuilds = defineTable({
 		type: "string",
 		maxLength: 255,
 		required: false
+	},
+	store_build: {
+		type: "boolean",
+		required: false
 	}
 }, {
 	key: ["id"],
@@ -2454,6 +2465,11 @@ const nativeBuilds = defineTable({
 			eq: ["scope_key", "build_key"],
 			sort: ["id"]
 		},
+		byStoreBuild: {
+			eq: ["scope_key", "store_build"],
+			sort: [],
+			unique: true
+		},
 		byChannel: {
 			eq: ["channel_id"],
 			sort: ["id"],
@@ -2674,15 +2690,8 @@ const LEASE_TABLE = "aggregate_lease";
 const LEASE = { id: "compaction" };
 /** How long a compaction holds the lease before another process may take it. */
 const LEASE_MS = 3e4;
-/**
-* Default windows: log mode compacts every 60 seconds, since reads compact
-* first; memory mode flushes every 15, since its window is what a crash
-* loses.
-*/
-const WINDOW_MS$1 = {
-	log: 6e4,
-	memory: 15e3
-};
+/** A commit compacts once this has passed since the last compaction. */
+const WINDOW_MS$1 = 6e4;
 /** Log rows a compaction reads from each log table for one group. */
 const LOG_PAGE = 200;
 /**
@@ -2696,8 +2705,6 @@ const GROUPS = {
 };
 /** Tries per write after a conflict or a transient error. */
 const ATTEMPTS = 5;
-/** Aggregate rows a memory buffer holds before a commit waits for a flush. */
-const MAX_BUFFERED = 1e4;
 const log = defineTable({
 	id: {
 		type: "string",
@@ -2747,7 +2754,7 @@ const valuesOf = ({ deltas, sketches }) => ({
 /**
 * Merges `values` into the change for `key`'s identity as `tx.aggregate`
 * does: deltas add up and sketches merge. One constant `shardBy` keys each
-* identity to one entry; the write picks the shard.
+* identity to one entry; `compile` writes it to shard 0.
 */
 const merge = (into, model, key, values) => recordAggregate(into, model, Object.fromEntries(shapeOf(model).key.map((field, at) => [field, key[at]])), values, "");
 const mergeAll = (into, changes) => {
@@ -2781,7 +2788,7 @@ const increment = ({ model, deltas }, key) => Object.values(deltas).some((delta)
 /**
 * The guarded write that merges `change` into `current`: insert, patch, or
 * delete at zero. Unlike a transaction's, a gauge may go below zero here: a
-* shard row holds one writer's net changes, and reads sum every shard.
+* group can hold a loss without the gain before it, and reads sum every shard.
 */
 const rewrite = (change, key, current) => {
 	const { model } = change;
@@ -2819,12 +2826,12 @@ const rewrite = (change, key, current) => {
 	};
 };
 /**
-* The write for each change on its shard: a blind increment that creates
-* the row for counters, and a guarded rewrite for gauges and sketches, whose
-* rows are read in one batch per table.
+* The write for each change on shard 0, since one compaction runs at a time:
+* a blind increment that creates the row for counters, and a guarded rewrite
+* for gauges and sketches, whose rows are read in one batch per table.
 */
-const compile = async (adapter, changes, shard) => {
-	const keys = changes.map(({ model, key }) => [...key.slice(0, -1), shard(model)]);
+const compile = async (adapter, changes) => {
+	const keys = changes.map(({ key }) => [...key.slice(0, -1), 0]);
 	const reads = /* @__PURE__ */ new Map();
 	changes.forEach((change, at) => {
 		if (rewrites(change)) reads.set(change.model, [...reads.get(change.model) ?? [], at]);
@@ -2878,14 +2885,13 @@ const encode$1 = async (changes) => {
 	return zipped !== void 0 && zipped.length < json.length ? `z${zipped}` : json;
 };
 /**
-* Batches changes to aggregates declared `batched`. A transaction records
-* them without writing their rows; once it commits, "memory" mode keeps
-* them in this process until its timer flushes them, and "log" mode has
-* written them as one log row in the same atomic write, which a compaction
-* later merges into the aggregates and deletes, atomically again, so each
-* applies exactly once. One lease row keeps compactions one at a time.
+* Batches changes to aggregates declared `batched`. A transaction writes
+* them as one log row in its own atomic write, in place of their rows; a
+* compaction later merges log rows into the aggregates and deletes them,
+* atomically again, so each applies exactly once. One lease row keeps
+* compactions one at a time.
 */
-const createAggregateBatches = ({ engine, adapter, schema, batching: { mode = "log", windowMs = WINDOW_MS$1[mode] }, now }) => {
+const createAggregateBatches = ({ engine, adapter, schema, batching: { windowMs = WINDOW_MS$1 }, now }) => {
 	if (!schema.models.has(LEASE_TABLE)) throw new DatabaseTransactionError("An engine that batches aggregates needs aggregateBatchingModule in its schema.");
 	const holder = crypto.randomUUID().replaceAll("-", "");
 	const table = (name) => schema.models.get(name).table;
@@ -2913,68 +2919,6 @@ const createAggregateBatches = ({ engine, adapter, schema, batching: { mode = "l
 		}
 		return changes;
 	};
-	/**
-	* Writes changes in atomic chunks within `fits`, and returns the ones it
-	* could not apply. A write whose outcome is unknown is dropped, never
-	* resent, so no change applies twice.
-	*/
-	const apply = async (changes, shard) => {
-		let rest = changes;
-		let ops = [];
-		let read = true;
-		for (let failures = 0; rest.length > 0 && failures < ATTEMPTS;) try {
-			if (read) ops = await compile(adapter, rest, shard);
-			let size = rest.length;
-			const chunk = () => ops.slice(0, size).filter(isOp);
-			while (size > 1 && !adapter.fits(chunk())) size = Math.ceil(size / 2);
-			let result = { ok: true };
-			if (chunk().length > 0) result = await adapter.write(chunk()).catch((error) => {
-				warn("flush")(error);
-				return { ok: true };
-			});
-			read = !result.ok && !("retry" in result);
-			if (result.ok) {
-				rest = rest.slice(size);
-				ops = ops.slice(size);
-				failures = 0;
-			} else {
-				failures += 1;
-				if (!read) await sleep(failures);
-			}
-		} catch (error) {
-			warn("flush")(error);
-			return rest;
-		}
-		return rest;
-	};
-	let buffer = /* @__PURE__ */ new Map();
-	let timer;
-	let flushing;
-	const shards = /* @__PURE__ */ new Map();
-	/** Each process writes its own shard, so flushes of two processes rarely meet. */
-	const processShard = (model) => {
-		if (!shards.has(model)) shards.set(model, Math.floor(Math.random() * shapeOf(model).shards));
-		return shards.get(model);
-	};
-	const schedule = () => {
-		if (timer !== void 0 || buffer.size === 0) return;
-		timer = setTimeout(() => {
-			timer = void 0;
-			flushBuffer();
-		}, windowMs);
-		timer.unref?.();
-	};
-	/** Never rejects: what it cannot apply goes back into the buffer. */
-	const flushBuffer = () => flushing ??= (async () => {
-		clearTimeout(timer);
-		timer = void 0;
-		const pending = [...buffer.values()];
-		buffer = /* @__PURE__ */ new Map();
-		mergeAll(buffer, await apply(pending, processShard));
-	})().catch(warn("flush")).finally(() => {
-		flushing = void 0;
-		schedule();
-	});
 	let nextDue = 0;
 	let compacting;
 	/** Log rows this process read, by `[log table's index, id]`, for the deletes after a group. */
@@ -3109,7 +3053,7 @@ const createAggregateBatches = ({ engine, adapter, schema, batching: { mode = "l
 			more
 		};
 	};
-	const rowsFor = async (changes) => (await compile(adapter, changes, () => 0)).filter(isOp);
+	const rowsFor = async (changes) => (await compile(adapter, changes)).filter(isOp);
 	/**
 	* Applies the oldest pending log rows whose merged changes fit in one
 	* atomic write with the lease, which lists them as applied; the rows are
@@ -3203,20 +3147,6 @@ const createAggregateBatches = ({ engine, adapter, schema, batching: { mode = "l
 	}))).then((pages) => pages.some((page) => page.rows.length > 0)).finally(() => {
 		checking = void 0;
 	});
-	/** Takes a committed transaction's changes; never rejects, since the transaction already committed. */
-	const committed = async (changes) => {
-		if (mode === "log") {
-			if (now() >= nextDue) await compact(false, GROUPS.commit);
-			return;
-		}
-		mergeAll(buffer, changes.values());
-		schedule();
-		if (buffer.size >= MAX_BUFFERED) await flushBuffer();
-	};
-	const flush = async () => {
-		await flushBuffer();
-		if (mode === "log" && await hasPending()) await compact(true, GROUPS.flush);
-	};
 	return {
 		async transaction(fn) {
 			let changes = /* @__PURE__ */ new Map();
@@ -3242,7 +3172,7 @@ const createAggregateBatches = ({ engine, adapter, schema, batching: { mode = "l
 						aggregate
 					});
 					if (failure) throw failure.error;
-					if (mode === "log" && attempt.size > 0) {
+					if (attempt.size > 0) {
 						const id = `${now().toString(36).padStart(9, "0")}${holder.slice(0, 8)}${crypto.randomUUID().slice(0, 8)}`;
 						const shard = Math.floor(Math.random() * LOG_TABLES.length);
 						const merged = mergeAll(/* @__PURE__ */ new Map(), attempt.values());
@@ -3256,24 +3186,18 @@ const createAggregateBatches = ({ engine, adapter, schema, batching: { mode = "l
 					open = false;
 				}
 			});
-			if (changes.size > 0) await committed(changes);
+			if (changes.size > 0 && now() >= nextDue) await compact(false, GROUPS.commit);
 			return result;
 		},
 		async beforeRead(name) {
 			if (!isBatched(schema.models.get(name))) return;
-			if (buffer.size > 0 || flushing !== void 0) await flushBuffer();
-			if (mode === "log") {
-				if (await hasPending().catch((error) => {
-					warn("read")(error);
-					return false;
-				})) await compact(true, GROUPS.read);
-			}
+			if (await hasPending().catch((error) => {
+				warn("read")(error);
+				return false;
+			})) await compact(true, GROUPS.read);
 		},
-		flush,
-		async dispose() {
-			clearTimeout(timer);
-			timer = void 0;
-			await flush();
+		async flush() {
+			if (await hasPending()) await compact(true, GROUPS.flush);
 		}
 	};
 };
@@ -4302,13 +4226,10 @@ const createDatabaseEngine = ({ batching, now = Date.now, meter, ...options }) =
 	};
 	return {
 		...engine,
-		/** Applies batched aggregate changes still pending: this process's buffer and the log. */
+		/** Applies the batched aggregate changes still in the log. */
 		flush: async () => {
 			await batches?.flush();
 		},
-		dispose: async () => {
-			await batches?.dispose();
-		},
 		database(module) {
 			const name = (model) => module.namespace ? `${module.namespace}_${model}` : model;
 			return {
@@ -4389,8 +4310,7 @@ const createEngine = (database, { plugins = [], now = Date.now } = {}) => {
 			if (module === void 0) throw new HotUpdaterConfigError(`Plugin "${plugin.id}" is not one of this engine's plugins.`);
 			return engine.database(module);
 		},
-		flush: () => engine.flush(),
-		dispose: () => engine.dispose()
+		flush: () => engine.flush()
 	};
 };
 //#endregion
@@ -4683,7 +4603,7 @@ const createKvAdapter = ({ store, tablePrefix = "" }) => {
 };
 //#endregion
 //#region ../../packages/server/dist/version.mjs
-const HOT_UPDATER_SERVER_VERSION = "1.2.0-rc.11";
+const HOT_UPDATER_SERVER_VERSION = "1.2.0-rc.13";
 //#endregion
 //#region ../../packages/server/dist/handlerVersionRoutes.mjs
 /**
@@ -5888,8 +5808,22 @@ const pick = (row) => ({
 	build_number: row.build_number ?? null,
 	submitted_to: row.submitted_to ?? null,
 	submitted_at_ms: row.submitted_at_ms ?? null,
-	submitted_version: row.submitted_version ?? null
+	submitted_version: row.submitted_version ?? null,
+	store_build: row.store_build === true ? true : null
 });
+/**
+* The channels only sandbox builds register on, which no store sells: the
+* registry's convention, as `@hot-updater/protocol/native-artifact` checks it
+* for a build's artifact.
+*/
+const SANDBOX_CHANNEL_PREFIX = "sandbox-";
+/**
+* How many older builds of a scope one read takes, looking for one older than
+* a bundle when a build made after the bundle is the newest.
+*/
+const OLDER_BUILDS_PAGE = 20;
+/** How many times a mark runs again after losing its scope's mark to another. */
+const MARK_ATTEMPTS = 8;
 /** The store track each platform's builds are submitted to. */
 const SUBMISSION_DESTINATIONS = {
 	android: "play-internal",
@@ -5966,7 +5900,8 @@ const createNativeBuildApi = (db, { now = Date.now } = {}) => ({
 			build_number: registration.buildNumber ?? null,
 			submitted_to: null,
 			submitted_at_ms: null,
-			submitted_version: null
+			submitted_version: null,
+			store_build: null
 		};
 		for (let attempt = 1;; attempt += 1) {
 			await insertChannel(db, {
@@ -6004,21 +5939,45 @@ const createNativeBuildApi = (db, { now = Date.now } = {}) => ({
 		const scopeKey = nativeBuildScopeKey(scope);
 		const buildKey = options?.buildKey;
 		if (buildKey !== void 0 && !BUILD_KEY.test(buildKey)) throw new NativeBuildInputError("Invalid native build key: it must be nbk1: and a SHA-256.");
-		const { rows } = buildKey === void 0 ? await db.findMany("native_builds", {
-			index: "byScope",
-			where: { scope_key: scopeKey },
-			order: "desc",
-			limit: 1
-		}) : await db.findMany("native_builds", {
-			index: "byBuildKey",
-			where: {
+		if (options?.storeBuild) {
+			const marked = await db.findOne("native_builds", {
 				scope_key: scopeKey,
-				build_key: buildKey
-			},
-			order: "desc",
-			limit: 1
-		});
-		return rows[0] === void 0 ? null : pick(rows[0]);
+				store_build: true
+			});
+			return marked === null ? null : pick(marked);
+		}
+		const read = (limit, before) => {
+			const page = {
+				order: "desc",
+				limit,
+				...before === void 0 ? {} : { range: { lt: before } }
+			};
+			return buildKey === void 0 ? db.findMany("native_builds", {
+				index: "byScope",
+				where: { scope_key: scopeKey },
+				...page
+			}) : db.findMany("native_builds", {
+				index: "byBuildKey",
+				where: {
+					scope_key: scopeKey,
+					build_key: buildKey
+				},
+				...page
+			});
+		};
+		const { rows } = await read(1);
+		const newest = rows[0];
+		if (newest === void 0) return null;
+		const bundleId = options?.builtInOlderThan;
+		if (bundleId === void 0 || newest.min_bundle_id < bundleId) return pick(newest);
+		for (let before = newest.id;;) {
+			const { rows: older } = await read(OLDER_BUILDS_PAGE, before);
+			const usable = older.find(({ min_bundle_id }) => min_bundle_id < bundleId);
+			if (usable !== void 0) return pick(usable);
+			const last = older.at(-1);
+			if (older.length < OLDER_BUILDS_PAGE || last === void 0) return null;
+			before = last.id;
+		}
 	},
 	async recordNativeBuildSubmission(id, { destination, version }) {
 		if (version.trim().length === 0 || version.length > SUBMITTED_VERSION_MAX_LENGTH) throw new NativeBuildInputError(`Invalid native build submission: version must be the store's label of the build, up to ${SUBMITTED_VERSION_MAX_LENGTH} characters.`);
@@ -6039,6 +5998,49 @@ const createNativeBuildApi = (db, { now = Date.now } = {}) => ({
 			};
 		});
 	},
+	async markNativeBuild(id, { storeBuild }) {
+		for (let attempt = 1;; attempt += 1) try {
+			return await db.transaction(async (tx) => {
+				const row = await tx.findOne("native_builds", { id });
+				if (row === null) return null;
+				const build = pick(row);
+				if (!storeBuild) {
+					if (build.store_build !== null) tx.update("native_builds", row, { store_build: null });
+					return {
+						nativeBuild: {
+							...build,
+							store_build: null
+						},
+						previous: null
+					};
+				}
+				if (decodeChannelKey(build.channel_id.slice(8)).startsWith(SANDBOX_CHANNEL_PREFIX)) throw new NativeBuildInputError("A build on a sandbox channel can't be the store build.");
+				if (build.store_build !== null) return {
+					nativeBuild: build,
+					previous: null
+				};
+				const holder = await tx.findOne("native_builds", {
+					scope_key: build.scope_key,
+					store_build: true
+				});
+				if (holder !== null) tx.update("native_builds", holder, { store_build: null });
+				tx.update("native_builds", row, { store_build: true });
+				return {
+					nativeBuild: {
+						...build,
+						store_build: true
+					},
+					previous: holder === null ? null : {
+						...pick(holder),
+						store_build: null
+					}
+				};
+			});
+		} catch (error) {
+			if (attempt < MARK_ATTEMPTS && error instanceof DatabaseConstraintError && error.reason === "unique") continue;
+			throw error;
+		}
+	},
 	async deleteNativeBuild(id) {
 		return db.transaction(async (tx) => {
 			const row = await tx.findOne("native_builds", { id });
@@ -7121,7 +7123,13 @@ const createAdminRouteHandlers = () => ({
 		const url = new URL(request.url);
 		const scope = nativeBuildScopeOf(url);
 		const buildKey = url.searchParams.get("buildKey");
-		return json$2({ data: await refusingInvalid(() => buildKey === null ? core.findNativeBuild(scope) : core.findNativeBuild(scope, { buildKey })) });
+		const builtInOlderThan = url.searchParams.get("builtInOlderThan");
+		const options = {
+			...buildKey === null ? {} : { buildKey },
+			...url.searchParams.get("storeBuild") === "true" ? { storeBuild: true } : {},
+			...builtInOlderThan === null ? {} : { builtInOlderThan }
+		};
+		return json$2({ data: await refusingInvalid(() => Object.keys(options).length === 0 ? core.findNativeBuild(scope) : core.findNativeBuild(scope, options)) });
 	}),
 	getNativeBuild: onCore(async (core, _request, params) => json$2({ data: await core.getNativeBuild(requireRouteParam(params, "id")) })),
 	listNativeBuilds: onCore(async (core, request) => {
@@ -7142,6 +7150,12 @@ const createAdminRouteHandlers = () => ({
 		};
 		return json$2({ data: await refusingInvalid(() => core.recordNativeBuildSubmission(requireRouteParam(params, "id"), submission)) });
 	}),
+	markNativeBuild: onCore(async (core, request, params) => {
+		const input = await body(request);
+		if (!isRecord$5(input) || typeof input.storeBuild !== "boolean") throw new HandlerBadRequestError("A native build's store build mark needs storeBuild, true or false.");
+		const mark = { storeBuild: input.storeBuild };
+		return json$2({ data: await refusingInvalid(() => core.markNativeBuild(requireRouteParam(params, "id"), mark)) });
+	}),
 	deleteNativeBuild: onCore(async (core, _request, params) => json$2({ data: await core.deleteNativeBuild(requireRouteParam(params, "id")) })),
 	deleteBundles: onCore(async (core, request) => {
 		const { ids } = await body(request);
@@ -7287,6 +7301,11 @@ const ADMIN_ROUTES = [
 		path: "/native-builds/:id/submission",
 		handler: "recordNativeBuildSubmission"
 	},
+	{
+		method: "POST",
+		path: "/native-builds/:id/store-build",
+		handler: "markNativeBuild"
+	},
 	{
 		method: "DELETE",
 		path: "/native-builds/:id",

package/dist/index.cjs

@@ -392,51 +392,62 @@ const crc32c = (bytes) => {
 /** The version IDs the secret's annotation lists. */
 const trackedVersions = (secret) => (secret.annotations?.[VERSIONS_ANNOTATION] ?? "").split(",").map((entry) => entry.trim()).filter((entry) => VERSION_ID_PATTERN.test(entry));
 const versionOf = (name) => typeof name === "string" ? name.slice(name.lastIndexOf("/") + 1) : "";
-/** The widest line a message has: the CLI prints no wider. */
-const LINE_WIDTH = 76;
-/** `text`, such as Google's own message, in lines that fit, broken at spaces. */
-const wrap = (text) => {
-	const lines = [];
-	let line = "";
-	for (const word of text.split(/\s+/u).filter(Boolean)) if (line && line.length + 1 + word.length > LINE_WIDTH) {
-		lines.push(line);
-		line = word;
-	} else line = line ? `${line} ${word}` : word;
-	if (line) lines.push(line);
-	return lines;
-};
 /** An error of one line each, for a terminal. */
 const failure = (lines, cause) => new Error(lines.join("\n"), cause === void 0 ? void 0 : { cause });
-const hint = (response, permission) => {
+/**
+* The one step that can fix the credentials in use, by the order they're
+* tried: signing in with gcloud changes nothing while a variable comes first.
+*/
+const signInHint = (credentials) => {
+	if (credentials) return [`Check the credentials passed to ${ADAPTER_NAME}().`];
+	const variable = ACCESS_TOKEN_ENV_NAMES.find((name) => process.env[name]?.trim()) ?? (process.env["GOOGLE_APPLICATION_CREDENTIALS"]?.trim() ? "GOOGLE_APPLICATION_CREDENTIALS" : void 0);
+	if (variable) return [`Fix or unset ${variable}.`];
+	return process.env["CI"] ? ["Use google-github-actions/auth."] : ["Sign in:", "gcloud auth application-default login"];
+};
+const hint = (response, permission, signIn) => {
 	const { status, error } = response;
 	if (error.details?.some((detail) => detail.reason === "SERVICE_DISABLED")) return ["Enable the Secret Manager API in the project:", "gcloud services enable secretmanager.googleapis.com --project <project>"];
-	if (status === 401) return [
-		"Google rejected the access token.",
-		"Sign in again with gcloud auth application-default login.",
-		"In CI, check the job's Workload Identity Federation."
-	];
-	if (status === 403) return wrap(`The Google identity needs ${permission}.`);
+	if (status === 401) return ["Google rejected the access token.", ...signIn];
+	if (status === 403) return [`The identity needs ${permission}.`];
 	if (status === 429) return ["Secret Manager's quota is exhausted: try again later."];
 	return [];
 };
 /**
-* An error for a failed request on `resource`, a line each: the HTTP
-* status, the resource, Google's status and message, which name resources
-* but never a value, `notes`, and what to fix.
+* An error for a failed request on `resource`, a line each: the HTTP status,
+* the resource, `notes`, and what to fix, or Google's own status and message,
+* which name resources but never a value, when nothing here says what to fix.
 */
-const requestError = (action, resource, response, permission, notes = []) => {
+const requestErrorOf = (signIn, action, resource, response, permission, notes = []) => {
 	const { status, message } = response.error;
-	const detail = [status, message?.slice(0, 300)].filter(Boolean).join(": ");
+	const fix = hint(response, permission, signIn);
+	if (response.status === 401 && notes.length === 0) return failure(fix);
 	return failure([
 		`${ADAPTER_NAME} couldn't ${action} (${response.status}).`,
 		resourceLine(resource),
-		...wrap(detail),
 		...notes,
-		...hint(response, permission)
+		...fix.length > 0 ? fix : [[status, message?.slice(0, 300)].filter(Boolean).join(": ")]
 	]);
 };
 /** The line that names a secret: its resource name is a line's worth. */
 const resourceLine = (secret) => `Secret: ${secret}`;
+let metadataWarningFiltered = false;
+/**
+* Drops the one warning `gcp-metadata` emits when its probe for a Google
+* runtime fails oddly: credentials are about to be reported as missing, and
+* the warning has nothing to act on. It stays filtered for the process, as
+* the library caches the probe; every other warning passes through.
+* `METADATA_SERVER_DETECTION=none` would also silence it, but skips the probe,
+* and with it the credentials of a Google runtime.
+*/
+const filterMetadataWarning = () => {
+	if (metadataWarningFiltered) return;
+	metadataWarningFiltered = true;
+	const emitWarning = process.emitWarning;
+	process.emitWarning = ((warning, ...rest) => {
+		if (rest[0] === "MetadataLookupWarning") return;
+		Reflect.apply(emitWarning, process, [warning, ...rest]);
+	});
+};
 /** Masks a value in the CLI's output, which loads `@hot-updater/cli-tools`. */
 const mask = async (value) => {
 	const { registerSecretValue } = await import("@hot-updater/cli-tools");
@@ -472,17 +483,11 @@ const createAccessToken = (credentials, projectId) => {
 			throw error;
 		});
 		const client = await auth;
+		filterMetadataWarning();
 		try {
 			return await client.getAccessToken() ?? void 0;
 		} catch (error) {
-			throw failure([
-				`${ADAPTER_NAME} found no Google credentials.`,
-				...wrap(error instanceof Error ? error.message.split("\n")[0] : String(error)),
-				"On your machine, run gcloud auth application-default login.",
-				"In CI, use google-github-actions/auth.",
-				"Or set GOOGLE_APPLICATION_CREDENTIALS to a service account key.",
-				`Or set ${ACCESS_TOKEN_ENV_NAMES.join(" or ")} to a token.`
-			], error);
+			throw failure([`${ADAPTER_NAME} found no Google credentials.`, ...signInHint(void 0)], error);
 		}
 	};
 	return async () => {
@@ -504,6 +509,7 @@ const createAccessToken = (credentials, projectId) => {
 */
 const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 	const accessToken = createAccessToken(credentials, projectId);
+	const requestError = (action, resource, response, permission, notes) => requestErrorOf(signInHint(credentials), action, resource, response, permission, notes);
 	const projectPath = () => {
 		if (typeof projectId !== "string" || !PROJECT_PATTERN.test(projectId)) throw failure([`${ADAPTER_NAME} can't use the projectId ${JSON.stringify(projectId)}.`, "Set the Google Cloud project's ID or number."]);
 		if (!PREFIX_PATTERN.test(prefix)) throw failure([`${ADAPTER_NAME} can't use the prefix ${JSON.stringify(prefix)}.`, "It takes letters, digits, \"-\", and \"_\"."]);
@@ -617,10 +623,8 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 		if (missing.length > 0) throw failure([
 			`${ADAPTER_NAME} can't store a value.`,
 			resourceLine(secret),
-			...wrap(`The Google identity lacks ${missing.join(", ")} on it.`),
-			"It adds a version, then destroys the versions it added before.",
-			"Grant roles/secretmanager.admin, or a custom role with:",
-			...wrap("secretmanager.secrets.get, secretmanager.secrets.update, secretmanager.versions.add, secretmanager.versions.destroy, secretmanager.versions.access")
+			`The identity lacks ${missing.join(", ")} on it.`,
+			"Grant roles/secretmanager.admin."
 		]);
 	};
 	/**
@@ -713,7 +717,7 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 				throw failure([
 					`${ADAPTER_NAME} couldn't ${notListed}.`,
 					resourceLine(secret),
-					...wrap(error instanceof Error ? error.message : String(error)),
+					error instanceof Error ? error.message : String(error),
 					notDestroyed
 				], error);
 			}
@@ -727,7 +731,7 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 		},
 		describe: (name) => {
 			const id = `${prefix}${name}`;
-			return `projects/${projectId}/secrets/${id} (https://console.cloud.google.com/security/secret-manager/secret/${encodeURIComponent(id)}/versions?project=${encodeURIComponent(projectId)})`;
+			return `the secret ${JSON.stringify(id)} in Google Secret Manager (https://console.cloud.google.com/security/secret-manager/secret/${encodeURIComponent(id)}/versions?project=${encodeURIComponent(projectId)})`;
 		}
 	};
 };

package/dist/index.d.cts

@@ -11,9 +11,8 @@ type FirebaseDatabaseConfig = AppOptions & {
   readonly collection?: string;
   /**
    * Firestore bills each document write, so Insights' aggregates are
-   * batched: through log rows a compaction merges (the default), or
-   * `{ mode: "memory" }` on a long-lived server. `false` commits them with
-   * each event.
+   * batched: through log rows a compaction merges (the default). `false` commits
+   * them with each event.
    */
   readonly aggregateBatching?: EngineDatabase["aggregateBatching"] | false;
 };

package/dist/index.d.mts

@@ -11,9 +11,8 @@ type FirebaseDatabaseConfig = AppOptions & {
   readonly collection?: string;
   /**
    * Firestore bills each document write, so Insights' aggregates are
-   * batched: through log rows a compaction merges (the default), or
-   * `{ mode: "memory" }` on a long-lived server. `false` commits them with
-   * each event.
+   * batched: through log rows a compaction merges (the default). `false` commits
+   * them with each event.
    */
   readonly aggregateBatching?: EngineDatabase["aggregateBatching"] | false;
 };

package/dist/index.mjs

@@ -391,51 +391,62 @@ const crc32c = (bytes) => {
 /** The version IDs the secret's annotation lists. */
 const trackedVersions = (secret) => (secret.annotations?.[VERSIONS_ANNOTATION] ?? "").split(",").map((entry) => entry.trim()).filter((entry) => VERSION_ID_PATTERN.test(entry));
 const versionOf = (name) => typeof name === "string" ? name.slice(name.lastIndexOf("/") + 1) : "";
-/** The widest line a message has: the CLI prints no wider. */
-const LINE_WIDTH = 76;
-/** `text`, such as Google's own message, in lines that fit, broken at spaces. */
-const wrap = (text) => {
-	const lines = [];
-	let line = "";
-	for (const word of text.split(/\s+/u).filter(Boolean)) if (line && line.length + 1 + word.length > LINE_WIDTH) {
-		lines.push(line);
-		line = word;
-	} else line = line ? `${line} ${word}` : word;
-	if (line) lines.push(line);
-	return lines;
-};
 /** An error of one line each, for a terminal. */
 const failure = (lines, cause) => new Error(lines.join("\n"), cause === void 0 ? void 0 : { cause });
-const hint = (response, permission) => {
+/**
+* The one step that can fix the credentials in use, by the order they're
+* tried: signing in with gcloud changes nothing while a variable comes first.
+*/
+const signInHint = (credentials) => {
+	if (credentials) return [`Check the credentials passed to ${ADAPTER_NAME}().`];
+	const variable = ACCESS_TOKEN_ENV_NAMES.find((name) => process.env[name]?.trim()) ?? (process.env["GOOGLE_APPLICATION_CREDENTIALS"]?.trim() ? "GOOGLE_APPLICATION_CREDENTIALS" : void 0);
+	if (variable) return [`Fix or unset ${variable}.`];
+	return process.env["CI"] ? ["Use google-github-actions/auth."] : ["Sign in:", "gcloud auth application-default login"];
+};
+const hint = (response, permission, signIn) => {
 	const { status, error } = response;
 	if (error.details?.some((detail) => detail.reason === "SERVICE_DISABLED")) return ["Enable the Secret Manager API in the project:", "gcloud services enable secretmanager.googleapis.com --project <project>"];
-	if (status === 401) return [
-		"Google rejected the access token.",
-		"Sign in again with gcloud auth application-default login.",
-		"In CI, check the job's Workload Identity Federation."
-	];
-	if (status === 403) return wrap(`The Google identity needs ${permission}.`);
+	if (status === 401) return ["Google rejected the access token.", ...signIn];
+	if (status === 403) return [`The identity needs ${permission}.`];
 	if (status === 429) return ["Secret Manager's quota is exhausted: try again later."];
 	return [];
 };
 /**
-* An error for a failed request on `resource`, a line each: the HTTP
-* status, the resource, Google's status and message, which name resources
-* but never a value, `notes`, and what to fix.
+* An error for a failed request on `resource`, a line each: the HTTP status,
+* the resource, `notes`, and what to fix, or Google's own status and message,
+* which name resources but never a value, when nothing here says what to fix.
 */
-const requestError = (action, resource, response, permission, notes = []) => {
+const requestErrorOf = (signIn, action, resource, response, permission, notes = []) => {
 	const { status, message } = response.error;
-	const detail = [status, message?.slice(0, 300)].filter(Boolean).join(": ");
+	const fix = hint(response, permission, signIn);
+	if (response.status === 401 && notes.length === 0) return failure(fix);
 	return failure([
 		`${ADAPTER_NAME} couldn't ${action} (${response.status}).`,
 		resourceLine(resource),
-		...wrap(detail),
 		...notes,
-		...hint(response, permission)
+		...fix.length > 0 ? fix : [[status, message?.slice(0, 300)].filter(Boolean).join(": ")]
 	]);
 };
 /** The line that names a secret: its resource name is a line's worth. */
 const resourceLine = (secret) => `Secret: ${secret}`;
+let metadataWarningFiltered = false;
+/**
+* Drops the one warning `gcp-metadata` emits when its probe for a Google
+* runtime fails oddly: credentials are about to be reported as missing, and
+* the warning has nothing to act on. It stays filtered for the process, as
+* the library caches the probe; every other warning passes through.
+* `METADATA_SERVER_DETECTION=none` would also silence it, but skips the probe,
+* and with it the credentials of a Google runtime.
+*/
+const filterMetadataWarning = () => {
+	if (metadataWarningFiltered) return;
+	metadataWarningFiltered = true;
+	const emitWarning = process.emitWarning;
+	process.emitWarning = ((warning, ...rest) => {
+		if (rest[0] === "MetadataLookupWarning") return;
+		Reflect.apply(emitWarning, process, [warning, ...rest]);
+	});
+};
 /** Masks a value in the CLI's output, which loads `@hot-updater/cli-tools`. */
 const mask = async (value) => {
 	const { registerSecretValue } = await import("@hot-updater/cli-tools");
@@ -471,17 +482,11 @@ const createAccessToken = (credentials, projectId) => {
 			throw error;
 		});
 		const client = await auth;
+		filterMetadataWarning();
 		try {
 			return await client.getAccessToken() ?? void 0;
 		} catch (error) {
-			throw failure([
-				`${ADAPTER_NAME} found no Google credentials.`,
-				...wrap(error instanceof Error ? error.message.split("\n")[0] : String(error)),
-				"On your machine, run gcloud auth application-default login.",
-				"In CI, use google-github-actions/auth.",
-				"Or set GOOGLE_APPLICATION_CREDENTIALS to a service account key.",
-				`Or set ${ACCESS_TOKEN_ENV_NAMES.join(" or ")} to a token.`
-			], error);
+			throw failure([`${ADAPTER_NAME} found no Google credentials.`, ...signInHint(void 0)], error);
 		}
 	};
 	return async () => {
@@ -503,6 +508,7 @@ const createAccessToken = (credentials, projectId) => {
 */
 const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 	const accessToken = createAccessToken(credentials, projectId);
+	const requestError = (action, resource, response, permission, notes) => requestErrorOf(signInHint(credentials), action, resource, response, permission, notes);
 	const projectPath = () => {
 		if (typeof projectId !== "string" || !PROJECT_PATTERN.test(projectId)) throw failure([`${ADAPTER_NAME} can't use the projectId ${JSON.stringify(projectId)}.`, "Set the Google Cloud project's ID or number."]);
 		if (!PREFIX_PATTERN.test(prefix)) throw failure([`${ADAPTER_NAME} can't use the prefix ${JSON.stringify(prefix)}.`, "It takes letters, digits, \"-\", and \"_\"."]);
@@ -616,10 +622,8 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 		if (missing.length > 0) throw failure([
 			`${ADAPTER_NAME} can't store a value.`,
 			resourceLine(secret),
-			...wrap(`The Google identity lacks ${missing.join(", ")} on it.`),
-			"It adds a version, then destroys the versions it added before.",
-			"Grant roles/secretmanager.admin, or a custom role with:",
-			...wrap("secretmanager.secrets.get, secretmanager.secrets.update, secretmanager.versions.add, secretmanager.versions.destroy, secretmanager.versions.access")
+			`The identity lacks ${missing.join(", ")} on it.`,
+			"Grant roles/secretmanager.admin."
 		]);
 	};
 	/**
@@ -712,7 +716,7 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 				throw failure([
 					`${ADAPTER_NAME} couldn't ${notListed}.`,
 					resourceLine(secret),
-					...wrap(error instanceof Error ? error.message : String(error)),
+					error instanceof Error ? error.message : String(error),
 					notDestroyed
 				], error);
 			}
@@ -726,7 +730,7 @@ const secretManager = ({ projectId, prefix = "hot-updater-", credentials }) => {
 		},
 		describe: (name) => {
 			const id = `${prefix}${name}`;
-			return `projects/${projectId}/secrets/${id} (https://console.cloud.google.com/security/secret-manager/secret/${encodeURIComponent(id)}/versions?project=${encodeURIComponent(projectId)})`;
+			return `the secret ${JSON.stringify(id)} in Google Secret Manager (https://console.cloud.google.com/security/secret-manager/secret/${encodeURIComponent(id)}/versions?project=${encodeURIComponent(projectId)})`;
 		}
 	};
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hot-updater/firebase",
   "type": "module",
-  "version": "1.2.0-rc.11",
+  "version": "1.2.0-rc.13",
   "description": "React Native OTA solution for self-hosted",
   "main": "dist/index.cjs",
   "types": "dist/index.d.cts",
@@ -38,10 +38,10 @@
   "dependencies": {
     "hono": "4.12.34",
     "google-auth-library": "10.7.0",
-    "@hot-updater/cli-tools": "1.2.0-rc.11",
-    "@hot-updater/protocol": "1.2.0-rc.11",
-    "@hot-updater/plugin-core": "1.2.0-rc.11",
-    "@hot-updater/server": "1.2.0-rc.11"
+    "@hot-updater/cli-tools": "1.2.0-rc.13",
+    "@hot-updater/plugin-core": "1.2.0-rc.13",
+    "@hot-updater/server": "1.2.0-rc.13",
+    "@hot-updater/protocol": "1.2.0-rc.13"
   },
   "publishConfig": {
     "access": "public"
@@ -56,8 +56,8 @@
     "firebase-tools": "15.29.0",
     "fkill": "^9.0.0",
     "mime": "^4.0.4",
-    "@hot-updater/mock": "1.2.0-rc.11",
-    "@hot-updater/test-utils": "1.2.0-rc.11"
+    "@hot-updater/mock": "1.2.0-rc.13",
+    "@hot-updater/test-utils": "1.2.0-rc.13"
   },
   "peerDependencies": {
     "firebase-admin": ">=11.10.0",