pyric-admin 0.1.0-alpha.21 → 0.1.0-alpha.24

package/dist/storage/index.js

@@ -7,10 +7,10 @@
  *
  *   - **Remote sandbox path** — a handle branded by `@pyric/cli`'
  *     `connectRemoteSandbox()`/`remoteSandbox()` relays every data
- *     operation over the bridge to the browser-hosted SharedWorker's
- *     object store (admin lens pinned — rules bypass). Single bucket;
- *     8 MiB per-op byte cap; `getSignedUrl` stays the local stub. See
- *     the remote arm section below.
+ *     operation to the sandbox's host (admin lens pinned — rules bypass).
+ *     Bytes move over the host's HTTP byte route when it has one, and as
+ *     frames when it does not (a browser tab's SharedWorker). Single bucket;
+ *     `getSignedUrl` stays the local stub. See the remote arm section below.
  *
  *   - **Sandbox path** — returns an in-process {@link Storage} backed
  *     by an in-memory `Map<bucketName, Map<path, FileEntry>>`. State
@@ -23,19 +23,37 @@
  *       - `storage.bucket(name?)` → {@link Bucket}-shaped handle
  *       - `bucket.file(path)` → {@link File}-shaped handle
  *       - `file.save(data, options?)` — `Buffer | string | Uint8Array`
- *       - `file.download(options?)` → `[Buffer]`
+ *       - `file.download(options?)` → `[Buffer]`, whole or `start..end`
+ *       - `file.createReadStream(options?)`, whole or `start..end`
+ *       - `file.createWriteStream(options?)`
+ *       - `file.getMetadata()` / `file.setMetadata(metadata)`: settable fields
+ *         and custom metadata; a custom key set to `null` is removed
+ *       - `getDownloadURL(file)`: mints a token into
+ *         `firebaseStorageDownloadTokens` when the file has none. The Node
+ *         host returns its HTTP URL; elsewhere the URL is a `data:` URI
  *       - `file.delete()` — idempotent
  *       - `file.exists()` → `[boolean]`
  *       - `file.getSignedUrl(options)` → `['pyric-sandbox-storage://…']`
  *
  *     **Deferred in the sandbox backend** (throws `"not implemented in
- *     pyric-admin/storage sandbox backend"`): streaming uploads
- *     (`createWriteStream`), resumable uploads, signed cookies, IAM
- *     policies, lifecycle rules, ACLs, copy/move, notifications.
+ *     pyric-admin/storage sandbox backend"`): resumable uploads, signed
+ *     cookies, IAM policies, lifecycle rules, ACLs, copy/move,
+ *     notifications.
  */
+import { createWriteStream as createFileWriteStream, openAsBlob } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable, Writable } from 'node:stream';
 import { isRemoteSandbox, } from 'pyric/sandbox';
+import { fetchFromByteRoute, uploadOverByteRoute } from 'pyric/storage/internal';
 import { ADMIN_APP_TARGET, getApp, } from '../app/index.js';
 import { assertAdminAppActive } from '../app/lifecycle.js';
+/** The custom metadata key holding a file's download tokens, comma-separated. */
+const DOWNLOAD_TOKENS_KEY = 'firebaseStorageDownloadTokens';
+/** Settable fields the sandbox keeps, besides custom metadata. */
+const SETTABLE_FIELDS = ['contentType', 'cacheControl', 'contentDisposition', 'contentEncoding', 'contentLanguage'];
 /**
  * Get the {@link Storage} service for the given app.
  *
@@ -64,13 +82,23 @@ export function getStorage(app) {
     throw new TypeError('pyric-admin/storage: getStorage expected a PyricAdminApp from `initializeApp`; ' +
         'received a value with no recognized ADMIN_APP_TARGET brand.');
 }
+/** Each arm's own download URL. */
+const DOWNLOAD_URL = Symbol('pyric-admin/storage download URL');
 /**
- * Link-compatible mirror of `firebase-admin/storage`'s `getDownloadURL(file)`.
- * Returns a deterministic sandbox storage stub URL from `file.getSignedUrl()`.
+ * Mirror of `firebase-admin/storage`'s `getDownloadURL(file)`. A file without
+ * a download token gets one in `firebaseStorageDownloadTokens`, as production
+ * mints it. On the Node host the URL is its HTTP byte route URL, which serves
+ * ranges and stops working when the token is removed. In process and on a
+ * SharedWorker host there is no HTTP origin, so the URL is a `data:` URI that
+ * carries the bytes.
  */
 export async function getDownloadURL(file) {
-    const [url] = await file.getSignedUrl({ action: 'read', expires: '2099-01-01' });
-    return url;
+    const source = file;
+    const served = typeof source[DOWNLOAD_URL] === 'function';
+    if (!served) {
+        throw new Error('pyric-admin/storage: getDownloadURL expects a File from getStorage().bucket().file().');
+    }
+    return source[DOWNLOAD_URL]();
 }
 // ─── Sandbox path ───────────────────────────────────────────────────────
 /**
@@ -79,6 +107,12 @@ export async function getDownloadURL(file) {
  * surfaces don't see an unexpected bucket name change.
  */
 const DEFAULT_SANDBOX_BUCKET = 'pyric-default';
