@hachej/boring-files 0.4.23 → 0.4.25

package/README.md

@@ -229,9 +229,24 @@ refresh after concurrent changes. Traversal over the configured `maxEntries`
 (default 100,000) fails explicitly. History contains revisions retained by the
 workspace journal, not Git commits or an imported filesystem's prior history.
 
-The existing resource transport limits still apply: requests default to 4 MiB
-and responses to 8 MiB, including their serialized envelope. This API does not
-provide streaming uploads.
+File search (the `@` picker, the tree's filter) and uploads use this one route
+too: `search` is a catalog request, and an upload is a conditional create
+(`expected: absent`) with a receipt, like any other publication. There is no
+separate search or upload route to serve.
+
+`createRevisionHandler({ resolve, maxFileBytes })` names the largest file one
+write may carry, in bytes (default 3 MiB; at most
+about 48 MiB). Bytes travel as base64, so the handler sizes its resource
+requests and responses to that limit (at least 4 MiB and 8 MiB). A larger file
+gets the typed `file_too_large` result (`{ path, size, limit, reason }`) and
+nothing is written; a replay of an operation the journal already has keeps its
+recorded result. A request larger than the transport carries is answered 413,
+which the client reports as `unavailable` (a definite refusal). The binding
+(`GET` without `op`) names the limit as `limits.maxFileBytes`;
+`connectRevisionProvider` sizes its requests to it and exposes it as
+`maxFileBytes`, and the file tree refuses a larger upload before sending it.
+The provider's own file system may refuse a smaller file (SQLite: 1 900 000
+bytes by default). This API does not provide streaming uploads.
 
 ### Durable Object apps
 

package/dist/remote.js

