@nestm/storage 0.1.0-alpha.7 → 0.1.0-alpha.9

package/dist/workspace/storage-workspace.js

@@ -1,6 +1,7 @@
 import { StorageClient } from '../storage.client.js';
+import { isCanonicalStorageEtag } from '../storage-etag.js';
 import { StorageErrorCode } from '../storage.error.js';
-import { StorageWorkspaceCursorStore } from './storage-workspace.cursor.js';
+import { STORAGE_WORKSPACE_MAX_CURSOR_BYTES, decodeStorageWorkspaceCursor, issueStorageWorkspaceCursor, resolveStorageWorkspaceCursorConfiguration, } from './storage-workspace.cursor.js';
 import { sanitizeWorkspaceError, workspaceError, } from './storage-workspace.error.js';
 import { assertWorkspacePath, containsControlCharacter, isPathInside, joinWorkspacePath, workspaceBasename, } from './storage-workspace.path.js';
 import { DEFAULT_STORAGE_WORKSPACE_LIMITS, STORAGE_WORKSPACE_PERMISSIONS, } from './storage-workspace.types.js';
@@ -29,18 +30,42 @@ function positiveSafeInteger(value, label) {
     }
     return value;
 }
-function assertEtag(etag, maxBytes, operation) {
-    if (typeof etag !== 'string' ||
-        etag.length === 0 ||
-        containsControlCharacter(etag) ||
-        encoder.encode(etag).byteLength > maxBytes) {
-        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `${operation} requires a valid non-empty etag.`, { permanent: true });
+function assertEtag(etag, operation) {
+    if (!isCanonicalStorageEtag(etag)) {
+        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `${operation} requires a canonical bare etag of at most 1,024 bytes.`, { permanent: true });
     }
 }
+function writeModeOf(options) {
+    const candidate = options;
+    const mode = candidate?.mode;
+    if (mode === 'create' || mode === 'overwrite' || mode === 'replace') {
+        if (mode !== 'replace' && candidate !== undefined && 'etag' in candidate) {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Workspace write options may include an etag only in replace mode.', { permanent: true });
+        }
+        return mode;
+    }
+    throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Workspace write mode must be create, overwrite, or replace.', { permanent: true });
+}
+function hasExplicitMode(options, expected, operation) {
+    if (typeof options !== 'object' || options === null) {
+        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `${operation} options must be an object.`, { permanent: true });
+    }
+    if (!('mode' in options)) {
+        return false;
+    }
+    if (options.mode !== expected) {
+        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `${operation} mode must be ${expected}.`, { permanent: true });
+    }
+    if ('etag' in options) {
+        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `${operation} ${expected} options must not include an etag.`, { permanent: true });
+    }
+    return true;
+}
 function resolveLimits(requested, parent) {
     const baseline = parent ?? DEFAULT_STORAGE_WORKSPACE_LIMITS;
     const next = {
         cursorTtlMs: requested?.cursorTtlMs ?? baseline.cursorTtlMs,
+        maxCursorBytes: requested?.maxCursorBytes ?? baseline.maxCursorBytes,
         maxPageSize: requested?.maxPageSize ?? baseline.maxPageSize,
         maxPathBytes: requested?.maxPathBytes ?? baseline.maxPathBytes,
         maxReadBytes: requested?.maxReadBytes ?? baseline.maxReadBytes,
@@ -55,6 +80,9 @@ function resolveLimits(requested, parent) {
             throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `Child workspace limit "${name}" cannot exceed its parent limit.`, { permanent: true });
         }
     }
