@augmentd-labs/canvas-edge 0.6.3 → 0.7.0

package/node_modules/canvas-stored/src/backends/file/index.js

@@ -27,7 +27,8 @@ export default class FileBackend extends StorageBackend {
     #tempDir;
     #tempRel = null;
     #watcher = null;
-    #watchEnabled;
+    #watchEpoch = 0;
+    #rootReady;
     #ignored;
     #ignoreMatcher = null;
     #defaultAlgorithms = ['sha256'];
@@ -42,7 +43,6 @@ export default class FileBackend extends StorageBackend {
         this.#tempDir = config.tempDir ? path.resolve(this.#root, String(config.tempDir)) : path.join(this.#root, TMP_DIR);
         const tempRel = path.relative(this.#root, this.#tempDir).split(path.sep).join('/');
         this.#tempRel = tempRel && !tempRel.startsWith('..') && !path.isAbsolute(tempRel) ? tempRel : null;
-        this.#watchEnabled = config.watch ?? false;
         this.#ignored = config.ignored || null;
         this.#ignoreMatcher = this.#buildIgnoreMatcher(this.#ignored);
         this.#defaultAlgorithms = config.algorithms || ['sha256'];
@@ -52,7 +52,12 @@ export default class FileBackend extends StorageBackend {
         // creating an empty dir at an unmounted mountpoint makes an absent
         // drive indistinguishable from an empty one — verifyRoot() + the
         // resync liveness gate rely on the root being genuinely missing.
-        if (config.createRoot !== false) fs.ensureDirSync(this.#root);
+        // A stat/mkdir on an unresponsive NAS can block the whole Node thread.
+        // Registration stays synchronous; filesystem users await readiness.
+        this.#rootReady = config.createRoot !== false ? fs.ensureDir(this.#root) : Promise.resolve();
+        // Keep registration fire-and-forget safe. ready()/operations still
+        // observe and propagate the original failure.
+        this.#rootReady.catch(() => {});
 
         // Network mount detection. A CIFS/NFS share reached through a POSIX path
         // is indistinguishable from local disk to every fs call we make, so the
@@ -69,10 +74,13 @@ export default class FileBackend extends StorageBackend {
     get root() { return this.#root; }
     get tempDir() { return this.#tempDir; }
     get watching() { return !!this.#watcher; }
-    get capabilities() { return { ...super.capabilities, canEnumerate: true }; }
+    static getCapabilities(config = {}) {
+        return { ...super.getCapabilities(config), canEnumerate: true, paths: true, mutableContainers: config.readOnly !== true, upload: config.readOnly !== true };
+    }
     get remote() { return this.#remote; }
     get transport() { return this.#transport; }
     get mountSource() { return this.#mountSource; }
+    ready() { return this.#rootReady; }
 
     /**
      * Absolute on-disk path for `key`. Public because cross-backend copy/move
@@ -152,6 +160,7 @@ export default class FileBackend extends StorageBackend {
         const snapshot = expected || this.config.fsid || null;
         let stats;
         try {
+            await this.ready();
             stats = await fs.stat(this.#root);
         } catch {
             return { ok: false, reason: 'root-missing', fsid: null };
@@ -164,6 +173,15 @@ export default class FileBackend extends StorageBackend {
         if (snapshot?.ino != null && Number(snapshot.ino) !== stats.ino) {
             return { ok: false, reason: 'root-replaced', fsid };
         }
+        // `config.marker` ({ file, id }) binds the folder to whoever keeps
+        // history about it: an empty directory standing in for an unmounted
+        // drive, or another folder at the same path, does not carry the id.
+        const marker = this.config.marker;
+        if (marker?.file) {
+            let found = null;
+            try { found = (await fs.readFile(path.join(this.#root, marker.file), 'utf8')).trim(); } catch { /* absent */ }
+            if (found !== String(marker.id)) return { ok: false, reason: found == null ? 'marker-missing' : 'marker-mismatch', fsid };
+        }
         return { ok: true, fsid };
     }
 
@@ -190,6 +208,7 @@ export default class FileBackend extends StorageBackend {
     // backends reflect the byte changes; empty directories are surfaced by the
     // caller (Workspace) inserting a tree node.
     async createContainer(key) {
+        await this.ready();
         const dir = this.#safeResolve(key);
         await fs.ensureDir(dir);
         debug(`MKDIR ${key}`);
@@ -197,6 +216,7 @@ export default class FileBackend extends StorageBackend {
     }
 
     async deleteContainer(key) {
+        await this.ready();
         const dir = this.#safeResolve(key);
         if (!await fs.pathExists(dir)) return false;
         await fs.remove(dir);
@@ -204,7 +224,87 @@ export default class FileBackend extends StorageBackend {
         return true;
     }
 
+    async removeEmptyContainer(key) {
+        await this.ready();
+        const dir = await this.#trashTarget(key);
+        try { await fs.rmdir(dir); return { removed: true }; }
+        catch (error) {
+            if (error.code === 'ENOENT') return { removed: false };
+            // Preserve unindexed and independently owned children.
+            if (error.code === 'ENOTEMPTY' || error.code === 'EEXIST') return { removed: false, reason: 'not-empty' };
+            throw error;
+        }
+    }
+
+    async statContainer(key) {
+        await this.ready();
+        const target = await this.#trashTarget(key);
+        try { const stat = await fs.lstat(target); return stat.isDirectory() ? { kind: 'directory', dev: stat.dev, ino: stat.ino } : null; }
+        catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+    }
+
+    #trashPath(id) {
+        if (!/^[a-f0-9-]{36}$/.test(id)) throw new Error('Invalid trash item id');
+        return path.join(this.#tempDir, 'trash', id);
+    }
+
+    async #trashTarget(key) {
+        const target = this.#safeResolve(key);
+        // Never traverse a symlink when deleting or restoring an original path.
+        let current = this.#root;
+        for (const part of path.relative(this.#root, target).split(path.sep)) {
+            current = path.join(current, part);
+            const stat = await fs.lstat(current).catch(error => {
+                if (error.code === 'ENOENT') return null;
+                throw error;
+            });
+            if (stat?.isSymbolicLink()) throw new Error('Trash paths cannot traverse symbolic links');
+        }
+        return target;
+    }
+
+    async trashContainer(key, id) {
+        await this.ready();
+        const source = await this.#trashTarget(key);
+        if (!(await fs.lstat(source)).isDirectory()) throw new Error('Trash source is not a directory');
+        const destination = this.#trashPath(id);
+        await fs.ensureDir(path.dirname(destination));
+        // EXDEV fails safely with the source intact (a custom staging directory
+        // on another volume must not trigger copy-and-delete of a live tree).
+        await fs.rename(source, destination);
+        await this.#syncDirectory(path.dirname(source));
+        await this.#syncDirectory(path.dirname(destination));
+    }
+
+    async trashFile(key, id) {
+        await this.ready();
+        const source = await this.#trashTarget(key);
+        if (!(await fs.lstat(source)).isFile()) throw new Error('Trash source is not a regular file');
+        const destination = this.#trashPath(id);
+        await fs.ensureDir(path.dirname(destination));
+        await fs.rename(source, destination);
+        await this.#syncDirectory(path.dirname(source));
+        await this.#syncDirectory(path.dirname(destination));
+        return { checksums: await checksumFile(destination, ['sha256']) };
+    }
+
+    async validateTrashTarget(key) { await this.#trashTarget(key); }
+
+    async hasTrashedDirectory(id) { return fs.pathExists(this.#trashPath(id)); }
+    async dropTrashedDirectory(id) { await fs.remove(this.#trashPath(id)); }
+
+    async restoreTrashedDirectory(id, key) {
+        await this.ready();
+        const destination = await this.#trashTarget(key);
+        if (await fs.pathExists(destination)) return { ok: false, reason: 'target-exists' };
+        if (!await this.hasTrashedDirectory(id)) return { ok: false, reason: 'not-found' };
+        await fs.ensureDir(path.dirname(destination));
+        await fs.move(this.#trashPath(id), destination, { overwrite: false });
+        return { ok: true };
+    }
+
     async renameContainer(fromKey, toKey) {
+        await this.ready();
         const from = this.#safeResolve(fromKey);
         const to = this.#safeResolve(toKey);
         if (!await fs.pathExists(from)) throw new Error(`Container not found: ${fromKey}`);
@@ -221,11 +321,18 @@ export default class FileBackend extends StorageBackend {
         return path.join(this.#tempDir, `${Date.now()}-${process.pid}-${Math.random().toString(16).slice(2)}`);
     }
 
+    async #syncDirectory(directory) {
+        for (let current = directory;; current = path.dirname(current)) {
+            const handle = await fsp.open(current, 'r');
+            try { await handle.sync(); } finally { await handle.close(); }
+            if (current === this.#root || !current.startsWith(`${this.#root}${path.sep}`)) break;
+        }
+    }
+
     // Every placement ends with rename(2) over the destination: a reader sees
     // either the previous bytes or the complete new ones, never a partial
-    // file, and a crash mid-write leaves only a staging file behind. This is
-    // also what makes hardlink-based retention safe (see retain()): the old
-    // inode is never written to in place, it is displaced.
+    // file. Retention uses independent inodes because external writers may
+    // keep modifying a displaced inode through an open handle.
     //
     // The staging dir normally shares the destination's filesystem, but a
     // configured `tempDir` can sit on another mount (a container's /state next
@@ -234,8 +341,11 @@ export default class FileBackend extends StorageBackend {
     // destination — same directory, same mount by construction — and the
     // rename from there. Siblings are ignored by the watcher/scan like the dir.
     async #finish(tmp, dest) {
+        const handle = await fsp.open(tmp, 'r');
+        try { await handle.sync(); } finally { await handle.close(); }
         try {
             await fs.rename(tmp, dest);
+            await this.#syncDirectory(path.dirname(dest));
             return;
         } catch (err) {
             if (err.code !== 'EXDEV') throw err;
@@ -243,13 +353,17 @@ export default class FileBackend extends StorageBackend {
         const sibling = path.join(path.dirname(dest), `${TMP_DIR}-${process.pid}-${Math.random().toString(16).slice(2)}`);
         try {
             await fs.copyFile(tmp, sibling);
+            const handle = await fsp.open(sibling, 'r');
+            try { await handle.sync(); } finally { await handle.close(); }
             await fs.rename(sibling, dest);
+            await this.#syncDirectory(path.dirname(dest));
         } finally {
             await fs.remove(sibling).catch(() => {});
         }
     }
 
     async put(key, data) {
+        await this.ready();
         const filePath = this.#resolvePath(key);
         await fs.ensureDir(path.dirname(filePath));
         const tmp = await this.#stagingPath();
@@ -265,20 +379,15 @@ export default class FileBackend extends StorageBackend {
         return { key, size: stats.size };
     }
 
-    // Place an already-written file (e.g. a streamed temp) at `key`: hardlink
-    // it to a staging name (zero copy on the same filesystem; a byte copy
-    // across filesystems), then rename over the destination.
+    // Clone to a separate inode before publishing. The input may be an
+    // immutable cache pin; writable files must never share its inode.
     async commit(key, srcPath) {
+        await this.ready();
         const dest = this.#resolvePath(key);
         await fs.ensureDir(path.dirname(dest));
         const tmp = await this.#stagingPath();
         try {
-            try {
-                await fs.link(srcPath, tmp);
-            } catch (err) {
-                if (!['EXDEV', 'EPERM', 'EMLINK', 'ENOTSUP', 'EOPNOTSUPP'].includes(err.code)) throw err;
-                await fs.copyFile(srcPath, tmp);
-            }
+            await fs.copyFile(srcPath, tmp, fs.constants.COPYFILE_FICLONE);
             await this.#finish(tmp, dest);
         } finally {
             await fs.remove(tmp).catch(() => {});
@@ -290,22 +399,36 @@ export default class FileBackend extends StorageBackend {
 
     // Create-only placement: link(2) fails with EEXIST even for an unindexed
     // file, directory or dangling symlink. Never use rename-over for this path.
-    async createFrom(key, srcPath) {
+    // `owned`: srcPath is the caller's private file, removed after this call,
+    // so it is linked into place itself; otherwise (or across filesystems) a
+    // copy gets its own inode first.
+    async createFrom(key, srcPath, { owned = false } = {}) {
+        await this.ready();
         const dest = this.#resolvePath(key);
         await fs.ensureDir(path.dirname(dest));
-        try {
-            await fs.link(srcPath, dest);
-        } catch (error) {
-            if (error.code !== 'EXDEV') throw error;
-            // Stage on the destination filesystem, then publish atomically.
-            const sibling = path.join(path.dirname(dest), `${TMP_DIR}-${process.pid}-${Math.random().toString(16).slice(2)}`);
+        if (owned) {
+            const handle = await fsp.open(srcPath, 'r');
+            try { await handle.sync(); } finally { await handle.close(); }
             try {
-                await fs.copyFile(srcPath, sibling);
-                await fs.link(sibling, dest);
-            } finally {
-                await fs.remove(sibling).catch(() => {});
+                await fs.link(srcPath, dest);
+                await this.#syncDirectory(path.dirname(dest));
+                const stat = await this.stat(key);
+                if (!stat) throw new Error(`Upload destination disappeared: ${key}`);
+                return stat;
+            } catch (error) {
+                if (error.code !== 'EXDEV') throw error;
             }
         }
+        const sibling = path.join(path.dirname(dest), `${TMP_DIR}-${process.pid}-${Math.random().toString(16).slice(2)}`);
+        try {
+            await fs.copyFile(srcPath, sibling, fs.constants.COPYFILE_FICLONE);
+            const handle = await fsp.open(sibling, 'r');
+            try { await handle.sync(); } finally { await handle.close(); }
+            await fs.link(sibling, dest);
+            await this.#syncDirectory(path.dirname(dest));
+        } finally {
+            await fs.remove(sibling).catch(() => {});
+        }
         const stat = await this.stat(key);
         if (!stat) throw new Error(`Upload destination disappeared: ${key}`);
         return stat;
@@ -315,10 +438,7 @@ export default class FileBackend extends StorageBackend {
     //
     // Bytes an overwrite or delete is about to displace are kept for a while
     // under `<tempDir>/retained/<sha256>` (Stored decides when; the window is
-    // its config). A hardlink shares the inode with the visible file only
-    // until the placement above renames a new inode over it — placements are
-    // never in-place writes, so the retained copy stays what it was. On
-    // filesystems without hardlinks the bytes are copied.
+    // its config). Reflink or copy gives each version an independent inode.
 
     get retainDir() { return path.join(this.#tempDir, 'retained'); }
     retainedPath(sha256) { return path.join(this.retainDir, String(sha256).toLowerCase()); }
@@ -328,16 +448,23 @@ export default class FileBackend extends StorageBackend {
         if (!sha256 || !await fs.pathExists(src)) return null;
         const dest = this.retainedPath(sha256);
         const existing = await fs.stat(dest).catch(() => null);
-        if (existing) return { path: dest, size: existing.size, existing: true };
+        if (existing) {
+            if ((await checksumFile(dest, ['sha256'])).sha256 !== sha256) throw new Error('Retained content failed verification');
+            return { path: dest, size: existing.size, existing: true };
+        }
         await fs.ensureDir(this.retainDir);
+        // A network-share writer can keep an inode open and modify it in
+        // place. A hardlink is therefore not a recoverable version.
+        const tmp = await this.#stagingPath();
         try {
-            await fs.link(src, dest);
-        } catch (err) {
-            if (!['EXDEV', 'EPERM', 'EMLINK', 'ENOTSUP', 'EOPNOTSUPP'].includes(err.code)) throw err;
-            const tmp = await this.#stagingPath();
-            try { await fs.copyFile(src, tmp); await fs.rename(tmp, dest); }
-            finally { await fs.remove(tmp).catch(() => {}); }
-        }
+            await fs.copyFile(src, tmp, fs.constants.COPYFILE_FICLONE);
+            const checksums = await checksumFile(tmp, ['sha256']);
+            if (checksums.sha256 !== sha256) throw Object.assign(new Error('File changed before retention'), { code: 'SOURCE_CHANGED' });
+            const handle = await fsp.open(tmp, 'r');
+            try { await handle.sync(); } finally { await handle.close(); }
+            await fs.rename(tmp, dest);
+            await this.#syncDirectory(path.dirname(dest));
+        } finally { await fs.remove(tmp).catch(() => {}); }
         const stats = await fs.stat(dest);
         debug(`RETAIN ${key} → ${sha256.slice(0, 12)} (${stats.size} bytes)`);
         return { path: dest, size: stats.size, existing: false };
@@ -357,6 +484,7 @@ export default class FileBackend extends StorageBackend {
      * EXDEV otherwise, which callers treat as "fall back to a stream copy".
      */
     async renameFrom(key, srcPath) {
+        await this.ready();
         const dest = this.#resolvePath(key);
         await fs.ensureDir(path.dirname(dest));
         await fs.rename(srcPath, dest);
@@ -366,6 +494,7 @@ export default class FileBackend extends StorageBackend {
     }
 
     async get(key, options = {}) {
+        await this.ready();
         const filePath = this.#resolvePath(key);
         if (!await fs.pathExists(filePath)) return null;
         return options.stream ? fs.createReadStream(filePath) : fs.readFile(filePath);
@@ -374,12 +503,14 @@ export default class FileBackend extends StorageBackend {
     // Ranged read for HTTP Range/streaming. `end` is inclusive (matches HTTP
     // Range and createReadStream). Null on miss → caller falls back to full read.
     async getRange(key, { start, end }) {
+        await this.ready();
         const filePath = this.#resolvePath(key);
         if (!await fs.pathExists(filePath)) return null;
         return fs.createReadStream(filePath, { start, end });
     }
 
     async delete(key) {
+        await this.ready();
         const filePath = this.#resolvePath(key);
         if (!await fs.pathExists(filePath)) return false;
         await fs.remove(filePath);
@@ -398,6 +529,7 @@ export default class FileBackend extends StorageBackend {
     async pruneEmptyParents(key) {
         let rel = path.posix.dirname(String(key).split(path.sep).join('/'));
         while (rel && rel !== '.' && rel !== '/') {
+            if (this.isDirectoryProtected?.(rel)) return;
             if (this.#isTempPath(rel) || (this.#tempRel && this.#tempRel.startsWith(`${rel}/`))) return;
             const dir = this.#resolvePath(rel);
             if (dir === this.#root) return;
@@ -413,6 +545,7 @@ export default class FileBackend extends StorageBackend {
      * on "when" without a second hash.
      */
     async utimes(key, mtime) {
+        await this.ready();
         const filePath = this.#resolvePath(key);
         const when = mtime instanceof Date ? mtime : new Date(typeof mtime === 'string' ? Date.parse(mtime) : Number(mtime));
         if (Number.isNaN(when.getTime())) throw new Error(`Invalid mtime: ${mtime}`);
@@ -421,6 +554,7 @@ export default class FileBackend extends StorageBackend {
     }
 
     async stat(key) {
+        await this.ready();
         const filePath = this.#resolvePath(key);
         let stats;
         try { stats = await fs.stat(filePath); } catch (error) {
@@ -437,6 +571,7 @@ export default class FileBackend extends StorageBackend {
     // is reported and skipped instead of aborting the walk — one denied subtree
     // must not kill (or worse, truncate) a whole-mount enumeration.
     async *list(options = {}) {
+        await this.ready();
         const { prefix = '', recursive = true, onError = null } = options;
         const searchPath = this.#resolvePath(prefix);
 
@@ -488,6 +623,11 @@ export default class FileBackend extends StorageBackend {
             return false;
         }
 
+        const epoch = this.#watchEpoch;
+        await this.ready();
+        if (epoch !== this.#watchEpoch) return false;
+        if (this.#watcher) return true;
+
         // `stabilityThreshold`: how long a file must stop growing before it is
         // hashed (a mirror bumps it — a multi-GB copy from a USB stick must
         // not be hashed mid-write). `followSymlinks`: chokidar's default is
@@ -660,6 +800,7 @@ export default class FileBackend extends StorageBackend {
      * folder skeleton (and size a progress bar) before the expensive scan.
      */
     async shape(prefix = '') {
+        await this.ready();
         const dirs = [];
         let files = 0;
         const walk = async (rel) => {
@@ -680,6 +821,7 @@ export default class FileBackend extends StorageBackend {
     }
 
     async stop() {
+        this.#watchEpoch++;
         if (this.#watcher) {
             await this.#watcher.close();
             this.#watcher = null;

package/node_modules/canvas-stored/src/backends/gdrive/index.js

@@ -62,11 +62,17 @@ const splitKey = (key) => {
 };
 
 class DriveError extends Error {
-    constructor(message, { code = 'unreachable', status = null } = {}) {
-        super(message);
+    constructor(message, { code = 'unreachable', status = null, cause = undefined } = {}) {
+        const transportCode = cause?.cause?.code || cause?.code;
+        // InvalidArgumentError's message names the rejected option/header.
+        // Keep it visible rather than reducing it to fetch's generic wrapper.
+        const argumentDetail = transportCode === 'UND_ERR_INVALID_ARG' ? cause?.cause?.message : null;
+        super(transportCode ? `${message} (${transportCode}${argumentDetail ? `: ${argumentDetail}` : ''})` : message, { cause });
         this.name = 'DriveError';
         this.code = code;
         this.status = status;
+        this.statusCode = code === 'invalid-request' ? 500 : 502;
+        if (transportCode) this.transportCode = transportCode;
     }
 }
 
@@ -89,6 +95,7 @@ export default class GdriveBackend extends StorageBackend {
 
     #pollTimer = null;
     #polling = false;
+    #creates = new Map();
     #pageToken = null;
 
     constructor(name, config = {}) {
@@ -100,7 +107,9 @@ export default class GdriveBackend extends StorageBackend {
         debug(`GdriveBackend "${name}" initialized (folder=${this.#rootRef})`);
     }
 
-    get capabilities() { return { read: true, write: true, delete: true, canEnumerate: true, remote: true }; }
+    static getCapabilities(config = {}) {
+        return { ...super.getCapabilities(config), canEnumerate: true, remote: true, paths: true, mutableContainers: config.readOnly !== true, upload: config.readOnly !== true };
+    }
     get remote() { return true; }
     get transport() { return DEV; }
     get watching() { return !!this.#pollTimer; }
@@ -134,12 +143,17 @@ export default class GdriveBackend extends StorageBackend {
                 }),
             });
         } catch (err) {
-            throw new DriveError(`gdrive token endpoint unreachable: ${err.message}`, { code: 'unreachable' });
+            throw new DriveError(`gdrive token endpoint unreachable: ${err.message}`, { code: 'unreachable', cause: err });
         }
         const json = await res.json().catch(() => null);
         if (!res.ok || !json?.access_token) {
-            const detail = json?.error_description || json?.error || `HTTP ${res.status}`;
-            throw new DriveError(`gdrive token refresh failed: ${detail}`, { code: 'unauthorized', status: res.status });
+            const detail = [json?.error, json?.error_description].filter(Boolean).join(': ') || `HTTP ${res.status}`;
+            const hint = json?.error === 'invalid_grant'
+                ? ' Reconnect this Google account and save the new refresh token.'
+                : json?.error === 'invalid_client'
+                    ? ' Check the OAuth client id and client secret.'
+                    : '';
+            throw new DriveError(`gdrive token refresh failed: ${detail}${hint}`, { code: 'unauthorized', status: res.status });
         }
         this.#accessToken = json.access_token;
         this.#tokenExpiresAt = Date.now() + (Number(json.expires_in) || 3600) * 1000;
@@ -159,8 +173,11 @@ export default class GdriveBackend extends StorageBackend {
             try {
                 res = await this.#fetch(url, { ...init, headers: { Authorization: `Bearer ${token}`, ...(init.headers || {}) } });
             } catch (err) {
+                if ((err.cause?.code || err.code) === 'UND_ERR_INVALID_ARG') {
+                    throw new DriveError(`gdrive ${init.method || 'GET'} request arguments rejected: ${err.message}`, { code: 'invalid-request', cause: err });
+                }
                 if (attempt < RETRY_DELAYS_MS.length) { await sleep(RETRY_DELAYS_MS[attempt]); continue; }
-                throw new DriveError(`gdrive request failed: ${err.message}`, { code: 'unreachable' });
+                throw new DriveError(`gdrive ${init.method || 'GET'} ${new URL(url).origin}${new URL(url).pathname} request failed: ${err.message}`, { code: 'unreachable', cause: err });
             }
             if (res.ok || okStatuses.includes(res.status)) return res;
             if (res.status === 404 && allow404) return res;
@@ -509,7 +526,19 @@ export default class GdriveBackend extends StorageBackend {
         const { dir, name, key: clean } = splitKey(key);
         if (!clean) throw new Error('gdrive put: key is required');
         const parentId = await this.#folderId(dir, { create: true });
-        const existing = await this.#lookup(clean);
+        let existing = null;
+        if (options.createOnly) {
+            // Query Drive, including folders and native documents: the local
+            // index and watcher may not have seen this name yet.
+            const found = await this.#json('/files', { query: {
+                q: `'${qEscape(parentId)}' in parents and name = '${qEscape(name)}' and trashed = false`,
+                fields: 'files(id)', pageSize: 1,
+                supportsAllDrives: true, includeItemsFromAllDrives: true,
+            } });
+            if (found?.files?.length) throw Object.assign(new Error(`File already exists: ${clean}`), { code: 'EEXIST' });
+            // Always POST. Drive permits duplicate names, so an external
+            // concurrent creator may produce a sibling, but is never patched.
+        } else existing = await this.#lookup(clean);
         const mimeType = options.mimeType || 'application/octet-stream';
         const source = Buffer.isBuffer(data) ? data : (typeof data === 'string' ? Buffer.from(data) : data);
         const size = Buffer.isBuffer(source) ? source.length : (Number.isFinite(options.size) ? options.size : null);
@@ -544,7 +573,12 @@ export default class GdriveBackend extends StorageBackend {
             : `bytes */${last ? total : '*'}`;
         const res = await this.#call(session, {
             method: 'PUT',
-            headers: { 'Content-Length': String(buf.length), 'Content-Range': range, 'Content-Type': mimeType },
+            // Drive uses 308 as an acknowledgement of an incomplete upload,
+            // not an instruction to replay this chunk at Location.
+            redirect: 'manual',
+            // fetch derives Content-Length from this Buffer. Supplying it
+            // separately is redundant and can conflict with fetch's framing.
+            headers: { 'Content-Range': range, 'Content-Type': mimeType },
             body: buf,
         }, { okStatuses: [308] });
         if (last) {
@@ -587,6 +621,19 @@ export default class GdriveBackend extends StorageBackend {
         return this.put(key, createReadStream(srcPath), { size });
     }
 
+    async createFrom(key, srcPath) {
+        const clean = splitKey(key).key;
+        const previous = this.#creates.get(clean) || Promise.resolve();
+        const task = previous.catch(() => {}).then(async () => {
+            const { size } = await fsp.stat(srcPath);
+            await this.put(clean, createReadStream(srcPath), { size, createOnly: true });
+            return this.stat(clean);
+        });
+        this.#creates.set(clean, task);
+        try { return await task; }
+        finally { if (this.#creates.get(clean) === task) this.#creates.delete(clean); }
+    }
+
     /**
      * Remove the bytes at `key`. Trashes by default — a user's Drive is shared
      * with their other tools and the trash is their safety net; set
@@ -738,7 +785,7 @@ export default class GdriveBackend extends StorageBackend {
         }
 
         for (const row of walk.files.values()) {
-            let checksums = null;
+            let checksums;
             const have = row.checksums || {};
             if (algorithms.every((a) => have[a])) {
                 checksums = Object.fromEntries(algorithms.map((a) => [a, have[a]]));

package/node_modules/canvas-stored/src/backends/http/index.js

@@ -22,7 +22,9 @@ export default class HttpBackend extends StorageBackend {
     }
 
     // Read-only source: bytes can't be removed remotely, only the reference dropped.
-    get capabilities() { return { read: true, write: false, delete: false, canEnumerate: false }; }
+    static getCapabilities(config = {}) {
+        return { ...super.getCapabilities(config), write: false, delete: false, remote: true };
+    }
 
     nativeUrl(key) {
         try { return this.#baseUrl ? new URL(key, this.#baseUrl).href : key; }