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

package/dist/hosting/client.d.ts

@@ -0,0 +1,144 @@
+/** Cloudflare's REST API. The kit calls it directly: Wrangler has no create-only upload. */
+export declare const CLOUDFLARE_API_BASE = "https://api.cloudflare.com/client/v4";
+/**
+ * How the client waits out Cloudflare rate limits (HTTP 429) before failing as `unavailable`.
+ * Cloudflare refuses a rate-limited request before acting on it, so resending is always safe.
+ */
+export interface RateLimitPolicy {
+    /** Rate-limited requests resent, each after the provider's `Retry-After` (else 1 s, doubling). */
+    readonly retries: number;
+    /** Longest single wait; a later `Retry-After` fails at once as `unavailable`. */
+    readonly maximumWaitMs: number;
+}
+/** A deploy's policy: three resends, none waiting more than 10 s. */
+export declare const DEFAULT_RATE_LIMIT: RateLimitPolicy;
+/**
+ * An operator command's policy: it has no deadline, so it waits out the five minutes Cloudflare
+ * blocks a user (the token owner) that went over its API limit.
+ */
+export declare const OPERATOR_RATE_LIMIT: RateLimitPolicy;
+export interface CloudflareClientOptions {
+    readonly accountId: string;
+    /** The API token, sent only to `base`; never logged, never part of an error. */
+    readonly token: string;
+    /** Default: the global `fetch`. With another one, `base` may name any host (a test fake). */
+    readonly fetch?: typeof fetch;
+    /** Default `CLOUDFLARE_API_BASE`; without `fetch`, only api.cloudflare.com or a loopback host. */
+    readonly base?: string;
+    /** Cancels every request and wait; a cancelled call rejects with the signal's reason. */
+    readonly signal?: AbortSignal;
+    /** An absolute instant (epoch ms) no request or rate-limit wait outlives. */
+    readonly deadline?: number;
+    /** Per-request timeout; multipart uploads get at least 120 s. Default 30 s. */
+    readonly timeoutMs?: number;
+    /** Default `DEFAULT_RATE_LIMIT`; `false` fails a rate-limited request at once. */
+    readonly rateLimit?: RateLimitPolicy | false;
+    /** Wait between rate-limited attempts; replaceable in tests. */
+    readonly pause?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** The clock `Retry-After` dates and the deadline are read on. */
+    readonly now?: () => number;
+}
+/** What a failure says about the request: whether to fix it, retry it, or treat it as absent. */
+export type CloudflareFailureKind = 
+/** 404: the resource does not exist. */
+'not_found'
+/** 401/403: the token lacks the permission. */
+ | 'unauthorized'
+/** Another 4xx: the request is refused as it is (412 for a create-only upload over a script). */
+ | 'invalid'
+/** 5xx, 429, a network failure or a timeout: the request may or may not have been applied. */
+ | 'unavailable'
+/** A success Cloudflare answered in a shape the kit does not admit. */
+ | 'upstream';
+/**
+ * A Cloudflare API refusal or failure. `status` is the HTTP status (absent when no response came
+ * back); `codes` are the error codes of Cloudflare's envelope (10018 for a create-only upload over
+ * an existing script). The message names the operation, never an account, script, key or value.
+ */
+export declare class CloudflareApiError extends Error {
+    readonly name = "CloudflareApiError";
+    readonly kind: CloudflareFailureKind;
+    readonly status: number | undefined;
+    readonly codes: readonly number[];
+    constructor(kind: CloudflareFailureKind, message: string, status?: number, codes?: readonly number[], options?: {
+        readonly cause?: unknown;
+    });
+}
+/** One page of a listing, as Cloudflare's `result_info` reports it. */
+export interface CloudflarePage {
+    readonly result: unknown;
+    readonly cursor?: string;
+    readonly page?: number;
+    readonly totalPages?: number;
+}
+/**
+ * The Cloudflare account API the hosting kit calls: dispatch namespaces and their scripts, account
+ * Workers, Workers KV, zones' DNS records and Worker routes. It runs wherever `fetch` does (Node or
+ * a Worker), reads bounded bodies, waits out rate limits by policy and turns every failure into a
+ * `CloudflareApiError`. Responses are never followed across redirects.
+ */
+export declare class CloudflareClient {
+    readonly accountId: string;
+    private readonly token;
+    private readonly fetcher;
+    private readonly base;
+    private readonly signal;
+    private readonly deadline;
+    private readonly timeoutMs;
+    private readonly rateLimit;
+    private readonly pause;
+    private readonly now;
+    constructor(options: CloudflareClientOptions);
+    /** `/accounts/<account><path>`. */
+    account(path: string): string;
+    /** `/zones/<zone><path>`. */
+    zone(zoneId: string, path: string): string;
+    /** Send a JSON request (or none) and return the envelope's `result`. */
+    json(method: string, path: string, body?: unknown): Promise<unknown>;
+    /** Send an effect whose success may answer an envelope or no body at all. */
+    effect(method: string, path: string, body?: unknown): Promise<void>;
+    /** One page of a JSON listing, its page evidence admitted. */
+    page(path: string): Promise<CloudflarePage>;
+    /**
+     * Every entry of a cursor-paged listing (`?cursor=`), across all of its pages. `path` may carry a
+     * query already. A cursor that repeats fails: the listing would never end.
+     */
+    cursorList(path: string): Promise<readonly unknown[]>;
+    /**
+     * Every entry of a numbered listing (`?per_page=&page=`), across all of its pages, stopping at
+     * the first page `found` matches (when given). A page that is not the one asked, or a total that
+     * changes between pages, fails.
+     */
+    pagedList(path: string, found?: (entry: unknown) => boolean, perPage?: number): Promise<readonly unknown[]>;
+    /**
+     * Send a multipart form (a script upload, an asset bucket) and return the envelope's `result`.
+     * `bearer` replaces the API token (an asset upload session's token).
+     */
+    form(method: string, path: string, body: FormData, options?: {
+        readonly bearer?: string;
+        readonly headers?: Readonly<Record<string, string>>;
+    }): Promise<unknown>;
+    /**
+     * A raw text request, for KV values: the response body as text, or undefined when a GET or a
+     * DELETE answers 404. Bodies are bounded to 1 MiB.
+     */
+    text(method: string, path: string, body?: {
+        readonly text: string;
+        readonly contentType: string;
+    }): Promise<string | undefined>;
+    /**
+     * A raw GET of bytes, for a KV value whose bytes are its meaning (a deployment record): the
+     * response body, or undefined when it answers 404. Bodies are bounded to 1 MiB.
+     */
+    bytes(path: string): Promise<Uint8Array | undefined>;
+    private send;
+    private request;
+    /** The request timeout, bounded by the deadline and the caller's cancellation. */
+    private requestSignal;
+    /** The wait before resending a rate-limited request, or undefined when its response stands. */
+    private rateLimitWait;
+    private read;
+    private unavailable;
+}
+/** Whether a failure is Cloudflare saying the resource does not exist. */
+export declare function isNotFound(cause: unknown): boolean;

