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

package/dist/hosting/dispatcher/cron.mjs

@@ -0,0 +1,135 @@
+// @ts-check
+
+/*
+ * Dependency-free five-field UTC crons: what `cron:<name>` holds and what the dispatcher fires.
+ * Uploaded as the dispatcher module `cron.mjs`; the kit validates schedules with the same code.
+ */
+
+const MONTHS = {
+  jan: 1,
+  feb: 2,
+  mar: 3,
+  apr: 4,
+  may: 5,
+  jun: 6,
+  jul: 7,
+  aug: 8,
+  sep: 9,
+  oct: 10,
+  nov: 11,
+  dec: 12,
+}
+const DAYS = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 }
+
+/** Admit one dependency-free five-field UTC cron expression. */
+/** @param {unknown} expression */
+export function isUtcCron(expression) {
+  if (typeof expression !== 'string') return false
+  const fields = expression.trim().split(/\s+/u)
+  return (
+    fields.length === 5 &&
+    fieldValid(fields[0], 0, 59) &&
+    fieldValid(fields[1], 0, 23) &&
+    fieldValid(fields[2], 1, 31) &&
+    fieldValid(fields[3], 1, 12, MONTHS) &&
+    fieldValid(fields[4], 0, 7, DAYS)
+  )
+}
+
+/** Admit one duplicate-free canonical UTC cron array after a representation boundary. */
+/** @param {unknown} input */
+export function canonicalUtcCrons(input) {
+  if (!Array.isArray(input) || input.some((value) => typeof value !== 'string')) return undefined
+  const canonical = input.map((value) => value.trim().toLowerCase())
+  if (!canonical.every(isUtcCron) || new Set(canonical).size !== canonical.length) return undefined
+  return Object.freeze(canonical)
+}
+
+/** Match one admitted five-field UTC cron expression. */
+/** @param {string} expression @param {Date} date */
+export function matches(expression, date) {
+  if (!isUtcCron(expression) || !Number.isFinite(date.getTime())) return false
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = expression.trim().split(/\s+/u)
+  if (!fieldMatches(minute, date.getUTCMinutes(), 0, 59)) return false
+  if (!fieldMatches(hour, date.getUTCHours(), 0, 23)) return false
+  if (!fieldMatches(month, date.getUTCMonth() + 1, 1, 12, MONTHS)) return false
+  const monthDayMatches = fieldMatches(dayOfMonth, date.getUTCDate(), 1, 31)
+  const weekDayMatches =
+    fieldMatches(dayOfWeek, date.getUTCDay(), 0, 7, DAYS) ||
+    (date.getUTCDay() === 0 && fieldMatches(dayOfWeek, 7, 0, 7, DAYS))
+  // Vixie marks a day field as wildcard by its leading character, including */n.
+  return dayOfMonth.startsWith('*') || dayOfWeek.startsWith('*')
+    ? monthDayMatches && weekDayMatches
+    : monthDayMatches || weekDayMatches
+}
+
+/** @param {string} field @param {number} value @param {number} minimum @param {number} maximum @param {Readonly<Record<string, number>>} [names] */
+export function fieldMatches(field, value, minimum, maximum, names) {
+  for (const segment of field.split(',')) {
+    const parsed = parseSegment(segment, minimum, maximum, names)
+    if (parsed === undefined) continue
+    if (
+      value >= parsed.lower &&
+      value <= parsed.upper &&
+      (value - parsed.lower) % parsed.step === 0
+    ) {
+      return true
+    }
+  }
+  return false
+}
+
+/** @param {string} field @param {number} minimum @param {number} maximum @param {Readonly<Record<string, number>>} [names] */
+function fieldValid(field, minimum, maximum, names) {
+  const segments = field.split(',')
+  return (
+    segments.length > 0 &&
+    segments.every((segment) => parseSegment(segment, minimum, maximum, names) !== undefined)
+  )
+}
+
+/** @param {string} segment @param {number} minimum @param {number} maximum @param {Readonly<Record<string, number>>} [names] */
+function parseSegment(segment, minimum, maximum, names) {
+  const parts = segment.split('/')
+  if (parts.length > 2 || parts[0] === '') return undefined
+  const basis = parts[0]
+  const rawStep = parts[1]
+  const step = rawStep === undefined ? 1 : Number(rawStep)
+  if (!Number.isSafeInteger(step) || step < 1) return undefined
+  let lower
+  let upper
+  if (basis === '*') {
+    lower = minimum
+    upper = maximum
+  } else if (basis.includes('-')) {
+    const range = basis.split('-')
+    if (range.length !== 2) return undefined
+    lower = resolve(range[0], names)
+    upper = resolve(range[1], names)
+  } else {
+    if (rawStep !== undefined) return undefined
+    lower = resolve(basis, names)
+    upper = lower
+  }
+  if (
+    lower === undefined ||
+    upper === undefined ||
+    lower < minimum ||
+    upper > maximum ||
+    lower > upper
+  ) {
+    return undefined
+  }
+  return { lower, upper, step }
+}
+
+/** @param {string} token @param {Readonly<Record<string, number>>} [names] */
+function resolve(token, names) {
+  if (token.length === 0) return undefined
+  const key = token.toLowerCase()
+  const named = names !== undefined && Object.hasOwn(names, key) ? names[key] : undefined
+  if (named !== undefined) return named
+  if (!/^\d+$/u.test(token)) return undefined
+  const value = Number(token)
+  return Number.isSafeInteger(value) ? value : undefined
+}

