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

package/dist/hosting/readiness.js

@@ -0,0 +1,82 @@
+import { wait } from './time.js';
+/** The response header the generated Worker answers its provider version in. */
+export const VERSION_HEADER = 'x-astrale-worker-version';
+/** Reach a deployment through its public URL, with `fetch`. */
+export function publicFetcher(fetcher) {
+    return (request) => fetcher(request);
+}
+/** Reach one deployment through a dispatch namespace binding (`env.<BINDING>.get(label)`). */
+export function dispatchFetcher(namespace, label) {
+    return (request) => namespace.get(label).fetch(request);
+}
+/**
+ * Wait until a deployment answers from exactly the provider version this deploy made: every
+ * `check` passes on responses carrying `x-astrale-worker-version` equal to `version` (the UUID
+ * form of the script's `deployment_id`). A response from another version is propagation still in
+ * progress; any failure of `check` is retried every `retryMs` until `timeoutMs`. Requests never
+ * leave `url`'s origin, never follow redirects and send no version override: a dispatcher always
+ * serves a script's current version.
+ *
+ * `check` defaults to: every path of `paths` (default `/`) answers 200. A deployer that verifies
+ * the release it sealed passes its own check over the versioned fetch it receives.
+ */
+export async function waitForReadiness(input) {
+    const origin = new URL(input.url);
+    if (origin.protocol !== 'https:' || origin.origin !== input.url.replace(/\/$/u, '')) {
+        throw new TypeError('Deployment readiness requires one exact HTTPS origin.');
+    }
+    const now = input.now ?? Date.now;
+    const pause = input.pause ?? wait;
+    const deadline = now() + input.timeoutMs;
+    const versioned = versionFetch(origin.origin, input.version, input.fetcher);
+    const check = input.check ?? pathsAnswer(input.paths ?? ['/']);
+    let last;
+    for (;;) {
+        input.signal?.throwIfAborted();
+        const attempt = AbortSignal.timeout(input.attemptTimeoutMs ?? 5_000);
+        try {
+            await check(versioned, input.signal === undefined ? attempt : AbortSignal.any([input.signal, attempt]));
+            return;
+        }
+        catch (cause) {
+            input.signal?.throwIfAborted();
+            last = cause;
+        }
+        if (now() >= deadline)
+            break;
+        await pause(input.retryMs ?? 1_000, input.signal);
+    }
+    throw new Error(`The deployment did not serve from version ${input.version} within ` +
+        `${input.timeoutMs / 1_000} s.`, { cause: last });
+}
+/**
+ * A fetch that stays on the deployment origin and admits only responses of the expected provider
+ * version: a response of another version is refused, as propagation still in progress.
+ */
+export function versionFetch(origin, version, fetcher) {
+    const expected = new URL(origin).origin;
+    return async (input, init) => {
+        const request = input instanceof Request
+            ? new Request(input, { ...init, redirect: 'manual' })
+            : new Request(new URL(String(input), expected), { ...init, redirect: 'manual' });
+        if (new URL(request.url).origin !== expected) {
+            throw new TypeError('Deployment readiness cannot leave the deployment origin.');
+        }
+        const response = await fetcher(request);
+        if (response.headers.get(VERSION_HEADER) !== version) {
+            await response.body?.cancel();
+            throw new Error('The deployment answered from another provider version.');
+        }
+        return response;
+    };
+}
+function pathsAnswer(paths) {
+    return async (fetcher, signal) => {
+        for (const path of paths) {
+            const response = await fetcher(path, { method: 'GET', signal });
+            await response.body?.cancel();
+            if (response.status !== 200)
+                throw new Error(`${path} answered HTTP ${response.status}.`);
+        }
+    };
+}

