@hachej/boring-execution 0.0.0-stage → 0.2.1

package/dist/remote-files-handler.js

@@ -0,0 +1,215 @@
+import { awaitWithContext, withAbortSignal, withoutAbortSignal } from '@earendil-works/chord/context';
+import { FileError, err } from '@earendil-works/pi-durable/env';
+import { identity, sameIdentity, positiveLimit, nativeVersion, schema, version, streamType, requestInput, wireResult } from './remote-files-protocol.js';
+import { servePositional } from './remote-files-positional.js';
+import { serveWatch } from './remote-files-watch.js';
+import { guardStatus, hasJsonContentType, readJsonBody } from '@hachej/boring-files/request-guard';
+const refused = (status) => new Response(null, { status, headers: { 'cache-control': 'no-store' } });
+function invoke(fs, call, context) {
+    switch (call.method) {
+        case 'absolutePath': return fs.absolutePath(...call.args, context);
+        case 'joinPath': return fs.joinPath(...call.args, context);
+        case 'readTextFile': return fs.readTextFile(...call.args, context);
+        case 'openTextLineReader': return fs.openTextLineReader(...call.args, context);
+        case 'readTextLines': return fs.readTextLines(...call.args, context);
+        case 'readBinaryFile': return fs.readBinaryFile(...call.args, context);
+        case 'writeFile': return fs.writeFile(...call.args, context);
+        case 'appendFile': return fs.appendFile(...call.args, context);
+        case 'truncateFile': return fs.truncateFile(...call.args, context);
+        case 'flushFile': return fs.flushFile(...call.args, context);
+        case 'renameFile': return fs.renameFile(...call.args, context);
+        case 'fileInfo': return fs.fileInfo(...call.args, context);
+        case 'listDir': return fs.listDir(...call.args, context);
+        case 'canonicalPath': return fs.canonicalPath(...call.args, context);
+        case 'exists': return fs.exists(...call.args, context);
+        case 'createDir': return fs.createDir(...call.args, context);
+        case 'remove': return fs.remove(...call.args, context);
+        case 'createTempDir': return fs.createTempDir(...call.args, context);
+        case 'createTempFile': return fs.createTempFile(...call.args, context);
+        case 'binaryInfo':
+        case 'readRange':
+        case 'scanLines':
+        case 'readDirPage':
+        case 'watch': throw new TypeError('Not a plain native call');
+    }
+}
+export function createRemoteFileSystemHandler(options) {
+    const maxRequestBytes = positiveLimit(options.maxRequestBytes ?? 1_048_576), maxResponseBytes = positiveLimit(options.maxResponseBytes ?? 4_194_304);
+    const maxFrameBytes = positiveLimit(options.maxFrameBytes ?? 1_048_576);
+    return async (request) => {
+        if (request.method !== 'POST')
+            return refused(405);
+        if (!hasJsonContentType(request.headers))
+            return refused(415);
+        let access;
+        try {
+            access = await options.authenticate(request);
+        }
+        catch {
+            return refused(503);
+        }
+        if (!access)
+            return refused(401);
+        const selected = identity(access.identity), { filesystemId, bindFileSystem, authorize, revoked } = access;
+        const stop = new AbortController(), context = withAbortSignal(AbortSignal.any([request.signal, revoked, stop.signal]), access.context);
+        const signal = context.abortSignal, cleanupContext = withoutAbortSignal(access.context);
+        let input;
+        try {
+            input = requestInput(await readJsonBody(request, maxRequestBytes, signal));
+        }
+        catch (error) {
+            return refused(guardStatus(error));
+        }
+        if (!sameIdentity(input.identity, selected) || input.filesystemId !== filesystemId)
+            return refused(409);
+        const binding = { schema, version, nativeVersion, requestId: input.requestId, identity: selected, filesystemId };
+        const reply = (result) => {
+            const body = new TextEncoder().encode(JSON.stringify({ ...binding, result: wireResult(result) }));
+            if (body.length > maxResponseBytes)
+                return refused(503);
+            return new Response(body, { headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } });
+        };
+        const permitted = async () => !signal?.aborted
+            && await awaitWithContext(Promise.resolve(authorize(structuredClone(input.call), input.cwd)), context) === true && !signal?.aborted;
+        let lease, released = false, transferred = false;
+        let closeReader;
+        const release = async () => { if (!lease || released)
+            return; released = true; await lease.release(cleanupContext); };
+        const matches = () => !!lease && sameIdentity(lease.identity, selected) && lease.environment.id === filesystemId && lease.environment.cwd === input.cwd;
+        try {
+            if (!await permitted())
+                return reply(err(new FileError('permission_denied', 'Filesystem operation is not permitted')));
+            const pending = Promise.resolve(bindFileSystem(input.cwd, context)).then(value => {
+                lease = value;
+                if (signal?.aborted)
+                    void release().catch(error => options.onCleanupError?.(error));
+                return value;
+            });
+            lease = await awaitWithContext(pending, context);
+            if (!matches() || signal?.aborted)
+                return refused(409);
+            if (!await permitted() || !matches())
+                return reply(err(new FileError('permission_denied', 'Filesystem binding is no longer permitted')));
+            const call = input.call;
+            if (call.method === 'binaryInfo' || call.method === 'readRange' || call.method === 'scanLines' || call.method === 'readDirPage') {
+                const result = await servePositional(lease.environment, call, context, cleanupContext, maxResponseBytes);
+                if (!await permitted() || !matches())
+                    return refused(403);
+                return reply(result);
+            }
+            if (call.method === 'watch') {
+                const started = await serveWatch({
+                    fs: lease.environment, targets: call.args[0], binding, requestId: input.requestId, context, cleanup: cleanupContext, maxFrameBytes,
+                    permitted: async () => await permitted() && matches(), release, onCleanupError: options.onCleanupError, stop: () => stop.abort(),
+                });
+                if (!started.ok) {
+                    if (!await permitted() || !matches())
+                        return refused(403);
+                    return reply(started);
+                }
+                transferred = true;
+                return started.value;
+            }
+            if (call.method !== 'openTextLineReader') {
+                const result = await invoke(lease.environment, call, context);
+                if (!await permitted() || !matches())
+                    return refused(403);
+                return reply(result);
+            }
+            const opened = await lease.environment.openTextLineReader(...call.args, context);
+            if (!opened.ok) {
+                if (!await permitted() || !matches())
+                    return refused(403);
+                return reply(opened);
+            }
+            let reader = opened.value;
+            let closing;
+            const close = () => closing ??= Promise.resolve().then(async () => {
+                const current = reader;
+                reader = undefined;
+                try {
+                    if (current)
+                        await current.close(cleanupContext);
+                }
+                finally {
+                    await release();
+                }
+            });
+            closeReader = close;
+            if (!await permitted() || !matches()) {
+                await close();
+                return refused(403);
+            }
+            let ended = false, sequence = 1;
+            let controller;
+            const frame = (value) => {
+                const bytes = new TextEncoder().encode(JSON.stringify(value) + '\n');
+                if (bytes.length > maxFrameBytes)
+                    throw new TypeError('Filesystem frame exceeds its byte limit');
+                return bytes;
+            };
+            const interrupt = () => {
+                if (ended)
+                    return;
+                ended = true;
+                signal?.removeEventListener('abort', interrupt);
+                controller.error(new Error('Remote file stream interrupted'));
+                void close().catch(error => options.onCleanupError?.(error));
+            };
+            const stream = new ReadableStream({
+                start(value) {
+                    controller = value;
+                    controller.enqueue(frame({ ...binding, type: 'opened', sequence: 0 }));
+                    signal?.addEventListener('abort', interrupt, { once: true });
+                    if (signal?.aborted)
+                        interrupt();
+                },
+                async pull() {
+                    try {
+                        if (ended)
+                            return;
+                        if (!await permitted() || !reader || !matches()) {
+                            interrupt();
+                            return;
+                        }
+                        const result = await reader.readLine(context);
+                        if (ended)
+                            return;
+                        if (!await permitted() || !matches()) {
+                            interrupt();
+                            return;
+                        }
+                        if (result.ok && result.value === undefined) {
+                            await close();
+                            if (ended || signal?.aborted)
+                                return;
+                            controller.enqueue(frame({ requestId: input.requestId, sequence: sequence++, type: 'end' }));
+                            ended = true;
+                            signal?.removeEventListener('abort', interrupt);
+                            controller.close();
+                        }
+                        else
+                            controller.enqueue(frame({ requestId: input.requestId, sequence: sequence++, type: 'line', result: wireResult(result) }));
+                    }
+                    catch {
+                        interrupt();
+                    }
+                },
+                async cancel() { ended = true; signal?.removeEventListener('abort', interrupt); stop.abort(); await close(); },
+            }, { highWaterMark: 1 });
+            transferred = true;
+            return new Response(stream, { headers: { 'content-type': streamType, 'cache-control': 'no-store' } });
+        }
+        catch {
+            return refused(503);
+        }
+        finally {
+            if (!transferred) {
+                if (closeReader)
+                    await closeReader();
+                else
+                    await release();
+            }
+        }
+    };
+}