package/dist/hosting/dispatcher/deployments.d.mts

@@ -0,0 +1,12 @@
+import type { DispatcherEnvironment } from './env.mjs'
+
+/** The probe path the dispatcher never counts as a call (`retirementVisible`). */
+export const RETIREMENT_PROBE_PATH: '/__services_retirement_probe__'
+/** Whether a host label is a deployment label, as the dispatcher admits it (≤ 57 characters). */
+export function isDeploymentLabel(label: string): boolean
+/** Route one request to one deployment label: record endpoint, tombstone, activation, call. */
+export function dispatchDeployment(
+  request: Request,
+  environment: DispatcherEnvironment,
+  label: string,
+): Promise<Response>

package/dist/hosting/dispatcher/deployments.mjs

@@ -0,0 +1,164 @@
+import { scriptMissing } from './failure.mjs'
+
+// @ts-check
+
+/** @typedef {import('./env.mjs').DispatcherEnvironment} DispatcherEnvironment */
+/** @typedef {{ body?: ArrayBuffer, contentType?: string }} PublishedRecord */
+
+/**
+ * Every deployment label, as `@astrale-os/sdk/deployment/address` declares `DEPLOYMENT_LABEL`: an
+ * optional readable part, the 16-character line fingerprint and the 16-character content, in
+ * lower-case base32. The dispatcher is uploaded as plain modules, so it holds its own copy.
+ */
+const DEPLOYMENT_LABEL = /^(?:[a-z0-9]+(?:-[a-z0-9]+)*-)?[a-z2-7]{16}-[a-z2-7]{16}$/u
+/** The longest label a deploy gives: a line of 40 characters, a dash and the content. */
+const MAXIMUM_LABEL_LENGTH = 57
+
+/**
+ * Where the dispatcher serves a deployment's record, which the deployment then never sees. A
+ * deployment that publishes no record answers the path itself.
+ */
+const DEPLOYMENT_RECORD_PATH = '/.well-known/astrale/deployment.json'
+/** The media type of a record written before records were opaque: a `DeploymentRecordV1`. */
+const DEPLOYMENT_RECORD_TYPE = 'application/vnd.astrale.deployment-record+json;v=1'
+const ENVELOPE_TYPE = 'application/vnd.astrale+json'
+/** The retirement probe (`retirementVisible`); it is never a call of the deployment. */
+export const RETIREMENT_PROBE_PATH = '/__services_retirement_probe__'
+const ACTIVATION_RETRY_AFTER_SECONDS = '30'
+
+/** @param {string} label */
+export function isDeploymentLabel(label) {
+  return label.length <= MAXIMUM_LABEL_LENGTH && DEPLOYMENT_LABEL.test(label)
+}
+
+/**
+ * Route one request to one deployment: the one its host names, or the one a name points at
+ * (`./services.mjs`). A deployer writes `record:<label>` to activate the label, and its owner
+ * `retirement:<label>` to retire it; the record outlives the retirement. Every call of a retired
+ * deployment answers `DEPLOYMENT_RETIRED`, whatever its path. The record endpoint is not a call:
+ * the dispatcher answers it itself with the record the deployer published, its bytes and its media
+ * type as written, and the record it serves immutable stays readable after retirement. A
+ * deployment without its record is not active yet (KV is eventually consistent, so a caller
+ * retries), and only an active deployment runs, as one call point when `CALLS` is bound.
+ *
+ * @param {Request} request
+ * @param {DispatcherEnvironment} environment
+ * @param {string} label
+ */
+export async function dispatchDeployment(request, environment, label) {
+  const url = new URL(request.url)
+  try {
+    const [retirement, record] = await Promise.all([
+      environment.SCHEDULES.get(`retirement:${label}`),
+      // Only the record endpoint reads the record's bytes; a call only needs its presence.
+      url.pathname === DEPLOYMENT_RECORD_PATH
+        ? publishedRecord(environment, label)
+        : environment.SCHEDULES.get(`record:${label}`).then((value) =>
+            value === null ? null : /** @type {PublishedRecord} */ ({}),
+          ),
+    ])
+    if (record?.contentType !== undefined) return deploymentRecordResponse(request, record)
+    if (retirement !== null) return deploymentRetiredResponse(url.origin)
+    if (record === null) return inactiveDeploymentResponse(url.origin)
+    if (url.pathname !== RETIREMENT_PROBE_PATH) {
+      environment.CALLS?.writeDataPoint({ indexes: [label] })
+    }
+    return await environment.DEPLOYMENTS.get(label).fetch(request)
+  } catch (cause) {
+    if (scriptMissing(cause)) return inactiveDeploymentResponse(url.origin)
+    return new Response('dispatch error', { status: 502 })
+  }
+}
+
+/**
+ * What `record:<label>` holds, as the record endpoint serves it: `null` when the label is not
+ * activated, the record's bytes and media type, or no `contentType` when the deployment publishes
+ * no record. A value written without metadata, before records were opaque, is a
+ * `DeploymentRecordV1`.
+ *
+ * @param {DispatcherEnvironment} environment
+ * @param {string} label
+ * @returns {Promise<PublishedRecord | null>}
+ */
+async function publishedRecord(environment, label) {
+  const stored = await environment.SCHEDULES.getWithMetadata(`record:${label}`, 'arrayBuffer')
+  if (stored.value === null) return null
+  if (stored.metadata === null || stored.metadata === undefined) {
+    return { body: stored.value, contentType: DEPLOYMENT_RECORD_TYPE }
+  }
+  const contentType = /** @type {{ contentType?: unknown }} */ (stored.metadata).contentType
+  return typeof contentType === 'string'
+    ? { body: stored.value, contentType }
+    : { body: stored.value }
+}
+
+/**
+ * The record a deployer published for this label. It never changes: the label is derived from the
+ * build and the configuration of the deployment it describes.
+ *
+ * @param {Request} request
+ * @param {PublishedRecord} record
+ */
+function deploymentRecordResponse(request, record) {
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    return new Response('method not allowed', {
+      status: 405,
+      headers: { allow: 'GET, HEAD', 'cache-control': 'no-store' },
+    })
+  }
+  return new Response(record.body, {
+    status: 200,
+    headers: {
+      'content-type': /** @type {string} */ (record.contentType),
+      'cache-control': 'public, max-age=31536000, immutable',
+    },
+  })
+}
+
+/**
+ * `DEPLOYMENT_RETIRED` in the one HTTP form every emitter answers, attributed to the deployment,
+ * whose issuer is its origin: the bytes of kernel-protocol `routes.deploymentRetiredBody`, in its
+ * key order, and `routes.deploymentRetiredHeaders`.
+ *
+ * @param {string} deployment
+ */
+function deploymentRetiredResponse(deployment) {
+  return new Response(
+    JSON.stringify({
+      error: {
+        code: 3002,
+        message: 'This deployment is retired.',
+        data: { code: 'DEPLOYMENT_RETIRED', details: { deployment } },
+      },
+      requestId: null,
+      invocation: { source: deployment, id: 'unavailable' },
+    }),
+    {
+      status: 410,
+      headers: {
+        'x-astrale-deployment-retired': '1',
+        'cache-control': 'no-store',
+        'content-type': ENVELOPE_TYPE,
+      },
+    },
+  )
+}
+
+/** @param {string} deployment */
+function inactiveDeploymentResponse(deployment) {
+  return new Response(
+    JSON.stringify({
+      requestId: null,
+      invocation: { source: deployment, id: 'unavailable' },
+      error: { code: 5001, message: 'This deployment is not active yet.' },
+    }),
+    {
+      status: 503,
+      headers: {
+        'cache-control': 'no-store',
+        'content-type': ENVELOPE_TYPE,
+        'retry-after': ACTIVATION_RETRY_AFTER_SECONDS,
+      },
+    },
+  )
+}