package/dist/hosting/refusal.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Why the hosting kit refused before, or instead of, a write. A refusal is a decision about what
+ * the account holds, never a transport failure (`CloudflareApiError`): rerunning without changing
+ * the account or the request is refused again.
+ */
+export declare class HostingRefusal extends Error {
+    readonly name = "HostingRefusal";
+    readonly reason: 
+    /** The namespace's routing KV does not exist: provision the namespace first. */
+    'not-provisioned'
+    /** The label names another deployment's script or record; nothing was written. */
+     | 'deployment-conflict'
+    /** The label is withdrawn and is never served again. */
+     | 'deployment-retired'
+    /** A stored `record:` is not a record the kit publishes (media type, bytes, metadata). */
+     | 'record-invalid'
+    /** A stored `retirement:` holds another value than `withdrawn`. */
+     | 'retirement-invalid'
+    /** A `current:` value (stored or asked) is not a deployment of its name. */
+     | 'route-invalid'
+    /** A `cron:` value (stored or asked) is not distinct canonical UTC crons. */
+     | 'schedules-invalid'
+    /** Provisioning would take over what serves something else. */
+     | 'resource-conflict'
+    /** The API token cannot read what provisioning must observe first. */
+     | 'token-scope';
+    constructor(reason: HostingRefusal['reason'], message: string);
+}

package/dist/hosting/refusal.js

@@ -0,0 +1,13 @@
+/**
+ * Why the hosting kit refused before, or instead of, a write. A refusal is a decision about what
+ * the account holds, never a transport failure (`CloudflareApiError`): rerunning without changing
+ * the account or the request is refused again.
+ */
+export class HostingRefusal extends Error {
+    name = 'HostingRefusal';
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}

package/dist/hosting/retirement.d.ts

@@ -0,0 +1,69 @@
+import type { WorkerRecord } from '@astrale-os/sdk/deployment/worker';
+import type { CloudflareClient } from './client.js';
+import type { RoutingKv } from './kv.js';
+import type { NamespaceScript } from './script.js';
+import { WITHDRAWN } from './kv.js';
+/** The dispatcher's retirement probe path; it is never a call of the deployment. */
+export declare const RETIREMENT_PROBE_PATH = "/__services_retirement_probe__";
+/** How long Workers KV takes to carry a tombstone to every dispatcher. */
+export declare const RETIREMENT_PROPAGATION_MS = 65000;
+/** How long a caller waits before probing again when the dispatcher does not answer yet. */
+export declare const RETIREMENT_PROBE_RETRY_MS = 15000;
+/**
+ * Phase one of a retirement: write the tombstone `retirement:<label>` = `withdrawn`, unless it is
+ * already there, read back before it counts. From then on the dispatcher answers
+ * `DEPLOYMENT_RETIRED` to every call of the label, while its record endpoint keeps serving
+ * `record:<label>`. A withdrawal is permanent: nothing deletes the tombstone.
+ */
+export declare function markRetired(kv: RoutingKv, label: string): Promise<{
+    readonly previous: 'absent' | typeof WITHDRAWN;
+}>;
+/** The tombstone of a label: `withdrawn`, or undefined; any other value is refused. */
+export declare function readRetirement(kv: RoutingKv, label: string): Promise<typeof WITHDRAWN | undefined>;
+/**
+ * Whether the dispatcher answers `DEPLOYMENT_RETIRED` for the deployment at `url`, exactly as
+ * kernel-protocol defines it: 410, `x-astrale-deployment-retired: 1`, and the envelope naming the
+ * deployment origin. The probe path is never counted as a call. A failed probe answers false;
+ * only the caller's cancellation rejects.
+ */
+export declare function retirementVisible(input: {
+    readonly fetch: typeof fetch;
+    readonly url: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}): Promise<boolean>;
+/** Where phase two of a retirement stands. */
+export type RetirementCompletion = {
+    readonly kind: 'removed';
+} | {
+    readonly kind: 'propagating';
+    readonly retryAfterMs: number;
+} | {
+    readonly kind: 'conflict';
+    readonly message: string;
+};
+/**
+ * Phase two of a retirement: once the tombstone has propagated (`RETIREMENT_PROPAGATION_MS` after
+ * `retiredAt`, when the caller kept it) and the dispatcher answers `DEPLOYMENT_RETIRED` for the
+ * label (`probe`, usually `retirementVisible` through the public URL), delete its script, and with
+ * it the key bound to it; until then delete nothing and answer `propagating`. The record stays at
+ * `record:<label>`.
+ *
+ * The script is deleted only when it is the caller's deployment: a stored record must be the one
+ * the caller published (`record`: the same media type and bytes, or `null` for none) when the
+ * caller passes it, and the script must satisfy `owns` (its tags, its etag) when the caller passes
+ * it; otherwise nothing is deleted (`conflict`). An absent script is already removed. Rerunning
+ * converges.
+ */
+export declare function completeRetirement(input: {
+    readonly client: CloudflareClient;
+    readonly kv: RoutingKv;
+    readonly namespace: string;
+    readonly label: string;
+    readonly probe: () => Promise<boolean>;
+    readonly record?: WorkerRecord | null;
+    readonly owns?: (script: NamespaceScript) => boolean;
+    /** When the tombstone was written (epoch ms), if the caller keeps it. */
+    readonly retiredAt?: number;
+    readonly now?: () => number;
+}): Promise<RetirementCompletion>;