package/dist/remote-files-io.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from '@earendil-works/chord';
+/** Read a response body as JSON under a byte cap (the shared guard of `@hachej/boring-files/request-guard`). */
+export declare function readJson(body: ReadableStream<Uint8Array> | null, context: Context, limit: number): Promise<unknown>;
+export declare function frameReader(body: ReadableStream<Uint8Array>, limit: number): {
+    next: () => Promise<unknown>;
+    close: () => Promise<void>;
+};
+//# sourceMappingURL=remote-files-io.d.ts.map

package/dist/remote-files-io.js

@@ -0,0 +1,46 @@
+import { readBoundedJson } from '@hachej/boring-files/request-guard';
+/** Read a response body as JSON under a byte cap (the shared guard of `@hachej/boring-files/request-guard`). */
+export function readJson(body, context, limit) {
+    return readBoundedJson(body, limit, context.abortSignal);
+}
+export function frameReader(body, limit) {
+    const reader = body.getReader();
+    let chunk = new Uint8Array(), offset = 0;
+    let buffer = new Uint8Array(Math.min(4096, limit)), length = 0;
+    let closed = false;
+    const close = async () => { if (closed)
+        return; closed = true; void reader.cancel().catch(() => { }); reader.releaseLock(); };
+    const next = async () => {
+        while (!closed) {
+            if (offset === chunk.length) {
+                const item = await reader.read();
+                if (item.done) {
+                    if (length)
+                        throw new TypeError('Truncated frame');
+                    return undefined;
+                }
+                chunk = item.value;
+                offset = 0;
+            }
+            const newline = chunk.indexOf(10, offset), end = newline === -1 ? chunk.length : newline;
+            const part = chunk.subarray(offset, end);
+            if (length + part.length > limit)
+                throw new TypeError('Frame byte limit exceeded');
+            if (length + part.length > buffer.length) {
+                const larger = new Uint8Array(Math.min(limit, Math.max(length + part.length, buffer.length * 2)));
+                larger.set(buffer.subarray(0, length));
+                buffer = larger;
+            }
+            buffer.set(part, length);
+            length += part.length;
+            offset = end + (newline === -1 ? 0 : 1);
+            if (newline !== -1) {
+                const text = new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, length));
+                length = 0;
+                return JSON.parse(text);
+            }
+        }
+        throw new TypeError('Reader is closed');
+    };
+    return { next, close };
+}