package/dist/hosting/client.js

@@ -0,0 +1,491 @@
+import { retryAfterMs } from './retry-after.js';
+import { wait } from './time.js';
+/** Cloudflare's REST API. The kit calls it directly: Wrangler has no create-only upload. */
+export const CLOUDFLARE_API_BASE = 'https://api.cloudflare.com/client/v4';
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** A multipart upload (a script, an asset bucket) may take longer than any other call. */
+const FORM_TIMEOUT_FLOOR_MS = 120_000;
+const MAXIMUM_JSON_RESPONSE_BYTES = 8 * 1024 * 1024;
+const MAXIMUM_TEXT_RESPONSE_BYTES = 1024 * 1024;
+/** Without `Retry-After`, a rate-limited resend backs off from one second, doubling. */
+const RATE_LIMIT_BACKOFF_MS = 1_000;
+/** The most entries one page of a numbered listing asks for, as Cloudflare caps KV namespaces. */
+const PAGE_SIZE = 1_000;
+/** A deploy's policy: three resends, none waiting more than 10 s. */
+export const DEFAULT_RATE_LIMIT = Object.freeze({
+    retries: 3,
+    maximumWaitMs: 10_000,
+});
+/**
+ * An operator command's policy: it has no deadline, so it waits out the five minutes Cloudflare
+ * blocks a user (the token owner) that went over its API limit.
+ */
+export const OPERATOR_RATE_LIMIT = Object.freeze({
+    retries: 5,
+    maximumWaitMs: 300_000,
+});
+/**
+ * A Cloudflare API refusal or failure. `status` is the HTTP status (absent when no response came
+ * back); `codes` are the error codes of Cloudflare's envelope (10018 for a create-only upload over
+ * an existing script). The message names the operation, never an account, script, key or value.
+ */
+export class CloudflareApiError extends Error {
+    name = 'CloudflareApiError';
+    kind;
+    status;
+    codes;
+    constructor(kind, message, status, codes = [], options) {
+        super(message, options);
+        this.kind = kind;
+        this.status = status;
+        this.codes = Object.freeze([...codes]);
+    }
+}
+/**
+ * The Cloudflare account API the hosting kit calls: dispatch namespaces and their scripts, account
+ * Workers, Workers KV, zones' DNS records and Worker routes. It runs wherever `fetch` does (Node or
+ * a Worker), reads bounded bodies, waits out rate limits by policy and turns every failure into a
+ * `CloudflareApiError`. Responses are never followed across redirects.
+ */
+export class CloudflareClient {
+    accountId;
+    token;
+    fetcher;
+    base;
+    signal;
+    deadline;
+    timeoutMs;
+    rateLimit;
+    pause;
+    now;
+    constructor(options) {
+        if (!stable(options.accountId))
+            invalid('Cloudflare accountId is required.');
+        if (!stable(options.token)) {
+            throw new CloudflareApiError('unauthorized', 'Cloudflare API token is required.');
+        }
+        this.accountId = options.accountId;
+        this.token = options.token;
+        this.base = (options.base ?? CLOUDFLARE_API_BASE).replace(/\/+$/u, '');
+        if (options.fetch === undefined && !allowedHost(this.base)) {
+            invalid('Cloudflare API base must be api.cloudflare.com or a loopback host.');
+        }
+        this.fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+        this.signal = options.signal;
+        this.deadline = options.deadline;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        if (!positiveInteger(this.timeoutMs))
+            invalid('Cloudflare timeoutMs must be positive.');
+        const rateLimit = options.rateLimit ?? DEFAULT_RATE_LIMIT;
+        if (rateLimit !== false &&
+            (!Number.isSafeInteger(rateLimit.retries) ||
+                rateLimit.retries < 0 ||
+                !positiveInteger(rateLimit.maximumWaitMs))) {
+            invalid('Cloudflare rateLimit needs non-negative retries and a positive maximumWaitMs.');
+        }
+        this.rateLimit = rateLimit;
+        this.pause = options.pause ?? wait;
+        this.now = options.now ?? Date.now;
+    }
+    /** `/accounts/<account><path>`. */
+    account(path) {
+        return `/accounts/${encodeURIComponent(this.accountId)}${path}`;
+    }
+    /** `/zones/<zone><path>`. */
+    zone(zoneId, path) {
+        if (!stable(zoneId))
+            invalid('Cloudflare zone id is required.');
+        return `/zones/${encodeURIComponent(zoneId)}${path}`;
+    }
+    /** Send a JSON request (or none) and return the envelope's `result`. */
+    async json(method, path, body) {
+        return (await this.send(method, path, jsonBody(body))).result;
+    }
+    /** Send an effect whose success may answer an envelope or no body at all. */
+    async effect(method, path, body) {
+        await this.send(method, path, jsonBody(body), true);
+    }
+    /** One page of a JSON listing, its page evidence admitted. */
+    async page(path) {
+        const envelope = await this.send('GET', path, {});
+        const info = envelope.resultInfo;
+        if (info !== undefined && info !== null && !isRecord(info))
+            upstream('page evidence');
+        const cursor = isRecord(info) ? info.cursor : undefined;
+        const page = isRecord(info) ? info.page : undefined;
+        const totalPages = isRecord(info) ? info.total_pages : undefined;
+        if (cursor !== undefined && cursor !== null && typeof cursor !== 'string') {
+            upstream('page cursor');
+        }
+        if (page !== undefined && !positiveInteger(page))
+            upstream('page evidence');
+        if (totalPages !== undefined && !Number.isSafeInteger(totalPages))
+            upstream('page evidence');
+        return Object.freeze({
+            result: envelope.result,
+            ...(typeof cursor === 'string' && cursor.length > 0 ? { cursor } : {}),
+            ...(page === undefined ? {} : { page: page }),
+            ...(totalPages === undefined ? {} : { totalPages: totalPages }),
+        });
+    }
+    /**
+     * Every entry of a cursor-paged listing (`?cursor=`), across all of its pages. `path` may carry a
+     * query already. A cursor that repeats fails: the listing would never end.
+     */
+    async cursorList(path) {
+        const entries = [];
+        const seen = new Set();
+        let cursor;
+        for (;;) {
+            const separator = path.includes('?') ? '&' : '?';
+            const page = await this.page(cursor === undefined ? path : `${path}${separator}cursor=${encodeURIComponent(cursor)}`);
+            if (!Array.isArray(page.result))
+                upstream('listing');
+            entries.push(...page.result);
+            if (page.cursor === undefined)
+                return Object.freeze(entries);
+            if (seen.has(page.cursor)) {
+                throw new CloudflareApiError('upstream', 'Cloudflare repeated a listing cursor.');
+            }
+            seen.add(page.cursor);
+            cursor = page.cursor;
+        }
+    }
+    /**
+     * Every entry of a numbered listing (`?per_page=&page=`), across all of its pages, stopping at
+     * the first page `found` matches (when given). A page that is not the one asked, or a total that
+     * changes between pages, fails.
+     */
+    async pagedList(path, found, perPage = PAGE_SIZE) {
+        const entries = [];
+        const separator = path.includes('?') ? '&' : '?';
+        let total;
+        for (let number = 1;; number += 1) {
+            const page = await this.page(`${path}${separator}per_page=${perPage}&page=${number}`);
+            if (!Array.isArray(page.result))
+                upstream('listing');
+            if ((page.page !== undefined && page.page !== number) ||
+                (total !== undefined && page.totalPages !== undefined && page.totalPages !== total)) {
+                upstream('page evidence');
+            }
+            total = page.totalPages ?? total;
+            entries.push(...page.result);
+            if (found !== undefined && page.result.some(found))
+                return Object.freeze(entries);
+            if (page.totalPages === undefined || number >= page.totalPages) {
+                return Object.freeze(entries);
+            }
+        }
+    }
+    /**
+     * Send a multipart form (a script upload, an asset bucket) and return the envelope's `result`.
+     * `bearer` replaces the API token (an asset upload session's token).
+     */
+    async form(method, path, body, options = {}) {
+        return (await this.send(method, path, {
+            body,
+            ...(options.bearer === undefined ? {} : { bearer: options.bearer }),
+            ...(options.headers === undefined ? {} : { headers: options.headers }),
+            timeoutMs: Math.max(this.timeoutMs, FORM_TIMEOUT_FLOOR_MS),
+        })).result;
+    }
+    /**
+     * A raw text request, for KV values: the response body as text, or undefined when a GET or a
+     * DELETE answers 404. Bodies are bounded to 1 MiB.
+     */
+    async text(method, path, body) {
+        const response = await this.request(method, path, body === undefined ? {} : { body: body.text, headers: { 'content-type': body.contentType } });
+        if (response.status === 404 && (method === 'GET' || method === 'DELETE')) {
+            await discard(response);
+            return undefined;
+        }
+        const text = await this.read(response, MAXIMUM_TEXT_RESPONSE_BYTES, method, path);
+        if (!response.ok)
+            throw failure(method, path, response.status, decodeEnvelope(text));
+        return text;
+    }
+    /**
+     * A raw GET of bytes, for a KV value whose bytes are its meaning (a deployment record): the
+     * response body, or undefined when it answers 404. Bodies are bounded to 1 MiB.
+     */
+    async bytes(path) {
+        const response = await this.request('GET', path, {});
+        if (response.status === 404) {
+            await discard(response);
+            return undefined;
+        }
+        let bytes;
+        try {
+            bytes = await boundedBytes(response, MAXIMUM_TEXT_RESPONSE_BYTES);
+        }
+        catch (cause) {
+            if (cause instanceof CloudflareApiError)
+                throw cause;
+            this.unavailable('GET', path, cause);
+        }
+        if (!response.ok) {
+            throw failure('GET', path, response.status, decodeEnvelope(new TextDecoder().decode(bytes)));
+        }
+        return bytes;
+    }
+    async send(method, path, input, allowEmptySuccess = false) {
+        const response = await this.request(method, path, input);
+        const text = await this.read(response, MAXIMUM_JSON_RESPONSE_BYTES, method, path);
+        const envelope = decodeEnvelope(text);
+        if (!response.ok || envelope?.success === false) {
+            throw failure(method, path, response.status, envelope);
+        }
+        if (envelope === undefined) {
+            if (allowEmptySuccess && text.length === 0) {
+                return { success: true, errors: [], result: null };
+            }
+            throw new CloudflareApiError('upstream', `Cloudflare ${method} ${describe(path)} returned no JSON envelope.`, response.status);
+        }
+        return envelope;
+    }
+    async request(method, path, input) {
+        if (!path.startsWith('/accounts/') && !path.startsWith('/zones')) {
+            throw new TypeError('Cloudflare API path is invalid.');
+        }
+        for (let attempt = 0;; attempt += 1) {
+            this.signal?.throwIfAborted();
+            let response;
+            try {
+                response = await this.fetcher(`${this.base}${path}`, {
+                    method,
+                    headers: { authorization: `Bearer ${input.bearer ?? this.token}`, ...input.headers },
+                    ...(input.body === undefined ? {} : { body: input.body }),
+                    // Workers admit only `follow` and `manual`; a redirect is a failure either way.
+                    redirect: 'manual',
+                    signal: this.requestSignal(input.timeoutMs ?? this.timeoutMs),
+                });
+            }
+            catch (cause) {
+                this.unavailable(method, path, cause);
+            }
+            const waitMs = this.rateLimitWait(response, attempt);
+            if (waitMs === undefined)
+                return response;
+            await discard(response);
+            try {
+                await this.pause(waitMs, this.signal);
+            }
+            catch (cause) {
+                this.unavailable(method, path, cause);
+            }
+        }
+    }
+    /** The request timeout, bounded by the deadline and the caller's cancellation. */
+    requestSignal(timeoutMs) {
+        const bounded = this.deadline === undefined
+            ? timeoutMs
+            : Math.min(timeoutMs, Math.max(1, Math.ceil(this.deadline - this.now())));
+        const timeout = AbortSignal.timeout(bounded);
+        return this.signal === undefined ? timeout : AbortSignal.any([this.signal, timeout]);
+    }
+    /** The wait before resending a rate-limited request, or undefined when its response stands. */
+    rateLimitWait(response, attempt) {
+        const policy = this.rateLimit;
+        if (response.status !== 429 || policy === false || attempt >= policy.retries)
+            return undefined;
+        const waitMs = retryAfterMs(response.headers.get('retry-after'), this.now()) ??
+            Math.min(policy.maximumWaitMs, RATE_LIMIT_BACKOFF_MS * 2 ** attempt);
+        if (waitMs > policy.maximumWaitMs)
+            return undefined;
+        if (this.deadline !== undefined && this.now() + waitMs >= this.deadline)
+            return undefined;
+        return waitMs;
+    }
+    async read(response, maximumBytes, method, path) {
+        try {
+            return await boundedText(response, maximumBytes);
+        }
+        catch (cause) {
+            if (cause instanceof CloudflareApiError)
+                throw cause;
+            this.unavailable(method, path, cause);
+        }
+    }
+    unavailable(method, path, cause) {
+        if (this.signal?.aborted === true)
+            throw this.signal.reason ?? cause;
+        throw new CloudflareApiError('unavailable', `Cloudflare ${method} ${describe(path)} is unavailable.`, undefined, [], { cause });
+    }
+}
+/** Whether a failure is Cloudflare saying the resource does not exist. */
+export function isNotFound(cause) {
+    return cause instanceof CloudflareApiError && cause.kind === 'not_found';
+}
+function jsonBody(body) {
+    return body === undefined
+        ? {}
+        : { body: JSON.stringify(body), headers: { 'content-type': 'application/json' } };
+}
+function decodeEnvelope(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value) || typeof value.success !== 'boolean')
+        return undefined;
+    const errors = value.errors;
+    if (errors !== undefined && errors !== null && !Array.isArray(errors))
+        return undefined;
+    const admitted = [];
+    for (const error of errors ?? []) {
+        if (!isRecord(error))
+            return undefined;
+        admitted.push({ code: error.code, message: error.message });
+    }
+    return Object.freeze({
+        success: value.success,
+        errors: Object.freeze(admitted),
+        result: value.result,
+        ...(Object.hasOwn(value, 'result_info') ? { resultInfo: value.result_info } : {}),
+    });
+}
+/** A Cloudflare failure, naming its error codes and messages but never a request body. */
+function failure(method, path, status, envelope) {
+    const errors = envelope?.errors ?? [];
+    const codes = errors
+        .map((error) => error.code)
+        .filter((code) => typeof code === 'number');
+    const detail = errors
+        .map((error) => error.message)
+        .filter((message) => typeof message === 'string')
+        .map((message) => (message.length <= 200 ? message : `${message.slice(0, 197)}...`))
+        .join('; ')
+        .replace(/\.$/u, '');
+    return new CloudflareApiError(kindOf(status), `Cloudflare ${method} ${describe(path)} failed with HTTP ${status}` +
+        `${codes.length > 0 ? ` [${codes.join(', ')}]` : ''}${detail === '' ? '' : `: ${detail}`}.`, status, codes);
+}
+function kindOf(status) {
+    if (status === 401 || status === 403)
+        return 'unauthorized';
+    if (status === 404)
+        return 'not_found';
+    // A rate limit refuses the caller's pace, never the request: retrying later succeeds.
+    if (status === 429 || status >= 500)
+        return 'unavailable';
+    if (status >= 400)
+        return 'invalid';
+    return 'upstream';
+}
+/** What a path addresses, without its account, zone, namespace, script or key names. */
+function describe(path) {
+    const route = path.split('?', 1)[0];
+    if (route.includes('/assets-upload-session'))
+        return 'asset upload session';
+    if (route.includes('/workers/assets/upload'))
+        return 'asset upload';
+    if (route.endsWith('/secrets'))
+        return 'script secret';
+    if (route.endsWith('/settings'))
+        return 'script settings';
+    if (route.endsWith('/subdomain'))
+        return 'workers.dev subdomain';
+    if (route.endsWith('/schedules'))
+        return 'script schedules';
+    if (route.includes('/dispatch/namespaces/') && route.includes('/scripts')) {
+        return 'namespace script';
+    }
+    if (route.includes('/dispatch/namespaces'))
+        return 'dispatch namespace';
+    if (route.includes('/workers/scripts'))
+        return 'Worker';
+    if (route.includes('/workers/domains'))
+        return 'Workers custom domain';
+    if (/\/storage\/kv\/namespaces\/[^/]+\/keys/u.test(route))
+        return 'KV keys';
+    if (/\/storage\/kv\/namespaces\/[^/]+\/values/u.test(route))
+        return 'KV value';
+    if (route.includes('/storage/kv/namespaces'))
+        return 'KV namespace';
+    if (route.includes('/dns_records'))
+        return 'DNS record';
+    if (route.includes('/workers/routes'))
+        return 'Worker route';
+    if (route.startsWith('/zones'))
+        return 'zone';
+    return 'request';
+}
+async function boundedText(response, maximumBytes) {
+    return new TextDecoder().decode(await boundedBytes(response, maximumBytes));
+}
+async function boundedBytes(response, maximumBytes) {
+    const declared = response.headers.get('content-length');
+    if (declared !== null) {
+        const bytes = Number(declared);
+        if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > maximumBytes) {
+            await discard(response);
+            throw new CloudflareApiError('upstream', 'Cloudflare response body is too large.');
+        }
+    }
+    if (response.body === null)
+        return new Uint8Array();
+    const reader = response.body.getReader();
+    const parts = [];
+    let size = 0;
+    for (;;) {
+        const part = await reader.read();
+        if (part.done)
+            break;
+        size += part.value.byteLength;
+        if (size > maximumBytes) {
+            try {
+                await reader.cancel('Cloudflare response body is too large.');
+            }
+            catch {
+                // Cancellation is cleanup; it cannot replace the overflow failure.
+            }
+            throw new CloudflareApiError('upstream', 'Cloudflare response body is too large.');
+        }
+        parts.push(part.value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const part of parts) {
+        bytes.set(part, offset);
+        offset += part.byteLength;
+    }
+    return bytes;
+}
+function allowedHost(base) {
+    try {
+        const host = new URL(base).hostname.toLowerCase();
+        return (host === 'api.cloudflare.com' ||
+            host === 'localhost' ||
+            host === '127.0.0.1' ||
+            host === '[::1]' ||
+            host.endsWith('.localhost'));
+    }
+    catch {
+        return false;
+    }
+}
+async function discard(response) {
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        // Releasing a response is cleanup; it never decides an outcome.
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function stable(value) {
+    return typeof value === 'string' && value.length > 0 && value.trim() === value;
+}
+function positiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
+function invalid(message) {
+    throw new CloudflareApiError('invalid', message);
+}
+function upstream(what) {
+    throw new CloudflareApiError('upstream', `Cloudflare returned invalid ${what}.`);
+}

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

@@ -0,0 +1,10 @@
+export function isUtcCron(expression: unknown): expression is string
+export function canonicalUtcCrons(input: unknown): readonly string[] | undefined
+export function matches(expression: string, date: Date): boolean
+export function fieldMatches(
+  field: string,
+  value: number,
+  minimum: number,
+  maximum: number,
+  names?: Readonly<Record<string, number>>,
+): boolean