package/dist/hosting/retirement.js

@@ -0,0 +1,106 @@
+import { readRecord, sameRecord } from './activation.js';
+import { retirementKey, WITHDRAWN } from './kv.js';
+import { HostingRefusal } from './refusal.js';
+import { deleteScript, observeScript } from './script.js';
+/** The dispatcher's retirement probe path; it is never a call of the deployment. */
+export const RETIREMENT_PROBE_PATH = '/__services_retirement_probe__';
+/** How long Workers KV takes to carry a tombstone to every dispatcher. */
+export const RETIREMENT_PROPAGATION_MS = 65_000;
+/** How long a caller waits before probing again when the dispatcher does not answer yet. */
+export const RETIREMENT_PROBE_RETRY_MS = 15_000;
+const DEFAULT_PROBE_TIMEOUT_MS = 10_000;
+/**
+ * Phase one of a retirement: write the tombstone `retirement:<label>` = `withdrawn`, unless it is
+ * already there, read back before it counts. From then on the dispatcher answers
+ * `DEPLOYMENT_RETIRED` to every call of the label, while its record endpoint keeps serving
+ * `record:<label>`. A withdrawal is permanent: nothing deletes the tombstone.
+ */
+export async function markRetired(kv, label) {
+    if ((await readRetirement(kv, label)) === WITHDRAWN)
+        return Object.freeze({ previous: WITHDRAWN });
+    await kv.put(retirementKey(label), WITHDRAWN, 'text/plain');
+    return Object.freeze({ previous: 'absent' });
+}
+/** The tombstone of a label: `withdrawn`, or undefined; any other value is refused. */
+export async function readRetirement(kv, label) {
+    const value = await kv.get(retirementKey(label));
+    if (value === undefined || value === WITHDRAWN)
+        return value;
+    throw new HostingRefusal('retirement-invalid', `The tombstone of ${label} holds another value than ${WITHDRAWN}.`);
+}
+/**
+ * Whether the dispatcher answers `DEPLOYMENT_RETIRED` for the deployment at `url`, exactly as
+ * kernel-protocol defines it: 410, `x-astrale-deployment-retired: 1`, and the envelope naming the
+ * deployment origin. The probe path is never counted as a call. A failed probe answers false;
+ * only the caller's cancellation rejects.
+ */
+export async function retirementVisible(input) {
+    const deployment = new URL(input.url).origin;
+    const probe = new URL(RETIREMENT_PROBE_PATH, deployment);
+    probe.searchParams.set('retirement', Date.now().toString(36));
+    const timeout = AbortSignal.timeout(input.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS);
+    try {
+        const response = await input.fetch(probe, {
+            method: 'GET',
+            headers: { accept: 'application/json', 'cache-control': 'no-cache' },
+            redirect: 'manual',
+            signal: input.signal === undefined ? timeout : AbortSignal.any([input.signal, timeout]),
+        });
+        const text = await response.text();
+        if (response.status !== 410 || response.headers.get('x-astrale-deployment-retired') !== '1') {
+            return false;
+        }
+        const body = JSON.parse(text);
+        return (body.error?.code === 3002 &&
+            body.error.data?.code === 'DEPLOYMENT_RETIRED' &&
+            body.error.data.details?.deployment === deployment);
+    }
+    catch (cause) {
+        if (input.signal?.aborted === true)
+            throw input.signal.reason ?? cause;
+        return false;
+    }
+}
+/**
+ * Phase two of a retirement: once the tombstone has propagated (`RETIREMENT_PROPAGATION_MS` after
+ * `retiredAt`, when the caller kept it) and the dispatcher answers `DEPLOYMENT_RETIRED` for the
+ * label (`probe`, usually `retirementVisible` through the public URL), delete its script, and with
+ * it the key bound to it; until then delete nothing and answer `propagating`. The record stays at
+ * `record:<label>`.
+ *
+ * The script is deleted only when it is the caller's deployment: a stored record must be the one
+ * the caller published (`record`: the same media type and bytes, or `null` for none) when the
+ * caller passes it, and the script must satisfy `owns` (its tags, its etag) when the caller passes
+ * it; otherwise nothing is deleted (`conflict`). An absent script is already removed. Rerunning
+ * converges.
+ */
+export async function completeRetirement(input) {
+    const { client, label } = input;
+    if (input.record !== undefined) {
+        const published = await readRecord(input.kv, label);
+        if (published !== undefined && !sameRecord(published, input.record)) {
+            return conflict(`The record published for ${label} is not this deployment's.`);
+        }
+    }
+    const script = await observeScript(client, input.namespace, label);
+    if (script !== undefined && input.owns !== undefined && !input.owns(script)) {
+        return conflict(`The script ${label} is not this deployment's; nothing was deleted.`);
+    }
+    if (input.retiredAt !== undefined) {
+        const remaining = input.retiredAt + RETIREMENT_PROPAGATION_MS - (input.now ?? Date.now)();
+        if (remaining > 0)
+            return Object.freeze({ kind: 'propagating', retryAfterMs: remaining });
+    }
+    if (!(await input.probe())) {
+        return Object.freeze({ kind: 'propagating', retryAfterMs: RETIREMENT_PROBE_RETRY_MS });
+    }
+    if (script !== undefined)
+        await deleteScript(client, input.namespace, label);
+    return Object.freeze({ kind: 'removed' });
+}
+function conflict(message) {
+    return Object.freeze({
+        kind: 'conflict',
+        message: message.length <= 500 ? message : `${message.slice(0, 497)}...`,
+    });
+}