package/dist/hosting/dispatcher/dispatcher.d.mts

@@ -0,0 +1,43 @@
+import type { DispatchFetcher, DispatcherEnvironment, ScheduleController } from './env.mjs'
+
+/** Where a cron fires: a fetcher, and the deployment it reaches when there is one (for logs). */
+export interface ScheduleTarget {
+  readonly fetcher: DispatchFetcher
+  readonly deployment?: string
+}
+
+/**
+ * What a consumer prepends to the kit's dispatcher without forking it (see `createDispatcher`).
+ */
+export interface DispatcherExtension<
+  Environment extends DispatcherEnvironment = DispatcherEnvironment,
+> {
+  /** Runs first; a `Response` is the answer, `undefined` hands the request to the kit. */
+  route?(
+    request: Request,
+    environment: Environment,
+  ): Promise<Response | undefined> | Response | undefined
+  /** Admits a `cron:<name>` the kit's name grammar does not. */
+  scheduleName?(name: string, environment: Environment): boolean
+  /** Where to fire a due cron: a target, `null` for nothing, `undefined` for the kit's default. */
+  scheduleTarget?(
+    name: string,
+    environment: Environment,
+  ): Promise<ScheduleTarget | null | undefined>
+}
+
+export interface Dispatcher<Environment extends DispatcherEnvironment = DispatcherEnvironment> {
+  fetch(request: Request, environment: Environment): Promise<Response>
+  scheduled(controller: ScheduleController, environment: Environment): Promise<void>
+}
+
+/**
+ * Whether a public path names the schedule endpoint in any spelling a router behind the dispatcher
+ * could normalize to it: percent-encoded, with repeated or trailing slashes, in any case.
+ */
+export function isSchedulePath(pathname: string): boolean
+
+/** Create one public dispatcher, extended or not (`index.mjs` is the unextended one). */
+export function createDispatcher<Environment extends DispatcherEnvironment = DispatcherEnvironment>(
+  extension?: DispatcherExtension<Environment>,
+): Dispatcher<Environment>