+let generationSequence = 0;
+/** A generation in the form `@google-cloud/storage` reports: microseconds since the epoch. */
+function nextGeneration() {
+    generationSequence = (generationSequence + 1) % 1000;
+    return `${Date.now()}${String(generationSequence).padStart(3, '0')}`;
+}
 /**
  * State + reset-handler registry keyed on `Sandbox` so a single
  * Sandbox shares its storage across every `getStorage` call. The
@@ -165,22 +199,97 @@ class SandboxFile {
             throw new Error('not implemented in pyric-admin/storage sandbox backend: resumable uploads');
         }
         const bytes = toBytes(data);
-        const metadata = options.metadata ?? {};
-        const entry = {
+        const saved = patchOf(options.metadata ?? {}, { strict: false });
+        const contentType = options.contentType ?? saved.settable.contentType;
+        const now = new Date().toISOString();
+        const custom = {};
+        for (const [key, value] of Object.entries(saved.customMetadata))
+            if (value !== null)
+                custom[key] = value;
+        const hasTokens = typeof saved.downloadTokens === 'string';
+        if (hasTokens)
+            custom[DOWNLOAD_TOKENS_KEY] = saved.downloadTokens;
+        this.files.set(this.name, {
             data: bytes,
-            metadata,
-            ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),
+            settable: { ...saved.settable, ...(contentType !== undefined ? { contentType } : {}) },
+            custom,
+            generation: nextGeneration(),
+            metageneration: 1,
+            timeCreated: now,
+            updated: now,
+        });
+    }
+    async getMetadata() {
+        return [this.metadataOf(this.entry())];
+    }
+    async setMetadata(metadata) {
+        const entry = this.entry();
+        const patch = patchOf(metadata, { strict: true });
+        Object.assign(entry.settable, patch.settable);
+        for (const [key, value] of Object.entries(patch.customMetadata)) {
+            if (value === null)
+                delete entry.custom[key];
+            else
+                entry.custom[key] = value;
+        }
+        if (patch.downloadTokens === null)
+            delete entry.custom[DOWNLOAD_TOKENS_KEY];
+        else if (patch.downloadTokens !== undefined)
+            entry.custom[DOWNLOAD_TOKENS_KEY] = patch.downloadTokens;
+        this.touch(entry);
+        return [this.metadataOf(entry)];
+    }
+    async [DOWNLOAD_URL]() {
+        const entry = this.entry();
+        const tokenless = !entry.custom[DOWNLOAD_TOKENS_KEY];
+        if (tokenless) {
+            entry.custom[DOWNLOAD_TOKENS_KEY] = randomUUID();
+            this.touch(entry);
+        }
+        return dataUri(entry.data, entry.settable.contentType);
+    }
+    entry() {
+        const entry = this.files.get(this.name);
+        if (!entry)
+            throw new Error(`No such object: ${this.bucket.name}/${this.name}`);
+        return entry;
+    }
+    touch(entry) {
+        entry.metageneration += 1;
+        entry.updated = new Date().toISOString();
+    }
+    metadataOf(entry) {
+        const hasCustom = Object.keys(entry.custom).length > 0;
+        return {
+            name: this.name,
+            bucket: this.bucket.name,
+            generation: entry.generation,
+            metageneration: String(entry.metageneration),
+            size: String(entry.data.byteLength),
+            timeCreated: entry.timeCreated,
+            updated: entry.updated,
+            ...entry.settable,
+            ...(hasCustom ? { metadata: { ...entry.custom } } : {}),
         };
-        this.files.set(this.name, entry);
     }
-    async download(_options = {}) {
+    async download(options = {}) {
         const entry = this.files.get(this.name);
         if (!entry) {
             // Mirror the gcs/firebase-admin error message shape so consumer
             // catch-blocks that string-match `No such object` keep working.
             throw new Error(`No such object: ${this.bucket.name}/${this.name}`);
         }
-        return [Buffer.from(entry.data)];
+        return [Buffer.from(byteRange(entry.data, options))];
+    }
+    createReadStream(options = {}) {
+        const read = async function* (file) {
+            const [bytes] = await file.download(options);
+            yield bytes;
+        };
+        return Readable.from(read(this), { objectMode: false });
+    }
+    createWriteStream(options = {}) {
+        return spooledWriteStream(async (spooled) => this.save(await readFile(spooled), options));
     }
     async delete() {
         this.files.delete(this.name);
@@ -191,21 +300,12 @@ class SandboxFile {
     async getSignedUrl(options) {
         return [stubSignedUrl(this.bucket.name, this.name, options)];
     }
-    // ─── Deferred surface (declared so TS callers see a clear error) ────
-    /** @deprecated Streaming writes are deferred — see module header. */
-    createWriteStream() {
-        throw new Error('not implemented in pyric-admin/storage sandbox backend: createWriteStream');
-    }
-    /** @deprecated Streaming reads are deferred — see module header. */
-    createReadStream() {
-        throw new Error('not implemented in pyric-admin/storage sandbox backend: createReadStream');
-    }
 }
 // ─── Remote sandbox arm (remote sandbox, slice 2) ───────────────────────
 //
