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

package/dist/hosting/kv.js

@@ -1,20 +1,20 @@
-import { acceptDeploymentRecord, parseDeploymentLabel } from '@astrale-os/sdk/deployment/address';
-import { json } from '@astrale-os/sdk/value';
-import { CloudflareApiError } from './client.js';
+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 | content type |
+ * | key | value | metadata |
  * |---|---|---|
- * | `record:<label>` | RFC 8785 JSON of the label's `DeploymentRecordV1`; never rewritten | `application/json` |
- * | `retirement:<label>` | `withdrawn`; any value retires the label at the dispatcher | `text/plain` |
- * | `current:<name>` | the label a name serves now, one of `<name>-…` | `text/plain` |
- * | `cron:<name>` | JSON array of distinct canonical five-field UTC crons; deleted when empty | `application/json` |
+ * | `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 |
  *
- * The record of a label activates it and outlives its retirement. Workers KV has no
- * compare-and-set: every write is read back before it counts.
+ * `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:';
@@ -38,39 +38,6 @@ export function currentKey(name) {
 export function cronKey(name) {
     return `${CRON_PREFIX}${name}`;
 }
-/** The text `record:<label>` holds: the record admitted, as RFC 8785 canonical JSON. */
-export function encodeRecord(record) {
-    return json.serialize(acceptDeploymentRecord(record));
-}
-/** Admit the text `record:<label>` holds as that label's record. */
-export function decodeRecord(text, label) {
-    let record;
-    try {
-        record = acceptDeploymentRecord(JSON.parse(text));
-    }
-    catch {
-        throw new HostingRefusal('record-invalid', `The record of ${label} is not a DeploymentRecordV1.`);
-    }
-    if (record.providerScript !== label) {
-        throw new HostingRefusal('record-invalid', `The record published under ${label} names the script ${record.providerScript}.`);
-    }
-    return record;
-}
-/**
- * Whether two records declare the same deployment: same origin, environment, release, build,
- * Schema revision, configuration and script. Only the commit may differ: a redeploy of identical
- * bytes and configuration from another commit is the same deployment, whose record keeps the
- * commit it was first activated from. This is the kit's one re-publication rule.
- */
-export function sameRelease(left, right) {
-    return (left.origin === right.origin &&
-        left.environment === right.environment &&
-        left.releaseDigest === right.releaseDigest &&
-        left.buildDigest === right.buildDigest &&
-        left.schemaRevision === right.schemaRevision &&
-        left.configuration === right.configuration &&
-        left.providerScript === right.providerScript);
-}
 /** Admit the label `current:<name>` holds: a deployment label of that name's line. */
 export function decodeCurrent(text, name) {
     if (!isLabelOf(text, name)) {
@@ -159,6 +126,40 @@ export class RoutingKv {
         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));
@@ -181,7 +182,10 @@ export class RoutingKv {
         }));
     }
     value(key) {
-        return this.client.account(`/storage/kv/namespaces/${encodeURIComponent(this.id)}/values/${encodeURIComponent(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. */

package/dist/hosting/listing.d.ts

@@ -1,19 +1,20 @@
+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';
 /**
  * One deployment of a line as the routing KV and the namespace hold it:
  *
- * - `record`: `record:<label>` as stored, JSON-decoded and never admitted (JSON `null` included;
- *   its text when it is not JSON); absent when the label has no record;
+ * - `record`: the record `record:<label>` publishes (its media type and bytes, never read), `null`
+ *   when the deployment publishes none; absent when the label is not activated;
  * - `retired`: whether `retirement:<label>` withdraws it;
  * - `script`: the script under the label, absent once deleted (a completed retirement).
  *
- * The dispatcher serves it (`active`) exactly when it has a record, no tombstone and a script.
+ * The dispatcher serves it (`active`) exactly when it is activated, has no tombstone and a script.
  */
 export interface LineDeployment {
     readonly label: string;
-    readonly record?: unknown;
+    readonly record?: WorkerRecord | null;
     readonly retired: boolean;
     readonly script?: NamespaceScript;
 }
@@ -22,8 +23,8 @@ export interface LineDeployment {
  * the routing KV, each with its script, in label order. A key there that names no deployment
  * label is refused (`record-invalid`, `retirement-invalid`); one whose label is on another line,
  * whose readable part happens to extend this one, is not this line's. A label that only has an
- * uploaded script (never activated nor retired) is not listed: nothing in the KV names it.
- * Nothing is written.
+ * uploaded script (never activated nor retired) is not listed: nothing in the KV names it. A stored
+ * record the kit refuses is refused (`record-invalid`). Nothing is written.
  */
 export declare function listLineDeployments(input: {
     readonly client: CloudflareClient;

package/dist/hosting/listing.js

@@ -1,6 +1,7 @@
 import { parseDeploymentLabel } from '@astrale-os/sdk/deployment/address';
+import { readRecord } from './activation.js';
 import { CLOUDFLARE_FAN_OUT, mapBounded } from './bounded.js';
-import { RECORD_PREFIX, recordKey, RETIREMENT_PREFIX } from './kv.js';
+import { RECORD_PREFIX, RETIREMENT_PREFIX } from './kv.js';
 import { HostingRefusal } from './refusal.js';
 import { readRetirement } from './retirement.js';
 import { observeScript } from './script.js';
@@ -9,8 +10,8 @@ import { observeScript } from './script.js';
  * the routing KV, each with its script, in label order. A key there that names no deployment
  * label is refused (`record-invalid`, `retirement-invalid`); one whose label is on another line,
  * whose readable part happens to extend this one, is not this line's. A label that only has an
- * uploaded script (never activated nor retired) is not listed: nothing in the KV names it.
- * Nothing is written.
+ * uploaded script (never activated nor retired) is not listed: nothing in the KV names it. A stored
+ * record the kit refuses is refused (`record-invalid`). Nothing is written.
  */
 export async function listLineDeployments(input) {
     const { client, kv, namespace, line } = input;
@@ -19,13 +20,13 @@ export async function listLineDeployments(input) {
     const activated = new Set(await labelsOf(kv, RECORD_PREFIX, line));
     const labels = [...new Set([...activated, ...retired])].sort();
     return Object.freeze(await mapBounded(labels, CLOUDFLARE_FAN_OUT, async (label) => {
-        const stored = activated.has(label) ? await kv.get(recordKey(label)) : undefined;
+        const stored = activated.has(label) ? await readRecord(kv, label) : undefined;
         if (retired.has(label))
             await readRetirement(kv, label);
         const script = await observeScript(client, namespace, label);
         return Object.freeze({
             label,
-            ...(stored === undefined ? {} : { record: parseStored(stored) }),
+            ...(stored === undefined ? {} : { record: stored }),
             retired: retired.has(label),
             ...(script === undefined ? {} : { script }),
         });
@@ -47,11 +48,3 @@ async function labelsOf(kv, prefix, line) {
     }
     return labels;
 }
-function parseStored(text) {
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return text;
-    }
-}

package/dist/hosting/refusal.d.ts

@@ -12,7 +12,7 @@ export declare class HostingRefusal extends Error {
      | 'deployment-conflict'
     /** The label is withdrawn and is never served again. */
      | 'deployment-retired'
-    /** A stored `record:` is not this label's `DeploymentRecordV1`. */
+    /** 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'

package/dist/hosting/retirement.d.ts

@@ -1,4 +1,4 @@
-import type { DeploymentRecordV1 } from '@astrale-os/sdk/deployment/address';
+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';
@@ -49,10 +49,11 @@ export type RetirementCompletion = {
  * 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 name the
- * caller's build, configuration and script when the caller passes its `record`, 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.
+ * 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;
@@ -60,7 +61,7 @@ export declare function completeRetirement(input: {
     readonly namespace: string;
     readonly label: string;
     readonly probe: () => Promise<boolean>;
-    readonly record?: Pick<DeploymentRecordV1, 'buildDigest' | 'configuration' | 'providerScript'>;
+    readonly record?: WorkerRecord | null;
     readonly owns?: (script: NamespaceScript) => boolean;
     /** When the tombstone was written (epoch ms), if the caller keeps it. */
     readonly retiredAt?: number;

package/dist/hosting/retirement.js

@@ -1,4 +1,5 @@
-import { recordKey, retirementKey, WITHDRAWN } from './kv.js';
+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. */
@@ -67,17 +68,18 @@ export async function retirementVisible(input) {
  * 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 name the
- * caller's build, configuration and script when the caller passes its `record`, 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.
+ * 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 input.kv.get(recordKey(label));
-        if (published !== undefined && !namesRelease(published, input.record)) {
-            return conflict(`The record published for ${label} names another build or configuration.`);
+        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);
@@ -96,21 +98,6 @@ export async function completeRetirement(input) {
         await deleteScript(client, input.namespace, label);
     return Object.freeze({ kind: 'removed' });
 }
-function namesRelease(published, record) {
-    let value;
-    try {
-        value = JSON.parse(published);
-    }
-    catch {
-        return false;
-    }
-    const read = value;
-    return (read !== null &&
-        typeof read === 'object' &&
-        read.buildDigest === record.buildDigest &&
-        read.configuration === record.configuration &&
-        read.providerScript === record.providerScript);
-}
 function conflict(message) {
     return Object.freeze({
         kind: 'conflict',

package/dist/hosting/script.d.ts

@@ -77,8 +77,11 @@ export interface DeploymentBindingsInput {
     readonly url: string;
     /** The build digest of the bytes uploaded (`ASTRALE_BUILD_DIGEST`). */
     readonly buildDigest: string;
-    /** Its execution settings, already encoded (`ASTRALE_SETTINGS`). */
-    readonly settings: 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. */
@@ -93,27 +96,29 @@ export interface DeploymentBindingsInput {
     }[];
     /** The Worker the `ROUTER` service binding reaches; none when absent. */
     readonly router?: string;
-    /** The private JWK text of its key (`ASTRALE_SIGNING_IDENTITY`). */
-    readonly signingIdentity: 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`, the variables, the service and dispatch namespace bindings, `ROUTER`, the
- * version metadata `ASTRALE_VERSION_METADATA`, the key `ASTRALE_SIGNING_IDENTITY`, 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.
+ * `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 key.
+ * 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 keyId?: string;
     readonly extra?: readonly string[];
 }): readonly string[];
 /** The artifact tag value of one build: the hexadecimal digest of its manifest. */

package/dist/hosting/script.js

@@ -28,16 +28,19 @@ const MODULE_PART_TYPES = Object.freeze({
 });
 /**
  * The bindings of one new deployment, in their order: `WORKER_URL`, `ASTRALE_BUILD_DIGEST`,
- * `ASTRALE_SETTINGS`, the variables, the service and dispatch namespace bindings, `ROUTER`, the
- * version metadata `ASTRALE_VERSION_METADATA`, the key `ASTRALE_SIGNING_IDENTITY`, 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.
+ * `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 function deploymentBindings(input) {
     const bindings = [
         { type: 'plain_text', name: WORKER_URL_BINDING, text: input.url },
         { type: 'plain_text', name: BUILD_DIGEST_BINDING, text: input.buildDigest },
-        { type: 'plain_text', name: SETTINGS_BINDING, text: input.settings },
+        ...(input.settings === undefined
+            ? []
+            : [{ type: 'plain_text', name: SETTINGS_BINDING, text: input.settings }]),
         ...Object.keys(input.vars)
             .sort()
             .map((name) => ({ type: 'plain_text', name, text: input.vars[name] })),
@@ -55,7 +58,15 @@ export function deploymentBindings(input) {
             ? []
             : [{ type: 'service', name: ROUTER_BINDING, service: input.router }]),
         { type: 'version_metadata', name: VERSION_METADATA_BINDING },
-        { type: 'secret_text', name: SIGNING_IDENTITY_BINDING, text: input.signingIdentity },
+        ...(input.signingIdentity === undefined
+            ? []
+            : [
+                {
+                    type: 'secret_text',
+                    name: SIGNING_IDENTITY_BINDING,
+                    text: input.signingIdentity,
+                },
+            ]),
         ...Object.keys(input.secrets)
             .sort()
             .map((name) => ({ type: 'secret_text', name, text: input.secrets[name] })),
@@ -69,14 +80,15 @@ export function deploymentBindings(input) {
 }
 /**
  * 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 key.
+ * Services' `astrale-service` and `astrale-install:`), then its artifact (build), line and, when
+ * it binds one, key.
  */
 export function deploymentTags(input) {
     return Object.freeze([
         ...(input.extra ?? []),
         `${ARTIFACT_TAG_PREFIX}${artifactOf(input.buildDigest)}`,
         `${LINE_TAG_PREFIX}${input.line}`,
-        `${KEY_TAG_PREFIX}${input.keyId}`,
+        ...(input.keyId === undefined ? [] : [`${KEY_TAG_PREFIX}${input.keyId}`]),
     ]);
 }
 /** The artifact tag value of one build: the hexadecimal digest of its manifest. */

package/dist/hosting/testing/fake-cloudflare.d.ts

@@ -95,6 +95,8 @@ interface KvNamespace {
     readonly id: string;
     readonly title: string;
     readonly values: Map<string, string>;
+    /** The metadata a value was written with; a value written without has none. */
+    readonly metadata: Map<string, unknown>;
 }
 interface Zone {
     readonly id: string;
@@ -172,8 +174,15 @@ export declare class FakeCloudflare {
     addKv(title: string): KvNamespace;
     /** Add one zone named `name` (the fake's first zone is `FAKE_ZONE`). */
     addZone(name: string): Zone;
-    /** The values of the KV namespace titled `title` (or with that id). */
+    /**
+     * The values of the KV namespace titled `title` (or with that id), as UTF-8 text: the fake keeps
+     * UTF-8 values only. A value set here has no metadata: a deployment record set here is one
+     * written before records were opaque.
+     */
     kv(titleOrId: string): Map<string, string>;
+    /** The metadata of the values of the KV namespace titled `title` (or with that id), by key. */
+    kvMetadata(titleOrId: string): Map<string, unknown>;
+    private kvNamespace;
     /** The scripts of one dispatch namespace. */
     scripts(namespace: string): Map<string, FakeScript>;
     /** A provider version in the UUID form a Worker's version metadata reports. */

package/dist/hosting/testing/fake-cloudflare.js

@@ -91,7 +91,12 @@ export class FakeCloudflare {
     }
     /** Add one KV namespace; its id is derived from its title. */
     addKv(title) {
-        const kv = { id: `kv${this.kvs.length}-${title}`.slice(0, 32), title, values: new Map() };
+        const kv = {
+            id: `kv${this.kvs.length}-${title}`.slice(0, 32),
+            title,
+            values: new Map(),
+            metadata: new Map(),
+        };
         this.kvs.push(kv);
         return kv;
     }
@@ -102,12 +107,23 @@ export class FakeCloudflare {
         this.zones.set(id, zone);
         return zone;
     }
-    /** The values of the KV namespace titled `title` (or with that id). */
+    /**
+     * The values of the KV namespace titled `title` (or with that id), as UTF-8 text: the fake keeps
+     * UTF-8 values only. A value set here has no metadata: a deployment record set here is one
+     * written before records were opaque.
+     */
     kv(titleOrId) {
+        return this.kvNamespace(titleOrId).values;
+    }
+    /** The metadata of the values of the KV namespace titled `title` (or with that id), by key. */
+    kvMetadata(titleOrId) {
+        return this.kvNamespace(titleOrId).metadata;
+    }
+    kvNamespace(titleOrId) {
         const kv = this.kvs.find((candidate) => candidate.title === titleOrId || candidate.id === titleOrId);
         if (kv === undefined)
             throw new TypeError(`The fake account has no KV ${titleOrId}.`);
-        return kv.values;
+        return kv;
     }
     /** The scripts of one dispatch namespace. */
     scripts(namespace) {
@@ -189,14 +205,27 @@ export class FakeCloudflare {
         };
     }
     kvBinding(id) {
-        const values = () => {
+        const namespace = () => {
             const kv = this.kvs.find((candidate) => candidate.id === id);
             if (kv === undefined)
                 throw new Error('KV namespace not found.');
-            return kv.values;
+            return kv;
         };
+        const values = () => namespace().values;
         return {
             get: async (key) => values().get(key) ?? null,
+            getWithMetadata: async (key, type) => {
+                if (type !== 'arrayBuffer')
+                    throw new TypeError('The fake reads metadata as bytes only.');
+                const value = values().get(key);
+                if (value === undefined)
+                    return { value: null, metadata: null };
+                const bytes = new TextEncoder().encode(value);
+                return {
+                    value: bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
+                    metadata: namespace().metadata.get(key) ?? null,
+                };
+            },
             list: async ({ prefix, cursor }) => {
                 const names = [...values().keys()].filter((key) => key.startsWith(prefix)).sort();
                 const size = this.options.kvKeysPageSize ?? 1000;
@@ -317,6 +346,18 @@ export class FakeCloudflare {
                 response: envelope(page.map((name) => ({ name })), { count: page.length, cursor: next }),
             };
         }
+        const metadata = /^\/storage\/kv\/namespaces\/([^/]+)\/metadata\/(.+)$/u.exec(path);
+        if (metadata !== null && method === 'GET') {
+            const kv = this.kvs.find((candidate) => candidate.id === decodeURIComponent(metadata[1]));
+            if (kv === undefined)
+                return { response: failure(404, 10013, 'namespace not found') };
+            const key = decodeURIComponent(metadata[2]);
+            return {
+                response: kv.values.has(key)
+                    ? envelope(kv.metadata.get(key) ?? null)
+                    : failure(404, 10009, 'get: key not found'),
+            };
+        }
         const value = /^\/storage\/kv\/namespaces\/([^/]+)\/values\/(.+)$/u.exec(path);
         if (value !== null) {
             const kv = this.kvs.find((candidate) => candidate.id === decodeURIComponent(value[1]));
@@ -332,15 +373,25 @@ export class FakeCloudflare {
                 };
             }
             if (method === 'PUT') {
+                const contentType = request.headers.get('content-type');
+                // A value written with metadata is a multipart form: its `value` and its JSON `metadata`.
+                if (contentType?.startsWith('multipart/form-data') === true) {
+                    const form = await request.formData();
+                    const part = form.get('value');
+                    const written = typeof part === 'string' ? part : await utf8(part);
+                    const declared = JSON.parse(String(form.get('metadata')));
+                    kv.values.set(key, written);
+                    kv.metadata.set(key, declared);
+                    return { response: envelope(null), body: { key, value: written, metadata: declared } };
+                }
                 const text = await request.text();
                 kv.values.set(key, text);
-                return {
-                    response: envelope(null),
-                    body: { key, value: text, contentType: request.headers.get('content-type') },
-                };
+                kv.metadata.delete(key);
+                return { response: envelope(null), body: { key, value: text, contentType } };
             }
             if (method === 'DELETE') {
                 kv.values.delete(key);
+                kv.metadata.delete(key);
                 return { response: envelope(null), body: { key } };
             }
         }
@@ -697,3 +748,9 @@ function redact(metadata) {
             : binding),
     };
 }
+/** A value part as UTF-8 text: the fake keeps UTF-8 values only, and refuses any other bytes. */
+async function utf8(part) {
+    if (part === null)
+        throw new TypeError('The fake KV write has no value.');
+    return new TextDecoder('utf-8', { fatal: true }).decode(await part.arrayBuffer());
+}