package/dist/hosting/dispatcher/dispatcher.mjs

@@ -0,0 +1,96 @@
+import { dispatchDeployment, isDeploymentLabel } from './deployments.mjs'
+import {
+  dispatchService,
+  fanOutSchedules,
+  isServiceName,
+  missingServiceResponse,
+} from './services.mjs'
+
+// @ts-check
+
+/** @typedef {import('./env.mjs').DispatcherEnvironment} DispatcherEnvironment */
+
+/**
+ * Whether a public path names the schedule endpoint in any spelling a router behind the dispatcher
+ * could normalize to it: percent-encoded, with repeated or trailing slashes, in any case.
+ *
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+export function isSchedulePath(pathname) {
+  let decoded = pathname
+  try {
+    decoded = decodeURIComponent(pathname)
+  } catch {
+    // A malformed escape is compared as written.
+  }
+  return (
+    decoded
+      .replace(/\/{2,}/gu, '/')
+      .replace(/\/+$/u, '')
+      .toLowerCase() === '/__scheduled'
+  )
+}
+
+/**
+ * Create one public dispatcher of a dispatch namespace. A deployment label
+ * (`https://<label>.<routing domain>`) reaches its own script; a name
+ * (`https://<name>.<routing domain>`) reaches the deployment `current:<name>` names, through the
+ * same deployment routing; anything else answers `no such service: <name>`. The public never
+ * reaches a deployment's schedule endpoint, `/__scheduled`: only the cron fan-out calls it.
+ *
+ * An extension lets a consumer keep its own routing and schedule targets ahead of the kit's
+ * without forking it:
+ *
+ * - `route(request, environment)` runs first, after the `/__scheduled` refusal: a `Response` it
+ *   answers is the answer, `undefined` hands the request to the kit's routing. It owns its own
+ *   failures.
+ * - `scheduleName(name, environment)` admits a `cron:<name>` the kit's name grammar does not.
+ * - `scheduleTarget(name, environment)` is asked, for each name with a cron due, where to fire it:
+ *   `{ fetcher, deployment? }` fires there, `null` fires nothing, `undefined` lets the kit fire
+ *   the name's current deployment (and nothing for a name only `scheduleName` admits).
+ *
+ * The dispatcher is given no custom limits: a dispatcher's `limits.subRequests` would also count
+ * the deployments' own binding calls.
+ *
+ * @template {DispatcherEnvironment} Environment
+ * @param {{
+ *   route?: (request: Request, environment: Environment) => Promise<Response | undefined> | Response | undefined,
+ *   scheduleName?: (name: string, environment: Environment) => boolean,
+ *   scheduleTarget?: (
+ *     name: string,
+ *     environment: Environment,
+ *   ) => Promise<{ fetcher: import('./env.mjs').DispatchFetcher, deployment?: string } | null | undefined>,
+ * }} [extension]
+ */
+export function createDispatcher(extension = {}) {
+  return Object.freeze({
+    /**
+     * @param {Request} request
+     * @param {Environment} environment
+     * @returns {Promise<Response>}
+     */
+    async fetch(request, environment) {
+      const url = new URL(request.url)
+      // Only the cron fan-out reaches a deployment's schedule endpoint, never the public.
+      if (isSchedulePath(url.pathname)) return new Response('not found', { status: 404 })
+      if (extension.route !== undefined) {
+        const routed = await extension.route(request, environment)
+        if (routed !== undefined) return routed
+      }
+      const name = url.hostname.split('.')[0] ?? ''
+      if (isDeploymentLabel(name)) return dispatchDeployment(request, environment, name)
+      if (isServiceName(name)) return dispatchService(request, environment, name)
+      return missingServiceResponse(request, name)
+    },
+
+    /**
+     * @param {{ scheduledTime?: number }} controller
+     * @param {Environment} environment
+     * @returns {Promise<void>}
+     */
+    async scheduled(controller, environment) {
+      await fanOutSchedules(controller, environment, extension)
+    },
+  })
+}