@@ -2,6 +2,7 @@ import { PublicationNotDispatchedError, identifier, publicationDigest, publicati
 import { contentType, encode, envelope, identity, jsonBody, limit, lookupResult, observe, publicationResult, renameResult, readResult, readSnapshot, sameIdentity, schema, version } from './remote-protocol.js';
 import { randomUUID } from './platform.js';
 export { createResourceHandler } from './remote-handler.js';
+const tooLarge = new Error('Resource request too large');
 export function createResourceClient(options) {
     if (options.publication && !options.reconciliation)
         throw new TypeError('A publishing resource client needs reconciliation: a lost save acknowledgement could otherwise never be resolved');
@@ -29,6 +30,8 @@ export function createResourceClient(options) {
             const response = await observe(pending, combined);
             if (response.redirected || response.status !== 200) {
                 void response.body?.cancel().catch(() => { });
+                if (response.status === 413 && !response.redirected)
+                    throw tooLarge;
                 throw new Error('Remote resource response unavailable');
             }
             const result = envelope(await jsonBody(response, responseLimit, combined));
@@ -36,9 +39,11 @@ export function createResourceClient(options) {
                 throw new TypeError('Resource response association mismatch');
             return result.value;
         }
-        catch {
+        catch (error) {
             if ((call.kind === 'publish' || call.kind === 'rename' || call.kind === 'delete') && !dispatched)
                 throw new PublicationNotDispatchedError(call.value.operationId);
+            if (error === tooLarge)
+                throw error;
             throw new Error('Remote resource operation is unconfirmed');
         }
         finally {
@@ -73,6 +78,9 @@ export function createResourceClient(options) {
                 catch (error) {
                     if (error instanceof PublicationNotDispatchedError)
                         throw error;
+                    // 413: the server refused the body before reading it as a write (the revision handler's `maxFileBytes`), so nothing was written.
+                    if (error === tooLarge)
+                        return { kind: 'unavailable', reason: 'The workspace refused the file as too large' };
                     return { kind: 'unknown', operationId: captured.operationId, reason: 'Remote publication is unconfirmed; reconcile the original operation without automatic replay' };
                 }
             },

package/dist/revision-contracts.d.ts

@@ -94,6 +94,12 @@ export interface RevisionProvider extends ResourceClient {
     readonly list: (request: FileListRequest, signal?: AbortSignal) => Promise<FilePage>;
     readonly search: (request: FileSearchRequest, signal?: AbortSignal) => Promise<FilePage>;
     readonly history: (path: string, signal?: AbortSignal) => Promise<readonly SavedRevision[]>;
+    /**
+     * The host's largest file content per write, in bytes, when the binding names one (`createRevisionHandler({ maxFileBytes })`). The
+     * server answers a larger file with the typed `file_too_large` result; a UI may refuse it before sending (the file tree does).
+     * Absent: the host named no limit.
+     */
+    readonly maxFileBytes?: number;
     /**
      * The workspace's change feed (`GET ?op=changes`, server-sent events), reconnecting after the last `seq` seen until `signal`
      * aborts; a refused binding (another workspace, revoked access) ends it with a `RevisionError`, and so does a route that serves no feed:

package/dist/revision-handler.d.ts

@@ -9,6 +9,15 @@ export interface RevisionHandlerOptions {
     }>;
     /** How often the change feed sends a comment line so proxies keep it open, in milliseconds (default 15 000). */
     readonly heartbeatMs?: number;
+    /**
+     * The largest file one write (an upload, a save) may carry, in bytes. Default 3 MiB (3 145 728), at most about 48 MiB.
+     * A larger file is refused with the typed `file_too_large` result before the provider writes anything, as the provider's own limit
+     * is. The binding (`GET` without `op`) names it as `limits.maxFileBytes`; `connectRevisionProvider` exposes it as `maxFileBytes` and
+     * sizes its requests to it, and the file tree refuses a larger upload before sending it. The resource calls' request and response
+     * limits follow from it (base64 plus the envelope), so a request carrying more in total is answered 413. The provider's file system
+     * may still refuse a smaller file (SQLite: 1 900 000 bytes by default).
+     */
+    readonly maxFileBytes?: number;
 }
 export declare function createRevisionHandler(options: RevisionHandlerOptions): (request: Request) => Promise<Response>;
 //# sourceMappingURL=revision-handler.d.ts.map

package/dist/revision-handler.js

@@ -1,5 +1,5 @@
 import { createResourceHandler } from './remote-handler.js';
-import { binding, bindingHeader, bindingValue, catalogHeader, filePage, record, savedRevisions } from './revision-protocol.js';
+import { binding, bindingHeader, bindingValue, catalogHeader, DEFAULT_MAX_FILE_BYTES, filePage, fileTransport, record, savedRevisions, tooLarge } from './revision-protocol.js';
 import { guardStatus, readJsonBody, RequestGuardError } from './request-guard.js';
 import { accessSnapshot, identifier } from './publication-input.js';
 import { RevisionError } from './revision-contracts.js';
@@ -97,6 +97,8 @@ export function createRevisionHandler(options) {
     const heartbeatMs = options.heartbeatMs ?? 15_000;
     if (!Number.isSafeInteger(heartbeatMs) || heartbeatMs < 1)
         throw new RangeError('The heartbeat interval must be a positive integer');
+    const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    const transport = fileTransport(maxFileBytes);
     return async (request) => {
         let release;
         const operations = new Set();
@@ -123,7 +125,7 @@ export function createRevisionHandler(options) {
             const respond = (value) => Response.json(value, { headers: { 'cache-control': 'no-store' } });
             const op = new URL(request.url).searchParams.get('op');
             if (request.method === 'GET' && op === null)
-                return respond(association);
+                return respond({ ...association, limits: { maxFileBytes } });
             // A resource call (POST without the catalog header) is `createResourceHandler`'s protocol, whose envelope carries and checks
             // the identity, so a plain `createResourceClient` works here too. The listing and the change feed need the binding; a binding
             // that is sent is always checked.
@@ -166,8 +168,17 @@ export function createRevisionHandler(options) {
             if (resourceCall)
                 return await createResourceHandler({
                     authenticate: async () => access,
+                    ...transport,
                     reader: { read: (value, context) => hold(provider.read(value, context)) },
-                    publisher: { publish: (value, context) => hold(provider.publication.publish(value, context)) },
+                    publisher: { publish: (value, context) => hold((async () => {
+                            // A file over the limit is refused like the provider's own limit, before the provider writes anything. An operation the
+                            // journal already knows is left to the provider, so a replay keeps its committed (or unknown) result.
+                            const oversized = value.changes.find(change => change.kind !== 'delete' && change.bytes.byteLength > maxFileBytes);
+                            if (oversized && oversized.kind !== 'delete' && (await provider.reconciliation.lookup(value.operationId, context)).kind === 'not-found') {
+                                return { kind: 'file_too_large', path: oversized.target.resource.path, size: oversized.bytes.byteLength, limit: maxFileBytes, reason: tooLarge(maxFileBytes) };
+                            }
+                            return provider.publication.publish(value, context);
+                        })()) },
                     lookup: { lookup: (value, context) => hold(provider.reconciliation.lookup(value, context)) },
                     ...(provider.renaming ? { renamer: { rename: (value, context) => hold(provider.renaming.rename(value, context)) } } : {}),
                     ...(provider.deletion ? { deleter: { delete: (value, context) => hold(provider.deletion.delete(value, context)) } } : {}),

package/dist/revision-protocol.d.ts

@@ -9,6 +9,18 @@ export interface RevisionBinding {
 }
 export declare function record(value: unknown): Record<string, unknown>;
 export declare function binding(value: unknown): RevisionBinding;
+/** The default largest file content one write carries: what the resource transport's 4 MiB request held as base64 before it had a name. */
+export declare const DEFAULT_MAX_FILE_BYTES = 3145728;
+/**
+ * The request and response byte limits that carry `maxFileBytes` of file content: base64 (4 bytes per 3) plus 64 KiB for the envelope,
+ * and at least the transport's usual 4 MiB request and 8 MiB response. A limit whose request would exceed the transport's 64 MiB cap
+ * (about 48 MiB of content) is refused, like zero or a fraction.
+ */
+export declare function fileTransport(maxFileBytes: number): {
+    readonly maxRequestBytes: number;
+    readonly maxResponseBytes: number;
+};
+export declare const tooLarge: (limit: number) => string;
 export declare const bindingValue: (value: RevisionBinding) => string;
 export declare function filePage(value: unknown): FilePage;
 export declare function savedRevisions(value: unknown): readonly SavedRevision[];

package/dist/revision-protocol.js

@@ -15,6 +15,22 @@ export function binding(value) {
             incarnation: identifier(workspace.incarnation), viewId: identifier(workspace.viewId),
         } };
 }
+/** The default largest file content one write carries: what the resource transport's 4 MiB request held as base64 before it had a name. */
+export const DEFAULT_MAX_FILE_BYTES = 3_145_728;
+/**
+ * The request and response byte limits that carry `maxFileBytes` of file content: base64 (4 bytes per 3) plus 64 KiB for the envelope,
+ * and at least the transport's usual 4 MiB request and 8 MiB response. A limit whose request would exceed the transport's 64 MiB cap
+ * (about 48 MiB of content) is refused, like zero or a fraction.
+ */
+export function fileTransport(maxFileBytes) {
+    if (!Number.isSafeInteger(maxFileBytes) || maxFileBytes < 1)
+        throw new RangeError('maxFileBytes must be a positive integer');
+    const wire = Math.ceil(maxFileBytes / 3) * 4 + 65_536;
+    if (wire > 67_108_864)
+        throw new RangeError('maxFileBytes is larger than the resource transport carries (64 MiB with base64)');
+    return { maxRequestBytes: Math.max(4_194_304, wire), maxResponseBytes: Math.max(8_388_608, wire) };
+}
+export const tooLarge = (limit) => `The file is larger than the workspace's ${limit}-byte limit`;
 export const bindingValue = (value) => encodeURIComponent(JSON.stringify(binding(value)));
 export function filePage(value) {
     const data = record(value);

package/dist/revision.js

@@ -1,5 +1,5 @@
 import { createResourceClient } from './remote.js';
-import { binding, bindingHeader, bindingValue, catalogHeader, changeEvent, filePage, record, savedRevisions, serverEvents } from './revision-protocol.js';
+import { binding, bindingHeader, bindingValue, catalogHeader, changeEvent, filePage, fileTransport, record, savedRevisions, serverEvents } from './revision-protocol.js';
 import { readJsonBody } from './request-guard.js';
 import { RevisionError } from './revision-contracts.js';
 import { observe } from './remote-protocol.js';
@@ -34,9 +34,20 @@ export async function connectRevisionProvider(options) {
             throw new RevisionError('unavailable', 'The file request could not be completed');
         }
     }
-    const selected = binding(await send(new Request(endpoint, { method: 'GET', redirect: 'error', ...(options.signal ? { signal: options.signal } : {}) })));
-    const bound = bindingValue(selected);
-    const client = createResourceClient({ endpoint, identity: selected.identity, publication: true, reconciliation: true,
+    const discovered = record(await send(new Request(endpoint, { method: 'GET', redirect: 'error', ...(options.signal ? { signal: options.signal } : {}) })));
+    const selected = binding(discovered), bound = bindingValue(selected);
+    // The host's file size limit (`createRevisionHandler({ maxFileBytes })`); a host that names none keeps the transport's defaults.
+    const maxFileBytes = discovered.limits === undefined ? undefined : record(discovered.limits).maxFileBytes;
+    let transport;
+    if (maxFileBytes !== undefined) {
+        try {
+            transport = fileTransport(maxFileBytes);
+        }
+        catch {
+            throw new RevisionError('invalid', 'Invalid file size limit');
+        }
+    }
+    const client = createResourceClient({ endpoint, identity: selected.identity, publication: true, reconciliation: true, ...transport,
         fetch: request => { const headers = new Headers(request.headers); headers.set(bindingHeader, bound); return fetch(new Request(request, { headers })); } });
     async function invoke(kind, value, signal) {
         const requestId = randomUUID();
@@ -136,7 +147,8 @@ export async function connectRevisionProvider(options) {
     if (!client.publish || !client.lookup)
         throw new Error('Publishing client lacks reconciliation');
     return {
-        ...client, publish: client.publish, lookup: client.lookup, identity: Object.freeze(selected.identity), workspace: Object.freeze(selected.workspace),
+        ...client, publish: client.publish, lookup: client.lookup, ...(transport ? { maxFileBytes: maxFileBytes } : {}),
+        identity: Object.freeze(selected.identity), workspace: Object.freeze(selected.workspace),
         locate: path => locator({ resource: { providerId: selected.workspace.providerId, path }, view: { kind: 'published' } }),
         list: async (request, signal) => filePage(await invoke('list', request, signal)),
         search: async (request, signal) => filePage(await invoke('search', request, signal)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-files",
-  "version": "0.4.23",
+  "version": "0.4.25",
   "license": "MIT",
   "private": false,
   "type": "module",