@astrale-os/adapter-cloudflare 0.5.0-beta.176 → 0.5.0-beta.178

package/dist/hosting/dispatcher/services.mjs

@@ -0,0 +1,231 @@
+import { canonicalUtcCrons, matches } from './cron.mjs'
+import { dispatchDeployment, isDeploymentLabel } from './deployments.mjs'
+import { errorText } from './failure.mjs'
+
+// @ts-check
+/* eslint-disable no-console -- the cron fan-out reports each schedule event to Workers logs. */
+
+/** @typedef {import('./env.mjs').DispatcherEnvironment} DispatcherEnvironment */
+/** @typedef {import('./env.mjs').ScheduleEnvironment} ScheduleEnvironment */
+/** @typedef {import('./env.mjs').DispatchFetcher} DispatchFetcher */
+
+/**
+ * @template {ScheduleEnvironment} Environment
+ * @typedef {{
+ *   scheduleName?: (name: string, environment: Environment) => boolean,
+ *   scheduleTarget?: (
+ *     name: string,
+ *     environment: Environment,
+ *   ) => Promise<{ fetcher: DispatchFetcher, deployment?: string } | null | undefined>,
+ * }} ScheduleExtension
+ */
+
+/**
+ * Every name a deployment line gives, as a deployer admits one: the 16-character fingerprint
+ * alone when opaque, `<readable>-<fingerprint>` when readable, and never a deployment label.
+ */
+const SERVICE_NAME = /^(?:[a-z0-9]+(?:-[a-z0-9]+)*-)?[a-z2-7]{16}$/u
+/** The longest line a deploy gives. */
+const MAXIMUM_SERVICE_NAME_LENGTH = 40
+const SCHEDULED_TIMEOUT_MS = 10_000
+const FAN_OUT_CONCURRENCY = 16
+
+/** @param {string} name */
+export function isServiceName(name) {
+  return (
+    name.length <= MAXIMUM_SERVICE_NAME_LENGTH &&
+    SERVICE_NAME.test(name) &&
+    !isDeploymentLabel(name)
+  )
+}
+
+/**
+ * The deployment one name serves now: `current:<name>`, admitted as one of its own labels.
+ *
+ * @param {Pick<DispatcherEnvironment, 'SCHEDULES'>} environment
+ * @param {string} service
+ * @returns {Promise<string | null>}
+ */
+async function currentDeployment(environment, service) {
+  const label = await environment.SCHEDULES.get(`current:${service}`)
+  if (label === null) return null
+  if (!isDeploymentLabel(label) || !label.startsWith(`${service}-`)) {
+    throw new TypeError('The current deployment of the name is not one of its labels.')
+  }
+  return label
+}
+
+/**
+ * Route one request to the deployment a name points at (`current:<name>`), exactly as that
+ * deployment's own URL routes it: its record, its tombstone and its call point apply. A name with
+ * no current deployment serves nothing.
+ *
+ * @param {Request} request
+ * @param {DispatcherEnvironment} environment
+ * @param {string} service
+ */
+export async function dispatchService(request, environment, service) {
+  /** @type {string | null} */
+  let label
+  try {
+    label = await currentDeployment(environment, service)
+  } catch {
+    return new Response('dispatch error', { status: 502 })
+  }
+  if (label === null) return missingServiceResponse(request, service)
+  return dispatchDeployment(request, environment, label)
+}
+
+/**
+ * The answer for a name nothing serves: `/invoke` answers the invocation envelope of an
+ * unavailable callee, every other path a plain 404 the ingress probe recognizes.
+ *
+ * @param {Request} request
+ * @param {string} service
+ */
+export function missingServiceResponse(request, service) {
+  const headers = { 'cache-control': 'no-store' }
+  const url = new URL(request.url)
+  if (url.pathname !== '/invoke') {
+    return new Response(`no such service: ${service}`, { status: 404, headers })
+  }
+  return new Response(
+    JSON.stringify({
+      requestId: null,
+      invocation: { source: url.origin, id: 'unavailable' },
+      error: { code: 5001, message: 'Service is unavailable.' },
+    }),
+    {
+      status: 503,
+      headers: { ...headers, 'content-type': 'application/vnd.astrale+json' },
+    },
+  )
+}
+
+/**
+ * Fire every cron of `cron:<name>` that matches this minute on the deployment the name serves now
+ * (`current:<name>`), while it is active (`record:<label>`) and not retired (`retirement:<label>`),
+ * or on the target an extension gives. One name's failure never stops the others.
+ *
+ * @template {ScheduleEnvironment} Environment
+ * @param {{ scheduledTime?: number }} controller
+ * @param {Environment} environment
+ * @param {ScheduleExtension<Environment>} [extension]
+ */
+export async function fanOutSchedules(controller, environment, extension = {}) {
+  const scheduledAt = controller.scheduledTime ?? Date.now()
+  const date = new Date(scheduledAt)
+  const cursors = new Set()
+  /** @type {string | undefined} */
+  let cursor
+  do {
+    const page = await environment.SCHEDULES.list({ prefix: 'cron:', cursor })
+    await pool(page.keys, FAN_OUT_CONCURRENCY, ({ name }) =>
+      fire(environment, extension, name.slice('cron:'.length), name, date, scheduledAt),
+    )
+    if (page.list_complete) cursor = undefined
+    else {
+      const next = page.cursor
+      if (typeof next !== 'string' || next.length === 0 || cursors.has(next)) {
+        throw new TypeError('Schedule cursor did not advance.')
+      }
+      cursors.add(next)
+      cursor = next
+    }
+  } while (cursor !== undefined)
+}
+
+/**
+ * Run one bounded sliding-window fan-out.
+ *
+ * @template Value
+ * @param {readonly Value[]} items
+ * @param {number} limit
+ * @param {(value: Value) => void | Promise<void>} operation
+ */
+export async function pool(items, limit, operation) {
+  const iterator = items[Symbol.iterator]()
+  const worker = async () => {
+    for (let item = iterator.next(); !item.done; item = iterator.next()) {
+      await operation(item.value)
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker))
+}
+
+/**
+ * @template {ScheduleEnvironment} Environment
+ * @param {Environment} environment
+ * @param {ScheduleExtension<Environment>} extension
+ * @param {string} service
+ * @param {string} key
+ * @param {Date} date
+ * @param {number} scheduledAt
+ */
+async function fire(environment, extension, service, key, date, scheduledAt) {
+  if (!isServiceName(service) && extension.scheduleName?.(service, environment) !== true) {
+    console.warn(JSON.stringify({ event: 'service.schedule.invalid-service', service }))
+    return
+  }
+  /** @type {unknown} */
+  let crons
+  try {
+    crons = JSON.parse((await environment.SCHEDULES.get(key)) ?? '[]')
+  } catch {
+    console.warn(JSON.stringify({ event: 'service.schedule.invalid', service }))
+    return
+  }
+  const schedules = canonicalUtcCrons(crons)
+  if (schedules === undefined) {
+    console.warn(JSON.stringify({ event: 'service.schedule.invalid', service }))
+    return
+  }
+  const cron = schedules.find((value) => matches(value, date))
+  if (cron === undefined) return
+  try {
+    const target = await extension.scheduleTarget?.(service, environment)
+    if (target === null) return
+    /** @type {DispatchFetcher} */
+    let fetcher
+    /** @type {string | undefined} */
+    let deployment
+    if (target !== undefined) {
+      fetcher = target.fetcher
+      deployment = target.deployment
+    } else {
+      // A name only the extension admits fires only on a target the extension gives.
+      if (!isServiceName(service)) return
+      const label = await currentDeployment(environment, service)
+      if (label === null) return
+      const [retirement, record] = await Promise.all([
+        environment.SCHEDULES.get(`retirement:${label}`),
+        environment.SCHEDULES.get(`record:${label}`),
+      ])
+      if (retirement !== null || record === null) return
+      fetcher = environment.DEPLOYMENTS.get(label)
+      deployment = label
+    }
+    const response = await fetcher.fetch('https://cron.internal/__scheduled', {
+      method: 'POST',
+      headers: {
+        'x-astrale-cron': cron,
+        'x-astrale-scheduled-time': String(scheduledAt),
+      },
+      signal: AbortSignal.timeout(SCHEDULED_TIMEOUT_MS),
+    })
+    if (!response.ok) {
+      console.warn(
+        JSON.stringify({
+          event: 'service.schedule.rejected',
+          service,
+          ...(deployment === undefined ? {} : { deployment }),
+          status: response.status,
+        }),
+      )
+    }
+  } catch (cause) {
+    console.error(
+      JSON.stringify({ event: 'service.schedule.failed', service, error: errorText(cause) }),
+    )
+  }
+}