package/dist/hosting/dispatcher/env.d.mts

@@ -0,0 +1,51 @@
+/** What a dispatch namespace binding's `get(name)` answers: the script's fetcher. */
+export interface DispatchFetcher {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>
+}
+
+/** A dispatch namespace binding (`DEPLOYMENTS`, or one a consumer binds beside it). */
+export interface DispatchNamespaceBinding {
+  get(name: string): DispatchFetcher
+}
+
+export interface ScheduleKey {
+  readonly name: string
+}
+
+export type SchedulePage =
+  | { readonly keys: readonly ScheduleKey[]; readonly list_complete: true }
+  | {
+      readonly keys: readonly ScheduleKey[]
+      readonly list_complete: false
+      readonly cursor: string
+    }
+
+/** The routing KV binding (`SCHEDULES`): the dispatcher only reads it. */
+export interface RoutingKvBinding {
+  get(key: string): Promise<string | null>
+  /** Read for the record endpoint only: a record's bytes and the metadata it was written with. */
+  getWithMetadata(
+    key: string,
+    type: 'arrayBuffer',
+  ): Promise<{ readonly value: ArrayBuffer | null; readonly metadata: unknown }>
+  list(options: { readonly prefix: string; readonly cursor?: string }): Promise<SchedulePage>
+}
+
+/** The calls dataset binding (`CALLS`), optional: one data point `{ indexes: [label] }` per call. */
+export interface CallsBinding {
+  writeDataPoint(point: { readonly indexes: readonly string[] }): void
+}
+
+/** The bindings the kit's dispatcher reads; a consumer's extension may read more. */
+export interface DispatcherEnvironment {
+  readonly DEPLOYMENTS: DispatchNamespaceBinding
+  readonly SCHEDULES: RoutingKvBinding
+  readonly CALLS?: CallsBinding
+}
+
+/** The bindings the cron fan-out reads. */
+export type ScheduleEnvironment = Pick<DispatcherEnvironment, 'DEPLOYMENTS' | 'SCHEDULES'>
+
+export interface ScheduleController {
+  readonly scheduledTime?: number
+}