package/dist/hosting/retry-after.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The wait an RFC 9110 `Retry-After` states, in milliseconds: delay seconds or an HTTP-date in any
+ * of its three forms, as of `now`. Anything else states no wait (undefined). Delay seconds too
+ * large to count in milliseconds state an unbounded wait, which no policy admits.
+ */
+export declare function retryAfterMs(value: string | null, now: number): number | undefined;

package/dist/hosting/retry-after.js

@@ -0,0 +1,55 @@
+// RFC 9110 §5.6.7: a recipient accepts all three HTTP-date forms, each case-sensitive and in GMT.
+const HTTP_DATES = [
+    // IMF-fixdate: Sun, 06 Nov 1994 08:49:37 GMT
+    /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (?<day>\d{2}) (?<month>[A-Z][a-z]{2}) (?<year>\d{4}) (?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2}) GMT$/u,
+    // Obsolete RFC 850 form: Sunday, 06-Nov-94 08:49:37 GMT
+    /^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (?<day>\d{2})-(?<month>[A-Z][a-z]{2})-(?<year>\d{2}) (?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2}) GMT$/u,
+    // Obsolete asctime form: Sun Nov  6 08:49:37 1994
+    /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) (?<month>[A-Z][a-z]{2}) (?<day>\d{2}| \d) (?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2}) (?<year>\d{4})$/u,
+];
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/**
+ * The wait an RFC 9110 `Retry-After` states, in milliseconds: delay seconds or an HTTP-date in any
+ * of its three forms, as of `now`. Anything else states no wait (undefined). Delay seconds too
+ * large to count in milliseconds state an unbounded wait, which no policy admits.
+ */
+export function retryAfterMs(value, now) {
+    if (value === null)
+        return undefined;
+    const text = value.trim();
+    if (/^\d+$/u.test(text)) {
+        const waitMs = Number(text) * 1_000;
+        return Number.isSafeInteger(waitMs) ? waitMs : Number.POSITIVE_INFINITY;
+    }
+    const at = httpDate(text, now);
+    return at === undefined ? undefined : Math.max(0, at - now);
+}
+/** The instant an RFC 9110 HTTP-date names, or undefined when the text is not a real one. */
+function httpDate(text, now) {
+    const fields = HTTP_DATES.map((form) => form.exec(text)?.groups).find(Boolean);
+    if (fields === undefined)
+        return undefined;
+    const month = MONTHS.indexOf(fields.month);
+    const day = Number(fields.day);
+    const [hour, minute, second] = [fields.hour, fields.minute, fields.second].map(Number);
+    if (month < 0 || hour > 23 || minute > 59 || second > 60)
+        return undefined;
+    const year = fields.year.length === 2 ? rfc850Year(Number(fields.year), now) : Number(fields.year);
+    // setUTCFullYear keeps years below 100 literal, which Date.UTC would move to the 1900s.
+    const date = new Date(0);
+    date.setUTCFullYear(year, month, day);
+    if (date.getUTCDate() !== day)
+        return undefined;
+    return date.getTime() + ((hour * 60 + minute) * 60 + second) * 1_000;
+}
+/**
+ * RFC 9110 §5.6.7: a two-digit year that would be more than 50 years ahead names the most recent
+ * past year with those last two digits.
+ */
+function rfc850Year(lastTwoDigits, now) {
+    const current = new Date(now).getUTCFullYear();
+    const year = current - (current % 100) + lastTwoDigits;
+    if (year > current + 50)
+        return year - 100;
+    return year <= current - 50 ? year + 100 : year;
+}

