@hot-updater/azure 0.0.0-stage → 1.0.2

package/dist/index.mjs

@@ -0,0 +1,734 @@
+import { isTokenCredential } from "@azure/core-auth";
+import { BlobSASPermissions, BlobServiceClient, RestError, StorageSharedKeyCredential, generateBlobSASQueryParameters } from "@azure/storage-blob";
+import { SETTINGS_TABLE, createEngineDatabase, createKvAdapter, createStorageAdapter, createStorageKeyBuilder, createStorageUri, encodeKvKey, migrateCoreSchema, parseStorageUri, toolingTargetOf } from "@hot-updater/plugin-core";
+import { CosmosClient } from "@azure/cosmos";
+import { createHash } from "node:crypto";
+//#region src/azureBlobStorage.ts
+const PROTOCOL = "azblob";
+/** Devices download right after the update check that returns the URL. */
+const SAS_EXPIRES_IN_MS = 36e5;
+/** A user delegation key signs SAS URLs for up to seven days; it is renewed well before. */
+const DELEGATION_KEY_LIFETIME_MS = 864e5;
+const isNotFound = (error) => error instanceof RestError && error.statusCode === 404;
+const serviceOf = (config) => "connectionString" in config ? BlobServiceClient.fromConnectionString(config.connectionString) : new BlobServiceClient(config.accountUrl, config.credential);
+/**
+* Bundles in an Azure Blob Storage container. Without `getDownloadUrl`,
+* devices download through SAS URLs: signed with the account key when the
+* connection has one, otherwise with a user delegation key, which needs the
+* identity's Storage Blob Delegator role.
+*/
+function azureBlobStorage(config) {
+	const { containerName, basePath, getDownloadUrl } = config;
+	const service = serviceOf(config);
+	const container = service.getContainerClient(containerName);
+	const normalizedBasePath = basePath?.replace(/^\/+|\/+$/g, "") ?? "";
+	const getStorageKey = createStorageKeyBuilder(normalizedBasePath);
+	const getListPrefix = (prefix = "") => {
+		const value = [normalizedBasePath, prefix.replace(/^\/+|\/+$/g, "")].filter(Boolean).join("/");
+		return value ? `${value}/` : "";
+	};
+	const getRelativeKey = (key) => {
+		const basePrefix = `${normalizedBasePath}/`;
+		return normalizedBasePath && key.startsWith(basePrefix) ? key.slice(basePrefix.length) : key;
+	};
+	/** The URI `put` returns for the key, or null for a key no `put` writes. */
+	const getListedStorageUri = (key) => {
+		try {
+			return createStorageUri({
+				bucket: containerName,
+				key,
+				protocol: PROTOCOL
+			});
+		} catch {
+			return null;
+		}
+	};
+	const parseAndValidate = (storageUri) => {
+		const parsed = parseStorageUri(storageUri, PROTOCOL);
+		if (parsed.bucket !== containerName) throw new Error(`Container name mismatch: expected "${containerName}", but found "${parsed.bucket}".`);
+		return parsed;
+	};
+	let delegation;
+	const delegationKey = () => {
+		const now = Date.now();
+		if (delegation === void 0 || delegation.renewAt <= now) {
+			const key = service.getUserDelegationKey(/* @__PURE__ */ new Date(now - 3e5), new Date(now + DELEGATION_KEY_LIFETIME_MS));
+			key.catch(() => {
+				delegation = void 0;
+			});
+			delegation = {
+				key,
+				renewAt: now + DELEGATION_KEY_LIFETIME_MS - SAS_EXPIRES_IN_MS
+			};
+		}
+		return delegation.key;
+	};
+	const signedUrl = async (key) => {
+		const blob = container.getBlobClient(key);
+		const expiresOn = new Date(Date.now() + SAS_EXPIRES_IN_MS);
+		const permissions = BlobSASPermissions.parse("r");
+		if (blob.credential instanceof StorageSharedKeyCredential) return blob.generateSasUrl({
+			permissions,
+			expiresOn
+		});
+		if (!isTokenCredential(blob.credential)) throw new Error("azureBlobStorage signs download URLs with an account key or a Microsoft Entra credential; a SAS connection string has neither. Pass getDownloadUrl, or connect with the account key.");
+		const sas = generateBlobSASQueryParameters({
+			containerName,
+			blobName: key,
+			permissions,
+			expiresOn
+		}, await delegationKey(), blob.accountName);
+		return `${blob.url}?${sas.toString()}`;
+	};
+	return createStorageAdapter({
+		name: "azureBlobStorage",
+		protocol: PROTOCOL,
+		async listObjects(prefix) {
+			const objects = [];
+			for await (const blob of container.listBlobsFlat({ prefix: getListPrefix(prefix) })) {
+				const storageUri = getListedStorageUri(blob.name);
+				if (storageUri === null) continue;
+				objects.push({
+					key: getRelativeKey(blob.name),
+					lastModifiedAt: blob.properties.lastModified,
+					size: blob.properties.contentLength ?? 0,
+					storageUri
+				});
+			}
+			return objects;
+		},
+		async deleteObjects(relativeKeys) {
+			const keys = relativeKeys.map((key) => getStorageKey(key));
+			for (let offset = 0; offset < keys.length; offset += 256) {
+				const batch = keys.slice(offset, offset + 256);
+				if (batch.length === 0) continue;
+				const failed = (await container.getBlobBatchClient().deleteBlobs(batch.map((key) => container.getBlobClient(key)))).subResponses.filter(({ status }) => status >= 300 && status !== 404);
+				if (failed.length > 0) throw new Error(`Failed to delete ${failed.length} Azure blob(s).`);
+			}
+		},
+		async put({ key, body, contentType }) {
+			const storageKey = getStorageKey(key);
+			const bytes = new Uint8Array(await new Response(body).arrayBuffer());
+			await container.getBlockBlobClient(storageKey).uploadData(bytes, { blobHTTPHeaders: {
+				blobContentType: contentType,
+				blobCacheControl: "max-age=31536000"
+			} });
+			return { storageUri: createStorageUri({
+				bucket: containerName,
+				key: storageKey,
+				protocol: PROTOCOL
+			}) };
+		},
+		async get({ storageUri }) {
+			const { key } = parseAndValidate(storageUri);
+			try {
+				const download = await container.getBlobClient(key).download();
+				const body = download.readableStreamBody;
+				if (body === void 0) return { response: null };
+				const headers = new Headers();
+				if (download.contentType) headers.set("content-type", download.contentType);
+				if (download.contentLength !== void 0) headers.set("content-length", String(download.contentLength));
+				const { Readable } = await import("node:stream");
+				return { response: new Response(Readable.toWeb(body), { headers }) };
+			} catch (error) {
+				if (isNotFound(error)) return { response: null };
+				throw error;
+			}
+		},
+		async getDownloadUrl({ storageUri }) {
+			const { key } = parseAndValidate(storageUri);
+			if (getDownloadUrl) return getDownloadUrl({ storageUri });
+			return { url: await signedUrl(key) };
+		},
+		async exists({ storageUri }) {
+			const { key } = parseAndValidate(storageUri);
+			return { exists: await container.getBlobClient(key).exists() };
+		},
+		async delete({ storageUri }) {
+			const { key } = parseAndValidate(storageUri);
+			await container.getBlobClient(key).deleteIfExists();
+			return { deleted: true };
+		}
+	});
+}
+//#endregion
+//#region src/azureInfrastructureNames.ts
+/** The Cosmos DB database `hot-updater init` creates. */
+const AZURE_COSMOS_V1_DATABASE = "hot-updater";
+/**
+* The one container the storage engine keeps every item in. It namespaces
+* the data, so item partitions are table names with no prefix.
+*/
+const AZURE_COSMOS_V1_CONTAINER = "hot_updater_v1";
+//#endregion
+//#region src/cosmosStore.ts
+/**
+* Cosmos DB commits a transactional batch only inside one logical
+* partition, and the engine's writes span tables and their index items, so
+* every item shares this partition key value. One logical partition holds
+* at most 20 GB and serves at most 10,000 RU/s.
+*/
+const COSMOS_PARTITION = "hot-updater";
+/** The container's partition key path, whose value is always `COSMOS_PARTITION`. */
+const COSMOS_PARTITION_KEY_PATH = "/partition";
+/**
+* A transactional batch takes 100 operations and a 2 MB request, an item
+* 2 MB. The kit measures a row's JSON, but a map or array value is stored
+* as JSON text whose quotes and backslashes escape again, so an item takes
+* up to twice the measured bytes; the rest leaves room for each item's
+* envelope. Every op takes one operation but an `exists: false` check or
+* delete, which takes two; the engine writes neither.
+*/
+const COSMOS_LIMITS = {
+	items: 100,
+	bytes: 1e6,
+	itemBytes: 1e6
+};
+/** The most operations one transactional batch takes. */
+const BATCH_OPERATIONS = 100;
+/** The most bytes of operations a transactional batch request takes, below its 2 MB. */
+const BATCH_BYTES = 2e6;
+const encoder = new TextEncoder();
+/** A query reads at most this many ids a call. */
+const GET_BATCH = 100;
+/** A patch takes at most 10 operations. */
+const PATCH_OPERATIONS = 10;
+/**
+* The container's indexing: only the id `get` looks up, and the partition
+* and sort keys a range read filters and orders by, through one composite
+* index that serves either order. Rows are never filtered on, so they are not indexed.
+*/
+const COSMOS_INDEXING_POLICY = {
+	indexingMode: "consistent",
+	automatic: true,
+	includedPaths: [{ path: "/pk/?" }, { path: "/sk/?" }],
+	excludedPaths: [{ path: "/*" }],
+	compositeIndexes: [[{
+		path: "/pk",
+		order: "ascending"
+	}, {
+		path: "/sk",
+		order: "ascending"
+	}]]
+};
+/** An item's id: a hash of its key, since keys may hold `/` and Cosmos DB ids take at most 1,023 bytes. */
+const cosmosItemId = ({ pk, sk }) => createHash("sha256").update(JSON.stringify([pk, sk])).digest("hex");
+/**
+* An item is `{ id, partition, pk, sk, row, ttl, expireAt }`. Row values
+* that are maps or arrays become JSON text inside a map, so a read returns
+* them exactly as written, map key order included.
+*/
+const encode = (value) => value !== null && typeof value === "object" ? { json: JSON.stringify(value) } : value;
+const decode = (value) => value !== null && typeof value === "object" && "json" in value ? JSON.parse(String(value.json)) : value;
+const encodeRow = (row) => Object.fromEntries(Object.entries(row).map(([name, value]) => [name, encode(value)]));
+const toRow = (row) => Object.fromEntries(Object.entries(row ?? {}).map(([name, value]) => [name, decode(value)]));
+/**
+* The least TTL an item gets. Cosmos DB hides an item the moment its TTL
+* passes, where DynamoDB and Firestore delete expired items within a day or
+* two and read them until then; an item written already past its retention,
+* such as a late Insights event, lives this long rather than vanishing
+* under the write that made it.
+*/
+const MIN_TTL_SECONDS = 86400;
+/**
+* Cosmos DB's TTL counts seconds from an item's last write, so every write
+* sets it again from the absolute `expireAt`; `-1` never expires.
+*/
+const ttlOf = (expireAt) => expireAt === null || expireAt === void 0 ? -1 : Math.max(MIN_TTL_SECONDS, Math.ceil((expireAt - Date.now()) / 1e3));
+/** The item Cosmos DB stores for a row. */
+const toItem = (key, row, expiresAt) => ({
+	id: cosmosItemId(key),
+	partition: COSMOS_PARTITION,
+	pk: key.pk,
+	sk: key.sk,
+	row: encodeRow(row),
+	expireAt: expiresAt ?? null,
+	ttl: ttlOf(expiresAt)
+});
+/** An item that exists only between a Create and a Delete of one batch, to guard or to delete a key whether or not it exists. */
+const placeholderOf = (key) => ({
+	id: cosmosItemId(key),
+	partition: COSMOS_PARTITION
+});
+/** Ids as an `IN` list: they are hex digests, so they need no parameters. */
+const idList = (ids) => ids.map((id) => JSON.stringify(id)).join(", ");
+/** A JSON Pointer to a row column. */
+const columnPath = (name) => `/row/${name.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+const guardOf = (v) => `FROM c WHERE c.row._v = ${JSON.stringify(v)}`;
+/** Statuses a rerun of the whole write can clear: timeout, throttling, retry-with, unavailable. */
+const TRANSIENT = /* @__PURE__ */ new Set([
+	408,
+	429,
+	449,
+	503
+]);
+/** An error's HTTP status, or its cause's: the SDK wraps some answers, such as a failed batch's. */
+const statusOf = (error) => {
+	for (let at = error; at !== null && typeof at === "object"; at = at.cause) {
+		const { statusCode, code } = at;
+		const status = statusCode ?? code;
+		if (typeof status === "number") return status;
+	}
+};
+/** A missing database or container reads as a missing schema, like SQL's 42P01. */
+const missingContainer = (error) => {
+	throw statusOf(error) === 404 ? Object.assign(new Error(error.message, { cause: error }), { code: "42P01" }) : error;
+};
+/** The header of a container read that reports its index transformation, in percent. */
+const INDEX_TRANSFORMATION_PROGRESS = "x-ms-documentdb-collection-index-transformation-progress";
+/** How long a migration waits for a changed indexing policy to apply. */
+const INDEX_TRANSFORMATION_TIMEOUT_MS = 18e5;
+/**
+* Waits until Cosmos DB has applied a changed indexing policy: until then,
+* a query that orders by the new composite index fails.
+*/
+const waitForIndexTransformation = async (container) => {
+	const deadline = Date.now() + INDEX_TRANSFORMATION_TIMEOUT_MS;
+	for (;;) {
+		const { headers } = await container.read({ populateQuotaInfo: true });
+		const progress = Number(headers[INDEX_TRANSFORMATION_PROGRESS] ?? 100);
+		if (!(progress < 100)) return;
+		if (Date.now() > deadline) throw new Error(`Cosmos DB container ${container.id} is still indexing (${progress}%). Run the migration again once it finishes.`);
+		await new Promise((resolve) => setTimeout(resolve, 2e3));
+	}
+};
+/** The settings row that names the storage layout a container holds. */
+const ENGINE_KEY = "schema.engine";
+/** The `schema.engine` setting this version's storage layout writes. */
+const currentCosmosEngine = () => toolingTargetOf([]).settings[ENGINE_KEY];
+/**
+* Refuses a container whose fixed settings Hot Updater's items cannot live
+* under: unique keys, or another partition key.
+*/
+const assertContainerShape = (resource) => {
+	if ((resource.uniqueKeyPolicy?.uniqueKeys?.length ?? 0) > 0) throw new Error(`Cosmos DB container ${resource.id} has unique keys, which Hot Updater's items cannot satisfy. Use another container.`);
+	const paths = resource.partitionKey?.paths ?? [];
+	if (paths.length !== 1 || paths[0] !== "/partition") throw new Error(`Cosmos DB container ${resource.id} is partitioned by ${paths.join(", ")}; Hot Updater needs ${COSMOS_PARTITION_KEY_PATH}. Use another container.`);
+};
+/**
+* Refuses a container a migration must not touch: one with unique keys or
+* another partition key, one whose `schema.engine` is another storage
+* layout's, or a populated one without the setting. Writing the settings
+* would make the server read it as this layout. Read only, so init checks
+* a reused container before it creates anything. Point reads and a scan: a
+* reused container may index nothing yet, and the migration only fixes its
+* indexing once this check passes.
+*/
+const assertCosmosContainerReusable = async (container, expected) => {
+	const missing = (error) => error.code === 404;
+	let existing;
+	try {
+		existing = (await container.read()).resource;
+	} catch (error) {
+		if (!missing(error)) throw error;
+	}
+	if (existing === void 0) return;
+	assertContainerShape(existing);
+	const { resource } = await container.item(cosmosItemId({
+		pk: SETTINGS_TABLE.name,
+		sk: encodeKvKey([ENGINE_KEY])
+	}), COSMOS_PARTITION).read().catch((error) => {
+		if (missing(error)) return { resource: void 0 };
+		throw error;
+	});
+	const found = resource?.row?.value;
+	if (found !== void 0) {
+		if (found !== expected) throw new Error(`Cosmos DB container ${container.id} holds storage engine "${String(found)}"; this version writes "${expected}". Use the Hot Updater version that wrote it, or another container.`);
+		return;
+	}
+	const { resources } = await container.items.query("SELECT TOP 1 VALUE c.id FROM c", { enableScanInQuery: true }).fetchAll();
+	if (resources.length > 0) throw new Error(`Cosmos DB container ${container.id} holds items but no ${ENGINE_KEY} setting. Use an empty container.`);
+};
+/**
+* Whether an add takes more operations than one patch does. When its
+* patches would take a batch past its operations, it replaces the row it
+* read instead, one operation, which is what `COSMOS_LIMITS.items` counts.
+*/
+const isWideAdd = (op) => op.type === "add" && Object.keys(op.by).length + (op.expiresAt === void 0 ? 0 : 2) > PATCH_OPERATIONS;
+/**
+* The PostgreSQL behind the vNext emulator aborts a batch that races
+* another one with these errors, having written nothing. Cosmos DB itself
+* runs the batches of a partition one at a time and never reports them.
+*/
+const emulatorAborted = (error) => statusOf(error) === 500 && /PostgresError\(SqlState\(E(25P02|40001|40P01)\)/.test(String(error instanceof Error ? error.message : error));
+/**
+* The key-value store over one Cosmos DB container of `{ pk, sk, row }`
+* items in one logical partition, read through the composite index on
+* (pk, sk). A write is one transactional batch whose operations carry most
+* ops' conditions themselves: a Create fails on an item that exists, a
+* Replace, Read or patch on one that is missing, and a patch whose
+* predicate finds another `_v`. Deletes and `_v` checks read their items
+* first, since a Delete of a missing item fails the batch and a patch
+* restarts the item's TTL, and so does an add wider than one patch, which
+* replaces the row it read.
+*/
+const createCosmosStore = ({ client, databaseId, containerId, engine, nativePageSize }) => {
+	const container = client.database(databaseId).container(containerId);
+	/**
+	* The state of the items `ids` names, by id, with the rows of `rowIds`;
+	* a missing item has none.
+	*/
+	const readStates = async (ids, rowIds) => {
+		const states = /* @__PURE__ */ new Map();
+		for (const [group, projection] of [[ids.filter((id) => !rowIds.has(id)), ""], [ids.filter((id) => rowIds.has(id)), ", c.row"]]) for (let at = 0; at < group.length; at += GET_BATCH) {
+			const { resources } = await container.items.query(`SELECT c.id, c._etag AS etag, c.row._v AS v, c.expireAt${projection} FROM c WHERE c.id IN (${idList(group.slice(at, at + GET_BATCH))})`, { partitionKey: COSMOS_PARTITION }).fetchAll().catch(missingContainer);
+			for (const { id, etag, v, expireAt, row } of resources) states.set(id, {
+				etag,
+				v,
+				expireAt: expireAt ?? null,
+				row
+			});
+		}
+		return states;
+	};
+	/** Whether `op` reads its item before the write plans it. */
+	const readsFirst = (op) => isWideAdd(op) || (op.condition === void 0 ? op.type === "delete" || op.type === "add" : "v" in op.condition && (op.type === "delete" || op.type === "check"));
+	/**
+	* The batch operations of `op`, given the state its item was read in;
+	* `failed` when that state already fails its condition.
+	*/
+	const operationsOf = (op, state, replaceWide) => {
+		const id = cosmosItemId(op.key);
+		const condition = op.condition;
+		const guard = condition !== void 0 && "v" in condition ? guardOf(condition.v) : void 0;
+		const patches = (operations, onFailure) => {
+			const chunks = [];
+			for (let at = 0; at < operations.length; at += PATCH_OPERATIONS) {
+				const operation = {
+					operationType: "Patch",
+					id,
+					resourceBody: {
+						...at === 0 && guard !== void 0 ? { condition: guard } : {},
+						operations: operations.slice(at, at + PATCH_OPERATIONS)
+					}
+				};
+				chunks.push([operation, onFailure]);
+			}
+			return chunks;
+		};
+		const expiry = (expiresAt) => [{
+			op: "set",
+			path: "/expireAt",
+			value: expiresAt ?? null
+		}, {
+			op: "set",
+			path: "/ttl",
+			value: ttlOf(expiresAt)
+		}];
+		/** A Create that fails on an item that exists, undone in the same batch. */
+		const absent = () => [[{
+			operationType: "Create",
+			resourceBody: placeholderOf(op.key)
+		}, "fail"], [{
+			operationType: "Delete",
+			id
+		}, "replan"]];
+		switch (op.type) {
+			case "put": {
+				const item = toItem(op.key, op.value, op.expiresAt);
+				if (condition === void 0) return [[{
+					operationType: "Upsert",
+					resourceBody: item
+				}, "replan"]];
+				if ("v" in condition) return patches([{
+					op: "set",
+					path: "/row",
+					value: item.row
+				}, ...expiry(op.expiresAt)], "fail");
+				return [[condition.exists ? {
+					operationType: "Replace",
+					id,
+					resourceBody: item
+				} : {
+					operationType: "Create",
+					resourceBody: item
+				}, "fail"]];
+			}
+			case "delete":
+				if (condition === void 0) {
+					if (state === void 0) return [];
+					return [[{
+						operationType: "Delete",
+						id
+					}, "replan"]];
+				}
+				if ("v" in condition) {
+					if (state === void 0 || state.v !== condition.v) return { failed: true };
+					return [[{
+						operationType: "Delete",
+						id,
+						ifMatch: state.etag
+					}, "replan"]];
+				}
+				return condition.exists ? [[{
+					operationType: "Delete",
+					id
+				}, "fail"]] : absent();
+			case "check":
+				if (condition === void 0) return [];
+				if ("v" in condition) {
+					if (state === void 0 || state.v !== condition.v) return { failed: true };
+					return patches(expiry(state.expireAt), "fail");
+				}
+				return condition.exists ? [[{
+					operationType: "Read",
+					id
+				}, "fail"]] : absent();
+			case "add":
+				if (condition === void 0 ? state === void 0 : "exists" in condition && !condition.exists) {
+					const created = { ...op.init };
+					for (const [name, delta] of Object.entries(op.by)) created[name] = Number(created[name] ?? 0) + delta;
+					return [[{
+						operationType: "Create",
+						resourceBody: toItem(op.key, created, op.expiresAt)
+					}, condition === void 0 ? "replan" : "fail"]];
+				}
+				if (replaceWide && isWideAdd(op)) {
+					if (state === void 0) return { failed: true };
+					if (guard !== void 0 && state.v !== condition.v) return { failed: true };
+					const row = { ...toRow(state.row) };
+					for (const [name, delta] of Object.entries(op.by)) row[name] = Number(row[name] ?? 0) + delta;
+					return [[{
+						operationType: "Replace",
+						id,
+						ifMatch: state.etag,
+						resourceBody: toItem(op.key, row, op.expiresAt ?? state.expireAt ?? void 0)
+					}, "replan"]];
+				}
+				return patches([...Object.entries(op.by).map(([name, delta]) => ({
+					op: "incr",
+					path: columnPath(name),
+					value: delta
+				})), ...op.expiresAt === void 0 ? [] : expiry(op.expiresAt)], condition === void 0 ? "replan" : "fail");
+		}
+	};
+	return {
+		id: "cosmos",
+		limits: COSMOS_LIMITS,
+		async get(keys) {
+			const found = /* @__PURE__ */ new Map();
+			const ids = [...new Set(keys.map(cosmosItemId))];
+			for (let at = 0; at < ids.length; at += GET_BATCH) {
+				const { resources } = await container.items.query(`SELECT c.id, c.row FROM c WHERE c.id IN (${idList(ids.slice(at, at + GET_BATCH))})`, { partitionKey: COSMOS_PARTITION }).fetchAll().catch(missingContainer);
+				for (const resource of resources) found.set(resource.id, toRow(resource.row));
+			}
+			return keys.map((key) => found.get(cosmosItemId(key)) ?? null);
+		},
+		async query({ pk, gte, lt, order, limit, after }) {
+			const size = Math.min(limit, nativePageSize ?? limit);
+			const filters = ["c.pk = @pk"];
+			const parameters = [{
+				name: "@pk",
+				value: pk
+			}, {
+				name: "@size",
+				value: size
+			}];
+			if (gte !== void 0) {
+				filters.push("c.sk >= @gte");
+				parameters.push({
+					name: "@gte",
+					value: gte
+				});
+			}
+			if (lt !== void 0) {
+				filters.push("c.sk < @lt");
+				parameters.push({
+					name: "@lt",
+					value: lt
+				});
+			}
+			if (after !== void 0) {
+				filters.push(order === "asc" ? "c.sk > @after" : "c.sk < @after");
+				parameters.push({
+					name: "@after",
+					value: after
+				});
+			}
+			const { resources } = await container.items.query({
+				query: `SELECT TOP @size c.sk, c.row FROM c WHERE ${filters.join(" AND ")} ORDER BY c.pk ${order === "asc" ? "ASC" : "DESC"}, c.sk ${order === "asc" ? "ASC" : "DESC"}`,
+				parameters
+			}, {
+				partitionKey: COSMOS_PARTITION,
+				maxItemCount: size
+			}).fetchAll().catch(missingContainer);
+			return {
+				items: resources.map((resource) => ({
+					sk: resource.sk,
+					value: toRow(resource.row)
+				})),
+				more: resources.length === size
+			};
+		},
+		async write(ops) {
+			for (let attempt = 0; attempt < 5; attempt += 1) {
+				const states = await readStates([...new Set(ops.filter(readsFirst).map((op) => cosmosItemId(op.key)))], new Set(ops.filter(isWideAdd).map((op) => cosmosItemId(op.key))));
+				const plan = (replaceWide) => {
+					const planned = [];
+					for (const [position, op] of ops.entries()) {
+						const operations = operationsOf(op, states.get(cosmosItemId(op.key)), replaceWide);
+						if ("failed" in operations) return { failedOp: position };
+						for (const [operation, onFailure] of operations) planned.push({
+							position,
+							operation,
+							onFailure
+						});
+					}
+					return planned;
+				};
+				let planned = plan(false);
+				if ("failedOp" in planned) return {
+					ok: false,
+					failedOp: planned.failedOp
+				};
+				if (planned.length > BATCH_OPERATIONS) {
+					const replaced = plan(true);
+					if ("failedOp" in replaced) return {
+						ok: false,
+						failedOp: replaced.failedOp
+					};
+					planned = replaced;
+					const bytes = encoder.encode(JSON.stringify(planned.map(({ operation }) => operation))).length;
+					if (bytes > BATCH_BYTES) throw new Error(`A Cosmos DB batch takes ${BATCH_BYTES} bytes; this write's rows of more counters than one patch takes need ${bytes}. Write fewer of them at once.`);
+				}
+				if (planned.length === 0) return { ok: true };
+				if (planned.length > BATCH_OPERATIONS) throw new Error(`A Cosmos DB batch takes ${BATCH_OPERATIONS} operations; this write needs ${planned.length}.`);
+				let results;
+				try {
+					const response = await container.items.batch(planned.map(({ operation }) => operation), COSMOS_PARTITION);
+					if (response.result === void 0) throw Object.assign(/* @__PURE__ */ new Error(`Cosmos DB refused the batch with status ${response.code}`), { code: response.code });
+					results = response.result;
+				} catch (error) {
+					if (emulatorAborted(error)) continue;
+					if (TRANSIENT.has(statusOf(error))) return {
+						ok: false,
+						retry: true
+					};
+					return missingContainer(error);
+				}
+				const failed = results.findIndex(({ statusCode }) => statusCode >= 400 && statusCode !== 424);
+				if (failed === -1) return { ok: true };
+				const status = results[failed].statusCode;
+				const { position, onFailure } = planned[failed];
+				if (TRANSIENT.has(status)) return {
+					ok: false,
+					retry: true
+				};
+				if (status !== 404 && status !== 409 && status !== 412) throw new Error(`Cosmos DB refused a batch operation with status ${status}.`);
+				if (onFailure === "fail") return {
+					ok: false,
+					failedOp: position
+				};
+			}
+			return {
+				ok: false,
+				retry: true
+			};
+		},
+		/** Plain deletes through the bulk API, where a missing item is no failure. */
+		async deleteConsumed(keys) {
+			let remaining = [...new Set(keys.map(cosmosItemId))];
+			for (let attempt = 0; remaining.length > 0; attempt += 1) {
+				const failed = (await container.items.executeBulkOperations(remaining.map((id) => ({
+					operationType: "Delete",
+					id,
+					partitionKey: COSMOS_PARTITION
+				}))).catch(missingContainer)).flatMap((result, at) => {
+					const status = result.response?.statusCode ?? statusOf(result.error);
+					return typeof status === "number" && status < 400 || status === 404 ? [] : [{
+						id: remaining[at],
+						error: result.error,
+						status
+					}];
+				});
+				if (failed.length === 0) return;
+				const retried = failed.filter(({ error, status }) => TRANSIENT.has(status) || emulatorAborted(error));
+				if (retried.length < failed.length || attempt >= 4) throw new Error(`Cosmos DB refused to delete ${failed.length} consumed item(s) with status ${failed[0].status}.`);
+				remaining = retried.map(({ id }) => id);
+			}
+		},
+		migrations: { 
+		/** Creates the database and the container when they are missing. */
+async apply() {
+			if (engine !== void 0) await assertCosmosContainerReusable(container, engine);
+			const { database } = await client.databases.createIfNotExists({ id: databaseId });
+			const { resource } = await database.containers.createIfNotExists({
+				id: containerId,
+				partitionKey: { paths: [COSMOS_PARTITION_KEY_PATH] },
+				defaultTtl: -1,
+				indexingPolicy: COSMOS_INDEXING_POLICY
+			});
+			if (resource === void 0) throw new Error(`Cosmos DB returned no container ${containerId}.`);
+			assertContainerShape(resource);
+			const policy = resource.indexingPolicy;
+			const indexed = (policy?.indexingMode ?? "consistent") === "consistent" && policy?.automatic !== false;
+			const composite = COSMOS_INDEXING_POLICY.compositeIndexes[0];
+			const ordered = policy?.compositeIndexes?.some((index) => index.length === 2 && index[0].path === "/pk" && index[1].path === "/sk" && (index[0].order ?? "ascending") === (index[1].order ?? "ascending"));
+			const expires = resource.defaultTtl !== void 0 && resource.defaultTtl !== null;
+			if (!indexed || !ordered || !expires) {
+				await database.container(containerId).replace({
+					...resource,
+					defaultTtl: expires ? resource.defaultTtl : -1,
+					indexingPolicy: {
+						...policy,
+						indexingMode: "consistent",
+						automatic: true,
+						compositeIndexes: ordered ? policy?.compositeIndexes : [...policy?.compositeIndexes ?? [], composite]
+					}
+				});
+				await waitForIndexTransformation(database.container(containerId));
+			}
+		} },
+		async dispose() {}
+	};
+};
+//#endregion
+//#region src/cosmosDatabase.ts
+const adapterOf = (config) => {
+	const { databaseId = AZURE_COSMOS_V1_DATABASE, containerId = AZURE_COSMOS_V1_CONTAINER, aggregateBatching: _, ...connection } = config;
+	if (connection.consistencyLevel !== void 0 && connection.consistencyLevel !== "Strong") throw new Error(`cosmosDatabase reads with strong consistency; consistencyLevel "${String(connection.consistencyLevel)}" is weaker.`);
+	const client = new CosmosClient(connection);
+	const store = createCosmosStore({
+		client,
+		databaseId,
+		containerId,
+		engine: currentCosmosEngine()
+	});
+	return {
+		client,
+		adapter: createKvAdapter({ store })
+	};
+};
+/**
+* Creates the database and the container when they are missing, refusing a
+* container of another storage layout or another app's items, and writes
+* the schema settings of core and `plugins`, the plugins the server runs,
+* which the database checks before its first read. `hot-updater init` runs
+* it with the managed server's plugins.
+*/
+const migrateCosmosDatabase = (config, plugins = []) => {
+	const { client, adapter } = adapterOf(config);
+	return migrateCoreSchema(adapter, "cosmosDatabase", plugins).finally(() => client.dispose());
+};
+/**
+* Hot Updater's database in one Azure Cosmos DB for NoSQL container,
+* through the storage engine. Every item shares one logical partition, so a
+* write commits as one transactional batch; that partition holds at most
+* 20 GB.
+*/
+const cosmosDatabase = (config) => {
+	const { client, adapter } = adapterOf(config);
+	return {
+		...createEngineDatabase({
+			name: "cosmosDatabase",
+			adapter,
+			aggregateBatching: config.aggregateBatching ?? {}
+		}),
+		async dispose() {
+			await adapter.dispose?.();
+			client.dispose();
+		}
+	};
+};
+//#endregion
+export { azureBlobStorage, cosmosDatabase, migrateCosmosDatabase };