package/dist/hosting/dispatcher/failure.d.mts

@@ -0,0 +1,4 @@
+/** The message of a failure, as the dispatcher logs it. */
+export function errorText(cause: unknown): string
+/** Whether a dispatch namespace refused a script it does not hold (`Worker not found.`). */
+export function scriptMissing(cause: unknown): boolean

package/dist/hosting/dispatcher/failure.mjs

@@ -0,0 +1,15 @@
+// @ts-check
+
+/** @param {unknown} cause */
+export function errorText(cause) {
+  return cause instanceof Error ? cause.message : String(cause)
+}
+
+/**
+ * Whether a dispatch namespace refused a script it does not hold. Cloudflare rejects
+ * `get(<absent>).fetch()` with `Error: Worker not found.`
+ * @param {unknown} cause
+ */
+export function scriptMissing(cause) {
+  return /not found|could not find|no such/iu.test(errorText(cause))
+}

package/dist/hosting/dispatcher/index.d.mts

@@ -0,0 +1,4 @@
+import type { Dispatcher } from './dispatcher.mjs'
+
+declare const dispatcher: Dispatcher
+export default dispatcher

package/dist/hosting/dispatcher/index.mjs

@@ -0,0 +1,10 @@
+import { createDispatcher } from './dispatcher.mjs'
+
+// @ts-check
+
+/**
+ * The kit's dispatcher with no extension: the main module (`index.mjs`) `dispatcherModules()`
+ * uploads. A consumer with routing of its own uploads its own `index.mjs` instead, which imports
+ * `./dispatcher.mjs` and exports `createDispatcher(extension)` as its default.
+ */
+export default createDispatcher()

package/dist/hosting/dispatcher/modules.d.ts

@@ -0,0 +1,25 @@
+/** One module of the dispatcher Worker upload. */
+export interface DispatcherModule {
+    /** The module name the Worker imports it by (`index.mjs` is the main module). */
+    readonly name: string;
+    readonly bytes: Uint8Array;
+    /** The multipart type Cloudflare reads the module as. */
+    readonly type: 'application/javascript+module';
+}
+/** The main module every dispatcher upload names. */
+export declare const DISPATCHER_MAIN_MODULE = "index.mjs";
+/**
+ * The kit's dispatcher modules, under the names they import each other by. They are plain ES
+ * modules shipped with the package (`dist/hosting/dispatcher/*.mjs`) and uploaded as they are.
+ */
+export declare const DISPATCHER_MODULE_NAMES: readonly ["index.mjs", "dispatcher.mjs", "deployments.mjs", "services.mjs", "failure.mjs", "cron.mjs"];
+/**
+ * The modules of one dispatcher upload: the kit's, read from the package, with `extra` added or
+ * replacing a kit module of the same name. A consumer with routing of its own supplies its own
+ * `index.mjs`, which imports `./dispatcher.mjs` by that relative name and exports
+ * `createDispatcher(extension)` as its default, plus any module that one imports.
+ */
+export declare function dispatcherModules(extra?: readonly {
+    readonly name: string;
+    readonly bytes: Uint8Array;
+}[]): Promise<readonly DispatcherModule[]>;