package/dist/hosting/script.d.ts

@@ -0,0 +1,186 @@
+import type { CloudflareClient } from './client.js';
+import { SIGNING_IDENTITY_BINDING } from '../identity/binding.js';
+import { BUILD_DIGEST_BINDING } from '../worker/build-digest.js';
+import { SETTINGS_BINDING } from '../worker/settings.js';
+import { type ScriptAsset } from './assets.js';
+/** The deployment URL, which is also its issuer. */
+export declare const WORKER_URL_BINDING = "WORKER_URL";
+/** The binding a deployment's Worker reads its provider version from, for readiness. */
+export declare const VERSION_METADATA_BINDING = "ASTRALE_VERSION_METADATA";
+/** The service binding through which a deployment reaches an instance router. */
+export declare const ROUTER_BINDING = "ROUTER";
+/** The binding of a deployment's static assets, when its build has a frontend. */
+export declare const ASSETS_BINDING = "ASSETS";
+/** The secret the generated Worker reads its private signing JWK from (`ASTRALE_SIGNING_IDENTITY`). */
+export { BUILD_DIGEST_BINDING, SETTINGS_BINDING, SIGNING_IDENTITY_BINDING };
+/** The build a script runs: `astrale-artifact:<hex digest of its build manifest>`. */
+export declare const ARTIFACT_TAG_PREFIX = "astrale-artifact:";
+/** The deployment line a script is a version of: `astrale-line:<line>`. */
+export declare const LINE_TAG_PREFIX = "astrale-line:";
+/** The signing key a script binds: `astrale-key:<RFC 7638 thumbprint>`. */
+export declare const KEY_TAG_PREFIX = "astrale-key:";
+/** The multipart type of each Worker module kind, as the Workers upload API reads it. */
+declare const MODULE_PART_TYPES: Readonly<{
+    esm: "application/javascript+module";
+    wasm: "application/wasm";
+    text: "text/plain";
+    data: "application/octet-stream";
+}>;
+/** One module of a script upload. */
+export interface ScriptModule {
+    readonly name: string;
+    readonly kind: keyof typeof MODULE_PART_TYPES;
+    readonly bytes: Uint8Array;
+}
+/** One binding of a script upload, as Cloudflare's upload metadata names it. */
+export type ScriptBinding = {
+    readonly type: 'plain_text';
+    readonly name: string;
+    readonly text: string;
+} | {
+    readonly type: 'secret_text';
+    readonly name: string;
+    readonly text: string;
+} | {
+    readonly type: 'service';
+    readonly name: string;
+    readonly service: string;
+} | {
+    readonly type: 'dispatch_namespace';
+    readonly name: string;
+    readonly namespace: string;
+} | {
+    readonly type: 'version_metadata';
+    readonly name: string;
+} | {
+    readonly type: 'assets';
+    readonly name: string;
+};
+/**
+ * What identifies one namespace script at the provider: its code hash (`etag`), its tags (the
+ * kit's `astrale-artifact:`, `astrale-line:` and `astrale-key:` decoded, every tag kept), and when
+ * Cloudflare created it. `version` is the provider version serving now (`deployment_id`), read
+ * only to check readiness: a secret written in place mints a new one, so nothing keeps it.
+ */
+export interface NamespaceScript {
+    readonly etag: string;
+    readonly version: string;
+    readonly tags: readonly string[];
+    readonly artifact?: string;
+    readonly line?: string;
+    readonly keyId?: string;
+    readonly createdOn?: string;
+}
+/** Everything one new deployment binds, all fixed at its create-only upload. */
+export interface DeploymentBindingsInput {
+    /** The deployment URL, which is its issuer (`WORKER_URL`). */
+    readonly url: string;
+    /** The build digest of the bytes uploaded (`ASTRALE_BUILD_DIGEST`). */
+    readonly buildDigest: string;
+    /**
+     * A generated Worker's execution settings, already encoded (`ASTRALE_SETTINGS`), bound after the
+     * build digest; none when absent (a Worker host binds a deployer's settings among its variables).
+     */
+    readonly settings?: string;
+    /** The author's plain variables, bound in name order. */
+    readonly vars: Readonly<Record<string, string>>;
+    /** Service bindings, in the order given. */
+    readonly services?: readonly {
+        readonly name: string;
+        readonly service: string;
+    }[];
+    /** Dispatch namespace bindings, in the order given. */
+    readonly dispatchNamespaces?: readonly {
+        readonly name: string;
+        readonly namespace: string;
+    }[];
+    /** The Worker the `ROUTER` service binding reaches; none when absent. */
+    readonly router?: string;
+    /** The private JWK text of its key (`ASTRALE_SIGNING_IDENTITY`); none when absent. */
+    readonly signingIdentity?: string;
+    /** Its secrets, bound in name order. */
+    readonly secrets: Readonly<Record<string, string>>;
+}
+/**
+ * The bindings of one new deployment, in their order: `WORKER_URL`, `ASTRALE_BUILD_DIGEST`,
+ * `ASTRALE_SETTINGS` (when given), the variables, the service and dispatch namespace bindings,
+ * `ROUTER` (when given), the version metadata `ASTRALE_VERSION_METADATA`, the key
+ * `ASTRALE_SIGNING_IDENTITY` (when given), then the secrets. A script upload with assets adds
+ * `ASSETS` last. Nothing ever adds a binding afterwards: only a secret's value is rewritten in
+ * place. A name bound twice is refused.
+ */
+export declare function deploymentBindings(input: DeploymentBindingsInput): readonly ScriptBinding[];
+/**
+ * The tags of one deployment script: the caller's `extra` tags first (a host's own, such as
+ * Services' `astrale-service` and `astrale-install:`), then its artifact (build), line and, when
+ * it binds one, key.
+ */
+export declare function deploymentTags(input: {
+    readonly buildDigest: string;
+    readonly line: string;
+    readonly keyId?: string;
+    readonly extra?: readonly string[];
+}): readonly string[];
+/** The artifact tag value of one build: the hexadecimal digest of its manifest. */
+export declare function artifactOf(buildDigest: string): string;
+/** What one create-only script upload carries. */
+export interface ScriptUpload {
+    readonly client: CloudflareClient;
+    readonly namespace: string;
+    /** The script name: the deployment label. */
+    readonly label: string;
+    readonly mainModule: string;
+    readonly modules: readonly ScriptModule[];
+    readonly assets?: readonly ScriptAsset[];
+    readonly compatibilityDate: string;
+    readonly compatibilityFlags: readonly string[];
+    /** `deploymentBindings`; `ASSETS` is added when there are assets. */
+    readonly bindings: readonly ScriptBinding[];
+    /** `deploymentTags`. */
+    readonly tags: readonly string[];
+}
+/**
+ * Upload one deployment script, create-only: `If-None-Match: *` makes the provider refuse with
+ * 412 (`isExistingScript`) when the label already names a script, so an upload never replaces
+ * another deployment. Its static assets are uploaded first, through the namespace's asset session;
+ * the Worker routes first and serves its frontend itself.
+ */
+export declare function uploadDeploymentScript(input: ScriptUpload): Promise<NamespaceScript>;
+/** Whether a create-only upload was refused because the label already names a script. */
+export declare function isExistingScript(cause: unknown): boolean;
+/** Read one script's identity, or undefined when the namespace holds no script by that name. */
+export declare function observeScript(client: CloudflareClient, namespace: string, label: string): Promise<NamespaceScript | undefined>;
+/** The names of one script's `secret_text` bindings, sorted. */
+export declare function scriptSecretNames(client: CloudflareClient, namespace: string, label: string): Promise<readonly string[]>;
+/** One script's settings as the provider reads them back: runtime and bindings, never secrets. */
+export interface ScriptSettings {
+    readonly compatibilityDate: string;
+    readonly compatibilityFlags: readonly string[];
+    readonly bindings: readonly Readonly<Record<string, unknown>>[];
+}
+export declare function scriptSettings(client: CloudflareClient, namespace: string, label: string): Promise<ScriptSettings>;
+/**
+ * Whether settings read back bind exactly this runtime and these bindings: compatibility date and
+ * flags (in any order), every binding by name, type and target or text, secrets by name only.
+ */
+export declare function settingsBind(settings: ScriptSettings, expected: {
+    readonly compatibilityDate: string;
+    readonly compatibilityFlags: readonly string[];
+    readonly bindings: readonly ScriptBinding[];
+}): boolean;
+/**
+ * Rewrite one secret of one script in place. Cloudflare keeps the script's name, etag, tags and
+ * other bindings, mints a new version, and answers only the secret's name and type.
+ */
+export declare function putScriptSecret(client: CloudflareClient, namespace: string, label: string, name: string, value: string): Promise<void>;
+/**
+ * Delete one script (with `?force=true`) and require that it is gone. A delete Cloudflare answers
+ * as unavailable counts when the script is observed absent afterwards.
+ */
+export declare function deleteScript(client: CloudflareClient, namespace: string, label: string): Promise<void>;
+/** A provider version in the UUID form a Worker's version metadata reports. */
+export declare function versionUuid(version: string): string;
+/** `/accounts/<a>/workers/dispatch/namespaces/<namespace>/scripts/<label><suffix>`. */
+export declare function scriptPath(client: CloudflareClient, namespace: string, label: string, suffix?: string): string;
+/** Decode the script identity an upload or a script read returns. */
+export declare function decodeScript(value: unknown): NamespaceScript;