-// The app's `Sandbox` is a Node-side handle onto the browser-hosted
-// SharedWorker sandbox. Every data operation relays over the handle's
-// worker channel with `actAs: { mode: 'admin' }` pinned — firebase-admin's
+// The app's `Sandbox` is a Node-side handle onto a hosted sandbox or a
+// browser tab's SharedWorker sandbox. Every data operation relays over the
+// handle's worker channel with `actAs: { mode: 'admin' }` pinned — firebase-admin's
 // rules-bypass semantics against the ONE object store the app + Studio +
 // agents share (the host resolves the lens to `pyric/storage/internal`'s
 // admin plane). There is deliberately NO local state here: a `WeakMap`
@@ -218,19 +318,21 @@ class SandboxFile {
 //     ("the data store is shared" — bucket names only round-trip in
 //     metadata), so `bucket('non-default')` throws instead of silently
 //     merging buckets. The default bucket name matches the local arm.
-//   - byte payloads are capped at 8 MiB per op (whole-object buffering
-//     over four relay hops; streaming stays unsupported on both sandbox arms).
+//   - a host with an HTTP byte route takes and serves bytes there; a
+//     SharedWorker host has none and takes frames, in 4 MiB parts past that.
 // `getSignedUrl` does NOT relay: it stays the byte-identical local stub.
 /** firebase-admin's rules-bypass lens, pinned on every relayed operation. */
 const STORAGE_REMOTE_ADMIN_LENS = { mode: 'admin' };
 /**
- * Raw per-op byte cap for relayed storage payloads. MUST mirror
- * `@pyric/cli`' `MAX_STORAGE_OP_BYTES` (serve/worker/protocol.ts) — the
+ * Raw per-part byte cap for storage payloads sent as frames. MUST mirror
+ * `@pyric/cli`' `MAX_STORAGE_PART_BYTES` (serve/worker/protocol.ts) — the
  * worker host enforces the same cap on its end. Inlined (like the RTDB
  * push-id generator) because `pyric-admin` deliberately does not depend on
  * `@pyric/cli`.
  */
-const MAX_REMOTE_STORAGE_OP_BYTES = 8 * 1024 * 1024;
+const MAX_STORAGE_PART_BYTES = 4 * 1024 * 1024;
+/** Maximum whole-object size supported by the sandbox backend (512 MiB). Matches MAX_STORAGE_OBJECT_BYTES. */
+const MAX_STORAGE_OBJECT_BYTES = 512 * 1024 * 1024;
 /** One remote `Storage` per remote handle (handles only — never data). */
 const remoteStorageBySandbox = new WeakMap();
 function getRemoteStorage(sandbox) {
@@ -283,38 +385,183 @@ class RemoteFile {
         if (options.resumable === true) {
             throw new Error('not implemented in pyric-admin/storage remote sandbox backend: resumable uploads');
         }
-        const bytes = toBytes(data);
-        if (bytes.byteLength > MAX_REMOTE_STORAGE_OP_BYTES) {
-            throw payloadTooLarge(bytes.byteLength, `save() payload for '${this.name}'`);
+        const rawLength = typeof data === 'string' ? Buffer.byteLength(data, 'utf8') : data.byteLength;
+        if (rawLength > MAX_STORAGE_OBJECT_BYTES) {
+            throw quotaExceeded(rawLength, `save() payload for '${this.name}'`);
         }
-        await this.channel.op({
-            method: 'storage.putBytes',
-            path: this.name,
-            dataB64: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64'),
+        await this.upload(new Blob([toBytes(data)]), options);
+    }
+    async download(options = {}) {
+        const parts = [];
+        for await (const part of this.read(options))
+            parts.push(part);
+        return [Buffer.concat(parts)];
+    }
+    createReadStream(options = {}) {
+        return Readable.from(this.read(options), { objectMode: false });
+    }
+    createWriteStream(options = {}) {
+        return spooledWriteStream(async (spooled) => {
+            const data = await openAsBlob(spooled);
+            if (data.size > MAX_STORAGE_OBJECT_BYTES) {
+                throw quotaExceeded(data.size, `createWriteStream() payload for '${this.name}'`);
+            }
+            await this.upload(data, options);
+        });
+    }
+    /** Store `data` over the host's byte route, or as one frame when the host has none. */
+    async upload(data, options) {
+        const request = {
             ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),
             ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
+        };
+        const route = await this.channel.byteRoute?.();
+        const routed = route !== undefined;
+        if (routed) {
+            await uploadOverByteRoute(this.channel, route, { path: this.name, data, ...request, actAs: STORAGE_REMOTE_ADMIN_LENS });
+            return;
+        }
+        const bytes = new Uint8Array(await data.arrayBuffer());
+        if (bytes.byteLength <= MAX_STORAGE_PART_BYTES) {
+            await this.channel.op({
+                method: 'storage.putBytes',
+                path: this.name,
+                dataB64: base64Of(bytes),
+                ...request,
+                actAs: STORAGE_REMOTE_ADMIN_LENS,
+            });
+            return;
+        }
+        // A SharedWorker host takes a larger object in parts (ADR 0015).
+        const { uploadId } = (await this.channel.op({
+            method: 'storage.beginUpload',
+            path: this.name,
+            size: bytes.byteLength,
+            ...request,
             actAs: STORAGE_REMOTE_ADMIN_LENS,
-        });
+        }));
+        try {
+            for (let offset = 0, index = 0; offset < bytes.byteLength; offset += MAX_STORAGE_PART_BYTES, index++) {
+                await this.channel.op({
+                    method: 'storage.putPart',
+                    uploadId,
+                    partIndex: index,
+                    dataB64: base64Of(bytes.subarray(offset, offset + MAX_STORAGE_PART_BYTES)),
+                    actAs: STORAGE_REMOTE_ADMIN_LENS,
+                });
+            }
+            await this.channel.op({ method: 'storage.finishUpload', uploadId, actAs: STORAGE_REMOTE_ADMIN_LENS });
+        }
+        catch (err) {
+            try {
+                await this.channel.op({ method: 'storage.abortUpload', uploadId, actAs: STORAGE_REMOTE_ADMIN_LENS });
+            }
+            catch {
+                // secondary abort best effort
+            }
+            throw err;
+        }
     }
-    async download(_options = {}) {
-        let wire;
+    /** The object's bytes, or the inclusive range `start..end`, as they arrive. */
+    async *read(options) {
+        const metadata = await this.missingAsNoSuchObject(this.channel.op({
+            method: 'storage.getMetadata',
+            path: this.name,
+            actAs: STORAGE_REMOTE_ADMIN_LENS,
+        }));
+        const route = await this.channel.byteRoute?.();
+        const routed = route !== undefined;
+        if (!routed) {
+            yield* this.readFrames(metadata, options);
+            return;
+        }
+        const response = await this.missingAsNoSuchObject(fetchFromByteRoute(route, {
+            bucket: metadata.bucket,
+            path: this.name,
+            start: options.start,
+            end: options.end,
+        }));
+        const body = response.body;
+        if (body === null)
+            return;
+        const reader = body.getReader();
         try {
-            wire = (await this.channel.op({
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                yield value;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /** Read from a SharedWorker host, which sends bytes as frames: whole, or in ranged parts (ADR 0015). */
+    async *readFrames(metadata, options) {
+        if (metadata.size <= MAX_STORAGE_PART_BYTES) {
+            const wire = await this.missingAsNoSuchObject(this.channel.op({
+                method: 'storage.getBytes',
+                path: this.name,
+                actAs: STORAGE_REMOTE_ADMIN_LENS,
+            }));
+            yield byteRange(Buffer.from(wire.dataB64, 'base64'), options);
+            return;
+        }
+        const last = Math.min(metadata.size, options.end === undefined ? metadata.size : options.end + 1);
+        for (let offset = options.start ?? 0; offset < last; offset += MAX_STORAGE_PART_BYTES) {
+            const wire = await this.missingAsNoSuchObject(this.channel.op({
                 method: 'storage.getBytes',
                 path: this.name,
+                offset,
+                length: Math.min(MAX_STORAGE_PART_BYTES, last - offset),
+                expectedGeneration: metadata.generation,
                 actAs: STORAGE_REMOTE_ADMIN_LENS,
             }));
+            yield Buffer.from(wire.dataB64, 'base64');
+        }
+    }
+    async getMetadata() {
+        const full = await this.missingAsNoSuchObject(this.channel.op({
+            method: 'storage.getMetadata',
+            path: this.name,
+            actAs: STORAGE_REMOTE_ADMIN_LENS,
+        }));
+        return [fileMetadataOf(full)];
+    }
+    async setMetadata(metadata) {
+        const full = await this.missingAsNoSuchObject(this.channel.op({
+            method: 'storage.setMetadata',
+            path: this.name,
+            patch: patchOf(metadata, { strict: true }),
+            actAs: STORAGE_REMOTE_ADMIN_LENS,
+        }));
+        return [fileMetadataOf(full)];
+    }
+    /** The host mints the token; the Node host serves the URL, a SharedWorker host has nowhere to. */
+    async [DOWNLOAD_URL]() {
+        const { path } = await this.missingAsNoSuchObject(this.channel.op({
+            method: 'storage.getDownloadURL',
+            path: this.name,
+            actAs: STORAGE_REMOTE_ADMIN_LENS,
+        }));
+        const route = await this.channel.byteRoute?.();
+        const routed = route !== undefined;
+        if (routed)
+            return new URL(path, route.baseUrl).href;
+        const [[metadata], [bytes]] = await Promise.all([this.getMetadata(), this.download()]);
+        return dataUri(bytes, metadata.contentType);
+    }
+    /** Mirror the gcs/firebase-admin (and local arm) `No such object` message for a missing file. */
+    async missingAsNoSuchObject(pending) {
+        try {
+            return await pending;
         }
         catch (err) {
-            if (isObjectNotFound(err)) {
-                // Mirror the gcs/firebase-admin (and local arm) message shape so
-                // consumer catch-blocks that string-match `No such object` work
-                // identically across arms.
+            if (isObjectNotFound(err))
                 throw new Error(`No such object: ${this.bucket.name}/${this.name}`);
-            }
             throw err;
         }
-        return [Buffer.from(wire.dataB64, 'base64')];
     }
     async delete() {
         try {
@@ -353,31 +600,124 @@ class RemoteFile {
     async getSignedUrl(options) {
         return [stubSignedUrl(this.bucket.name, this.name, options)];
     }
-    // ─── Deferred surface (remediating throws, remote-flavored) ─────────
-    createWriteStream() {
-        throw new Error('not implemented in pyric-admin/storage remote sandbox backend: createWriteStream — ' +
-            'streams cannot span the bridge relay; use file.save(buffer) (≤ 8 MiB) instead.');
-    }
-    createReadStream() {
-        throw new Error('not implemented in pyric-admin/storage remote sandbox backend: createReadStream — ' +
-            'streams cannot span the bridge relay; use file.download() (≤ 8 MiB) instead.');
+}
+/** A host's metadata in `@google-cloud/storage`'s shape: the download tokens become the custom key production uses. */
+function fileMetadataOf(host) {
+    const custom = { ...(host.customMetadata ?? {}) };
+    if (host.downloadTokens)
+        custom[DOWNLOAD_TOKENS_KEY] = host.downloadTokens;
+    const settable = {};
+    for (const field of SETTABLE_FIELDS) {
+        const value = host[field];
+        if (value !== undefined)
+            settable[field] = value;
     }
+    const hasCustom = Object.keys(custom).length > 0;
+    return {
+        name: host.fullPath,
+        bucket: host.bucket,
+        generation: host.generation,
+        metageneration: host.metageneration,
+        size: String(host.size),
+        timeCreated: host.timeCreated,
+        updated: host.updated,
+        ...settable,
+        ...(host.md5Hash !== undefined ? { md5Hash: host.md5Hash } : {}),
+        ...(hasCustom ? { metadata: custom } : {}),
+    };
 }
 /** Is this relayed error the worker's `storage/object-not-found`? */
 function isObjectNotFound(err) {
     return err?.code === 'storage/object-not-found';
 }
-/** Over-cap rejection (code `payload-too-large`) — mirrors the worker host's
- *  message shape and names the streaming gap. */
-function payloadTooLarge(sizeBytes, what) {
+/** Over-cap rejection (code `storage/quota-exceeded`) — mirrors the worker host's message shape. */
+function quotaExceeded(sizeBytes, what) {
     const err = new Error(`pyric-admin/storage: ${what} is ${sizeBytes} bytes — over the ` +
-        `${MAX_REMOTE_STORAGE_OP_BYTES / (1024 * 1024)} MiB remote storage op cap. ` +
-        'Streaming/resumable transfers are not supported on the sandbox backend; ' +
-        'split the object or keep it under the cap.');
-    err.code = 'payload-too-large';
+        `${MAX_STORAGE_OBJECT_BYTES / (1024 * 1024)} MiB maximum storage object cap (MAX_STORAGE_OBJECT_BYTES).`);
+    err.code = 'storage/quota-exceeded';
     return err;
 }
-// ─── Helpers ────────────────────────────────────────────────────────────
+/**
+ * Split `@google-cloud/storage`-shaped metadata into a {@link MetadataPatch}.
+ * `setMetadata` is strict and refuses fields the sandbox does not keep;
+ * `save` has always stored what it was given and ignores them.
+ */
+function patchOf(metadata, { strict }) {
+    const source = metadata;
+    const unsupported = Object.keys(source).filter(key => key !== 'metadata' && !SETTABLE_FIELDS.includes(key));
+    const refused = strict && unsupported.length > 0;
+    if (refused) {
+        throw new Error(`not implemented in pyric-admin/storage sandbox backend: setMetadata of ${unsupported.join(', ')}. ` +
+            `The sandbox keeps ${SETTABLE_FIELDS.join(', ')}, and custom metadata under \`metadata\`.`);
+    }
+    const patch = { settable: {}, customMetadata: {} };
+    for (const field of SETTABLE_FIELDS) {
+        const value = source[field];
+        if (typeof value === 'string')
+            patch.settable[field] = value;
+    }
+    const custom = source.metadata;
+    const hasCustom = custom !== null && typeof custom === 'object';
+    if (!hasCustom)
+        return patch;
+    for (const [key, value] of Object.entries(custom)) {
+        if (value === undefined)
+            continue;
+        const next = value === null ? null : String(value);
+        if (key === DOWNLOAD_TOKENS_KEY)
+            patch.downloadTokens = next;
+        else
+            patch.customMetadata[key] = next;
+    }
+    return patch;
+}
+/** A `data:` URI carrying `bytes`, the download URL where no host serves them over HTTP. */
+function dataUri(bytes, contentType) {
+    return `data:${contentType ?? 'application/octet-stream'};base64,${base64Of(bytes)}`;
+}
+/** `bytes` as base64, for a frame. */
+function base64Of(bytes) {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64');
+}
+/** The inclusive range `start..end` of `bytes`, as `@google-cloud/storage` reads it. */
+function byteRange(bytes, options) {
+    const end = options.end === undefined ? undefined : options.end + 1;
+    return bytes.subarray(options.start ?? 0, end);
+}
+/**
+ * A writable stream that spools its bytes to a temporary file and, once it
+ * finishes, hands that file to `commit`. The file is removed either way.
+ */
+function spooledWriteStream(commit) {
+    let directory;
+    let sink;
+    return new Writable({
+        construct(callback) {
+            mkdtemp(join(tmpdir(), 'pyric-admin-upload-')).then(created => {
+                directory = created;
+                sink = createFileWriteStream(join(created, 'object'));
+                callback();
+            }, callback);
+        },
+        write(chunk, _encoding, callback) {
+            sink.write(chunk, callback);
+        },
+        final(callback) {
+            sink.end(() => {
+                commit(join(directory, 'object')).then(() => callback(), callback);
+            });
+        },
+        destroy(error, callback) {
+            sink?.destroy();
+            const created = directory;
+            if (created === undefined) {
+                callback(error);
+                return;
+            }
+            rm(created, { recursive: true, force: true }).finally(() => callback(error));
+        },
+    });
+}
 /**
  * The deterministic sandbox signed-URL stub, shared by the local and remote
  * arms so their output is byte-identical (the URL is never served — it's a