package/dist/hosting/identity.d.ts

@@ -0,0 +1,15 @@
+/** The private key of one deployment, as its Worker reads `ASTRALE_SIGNING_IDENTITY`. */
+export interface DeploymentSigningIdentity {
+    /** RFC 7638 thumbprint of the public key: the `astrale-key:` tag and the JWK's `kid`. */
+    readonly keyId: string;
+    /**
+     * The private Ed25519 JWK as JSON text, `{ kty, crv, x, d, alg: 'EdDSA', kid }`: bound once as a
+     * `secret_text` and never logged, returned or stored anywhere else.
+     */
+    readonly secret: string;
+}
+/**
+ * Generate the Ed25519 key of one new deployment with WebCrypto, so it runs in Node and in a
+ * Worker. Every deployment is its own issuer with a key of its own.
+ */
+export declare function createSigningIdentity(): Promise<DeploymentSigningIdentity>;

package/dist/hosting/identity.js

@@ -0,0 +1,36 @@
+import { base64url } from './bytes.js';
+/**
+ * Generate the Ed25519 key of one new deployment with WebCrypto, so it runs in Node and in a
+ * Worker. Every deployment is its own issuer with a key of its own.
+ */
+export async function createSigningIdentity() {
+    const pair = (await crypto.subtle.generateKey({ name: 'Ed25519' }, true, [
+        'sign',
+        'verify',
+    ]));
+    const exported = (await crypto.subtle.exportKey('jwk', pair.privateKey));
+    if (exported.kty !== 'OKP' ||
+        exported.crv !== 'Ed25519' ||
+        typeof exported.x !== 'string' ||
+        typeof exported.d !== 'string') {
+        throw new TypeError('The generated deployment key is not an Ed25519 key.');
+    }
+    const keyId = await thumbprint(exported.crv, exported.kty, exported.x);
+    return Object.freeze({
+        keyId,
+        secret: JSON.stringify({
+            kty: exported.kty,
+            crv: exported.crv,
+            x: exported.x,
+            d: exported.d,
+            alg: 'EdDSA',
+            kid: keyId,
+        }),
+    });
+}
+/** RFC 7638: SHA-256 of the required public members in lexicographic order, base64url. */
+async function thumbprint(crv, kty, x) {
+    const members = JSON.stringify({ crv, kty, x });
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(members));
+    return base64url(new Uint8Array(digest));
+}