+    if (next.maxCursorBytes > STORAGE_WORKSPACE_MAX_CURSOR_BYTES) {
+        throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, `limits.maxCursorBytes cannot exceed ${STORAGE_WORKSPACE_MAX_CURSOR_BYTES}.`, { permanent: true });
+    }
     return Object.freeze(next);
 }
 function resolvePermissions(requested, parent) {
@@ -77,8 +105,7 @@ function logicalFile(metadata, path) {
         metadata.size < 0 ||
         typeof metadata.contentType !== 'string' ||
         metadata.contentType.length === 0 ||
-        (metadata.etag !== undefined &&
-            (typeof metadata.etag !== 'string' || metadata.etag.length === 0)) ||
+        (metadata.etag !== undefined && !isCanonicalStorageEtag(metadata.etag)) ||
         (metadata.lastModified !== undefined &&
             !Number.isFinite(new Date(metadata.lastModified).getTime()))) {
         throw workspaceError(StorageErrorCode.PROVIDER, 'Storage provider returned malformed file metadata.', { permanent: true });
@@ -224,7 +251,7 @@ async function collectBoundedText(stream, announcedSize, maxBytes, path) {
 async function collectBoundedBytes(stream, announcedSize, maxBytes, path) {
     if (announcedSize > maxBytes) {
         await stream.cancel().catch(() => undefined);
-        throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `Workspace file "${path}" exceeds the ${maxBytes}-byte copy limit.`, { path, permanent: true });
+        throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `Workspace file "${path}" exceeds the ${maxBytes}-byte limit.`, { path, permanent: true });
     }
     const reader = stream.getReader();
     const chunks = [];
@@ -241,7 +268,7 @@ async function collectBoundedBytes(stream, announcedSize, maxBytes, path) {
             size += result.value.byteLength;
             if (size > maxBytes) {
                 await reader.cancel().catch(() => undefined);
-                throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `Workspace file "${path}" exceeded the ${maxBytes}-byte copy limit.`, { path, permanent: true });
+                throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `Workspace file "${path}" exceeded the ${maxBytes}-byte limit.`, { path, permanent: true });
             }
             chunks.push(result.value);
         }
@@ -315,10 +342,31 @@ class StorageWorkspaceImplementation {
             });
         }
     }