package/dist/hosting/dispatcher/modules.js

@@ -0,0 +1,56 @@
+/** The main module every dispatcher upload names. */
+export const DISPATCHER_MAIN_MODULE = 'index.mjs';
+/**
+ * The kit's dispatcher modules, under the names they import each other by. They are plain ES
+ * modules shipped with the package (`dist/hosting/dispatcher/*.mjs`) and uploaded as they are.
+ */
+export const DISPATCHER_MODULE_NAMES = Object.freeze([
+    'index.mjs',
+    'dispatcher.mjs',
+    'deployments.mjs',
+    'services.mjs',
+    'failure.mjs',
+    'cron.mjs',
+]);
+/**
+ * The modules of one dispatcher upload: the kit's, read from the package, with `extra` added or
+ * replacing a kit module of the same name. A consumer with routing of its own supplies its own
+ * `index.mjs`, which imports `./dispatcher.mjs` by that relative name and exports
+ * `createDispatcher(extension)` as its default, plus any module that one imports.
+ */
+export async function dispatcherModules(extra = []) {
+    const names = new Set();
+    for (const module of extra) {
+        if (!/^[A-Za-z0-9_][A-Za-z0-9_./-]*\.mjs$/u.test(module.name) || module.name.includes('..')) {
+            throw new TypeError(`Dispatcher module name ${module.name} is invalid.`);
+        }
+        if (names.has(module.name))
+            throw new TypeError(`Dispatcher module ${module.name} repeats.`);
+        names.add(module.name);
+    }
+    const kit = await Promise.all(DISPATCHER_MODULE_NAMES.filter((name) => !names.has(name)).map(async (name) => ({
+        name,
+        bytes: await readModule(name),
+    })));
+    const all = [...kit, ...extra];
+    // The main module first, as Cloudflare's own uploads list it.
+    all.sort((left, right) => Number(right.name === DISPATCHER_MAIN_MODULE) - Number(left.name === DISPATCHER_MAIN_MODULE));
+    return Object.freeze(all.map((module) => Object.freeze({
+        name: module.name,
+        bytes: module.bytes,
+        type: 'application/javascript+module',
+    })));
+}
+/**
+ * Read one kit module beside this one. Node's file system is reached through
+ * `process.getBuiltinModule`, never an import: the rest of the kit runs in a Worker, and a bundler
+ * must not see a `node:` module through it.
+ */
+async function readModule(name) {
+    const host = globalThis.process;
+    const fs = host?.getBuiltinModule?.('node:fs/promises');
+    if (fs === undefined) {
+        throw new TypeError('Reading the dispatcher modules needs Node.js (provisioning runs in Node).');
+    }
+    return new Uint8Array(await fs.readFile(new URL(`./${name}`, import.meta.url)));
+}

package/dist/hosting/dispatcher/services.d.mts

@@ -0,0 +1,28 @@
+import type { DispatcherExtension } from './dispatcher.mjs'
+import type { DispatcherEnvironment, ScheduleController, ScheduleEnvironment } from './env.mjs'
+
+/** Whether a host label is a line name (≤ 40 characters, never a deployment label). */
+export function isServiceName(name: string): boolean
+/** Route one request to the deployment `current:<name>` names. */
+export function dispatchService(
+  request: Request,
+  environment: DispatcherEnvironment,
+  service: string,
+): Promise<Response>
+/** 404 `no such service: <name>` (no-store), or the 503 5001 envelope on `/invoke`. */
+export function missingServiceResponse(request: Request, service: string): Response
+/** Fire every due `cron:<name>` on its current deployment, or on an extension's target. */
+export function fanOutSchedules<Environment extends ScheduleEnvironment>(
+  controller: ScheduleController,
+  environment: Environment,
+  extension?: Pick<
+    DispatcherExtension<Environment & DispatcherEnvironment>,
+    'scheduleName' | 'scheduleTarget'
+  >,
+): Promise<void>
+/** Run one bounded sliding-window fan-out. */
+export function pool<Value>(
+  items: readonly Value[],
+  limit: number,
+  operation: (value: Value) => void | Promise<void>,
+): Promise<void>