package/dist/remote-files-positional.d.ts

@@ -0,0 +1,12 @@
+import { FileError } from '@earendil-works/pi-durable/env';
+import type { FileSystem, Result } from '@earendil-works/pi-durable/env';
+import type { Context } from '@earendil-works/chord';
+import { z } from 'zod';
+import type { PositionalCall, RemoteFileSystemCall } from './remote-files-protocol.js';
+/** Worker side: serve one positional call over the worker's native `FileSystem`. `cleanup` closes readers after the request context ends. */
+export declare function servePositional(fs: FileSystem, call: PositionalCall, context: Context, cleanup: Context, maxResponseBytes: number): Promise<Result<unknown, FileError>>;
+type Invoke = <Value>(call: RemoteFileSystemCall, output: z.ZodType<Value>, context: Context) => Promise<Result<Value, FileError>>;
+/** Client side: Pi's `openBinaryReader` and `openDirReader` over `invoke`, one bounded request per call. */
+export declare function remoteReaders(invoke: Invoke, maxResponseBytes: number): Pick<FileSystem, 'openBinaryReader' | 'openDirReader'>;
+export {};
+//# sourceMappingURL=remote-files-positional.d.ts.map

package/dist/remote-files-positional.js

@@ -0,0 +1,208 @@
+// Pi's `BinaryReader` and `DirReader` keep an open handle; a stateless request cannot. Over the remote-files wire each reader call
+// is one request that opens the worker's own native reader, answers a bounded range, page or scan, and closes it again. The client
+// remembers what the file looked like when it was opened and the worker refuses a request when the file no longer matches, which is
+// the stateless counterpart of Pi's "all calls see the same file".
+import { FileError, err, ok } from '@earendil-works/pi-durable/env';
+import { z } from 'zod';
+import { bytes, dirPage, fileInfo, lineScan, maxDirPageEntries, maxRangeBytes } from './remote-files-protocol.js';
+const changed = (left, right) => left.size !== right.size || left.mtimeMs !== right.mtimeMs;
+const changedFile = (path) => new FileError('invalid', 'The file changed since it was opened', path);
+const closedReader = (what, path) => new FileError('invalid', `${what} is closed`, path);
+const aborted = (context, path) => context.abortSignal?.aborted ? new FileError('aborted', 'Operation aborted', path) : undefined;
+/** Worker side: serve one positional call over the worker's native `FileSystem`. `cleanup` closes readers after the request context ends. */
+export async function servePositional(fs, call, context, cleanup, maxResponseBytes) {
+    if (call.method === 'readDirPage')
+        return serveDirPage(fs, call.args, context, cleanup);
+    const [path, options] = call.args;
+    const opened = await fs.openBinaryReader(path, options, context);
+    if (!opened.ok)
+        return opened;
+    const reader = opened.value;
+    try {
+        const before = await reader.info(context);
+        if (!before.ok)
+            return before;
+        if (call.method === 'binaryInfo')
+            return before;
+        const expected = (call.method === 'readRange' ? call.args[4] : call.args[3]) ?? before.value;
+        if (changed(before.value, expected))
+            return err(changedFile(path));
+        let produced;
+        if (call.method === 'readRange') {
+            const [, , offset, length] = call.args;
+            if (length > maxRangeBytes(maxResponseBytes))
+                return err(new FileError('invalid', 'The range exceeds the remote response limit', path));
+            produced = await reader.read(offset, length, context);
+        }
+        else {
+            const { startLine, endLine } = call.args[2];
+            if (endLine !== undefined && endLine <= startLine)
+                return err(new FileError('invalid', 'Invalid line range', path));
+            produced = await reader.scanLines(call.args[2], context);
+        }
+        if (!produced.ok)
+            return produced;
+        // A change while the range was read or the file scanned would mix two versions of it.
+        const after = await reader.info(context);
+        if (!after.ok)
+            return after;
+        return changed(after.value, expected) ? err(changedFile(path)) : produced;
+    }
+    finally {
+        await reader.close(cleanup);
+    }
+}
+async function serveDirPage(fs, [path, offset, maxEntries, expectedMtimeMs], context, cleanup) {
+    const stamp = async () => {
+        // A symbolic link's own timestamps say nothing about the directory behind it.
+        const canonical = await fs.canonicalPath(path, context);
+        if (!canonical.ok)
+            return canonical;
+        const info = await fs.fileInfo(canonical.value, context);
+        return info.ok ? ok(info.value.mtimeMs) : info;
+    };
+    const opened = await fs.openDirReader(path, context);
+    if (!opened.ok)
+        return opened;
+    const reader = opened.value;
+    try {
+        const before = await stamp();
+        if (!before.ok)
+            return before;
+        if (expectedMtimeMs !== undefined && before.value !== expectedMtimeMs)
+            return err(new FileError('invalid', 'The directory changed since it was opened', path));
+        const entries = [];
+        let done = false, skip = offset;
+        while (skip > 0 && !done) {
+            const page = await reader.next(Math.min(skip, maxDirPageEntries), context);
+            if (!page.ok)
+                return page;
+            skip -= page.value.entries.length;
+            done = page.value.done;
+            if (page.value.entries.length === 0 && !page.value.done)
+                return err(new FileError('unknown', 'The native directory reader made no progress', path));
+        }
+        if (maxEntries > 0 && !done) {
+            const page = await reader.next(maxEntries, context);
+            if (!page.ok)
+                return page;
+            entries.push(...page.value.entries);
+            done = page.value.done;
+            if (entries.length === 0 && !done)
+                return err(new FileError('unknown', 'The native directory reader made no progress', path));
+        }
+        const after = await stamp();
+        if (!after.ok)
+            return after;
+        if (after.value !== before.value)
+            return err(new FileError('invalid', 'The directory changed while it was being read', path));
+        return ok({ entries, done, mtimeMs: before.value });
+    }
+    finally {
+        await reader.close(cleanup);
+    }
+}
+/** Client side: Pi's `openBinaryReader` and `openDirReader` over `invoke`, one bounded request per call. */
+export function remoteReaders(invoke, maxResponseBytes) {
+    const chunk = maxRangeBytes(maxResponseBytes);
+    return {
+        openBinaryReader: async (requested, options, context) => {
+            // Snapshot the caller's options before any await: a caller may mutate them while the open is in flight.
+            const wire = options?.noFollow === undefined ? undefined : { noFollow: options.noFollow };
+            // Resolve once: the lease's cwd can change later, and every request of this reader must name the file it opened.
+            const resolved = await invoke({ method: 'absolutePath', args: [requested] }, z.string(), context);
+            if (!resolved.ok)
+                return resolved;
+            const path = resolved.value;
+            const info = await invoke({ method: 'binaryInfo', args: [path, wire] }, fileInfo, context);
+            if (!info.ok)
+                return info;
+            const opened = info.value, expected = { size: opened.size, mtimeMs: opened.mtimeMs };
+            let closed = false;
+            const refuse = (inner) => aborted(inner, path) ?? (closed ? closedReader('Binary reader', path) : undefined);
+            return ok({
+                info: async (inner) => { const failed = refuse(inner); return failed ? err(failed) : ok({ ...opened }); },
+                read: async (offset, length, inner) => {
+                    const failed = refuse(inner);
+                    if (failed)
+                        return err(failed);
+                    if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length < 0)
+                        return err(new FileError('invalid', 'Offset and length must be non-negative safe integers', path));
+                    const parts = [];
+                    let total = 0;
+                    while (total < length) {
+                        const want = Math.min(length - total, chunk);
+                        const piece = await invoke({ method: 'readRange', args: [path, wire, offset + total, want, expected] }, bytes, inner);
+                        if (!piece.ok)
+                            return piece;
+                        parts.push(piece.value);
+                        total += piece.value.length;
+                        if (piece.value.length < want)
+                            break;
+                    }
+                    if (parts.length === 1)
+                        return ok(parts[0]);
+                    const joined = new Uint8Array(total);
+                    let position = 0;
+                    for (const part of parts) {
+                        joined.set(part, position);
+                        position += part.length;
+                    }
+                    return ok(joined);
+                },
+                // The worker's native reader scans in place; moving the file to count its newlines here would defeat a bounded read.
+                scanLines: async (range, inner) => {
+                    const failed = refuse(inner);
+                    if (failed)
+                        return err(failed);
+                    const { startLine, endLine } = range;
+                    if (!Number.isSafeInteger(startLine) || startLine < 0 || (endLine !== undefined && (!Number.isSafeInteger(endLine) || endLine <= startLine)))
+                        return err(new FileError('invalid', 'Invalid line range', path));
+                    return invoke({ method: 'scanLines', args: [path, wire, endLine === undefined ? { startLine } : { startLine, endLine }, expected] }, lineScan, inner);
+                },
+                close: async () => { closed = true; },
+            });
+        },
+        openDirReader: async (requested, context) => {
+            const resolved = await invoke({ method: 'absolutePath', args: [requested] }, z.string(), context);
+            if (!resolved.ok)
+                return resolved;
+            const path = resolved.value;
+            const probe = await invoke({ method: 'readDirPage', args: [path, 0, 0, undefined] }, dirPage, context);
+            if (!probe.ok)
+                return probe;
+            const mtimeMs = probe.value.mtimeMs;
+            let offset = 0, done = false, closed = false, busy = false;
+            return ok({
+                next: async (maxEntries, inner) => {
+                    const failed = aborted(inner, path) ?? (closed ? closedReader('Directory reader', path) : undefined);
+                    if (failed)
+                        return err(failed);
+                    if (!Number.isSafeInteger(maxEntries) || maxEntries <= 0)
+                        return err(new FileError('invalid', 'maxEntries must be a positive safe integer', path));
+                    if (busy)
+                        return err(new FileError('invalid', 'A directory read is already pending', path));
+                    busy = true;
+                    try {
+                        const entries = [];
+                        while (!done && entries.length < maxEntries) {
+                            const page = await invoke({ method: 'readDirPage', args: [path, offset, Math.min(maxEntries - entries.length, maxDirPageEntries), mtimeMs] }, dirPage, inner);
+                            if (!page.ok)
+                                return page;
+                            entries.push(...page.value.entries);
+                            offset += page.value.entries.length;
+                            done = page.value.done;
+                            if (page.value.entries.length === 0 && !done)
+                                return err(new FileError('unknown', 'The remote directory reader made no progress', path));
+                        }
+                        return ok({ entries, done });
+                    }
+                    finally {
+                        busy = false;
+                    }
+                },
+                close: async () => { closed = true; },
+            });
+        },
+    };
+}