+    async readBytes(path, options) {
+        this.#require('read');
+        const logicalPath = this.#filePath(path);
+        const maxBytes = options?.maxBytes ?? this.#limits.maxReadBytes;
+        positiveSafeInteger(maxBytes, 'maxBytes');
+        if (maxBytes > this.#limits.maxReadBytes) {
+            throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `maxBytes cannot exceed the ${this.#limits.maxReadBytes}-byte workspace read limit.`, { path: logicalPath, permanent: true });
+        }
+        try {
+            const object = await this.#state.client.downloadStream(this.#scope(logicalPath), operationOptions(options));
+            this.#assertResultPath(object.key, logicalPath);
+            const bytes = await collectBoundedBytes(object.body, object.size, maxBytes, logicalPath);
+            return { ...logicalFile(object, logicalPath), bytes };
+        }
+        catch (error) {
+            throw sanitizeWorkspaceError(error, {
+                operation: 'read',
+                path: logicalPath,
+            });
+        }
+    }
     async list(options = {}) {
         this.#require('list');
-        const continuation = options.cursor
-            ? this.#state.cursorStore.consume(options.cursor, this.#binding('list'))
+        const continuation = options.cursor !== undefined
+            ? await decodeStorageWorkspaceCursor(this.#state.cursor, this.#cursorBinding(), 'list', options.cursor)
             : undefined;
         if (continuation !== undefined &&
             ((options.directory !== undefined &&
@@ -331,7 +379,6 @@ class StorageWorkspaceImplementation {
         const directory = this.#directoryPath(continuation?.directory ?? options.directory ?? '');
         const limit = this.#pageLimit(continuation?.limit ?? options.limit, this.#limits.maxPageSize);
         const recursive = continuation?.recursive ?? options.recursive === true;
-        const binding = this.#binding('list');
         const scopedDirectory = this.#scopeDirectory(directory);
         try {
             const page = await this.#state.client.list({
@@ -383,12 +430,13 @@ class StorageWorkspaceImplementation {
             }
             return {
                 ...(page.cursor !== undefined && {
-                    cursor: this.#state.cursorStore.issue(binding, {
+                    cursor: await issueStorageWorkspaceCursor(this.#state.cursor, this.#cursorBinding(), {
                         backendCursor: page.cursor,
                         directory,
                         limit,
+                        operation: 'list',
                         recursive,
-                    }, this.#limits.cursorTtlMs),
+                    }),
                 }),
                 entries,
             };
@@ -402,8 +450,8 @@ class StorageWorkspaceImplementation {
     }
     async search(query, options = {}) {
         this.#require('search');
-        const continuation = options.cursor
-            ? this.#state.cursorStore.consume(options.cursor, this.#binding('search'))
+        const continuation = options.cursor !== undefined
+            ? await decodeStorageWorkspaceCursor(this.#state.cursor, this.#cursorBinding(), 'search', options.cursor)
             : undefined;
         if (continuation !== undefined &&
             ((query.length > 0 && query !== continuation.query) ||
@@ -432,18 +480,11 @@ class StorageWorkspaceImplementation {
         }
         const caseInsensitive = continuation?.caseInsensitive ?? options.caseInsensitive === true;
         const limit = this.#pageLimit(continuation?.limit ?? options.limit, this.#limits.maxSearchResults);
-        const binding = this.#binding('search');
-        const prior = continuation ?? {
-            backendCursor: undefined,
-            caseInsensitive,
-            directory,
-            limit,
-            match,
-            query,
-            scanned: 0,
+        const prior = {
+            backendCursor: continuation?.backendCursor,
+            scanned: continuation?.scanned ?? 0,
         };
         return this.#searchPage(query, {
-            binding,
             caseInsensitive,
             directory,
             limit,
@@ -453,7 +494,8 @@ class StorageWorkspaceImplementation {
         });
     }
     async writeFile(path, body, options) {
-        this.#require(options.mode);
+        const mode = writeModeOf(options);
+        this.#require(mode === 'overwrite' ? 'write' : mode);
         const logicalPath = this.#filePath(path);
         if (typeof body !== 'string' && !(body instanceof Uint8Array)) {
             throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Workspace writes accept only strings or Uint8Array bodies.', { path: logicalPath, permanent: true });
@@ -464,9 +506,6 @@ class StorageWorkspaceImplementation {
         if (size > this.#limits.maxWriteBytes) {
             throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `Workspace write exceeds the ${this.#limits.maxWriteBytes}-byte limit.`, { path: logicalPath, permanent: true });
         }
-        if (options.mode === 'replace') {
-            assertEtag(options.etag, this.#limits.maxPathBytes, 'Replace');
-        }
         try {
             const common = {
                 ...(options.contentType !== undefined && {
@@ -475,18 +514,27 @@ class StorageWorkspaceImplementation {
                 ...(options.metadata !== undefined && { metadata: options.metadata }),
                 ...operationOptions(options),
             };
-            const result = options.mode === 'create'
-                ? await this.#state.client.uploadConditional(this.#scope(logicalPath), body, { ...common, condition: { type: 'create' } })
-                : await this.#state.client.uploadConditional(this.#scope(logicalPath), body, {
+            let result;
+            if (mode === 'overwrite') {
+                result = await this.#state.client.upload(this.#scope(logicalPath), body, common);
+            }
+            else if (mode === 'create') {
+                result = await this.#state.client.uploadConditional(this.#scope(logicalPath), body, { ...common, condition: { type: 'create' } });
+            }
+            else {
+                const etag = options.etag;
+                assertEtag(etag, 'Replace');
+                result = await this.#state.client.uploadConditional(this.#scope(logicalPath), body, {
                     ...common,
-                    condition: { etag: options.etag, type: 'replace' },
+                    condition: { etag, type: 'replace' },
                 });
+            }
             this.#assertResultPath(result.key, logicalPath);
             return logicalFile(result, logicalPath);
         }
         catch (error) {
             throw sanitizeWorkspaceError(error, {
-                operation: options.mode,
+                operation: mode,
                 path: logicalPath,
             });
         }
@@ -494,34 +542,45 @@ class StorageWorkspaceImplementation {
     async copyFile(source, destination, options) {
         this.#require('copy');
         this.#require('read');
-        this.#require('create');
+        const overwrite = hasExplicitMode(options, 'overwrite', 'Copy');
+        this.#require(overwrite ? 'write' : 'create');
         const sourcePath = this.#filePath(source, 'source path');
         const destinationPath = this.#filePath(destination, 'destination path');
         if (sourcePath === destinationPath) {
             throw workspaceError(StorageErrorCode.CONFLICT, 'Copy destination must differ from its source.', { path: destinationPath, permanent: true });
         }
-        if (this.#state.client.capabilities.conditionalMutation?.create !== true) {
-            throw workspaceError(StorageErrorCode.NOT_SUPPORTED, 'Safe copy requires create-only conditional upload support.', { operation: 'copy', path: destinationPath, permanent: true });
+        if (overwrite) {
+            return this.#copyOverwrite(sourcePath, destinationPath, options);
+        }
+        const conditional = options;
+        assertEtag(conditional.etag, 'Copy');
+        const capabilities = this.#state.client.capabilities;
+        if (capabilities.conditionalCreate?.resultEtag !== true ||
+            capabilities.conditionalRead?.etag !== true) {
+            throw workspaceError(StorageErrorCode.NOT_SUPPORTED, 'Safe copy requires exact-ETag reads and create-only uploads that return an ETag.', { operation: 'copy', path: destinationPath, permanent: true });
         }
-        return this.#copyCreate(sourcePath, destinationPath, options);
+        return this.#copyCreate(sourcePath, destinationPath, conditional);
     }
     async moveFile(source, destination, options) {
         this.#require('move');
         this.#require('read');
         this.#require('create');
         this.#require('delete');
-        const conditional = this.#state.client.capabilities.conditionalMutation;
-        if (conditional?.create !== true ||
-            conditional.delete !== true ||
-            conditional.etag !== true) {
-            throw workspaceError(StorageErrorCode.NOT_SUPPORTED, 'Safe move requires create-only upload, conditional delete, and upload ETag support.', { operation: 'move', permanent: true });
+        if (typeof options !== 'object' || options === null || 'mode' in options) {
+            throw workspaceError(StorageErrorCode.INVALID_ARGUMENT, 'Workspace move supports only an ETag-conditional mutation.', { permanent: true });
         }
         const sourcePath = this.#filePath(source, 'source path');
         const destinationPath = this.#filePath(destination, 'destination path');
         if (sourcePath === destinationPath) {
             throw workspaceError(StorageErrorCode.CONFLICT, 'Move destination must differ from its source.', { path: destinationPath, permanent: true });
         }
-        assertEtag(options.etag, this.#limits.maxPathBytes, 'Move');
+        const capabilities = this.#state.client.capabilities;
+        if (capabilities.conditionalCreate?.resultEtag !== true ||
+            capabilities.conditionalDelete?.etag !== true ||
+            capabilities.conditionalRead?.etag !== true) {
+            throw workspaceError(StorageErrorCode.NOT_SUPPORTED, 'Safe move requires exact-ETag reads, create-only uploads that return an ETag, and conditional delete.', { operation: 'move', permanent: true });
+        }
+        assertEtag(options.etag, 'Move');
         const copied = await this.#copyCreate(sourcePath, destinationPath, options);
         if (copied.etag === undefined) {
             throw workspaceError(StorageErrorCode.NOT_SUPPORTED, 'Safe move requires the destination provider to return an etag.', { path: destinationPath, permanent: true });
@@ -544,12 +603,22 @@ class StorageWorkspaceImplementation {
     async deleteFile(path, options) {
         this.#require('delete');
         const logicalPath = this.#filePath(path);
-        assertEtag(options.etag, this.#limits.maxPathBytes, 'Delete');
+        const unconditional = hasExplicitMode(options, 'unconditional', 'Delete');
+        if (unconditional) {
+            this.#require('write');
+        }
         try {
-            await this.#state.client.deleteConditional(this.#scope(logicalPath), {
-                condition: { etag: options.etag },
-                ...operationOptions(options),
-            });
+            if (unconditional) {
+                await this.#state.client.delete(this.#scope(logicalPath), operationOptions(options));
+            }
+            else {
+                const conditional = options;
+                assertEtag(conditional.etag, 'Delete');
+                await this.#state.client.deleteConditional(this.#scope(logicalPath), {
+                    condition: { etag: conditional.etag },
+                    ...operationOptions(conditional),
+                });
+            }
         }
         catch (error) {
             throw sanitizeWorkspaceError(error, {
@@ -565,14 +634,20 @@ class StorageWorkspaceImplementation {
         }
         return new StorageWorkspaceImplementation(WORKSPACE_CONSTRUCTOR, {
             ...this.#state,
-            id: `${this.#state.id}/${path}`,
             prefix: joinWorkspacePath(this.#state.prefix, path),
         }, resolvePermissions(options.permissions, this.#permissions), resolveLimits(options.limits, this.#limits));
     }
     async #copyCreate(sourcePath, destinationPath, options) {
         try {
-            const source = await this.#state.client.downloadStream(this.#scope(sourcePath), operationOptions(options));
+            const source = await this.#state.client.downloadConditional(this.#scope(sourcePath), {
+                condition: { etag: options.etag },
+                ...operationOptions(options),
+            });
             this.#assertResultPath(source.key, sourcePath);
+            if (source.etag !== options.etag) {
+                await source.body.cancel().catch(() => undefined);
+                throw workspaceError(StorageErrorCode.PROVIDER, 'Conditional read returned an unexpected source ETag.', { operation: 'copy', path: sourcePath, permanent: true });
+            }
             const bytes = await collectBoundedBytes(source.body, source.size, this.#limits.maxWriteBytes, sourcePath);
             const result = await this.#state.client.uploadConditional(this.#scope(destinationPath), bytes, {
                 condition: { type: 'create' },
@@ -590,6 +665,26 @@ class StorageWorkspaceImplementation {
             });
         }
     }
+    async #copyOverwrite(sourcePath, destinationPath, options) {
+        try {
+            const source = await this.#state.client.downloadStream(this.#scope(sourcePath), operationOptions(options));
+            this.#assertResultPath(source.key, sourcePath);
+            const bytes = await collectBoundedBytes(source.body, source.size, this.#limits.maxWriteBytes, sourcePath);
+            const result = await this.#state.client.upload(this.#scope(destinationPath), bytes, {
+                contentType: source.contentType,
+                ...(source.metadata !== undefined && { metadata: source.metadata }),
+                ...operationOptions(options),
+            });
+            this.#assertResultPath(result.key, destinationPath);
+            return logicalFile(result, destinationPath);
+        }
+        catch (error) {
+            throw sanitizeWorkspaceError(error, {
+                operation: 'copy',
+                path: destinationPath,
+            });
+        }
+    }
     async #searchPage(query, context) {
         const entries = [];
         let backendCursor = context.state.backendCursor;
@@ -648,17 +743,19 @@ class StorageWorkspaceImplementation {
             if (scanned >= this.#limits.maxSearchScan && hasMore) {
                 throw workspaceError(StorageErrorCode.LIMIT_EXCEEDED, `Search exceeded the ${this.#limits.maxSearchScan}-object scan limit.`, { permanent: true });
             }
+            const nextBackendCursor = backendCursor;
             return {
-                ...(hasMore && {
-                    cursor: this.#state.cursorStore.issue(context.binding, {
-                        backendCursor,
+                ...(nextBackendCursor !== undefined && {
+                    cursor: await issueStorageWorkspaceCursor(this.#state.cursor, this.#cursorBinding(), {
+                        backendCursor: nextBackendCursor,
                         caseInsensitive: context.caseInsensitive,
                         directory: context.directory,
                         limit: context.limit,
                         match: context.match,
+                        operation: 'search',
                         query,
                         scanned,
-                    }, this.#limits.cursorTtlMs),
+                    }),
                 }),
                 entries,
             };
@@ -725,8 +822,12 @@ class StorageWorkspaceImplementation {
         }
         return limit;
     }
-    #binding(operation) {
-        return `${this.#state.id}:${operation}`;
+    #cursorBinding() {
+        return {
+            limits: this.#limits,
+            prefix: this.#state.prefix,
+            store: this.#state.client.name,
+        };
     }
 }
 export function mountStorageWorkspace(client, options) {
@@ -737,8 +838,7 @@ export function mountStorageWorkspace(client, options) {
     });
     return new StorageWorkspaceImplementation(WORKSPACE_CONSTRUCTOR, {
         client,
-        cursorStore: new StorageWorkspaceCursorStore(),
-        id: `workspace:${crypto.randomUUID()}`,
+        cursor: resolveStorageWorkspaceCursorConfiguration(options.cursor),
         prefix,
     }, resolvePermissions(options.permissions), limits);
 }