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

package/dist/storage/index.js

@@ -9,8 +9,13 @@
  *     `connectRemoteSandbox()`/`remoteSandbox()` relays every data
  *     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.
+ *     frames when it does not (a browser tab's SharedWorker). Each bucket
+ *     name is its own bucket on the host; the default bucket is the host's
+ *     default one. `createResumableUpload` gives a session URL on the byte
+ *     route. `getSignedUrl` stays the local stub. See the remote arm section below.
+ *
+ *   - **Default bucket**: `bucket()` is the bucket the app's `storageBucket`
+ *     option names, or `'pyric-default'` without one, on both paths.
  *
  *   - **Sandbox path** — returns an in-process {@link Storage} backed
  *     by an in-memory `Map<bucketName, Map<path, FileEntry>>`. State
@@ -26,6 +31,9 @@
  *       - `file.download(options?)` → `[Buffer]`, whole or `start..end`
  *       - `file.createReadStream(options?)`, whole or `start..end`
  *       - `file.createWriteStream(options?)`
+ *       - `save` and `createWriteStream` take `firebaseStorageDownloadTokens`
+ *         under `metadata.metadata` as the file's download tokens, which grant
+ *         its download URL as `getDownloadURL` mints them
  *       - `file.getMetadata()` / `file.setMetadata(metadata)`: settable fields
  *         and custom metadata; a custom key set to `null` is removed
  *       - `getDownloadURL(file)`: mints a token into
@@ -34,11 +42,17 @@
  *       - `file.delete()` — idempotent
  *       - `file.exists()` → `[boolean]`
  *       - `file.getSignedUrl(options)` → `['pyric-sandbox-storage://…']`
+ *       - `file.copy(destination, options?)`, within a bucket or across buckets
+ *       - `bucket.getFiles(query?)` → `[files, nextQuery, apiResponse]`, with
+ *         `prefix`, `delimiter`, `maxResults`, `pageToken`, `autoPaginate`
+ *       - `bucket.deleteFiles(query?)`, honoring `force`
  *
  *     **Deferred in the sandbox backend** (throws `"not implemented in
- *     pyric-admin/storage sandbox backend"`): resumable uploads, signed
- *     cookies, IAM policies, lifecycle rules, ACLs, copy/move,
- *     notifications.
+ *     pyric-admin/storage sandbox backend"`): `file.createResumableUpload`
+ *     upload sessions, which need an HTTP host, signed cookies, IAM
+ *     policies, lifecycle rules, ACLs, move, notifications. Every other
+ *     `Bucket` and `File` method is a deferred member listed in
+ *     `deferred-members.ts`.
  */
 import { createWriteStream as createFileWriteStream, openAsBlob } from 'node:fs';
 import { randomUUID } from 'node:crypto';
@@ -47,9 +61,16 @@ 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 { deleteObject as storageDeleteObject, getMetadata as storageGetMetadata, ref as storageRef, } from 'pyric/storage';
+import { copyObject, fetchFromByteRoute, getAdminStorageSandbox, getStorageService, patchObjectMetadata, uploadObject, uploadOverByteRoute, } from 'pyric/storage/internal';
 import { ADMIN_APP_TARGET, getApp, } from '../app/index.js';
 import { assertAdminAppActive } from '../app/lifecycle.js';
+import { defineDeferredMembers } from 'pyric/app/internal';
+import { BUCKET_DEFERRED_MEMBERS, FILE_DEFERRED_MEMBERS } from './deferred-members.js';
+import { deleteListedFiles } from './delete-files.js';
+import { assertQuery } from './file-query.js';
+import { getFilesResponse } from './get-files.js';
+import { namesUnderPrefix } from './remote-names.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. */
@@ -71,10 +92,11 @@ export function getStorage(app) {
         // must never touch a remote handle — local state keyed off a remote
         // handle would be a private server-side store the browser never sees,
         // and `onEvent` throws on remote handles by design.
+        const defaultBucket = resolved.options.storageBucket ?? DEFAULT_SANDBOX_BUCKET;
         if (isRemoteSandbox(resolved.sandbox)) {
-            return getRemoteStorage(resolved.sandbox);
+            return getRemoteStorage(resolved.sandbox, defaultBucket);
         }
-        return getSandboxStorage(resolved);
+        return getSandboxStorage(resolved, defaultBucket);
     }
     // Defensive: the union is closed at the type level. A runtime value
     // that lands here means a caller forged a handle without going
@@ -107,179 +129,198 @@ 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
- * `WeakMap` lets a discarded `Sandbox` (and its state) be GC'd
+ * Sandbox shares its storage across every `getStorage` call and with
+ * `pyric/storage`. The `WeakMap` lets a discarded `Sandbox` be GC'd
  * naturally.
  */
 const SANDBOX_STATE = new WeakMap();
-/**
- * Reset-subscription bookkeeping. We subscribe to `sandbox.onEvent`
- * once per Sandbox and re-create the bucket map on
- * `session_boundary` events with `phase: 'reset'`. Without this,
- * `sandbox.reset()` would wipe Firestore but leave storage untouched —
- * a leak the sandbox model deliberately avoids.
- */
-const RESET_HOOKED = new WeakSet();
-function ensureBucketMap(sandbox) {
-    let map = SANDBOX_STATE.get(sandbox);
-    if (!map) {
-        map = new Map();
-        SANDBOX_STATE.set(sandbox, map);
-    }
-    if (!RESET_HOOKED.has(sandbox)) {
-        RESET_HOOKED.add(sandbox);
+function ensureSandboxStorageState(sandbox, defaultBucket) {
+    let state = SANDBOX_STATE.get(sandbox);
+    if (!state) {
+        state = {
+            dbName: `pyric-admin-storage:${randomUUID()}`,
+            defaultBucketNames: new Set([DEFAULT_SANDBOX_BUCKET]),
+            buckets: new Set([DEFAULT_SANDBOX_BUCKET]),
+            pendingReset: undefined,
+        };
+        SANDBOX_STATE.set(sandbox, state);
         sandbox.onEvent((event) => {
             if (event.kind === 'session_boundary' && event.phase === 'reset') {
-                // Replace the map in place so existing Storage / Bucket / File
-                // handles keep working but observe an empty state.
-                const existing = SANDBOX_STATE.get(sandbox);
-                if (existing)
-                    existing.clear();
+                const current = SANDBOX_STATE.get(sandbox);
+                if (!current)
+                    return;
+                const previous = current.pendingReset ?? Promise.resolve();
+                const bucketsToReset = [...current.buckets];
+                const nextReset = previous
+                    .then(async () => {
+                    await Promise.all(bucketsToReset.map(async (bucket) => {
+                        const handle = getAdminStorageSandbox(sandbox, {
+                            dbName: current.dbName,
+                            bucket,
+                        });
+                        const service = await getStorageService(handle);
+                        await service.backend.reset(bucket);
+                    }));
+                })
+                    .catch(() => {
+                    // Best-effort reset across open bucket handles
+                });
+                current.pendingReset = nextReset;
             }
         });
     }
-    return map;
+    state.defaultBucketNames.add(defaultBucket);
+    return state;
 }
-function getSandboxStorage(app) {
+function getSandboxStorage(app, defaultBucket) {
     const sandbox = app.sandbox;
-    const buckets = ensureBucketMap(sandbox);
-    return new SandboxStorage(buckets);
+    const state = ensureSandboxStorageState(sandbox, defaultBucket);
+    return new SandboxStorage(sandbox, state, defaultBucket);
 }
 /**
- * Sandbox `Storage` implementation. Holds a reference to the per-
- * sandbox bucket map; each `bucket()` call returns a fresh `Bucket`
- * handle bound to the same underlying map, mirroring how
- * `@google-cloud/storage` returns lightweight per-call handles.
+ * Sandbox `Storage` implementation. Delegates to the per-sandbox
+ * `pyric/storage` admin plane (`getAdminStorageSandbox`) so `pyric-admin/storage`,
+ * `pyric/storage`, and `captureFullState` share one object store.
  */
 class SandboxStorage {
-    buckets;
-    constructor(buckets) {
-        this.buckets = buckets;
+    sandbox;
+    state;
+    defaultBucket;
+    constructor(sandbox, state, defaultBucket) {
+        this.sandbox = sandbox;
+        this.state = state;
+        this.defaultBucket = defaultBucket;
+    }
+    storeBucketOf(bucketName) {
+        if (bucketName === DEFAULT_SANDBOX_BUCKET ||
+            bucketName === this.defaultBucket ||
+            this.state.defaultBucketNames.has(bucketName)) {
+            return DEFAULT_SANDBOX_BUCKET;
+        }
+        return bucketName;
+    }
+    async waitForReset() {
+        while (this.state.pendingReset !== undefined) {
+            const pending = this.state.pendingReset;
+            await pending;
+            if (this.state.pendingReset === pending) {
+                this.state.pendingReset = undefined;
+            }
+        }
     }
     bucket(name) {
-        const bucketName = name ?? DEFAULT_SANDBOX_BUCKET;
-        let files = this.buckets.get(bucketName);
-        if (!files) {
-            files = new Map();
-            this.buckets.set(bucketName, files);
-        }
-        return new SandboxBucket(bucketName, files);
+        const bucketName = name ?? this.defaultBucket;
+        const storeBucket = this.storeBucketOf(bucketName);
+        this.state.buckets.add(storeBucket);
+        return new SandboxBucket(bucketName, storeBucket, this);
     }
 }
 class SandboxBucket {
     name;
-    files;
-    constructor(name, files) {
+    storeBucket;
+    storage;
+    constructor(name, storeBucket, storage) {
         this.name = name;
-        this.files = files;
+        this.storeBucket = storeBucket;
+        this.storage = storage;
+    }
+    adminStorage() {
+        this.storage.state.buckets.add(this.storeBucket);
+        return getAdminStorageSandbox(this.storage.sandbox, {
+            dbName: this.storage.state.dbName,
+            bucket: this.storeBucket,
+        });
     }
     file(path) {
-        return new SandboxFile(path, this, this.files);
+        return new SandboxFile(path, this);
+    }
+    async getFiles(query = {}) {
+        assertQuery(query, 'getFiles');
+        return getFilesResponse(await this.namesUnder(query.prefix ?? ''), query, (name) => this.file(name));
+    }
+    async deleteFiles(query = {}) {
+        assertQuery(query, 'deleteFiles');
+        await deleteListedFiles(await this.namesUnder(query.prefix ?? ''), query, (name) => this.file(name).delete());
+    }
+    async namesUnder(prefix) {
+        await this.storage.waitForReset();
+        const service = await getStorageService(this.adminStorage());
+        const items = await service.backend.listByPrefix(prefix, this.storeBucket);
+        return items.map((item) => item.fullPath);
     }
 }
 class SandboxFile {
     name;
     bucket;
-    files;
-    constructor(name, bucket, files) {
+    constructor(name, bucket) {
         this.name = name;
         this.bucket = bucket;
-        this.files = files;
     }
+    /**
+      * Store `data` in one write. `resumable` only chooses how
+      * `@google-cloud/storage` sends the bytes; the stored object is the same.
+      */
     async save(data, options = {}) {
-        if (options.resumable === true) {
-            throw new Error('not implemented in pyric-admin/storage sandbox backend: resumable uploads');
+        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.bucket.storage.waitForReset();
         const bytes = toBytes(data);
-        const saved = patchOf(options.metadata ?? {}, { strict: false });
+        const saved = savedMetadataOf(options.metadata ?? {});
         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,
-            settable: { ...saved.settable, ...(contentType !== undefined ? { contentType } : {}) },
-            custom,
-            generation: nextGeneration(),
-            metageneration: 1,
-            timeCreated: now,
-            updated: now,
-        });
+        const settable = {
+            ...saved.settable,
+            ...(contentType !== undefined ? { contentType } : {}),
+            ...(Object.keys(saved.custom).length > 0 ? { customMetadata: saved.custom } : {}),
+        };
+        await uploadObject(storageRef(this.bucket.adminStorage(), this.name), bytes, settable, { ...(saved.downloadTokens !== undefined ? { downloadTokens: saved.downloadTokens } : {}) });
     }
     async getMetadata() {
-        return [this.metadataOf(this.entry())];
+        await this.bucket.storage.waitForReset();
+        const full = (await this.missingAsNoSuchObject(storageGetMetadata(storageRef(this.bucket.adminStorage(), this.name))));
+        return [fileMetadataOf({ ...full, bucket: this.bucket.name })];
     }
     async setMetadata(metadata) {
-        const entry = this.entry();
+        await this.bucket.storage.waitForReset();
         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)];
+        const full = (await this.missingAsNoSuchObject(patchObjectMetadata(storageRef(this.bucket.adminStorage(), this.name), patch)));
+        return [fileMetadataOf({ ...full, bucket: this.bucket.name })];
     }
     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);
+        await this.bucket.storage.waitForReset();
+        const r = storageRef(this.bucket.adminStorage(), this.name);
+        const full = (await this.missingAsNoSuchObject(storageGetMetadata(r)));
+        const token = (full.downloadTokens ?? '').split(',').find((existing) => existing !== '');
+        if (token === undefined) {
+            await patchObjectMetadata(r, { downloadTokens: randomUUID() });
         }
-        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();
+        const [bytes] = await this.download();
+        return dataUri(bytes, full.contentType);
     }
-    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 } } : {}),
-        };
+    async missingAsNoSuchObject(pending) {
+        try {
+            return await pending;
+        }
+        catch (err) {
+            if (isObjectNotFound(err))
+                throw new Error(`No such object: ${this.bucket.name}/${this.name}`);
+            throw err;
+        }
     }
     async download(options = {}) {
-        const entry = this.files.get(this.name);
-        if (!entry) {
+        await this.bucket.storage.waitForReset();
+        const service = await getStorageService(this.bucket.adminStorage());
+        const object = await service.backend.getObject(this.name, this.bucket.storeBucket);
+        if (!object) {
             // 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(byteRange(entry.data, options))];
+        const bytes = new Uint8Array(await object.blob.arrayBuffer());
+        return [Buffer.from(byteRange(bytes, options))];
     }
     createReadStream(options = {}) {
         const read = async function* (file) {
@@ -291,11 +332,29 @@ class SandboxFile {
     createWriteStream(options = {}) {
         return spooledWriteStream(async (spooled) => this.save(await readFile(spooled), options));
     }
+    async createResumableUpload() {
+        throw new Error('not implemented in pyric-admin/storage sandbox backend: resumable upload sessions (createResumableUpload). ' +
+            'The in-process sandbox has no HTTP host to take the bytes; upload with file.save() or file.createWriteStream().');
+    }
+    async copy(destination, options = {}) {
+        const target = copyTargetOf(this, destination, this.bucket.storage);
+        const local = target instanceof SandboxFile && target.bucket.storage.sandbox === this.bucket.storage.sandbox;
+        if (!local)
+            throw new Error('pyric-admin/storage: File.copy copies to a File from the same getStorage() sandbox.');
+        await this.bucket.storage.waitForReset();
+        const patch = patchOf(copyMetadataOf(options), { strict: false });
+        const full = (await this.missingAsNoSuchObject(copyObject(storageRef(this.bucket.adminStorage(), this.name), storageRef(target.bucket.adminStorage(), target.name), patch)));
+        return [target, fileMetadataOf({ ...full, bucket: target.bucket.name })];
+    }
     async delete() {
-        this.files.delete(this.name);
+        await this.bucket.storage.waitForReset();
+        await storageDeleteObject(storageRef(this.bucket.adminStorage(), this.name));
     }
     async exists() {
-        return [this.files.has(this.name)];
+        await this.bucket.storage.waitForReset();
+        const service = await getStorageService(this.bucket.adminStorage());
+        const stored = await service.backend.getMetadata(this.name, this.bucket.storeBucket);
+        return [stored !== undefined];
     }
     async getSignedUrl(options) {
         return [stubSignedUrl(this.bucket.name, this.name, options)];
@@ -313,13 +372,15 @@ class SandboxFile {
 // the browser never sees, and the local arm's `onEvent` reset hook throws
 // on remote handles by design.
 //
+// Buckets: every op names its bucket, and gives the app's name for the
+// default bucket, so the host stores each named bucket apart and answers to
+// the configured default name, in ops and in byte route URLs alike.
+//
 // Divergences from the local arm, all LOUD:
-//   - single bucket: the worker's `pyric/storage` store is single-bucket
-//     ("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.
 //   - 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.
+//   - a host with a byte route gives `createResumableUpload` session URLs;
+//     the local arm and a SharedWorker host reject it.
 // `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' };
@@ -333,44 +394,75 @@ const STORAGE_REMOTE_ADMIN_LENS = { mode: 'admin' };
 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). */
+/** One remote `Storage` per remote handle and default bucket name (handles only, never data). */
 const remoteStorageBySandbox = new WeakMap();
-function getRemoteStorage(sandbox) {
-    let storage = remoteStorageBySandbox.get(sandbox);
+function getRemoteStorage(sandbox, defaultBucket) {
+    let byDefault = remoteStorageBySandbox.get(sandbox);
+    if (!byDefault) {
+        byDefault = new Map();
+        remoteStorageBySandbox.set(sandbox, byDefault);
+    }
+    let storage = byDefault.get(defaultBucket);
     if (!storage) {
-        storage = new RemoteStorage(sandbox.channel);
-        remoteStorageBySandbox.set(sandbox, storage);
+        storage = new RemoteStorage(sandbox.channel, defaultBucket);
+        byDefault.set(defaultBucket, storage);
     }
     return storage;
 }
 class RemoteStorage {
     channel;
-    constructor(channel) {
+    defaultBucket;
+    constructor(channel, defaultBucket) {
         this.channel = channel;
+        this.defaultBucket = defaultBucket;
     }
+    /** Each bucket name is its own bucket on the host; the default one is the host's default bucket. */
     bucket(name) {
-        // The worker's object store is single-bucket. A non-default name can't
-        // be faithfully relayed — throw loudly instead of silently merging
-        // buckets (the local arm has REAL multi-bucket isolation; this is the
-        // sharpest local/remote divergence, so it must be explicit).
-        if (name !== undefined && name !== DEFAULT_SANDBOX_BUCKET) {
-            throw new Error(`pyric-admin/storage: the remote (browser) sandbox has a single bucket — ` +
-                `bucket('${name}') cannot be isolated. Use bucket() (the default ` +
-                `'${DEFAULT_SANDBOX_BUCKET}' bucket) instead.`);
-        }
-        return new RemoteBucket(DEFAULT_SANDBOX_BUCKET, this.channel);
+        return new RemoteBucket(name ?? this.defaultBucket, this.channel, this);
     }
 }
 class RemoteBucket {
     name;
     channel;
-    constructor(name, channel) {
+    storage;
+    constructor(name, channel, storage) {
         this.name = name;
         this.channel = channel;
+        this.storage = storage;
+    }
+    /**
+     * How ops name this bucket: the default bucket has no `bucket`, and every op
+     * gives the app's name for the default bucket, so the host answers to it.
+     */
+    get wire() {
+        const defaultName = this.storage.defaultBucket;
+        const namesDefault = defaultName !== DEFAULT_SANDBOX_BUCKET;
+        const isDefault = this.name === defaultName;
+        return {
+            ...(isDefault ? {} : { bucket: this.name }),
+            ...(namesDefault ? { defaultBucket: defaultName } : {}),
+        };
     }
     file(path) {
         return new RemoteFile(path, this, this.channel);
     }
+    async getFiles(query = {}) {
+        assertQuery(query, 'getFiles');
+        return getFilesResponse(await this.namesUnder(query.prefix ?? ''), query, name => this.file(name));
+    }
+    async deleteFiles(query = {}) {
+        assertQuery(query, 'deleteFiles');
+        await deleteListedFiles(await this.namesUnder(query.prefix ?? ''), query, name => this.file(name).delete());
+    }
+    /** The host's object names under `prefix`, walked folder by folder with `storage.listAll`. */
+    namesUnder(prefix) {
+        return namesUnderPrefix(prefix, async (path) => (await this.channel.op({
+            method: 'storage.listAll',
+            ...this.wire,
+            path,
+            actAs: STORAGE_REMOTE_ADMIN_LENS,
+        })));
+    }
 }
 class RemoteFile {
     name;
@@ -381,10 +473,11 @@ class RemoteFile {
         this.bucket = bucket;
         this.channel = channel;
     }
+    /**
+     * Store `data` in one upload. `resumable` only chooses how
+     * `@google-cloud/storage` sends the bytes; the stored object is the same.
+     */
     async save(data, options = {}) {
-        if (options.resumable === true) {
-            throw new Error('not implemented in pyric-admin/storage remote sandbox backend: resumable uploads');
-        }
         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}'`);
@@ -409,12 +502,57 @@ class RemoteFile {
             await this.upload(data, options);
         });
     }
-    /** Store `data` over the host's byte route, or as one frame when the host has none. */
+    /**
+     * A session URL on the host's byte route that takes this object's bytes,
+     * as `@google-cloud/storage` returns a resumable upload URI. A browser sends
+     * them in one `PUT`, or in `Content-Range` slices whose first one names the
+     * total size, and the object is created with `metadata` when the last byte
+     * arrives. With `origin`, the URL answers that page origin's cross-origin
+     * requests. A host without a byte route (a browser tab's SharedWorker) has
+     * no URL to give, so this rejects there.
+     */
+    async createResumableUpload(options = {}) {
+        const route = await this.channel.byteRoute?.();
+        const routed = route !== undefined;
+        if (!routed) {
+            throw new Error('not implemented in pyric-admin/storage remote sandbox backend: resumable upload sessions (createResumableUpload) ' +
+                'on a host without an HTTP byte route. Upload with file.save() or file.createWriteStream().');
+        }
+        const { uploadUrl } = (await this.channel.op({
+            method: 'storage.createUploadSession',
+            ...this.bucket.wire,
+            path: this.name,
+            ...uploadRequestOf({ ...(options.metadata !== undefined ? { metadata: options.metadata } : {}) }),
+            ...(options.origin !== undefined ? { origin: options.origin } : {}),
+            actAs: STORAGE_REMOTE_ADMIN_LENS,
+        }));
+        return [new URL(uploadUrl, route.baseUrl).href];
+    }
+    /** Copy this object, with its metadata, to `destination`; `options` change the copy's metadata. */
+    async copy(destination, options = {}) {
+        const target = copyTargetOf(this, destination, this.bucket.storage);
+        const remote = target instanceof RemoteFile && target.channel === this.channel;
+        if (!remote)
+            throw new Error('pyric-admin/storage: File.copy copies to a File from the same remote sandbox.');
+        const destinationWire = target.bucket.wire;
+        const full = await this.missingAsNoSuchObject(this.channel.op({
+            method: 'storage.copyObject',
+            ...this.bucket.wire,
+            path: this.name,
+            ...(destinationWire.bucket !== undefined ? { destinationBucket: destinationWire.bucket } : {}),
+            destinationPath: target.name,
+            patch: patchOf(copyMetadataOf(options), { strict: false }),
+            actAs: STORAGE_REMOTE_ADMIN_LENS,
+        }));
+        return [target, fileMetadataOf(full)];
+    }
+    /**
+     * Store `data` over the host's byte route, or as one frame when the host has
+     * none. `firebaseStorageDownloadTokens` becomes the object's download tokens,
+     * as `setMetadata` sends it, and the other custom keys stay custom metadata.
+     */
     async upload(data, options) {
-        const request = {
-            ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),
-            ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
-        };
+        const request = { ...this.bucket.wire, ...uploadRequestOf(options) };
         const route = await this.channel.byteRoute?.();
         const routed = route !== undefined;
         if (routed) {
@@ -466,6 +604,7 @@ class RemoteFile {
     async *read(options) {
         const metadata = await this.missingAsNoSuchObject(this.channel.op({
             method: 'storage.getMetadata',
+            ...this.bucket.wire,
             path: this.name,
             actAs: STORAGE_REMOTE_ADMIN_LENS,
         }));
@@ -477,6 +616,7 @@ class RemoteFile {
         }
         const response = await this.missingAsNoSuchObject(fetchFromByteRoute(route, {
             bucket: metadata.bucket,
+            ...this.bucket.wire,
             path: this.name,
             start: options.start,
             end: options.end,
@@ -502,6 +642,7 @@ class RemoteFile {
         if (metadata.size <= MAX_STORAGE_PART_BYTES) {
             const wire = await this.missingAsNoSuchObject(this.channel.op({
                 method: 'storage.getBytes',
+                ...this.bucket.wire,
                 path: this.name,
                 actAs: STORAGE_REMOTE_ADMIN_LENS,
             }));
@@ -512,6 +653,7 @@ class RemoteFile {
         for (let offset = options.start ?? 0; offset < last; offset += MAX_STORAGE_PART_BYTES) {
             const wire = await this.missingAsNoSuchObject(this.channel.op({
                 method: 'storage.getBytes',
+                ...this.bucket.wire,
                 path: this.name,
                 offset,
                 length: Math.min(MAX_STORAGE_PART_BYTES, last - offset),
@@ -524,6 +666,7 @@ class RemoteFile {
     async getMetadata() {
         const full = await this.missingAsNoSuchObject(this.channel.op({
             method: 'storage.getMetadata',
+            ...this.bucket.wire,
             path: this.name,
             actAs: STORAGE_REMOTE_ADMIN_LENS,
         }));
@@ -532,6 +675,7 @@ class RemoteFile {
     async setMetadata(metadata) {
         const full = await this.missingAsNoSuchObject(this.channel.op({
             method: 'storage.setMetadata',
+            ...this.bucket.wire,
             path: this.name,
             patch: patchOf(metadata, { strict: true }),
             actAs: STORAGE_REMOTE_ADMIN_LENS,
@@ -542,6 +686,7 @@ class RemoteFile {
     async [DOWNLOAD_URL]() {
         const { path } = await this.missingAsNoSuchObject(this.channel.op({
             method: 'storage.getDownloadURL',
+            ...this.bucket.wire,
             path: this.name,
             actAs: STORAGE_REMOTE_ADMIN_LENS,
         }));
@@ -567,6 +712,7 @@ class RemoteFile {
         try {
             await this.channel.op({
                 method: 'storage.deleteObject',
+                ...this.bucket.wire,
                 path: this.name,
                 actAs: STORAGE_REMOTE_ADMIN_LENS,
             });
@@ -584,6 +730,7 @@ class RemoteFile {
         try {
             await this.channel.op({
                 method: 'storage.getMetadata',
+                ...this.bucket.wire,
                 path: this.name,
                 actAs: STORAGE_REMOTE_ADMIN_LENS,
             });
@@ -637,6 +784,34 @@ function quotaExceeded(sizeBytes, what) {
     err.code = 'storage/quota-exceeded';
     return err;
 }
+// ─── Helpers ────────────────────────────────────────────────────────────
+/**
+ * The File a copy writes: a path in the source's bucket, a `gs://` URL, the
+ * source's path in another Bucket, or a File.
+ */
+function copyTargetOf(source, destination, storage) {
+    if (typeof destination === 'string') {
+        const url = /^gs:\/\/([^/]+)\/(.+)$/.exec(destination);
+        return url === null ? source.bucket.file(destination) : storage.bucket(url[1]).file(url[2]);
+    }
+    const isFile = 'save' in destination;
+    return isFile ? destination : destination.file(source.name);
+}
+/** {@link CopyOptions} as the metadata `save` takes: settable fields, and custom keys under `metadata`. */
+function copyMetadataOf(options) {
+    const { metadata, ...settable } = options;
+    return { ...settable, ...(metadata !== undefined ? { metadata } : {}) };
+}
+/** What an upload sends besides its bytes: settable fields and custom metadata, with the download tokens apart. */
+function uploadRequestOf(options) {
+    const saved = options.metadata === undefined ? undefined : savedMetadataOf(options.metadata);
+    const hasCustom = saved !== undefined && Object.keys(saved.custom).length > 0;
+    return {
+        ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),
+        ...(saved !== undefined ? { metadata: { ...saved.settable, ...(hasCustom ? { metadata: saved.custom } : {}) } } : {}),
+        ...(saved?.downloadTokens !== undefined ? { downloadTokens: saved.downloadTokens } : {}),
+    };
+}
 /**
  * Split `@google-cloud/storage`-shaped metadata into a {@link MetadataPatch}.
  * `setMetadata` is strict and refuses fields the sandbox does not keep;
@@ -671,6 +846,20 @@ function patchOf(metadata, { strict }) {
     }
     return patch;
 }
+/**
+ * The metadata `save` and `createWriteStream` create an object with. It is the
+ * {@link patchOf} split `setMetadata` uses, so `firebaseStorageDownloadTokens`
+ * becomes the object's download tokens on every path; a `null` key is not stored.
+ */
+function savedMetadataOf(metadata) {
+    const patch = patchOf(metadata, { strict: false });
+    const custom = {};
+    for (const [key, value] of Object.entries(patch.customMetadata))
+        if (value !== null)
+            custom[key] = value;
+    const tokens = patch.downloadTokens;
+    return { settable: patch.settable, custom, ...(typeof tokens === 'string' ? { downloadTokens: tokens } : {}) };
+}
 /** 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)}`;
@@ -758,4 +947,14 @@ function normalizeExpires(expires) {
     // strictness because the value only feeds the deterministic sandbox stub.
     return new Date(expires).getTime();
 }
+// ─── Deferred members ────────────────────────────────────────────────────
+//
+// The `Bucket` and `File` methods neither arm models fail with an error that
+// names the method instead of reading as `undefined`. See deferred-members.ts.
+for (const bucket of [SandboxBucket, RemoteBucket]) {
+    defineDeferredMembers(bucket.prototype, 'pyric-admin/storage', 'Bucket', BUCKET_DEFERRED_MEMBERS);
+}
+for (const file of [SandboxFile, RemoteFile]) {
+    defineDeferredMembers(file.prototype, 'pyric-admin/storage', 'File', FILE_DEFERRED_MEMBERS);
+}
 //# sourceMappingURL=index.js.map