package/dist/hosting/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `@astrale-os/adapter-cloudflare/hosting` — host immutable Astrale deployments on your own
+ * Cloudflare account with Workers for Platforms and a domain of your own, with no Astrale
+ * infrastructure:
+ *
+ * - provision once: a dispatch namespace, its routing KV, the dispatcher Worker and the wildcard
+ *   ingress of the routing domain (`planHosting`, `provisionHosting`; `astrale-domain cloudflare init`);
+ * - deploy: one create-only script per deployment label, activated by its record in the routing
+ *   KV, opaque bytes the dispatcher serves verbatim (`uploadDeploymentScript`,
+ *   `activateDeployment`; `cloudflare({ namespace })` and Admin's Services do it);
+ * - operate: point a name at a deployment, schedule crons, retire in two phases, list a line.
+ *
+ * Everything but provisioning runs in Node and inside a Worker (`fetch` and WebCrypto only).
+ * Provisioning reads the dispatcher modules shipped with this package, so it runs in Node.
+ */
+export { CLOUDFLARE_API_BASE, CloudflareApiError, CloudflareClient, DEFAULT_RATE_LIMIT, isNotFound, OPERATOR_RATE_LIMIT, type CloudflareClientOptions, type CloudflareFailureKind, type CloudflarePage, type RateLimitPolicy, } from './client.js';
+export { HostingRefusal } from './refusal.js';
+export { callsDataset, isWorkerName, routingKvTitle } from './names.js';
+export { CRON_PREFIX, cronKey, CURRENT_PREFIX, currentKey, decodeCurrent, decodeSchedules, encodeSchedules, findKvNamespace, isLabelOf, RECORD_PREFIX, recordKey, RETIREMENT_PREFIX, retirementKey, RoutingKv, WITHDRAWN, type RoutingKvLocator, } from './kv.js';
+export { ARTIFACT_TAG_PREFIX, artifactOf, ASSETS_BINDING, BUILD_DIGEST_BINDING, decodeScript, deleteScript, deploymentBindings, deploymentTags, isExistingScript, KEY_TAG_PREFIX, LINE_TAG_PREFIX, observeScript, putScriptSecret, ROUTER_BINDING, scriptPath, scriptSecretNames, scriptSettings, SETTINGS_BINDING, settingsBind, SIGNING_IDENTITY_BINDING, uploadDeploymentScript, VERSION_METADATA_BINDING, versionUuid, WORKER_URL_BINDING, type DeploymentBindingsInput, type NamespaceScript, type ScriptBinding, type ScriptModule, type ScriptSettings, type ScriptUpload, } from './script.js';
+export { uploadAssets, type ScriptAsset } from './assets.js';
+export { createSigningIdentity, type DeploymentSigningIdentity } from './identity.js';
+export { activateDeployment, promoteDeployment, readCurrent, readRecord, readSchedules, replaceSchedules, sameRecord, } from './activation.js';
+export { completeRetirement, markRetired, readRetirement, RETIREMENT_PROBE_PATH, RETIREMENT_PROBE_RETRY_MS, RETIREMENT_PROPAGATION_MS, retirementVisible, type RetirementCompletion, } from './retirement.js';
+export { dispatchFetcher, publicFetcher, VERSION_HEADER, versionFetch, waitForReadiness, type ReadinessFetcher, } from './readiness.js';
+export { listLineDeployments, type LineDeployment } from './listing.js';
+export { createDispatcher } from './dispatcher/dispatcher.mjs';
+export type { Dispatcher, DispatcherExtension, ScheduleTarget } from './dispatcher/dispatcher.mjs';
+export type { DispatcherEnvironment, DispatchFetcher, DispatchNamespaceBinding, RoutingKvBinding, } from './dispatcher/env.mjs';
+export { DISPATCHER_MAIN_MODULE, DISPATCHER_MODULE_NAMES, dispatcherModules, type DispatcherModule, } from './dispatcher/modules.js';
+export { DISPATCHER_COMPATIBILITY_DATE, DISPATCHER_COMPATIBILITY_FLAGS, dispatcherBindings, type WorkerBinding, } from './provision/dispatcher.js';
+export { dispatcherIngressReady } from './provision/ingress.js';
+export { findZone, routeReaches } from './provision/routing.js';
+export { applyHosting, openHostingKv, planHosting, provisionHosting, type HostingConfig, type HostingPlan, type HostingProvisioning, } from './provision/plan.js';

package/dist/hosting/index.js

@@ -0,0 +1,32 @@
+/**
+ * `@astrale-os/adapter-cloudflare/hosting` — host immutable Astrale deployments on your own
+ * Cloudflare account with Workers for Platforms and a domain of your own, with no Astrale
+ * infrastructure:
+ *
+ * - provision once: a dispatch namespace, its routing KV, the dispatcher Worker and the wildcard
+ *   ingress of the routing domain (`planHosting`, `provisionHosting`; `astrale-domain cloudflare init`);
+ * - deploy: one create-only script per deployment label, activated by its record in the routing
+ *   KV, opaque bytes the dispatcher serves verbatim (`uploadDeploymentScript`,
+ *   `activateDeployment`; `cloudflare({ namespace })` and Admin's Services do it);
+ * - operate: point a name at a deployment, schedule crons, retire in two phases, list a line.
+ *
+ * Everything but provisioning runs in Node and inside a Worker (`fetch` and WebCrypto only).
+ * Provisioning reads the dispatcher modules shipped with this package, so it runs in Node.
+ */
+export { CLOUDFLARE_API_BASE, CloudflareApiError, CloudflareClient, DEFAULT_RATE_LIMIT, isNotFound, OPERATOR_RATE_LIMIT, } from './client.js';
+export { HostingRefusal } from './refusal.js';
+export { callsDataset, isWorkerName, routingKvTitle } from './names.js';
+export { CRON_PREFIX, cronKey, CURRENT_PREFIX, currentKey, decodeCurrent, decodeSchedules, encodeSchedules, findKvNamespace, isLabelOf, RECORD_PREFIX, recordKey, RETIREMENT_PREFIX, retirementKey, RoutingKv, WITHDRAWN, } from './kv.js';
+export { ARTIFACT_TAG_PREFIX, artifactOf, ASSETS_BINDING, BUILD_DIGEST_BINDING, decodeScript, deleteScript, deploymentBindings, deploymentTags, isExistingScript, KEY_TAG_PREFIX, LINE_TAG_PREFIX, observeScript, putScriptSecret, ROUTER_BINDING, scriptPath, scriptSecretNames, scriptSettings, SETTINGS_BINDING, settingsBind, SIGNING_IDENTITY_BINDING, uploadDeploymentScript, VERSION_METADATA_BINDING, versionUuid, WORKER_URL_BINDING, } from './script.js';
+export { uploadAssets } from './assets.js';
+export { createSigningIdentity } from './identity.js';
+export { activateDeployment, promoteDeployment, readCurrent, readRecord, readSchedules, replaceSchedules, sameRecord, } from './activation.js';
+export { completeRetirement, markRetired, readRetirement, RETIREMENT_PROBE_PATH, RETIREMENT_PROBE_RETRY_MS, RETIREMENT_PROPAGATION_MS, retirementVisible, } from './retirement.js';
+export { dispatchFetcher, publicFetcher, VERSION_HEADER, versionFetch, waitForReadiness, } from './readiness.js';
+export { listLineDeployments } from './listing.js';
+export { createDispatcher } from './dispatcher/dispatcher.mjs';
+export { DISPATCHER_MAIN_MODULE, DISPATCHER_MODULE_NAMES, dispatcherModules, } from './dispatcher/modules.js';
+export { DISPATCHER_COMPATIBILITY_DATE, DISPATCHER_COMPATIBILITY_FLAGS, dispatcherBindings, } from './provision/dispatcher.js';
+export { dispatcherIngressReady } from './provision/ingress.js';
+export { findZone, routeReaches } from './provision/routing.js';
+export { applyHosting, openHostingKv, planHosting, provisionHosting, } from './provision/plan.js';

package/dist/hosting/kv.d.ts

@@ -0,0 +1,89 @@
+import type { CloudflareClient } from './client.js';
+/**
+ * The routing KV contract every dispatcher reads (`SCHEDULES`) and every writer of the kit keeps:
+ *
+ * | key | value | metadata |
+ * |---|---|---|
+ * | `record:<label>` | the deployment's record, opaque bytes; `-` when it publishes none; never rewritten | `{"contentType":<its media type>}`, `{"contentType":null}` without a record |
+ * | `retirement:<label>` | `withdrawn`; any value retires the label at the dispatcher | none |
+ * | `current:<name>` | the label a name serves now, one of `<name>-…` | none |
+ * | `cron:<name>` | JSON array of distinct canonical five-field UTC crons; deleted when empty | none |
+ *
+ * `record:<label>` activates the label and outlives its retirement. One written before records
+ * were opaque has no metadata: it is the RFC 8785 JSON of a `DeploymentRecordV1`, served as one.
+ * Workers KV has no compare-and-set: every write is read back before it counts.
+ */
+export declare const RECORD_PREFIX = "record:";
+export declare const RETIREMENT_PREFIX = "retirement:";
+export declare const CURRENT_PREFIX = "current:";
+export declare const CRON_PREFIX = "cron:";
+/** The one tombstone value the kit writes: a withdrawal by the deployment's owner. */
+export declare const WITHDRAWN = "withdrawn";
+/** The key whose presence activates a label at the dispatcher. */
+export declare function recordKey(label: string): string;
+/** The key whose presence retires a label at the dispatcher, whatever the record says. */
+export declare function retirementKey(label: string): string;
+/** The key that points a name (a deployment line) at the deployment its host serves now. */
+export declare function currentKey(name: string): string;
+/** The key of a name's UTC crons, which the dispatcher fires on its current deployment. */
+export declare function cronKey(name: string): string;
+/** Admit the label `current:<name>` holds: a deployment label of that name's line. */
+export declare function decodeCurrent(text: string, name: string): string;
+/** Whether `label` is a deployment label whose line is `name`, as the dispatcher admits it. */
+export declare function isLabelOf(label: string, name: string): boolean;
+/**
+ * The text `cron:<name>` holds for these crons: their canonical form as JSON, or undefined when
+ * there are none and the key is deleted. Crons that are not distinct five-field UTC expressions are
+ * refused before anything is written.
+ */
+export declare function encodeSchedules(crons: readonly string[]): {
+    readonly crons: readonly string[];
+    readonly text: string | undefined;
+};
+/** Admit the text `cron:<name>` holds as canonical crons. */
+export declare function decodeSchedules(text: string, name: string): readonly string[];
+/** Where a routing KV is: by the id a caller keeps, or by its title (`routingKvTitle`). */
+export type RoutingKvLocator = {
+    readonly id: string;
+} | {
+    readonly title: string;
+};
+/**
+ * One routing KV, through the account API. Reads answer the stored text (undefined when absent);
+ * every write and delete is read back before it counts, and fails `unavailable` otherwise.
+ */
+export declare class RoutingKv {
+    private readonly client;
+    readonly id: string;
+    private constructor();
+    /**
+     * Open the routing KV by id, or find it by title; a title the account holds no KV under is a
+     * `not-provisioned` refusal: only provisioning creates it.
+     */
+    static open(client: CloudflareClient, locator: RoutingKvLocator): Promise<RoutingKv>;
+    /** The text stored at `key`, or undefined. */
+    get(key: string): Promise<string | undefined>;
+    /** Write `text` at `key`, then read it back. */
+    put(key: string, text: string, contentType: string): Promise<void>;
+    /**
+     * The bytes stored at `key` and their metadata (`null` when they were written without), or
+     * undefined when the key is absent.
+     */
+    getWithMetadata(key: string): Promise<{
+        readonly bytes: Uint8Array;
+        readonly metadata: unknown;
+    } | undefined>;
+    /** Write `bytes` at `key` with its JSON `metadata`, then read both back. */
+    putWithMetadata(key: string, bytes: Uint8Array, metadata: Readonly<Record<string, unknown>>): Promise<void>;
+    /** Delete `key`, then read back its absence. */
+    delete(key: string): Promise<void>;
+    /**
+     * Every key name that starts with `prefix`, in Cloudflare's (lexicographic) order, following
+     * the listing's cursor to its end.
+     */
+    keys(prefix: string): Promise<readonly string[]>;
+    private value;
+    private path;
+}
+/** The id of the account's KV namespace with exactly this title, or undefined. */
+export declare function findKvNamespace(client: CloudflareClient, title: string): Promise<string | undefined>;

package/dist/hosting/kv.js

@@ -0,0 +1,206 @@
+import { parseDeploymentLabel } from '@astrale-os/sdk/deployment/address';
+import { CloudflareApiError, isNotFound } from './client.js';
+import { canonicalUtcCrons } from './dispatcher/cron.mjs';
+import { HostingRefusal } from './refusal.js';
+/**
+ * The routing KV contract every dispatcher reads (`SCHEDULES`) and every writer of the kit keeps:
+ *
+ * | key | value | metadata |
+ * |---|---|---|
+ * | `record:<label>` | the deployment's record, opaque bytes; `-` when it publishes none; never rewritten | `{"contentType":<its media type>}`, `{"contentType":null}` without a record |
+ * | `retirement:<label>` | `withdrawn`; any value retires the label at the dispatcher | none |
+ * | `current:<name>` | the label a name serves now, one of `<name>-…` | none |
+ * | `cron:<name>` | JSON array of distinct canonical five-field UTC crons; deleted when empty | none |
+ *
+ * `record:<label>` activates the label and outlives its retirement. One written before records
+ * were opaque has no metadata: it is the RFC 8785 JSON of a `DeploymentRecordV1`, served as one.
+ * Workers KV has no compare-and-set: every write is read back before it counts.
+ */
+export const RECORD_PREFIX = 'record:';
+export const RETIREMENT_PREFIX = 'retirement:';
+export const CURRENT_PREFIX = 'current:';
+export const CRON_PREFIX = 'cron:';
+/** The one tombstone value the kit writes: a withdrawal by the deployment's owner. */
+export const WITHDRAWN = 'withdrawn';
+/** The key whose presence activates a label at the dispatcher. */
+export function recordKey(label) {
+    return `${RECORD_PREFIX}${label}`;
+}
+/** The key whose presence retires a label at the dispatcher, whatever the record says. */
+export function retirementKey(label) {
+    return `${RETIREMENT_PREFIX}${label}`;
+}
+/** The key that points a name (a deployment line) at the deployment its host serves now. */
+export function currentKey(name) {
+    return `${CURRENT_PREFIX}${name}`;
+}
+/** The key of a name's UTC crons, which the dispatcher fires on its current deployment. */
+export function cronKey(name) {
+    return `${CRON_PREFIX}${name}`;
+}
+/** Admit the label `current:<name>` holds: a deployment label of that name's line. */
+export function decodeCurrent(text, name) {
+    if (!isLabelOf(text, name)) {
+        throw new HostingRefusal('route-invalid', `current:${name} names ${text}, which is not a deployment of ${name}.`);
+    }
+    return text;
+}
+/** Whether `label` is a deployment label whose line is `name`, as the dispatcher admits it. */
+export function isLabelOf(label, name) {
+    if (!label.startsWith(`${name}-`))
+        return false;
+    try {
+        return parseDeploymentLabel(label).line === name;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The text `cron:<name>` holds for these crons: their canonical form as JSON, or undefined when
+ * there are none and the key is deleted. Crons that are not distinct five-field UTC expressions are
+ * refused before anything is written.
+ */
+export function encodeSchedules(crons) {
+    const canonical = canonicalUtcCrons(crons);
+    if (canonical === undefined) {
+        throw new HostingRefusal('schedules-invalid', 'Schedules must be distinct five-field UTC cron expressions.');
+    }
+    return Object.freeze({
+        crons: canonical,
+        text: canonical.length === 0 ? undefined : JSON.stringify(canonical),
+    });
+}
+/** Admit the text `cron:<name>` holds as canonical crons. */
+export function decodeSchedules(text, name) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        value = undefined;
+    }
+    const crons = canonicalUtcCrons(value);
+    if (crons === undefined) {
+        throw new HostingRefusal('schedules-invalid', `cron:${name} holds no canonical UTC crons.`);
+    }
+    return crons;
+}
+/** The most keys one page of a KV key listing returns, as Cloudflare caps it. */
+const KEYS_PAGE = 1_000;
+/**
+ * One routing KV, through the account API. Reads answer the stored text (undefined when absent);
+ * every write and delete is read back before it counts, and fails `unavailable` otherwise.
+ */
+export class RoutingKv {
+    client;
+    id;
+    constructor(client, id) {
+        this.client = client;
+        this.id = id;
+    }
+    /**
+     * Open the routing KV by id, or find it by title; a title the account holds no KV under is a
+     * `not-provisioned` refusal: only provisioning creates it.
+     */
+    static async open(client, locator) {
+        if ('id' in locator) {
+            if (locator.id.length === 0)
+                throw new TypeError('Routing KV id is required.');
+            return new RoutingKv(client, locator.id);
+        }
+        const id = await findKvNamespace(client, locator.title);
+        if (id === undefined) {
+            throw new HostingRefusal('not-provisioned', `The account has no routing KV titled ${locator.title}; the namespace is not provisioned ` +
+                '(`astrale-domain cloudflare init <environment>` provisions it).');
+        }
+        return new RoutingKv(client, id);
+    }
+    /** The text stored at `key`, or undefined. */
+    async get(key) {
+        return this.client.text('GET', this.value(key));
+    }
+    /** Write `text` at `key`, then read it back. */
+    async put(key, text, contentType) {
+        await this.client.text('PUT', this.value(key), { text, contentType });
+        if ((await this.get(key)) !== text)
+            notKept(key);
+    }
+    /**
+     * The bytes stored at `key` and their metadata (`null` when they were written without), or
+     * undefined when the key is absent.
+     */
+    async getWithMetadata(key) {
+        const bytes = await this.client.bytes(this.value(key));
+        if (bytes === undefined)
+            return undefined;
+        let metadata;
+        try {
+            metadata = await this.client.json('GET', this.path('metadata', key));
+        }
+        catch (cause) {
+            if (isNotFound(cause))
+                return undefined;
+            throw cause;
+        }
+        return Object.freeze({ bytes, metadata: metadata ?? null });
+    }
+    /** Write `bytes` at `key` with its JSON `metadata`, then read both back. */
+    async putWithMetadata(key, bytes, metadata) {
+        const text = JSON.stringify(metadata);
+        const form = new FormData();
+        form.append('value', new Blob([bytes]));
+        form.append('metadata', text);
+        await this.client.form('PUT', this.value(key), form);
+        const stored = await this.getWithMetadata(key);
+        if (stored === undefined ||
+            stored.bytes.byteLength !== bytes.byteLength ||
+            stored.bytes.some((byte, index) => byte !== bytes[index]) ||
+            JSON.stringify(stored.metadata) !== text) {
+            notKept(key);
+        }
+    }
+    /** Delete `key`, then read back its absence. */
+    async delete(key) {
+        await this.client.text('DELETE', this.value(key));
+        if ((await this.get(key)) !== undefined)
+            notKept(key);
+    }
+    /**
+     * Every key name that starts with `prefix`, in Cloudflare's (lexicographic) order, following
+     * the listing's cursor to its end.
+     */
+    async keys(prefix) {
+        const query = new URLSearchParams({ prefix, limit: String(KEYS_PAGE) });
+        const entries = await this.client.cursorList(this.client.account(`/storage/kv/namespaces/${encodeURIComponent(this.id)}/keys?${query}`));
+        return Object.freeze(entries.map((entry) => {
+            const name = entry?.name;
+            if (typeof name !== 'string' || !name.startsWith(prefix)) {
+                throw new CloudflareApiError('upstream', 'Cloudflare returned an invalid KV key listing.');
+            }
+            return name;
+        }));
+    }
+    value(key) {
+        return this.path('values', key);
+    }
+    path(kind, key) {
+        return this.client.account(`/storage/kv/namespaces/${encodeURIComponent(this.id)}/${kind}/${encodeURIComponent(key)}`);
+    }
+}
+/** The id of the account's KV namespace with exactly this title, or undefined. */
+export async function findKvNamespace(client, title) {
+    const matches = (entry) => entry?.title === title;
+    const listed = await client.pagedList(client.account('/storage/kv/namespaces'), matches);
+    const found = listed.find(matches);
+    if (found === undefined)
+        return undefined;
+    if (typeof found.id !== 'string' || found.id.length === 0) {
+        throw new CloudflareApiError('upstream', 'Cloudflare returned an invalid KV namespace id.');
+    }
+    return found.id;
+}
+function notKept(key) {
+    const kind = key.slice(0, key.indexOf(':') + 1) || 'a key';
+    throw new CloudflareApiError('unavailable', `Cloudflare did not keep the write at ${kind}.`);
+}