@telepath-computer/vault-server 0.4.1 → 0.5.0

package/dist/src/server.js

@@ -1,485 +1,637 @@
-/** Composes the vault HTTP API, filesystem watcher, and WebSocket subscriptions. */
-import { createServer } from "node:http";
-import { realpathSync } from "node:fs";
-import { stat } from "node:fs/promises";
-import { relative } from "node:path";
-import chokidar from "chokidar";
+import { lstat, readdir, realpath } from "node:fs/promises";
+import { STATUS_CODES } from "node:http";
+import { join } from "node:path";
+import { TextDecoder } from "node:util";
+import { FileServer, } from "@telepath-computer/file-server";
 import express from "express";
-import { WebSocketServer, WebSocket } from "ws";
-import { deleteNote, InvalidReferenceError, InvalidUtf8Error, listNotes, mergeFields, readNote, readRawRecord, storedBody, storedFields, VaultIndex, writeNote } from "./notes.js";
-import { hasDotSegment, isVaultPathConfined, resolveVaultPath, toVaultPath } from "./paths.js";
-const noteContentType = "application/vnd.telepath.record+json";
-const watcherDebounceMs = 50;
-/** Raised when a caller's `validate` refuses a write. */
+import { InvalidReferenceError, InvalidUtf8Error, mergeFields, readRawRecord, serializeNote, storedBody, storedFields, VaultIndex, } from "./notes.js";
+const recordContentType = "application/vnd.telepath.record+json";
+const recordResponseContentType = `${recordContentType}; charset=utf-8`;
+const jsonContentType = "application/json; charset=utf-8";
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+const exposedResponseHeaders = "ETag, Accept-Ranges, Content-Range, Accept-Patch";
+const bootstrapQuietMs = 100;
+const bootstrapQuietLimitMs = 1_000;
+/** Raised when a caller's validate hook refuses a record write. */
 class ValidationError extends Error {
 }
+/** A file server with cached structured views for visible markdown files. */
 export class VaultServer {
     app;
     server;
-    /** Resolves once the watcher has indexed the vault and the root is known good. */
     ready;
+    files;
+    validate;
+    maximumJsonBytes;
+    activeChanges = new Set();
+    changesByPath = new Map();
+    bootstrapPathGenerations = new Map();
+    directories = new Set();
+    pathView;
     root;
     index;
-    validate;
-    watcher;
-    webSockets = new WebSocketServer({ noServer: true });
-    sockets = new Map();
-    pendingIndexRefreshes = new Set();
-    pendingWatcherEvents = new Map();
-    pingTimer;
-    isReady = false;
-    isClosing = false;
-    startupRefreshFailed = false;
-    startupRefreshError;
-    boundHost;
+    linkFormat;
+    bodyFormat;
+    resolveIndex;
+    indexAvailable;
+    changeGeneration = 0;
+    bootstrapComplete = false;
     constructor(options) {
         rejectUnknownOptions(options, ["root", "linkFormat", "bodyFormat", "validate", "jsonLimit", "pingIntervalMs"]);
-        const { root, linkFormat = "wikilink", bodyFormat = "markdown", validate, jsonLimit = "32mb", pingIntervalMs = 30_000, } = options;
-        // A symlinked root (e.g. ~/workspace/vault -> ~/Dropbox/Vault) must be
-        // resolved up front: the watcher ignores symlinks, so an unresolved root
-        // would index and watch nothing.
-        this.root = realpathSync(root);
+        const { root, linkFormat = "wikilink", bodyFormat = "markdown", validate, jsonLimit = "32mb", pingIntervalMs, } = options;
+        this.linkFormat = linkFormat;
+        this.bodyFormat = bodyFormat;
         this.validate = validate;
-        const resolveBodyFormat = typeof bodyFormat === "function" ? bodyFormat : () => bodyFormat;
-        this.index = new VaultIndex(this.root, undefined, linkFormat, resolveBodyFormat);
-        this.app = express();
-        this.app.use((request, response, next) => {
-            response.set("Access-Control-Allow-Origin", "*");
-            if (request.method !== "OPTIONS") {
-                next();
-                return;
-            }
-            response.set({
-                "Access-Control-Allow-Methods": "GET, PUT, PATCH, DELETE",
-                "Access-Control-Allow-Headers": "content-type",
-                "Access-Control-Max-Age": "86400",
-            });
-            if (request.get("Access-Control-Request-Private-Network") === "true") {
-                response.set("Access-Control-Allow-Private-Network", "true");
-            }
-            response.status(204).end();
-        });
-        this.app.use(express.json({ type: (request) => shouldParseNoteBody(request), limit: jsonLimit }));
-        this.app.use(async (request, response) => { await handleRequest(this.context(), request, response); });
-        this.app.use((error, _request, response, _next) => {
-            if (isPayloadTooLarge(error))
-                sendError(response, 413, "request body too large");
-            else if (error instanceof SyntaxError)
-                sendError(response, 400, "malformed JSON");
-            else
-                sendError(response, 500, "internal server error");
-        });
-        this.server = createServer(this.app);
-        this.watcher = chokidar.watch(this.root, {
-            ignoreInitial: false,
-            followSymlinks: false,
-            ignored: (path, stats) => stats?.isSymbolicLink() === true || hasDotSegment(toVaultPath(relative(this.root, path))),
-        });
-        const watcherReady = new Promise((resolve, reject) => {
-            this.watcher.once("ready", resolve);
-            this.watcher.on("error", (error) => {
-                if (!this.isReady)
-                    reject(error);
-                else
-                    console.error("sv-vault watcher error", error);
-            });
+        this.maximumJsonBytes = parseByteLimit(jsonLimit);
+        this.indexAvailable = new Promise((resolve) => { this.resolveIndex = resolve; });
+        this.pathView = {
+            [Symbol.iterator]: () => this.index?.[Symbol.iterator]() ?? [][Symbol.iterator](),
+        };
+        const extension = {
+            handle: (request, response, context) => this.handle(request, response, context),
+            listing: async (_request, listing) => {
+                await this.ready;
+                return decorateListing(listing, this.index);
+            },
+            change: (event) => this.change(event),
+        };
+        this.files = new FileServer({
+            root,
+            defaultPort: 4747,
+            ...(pingIntervalMs === undefined ? {} : { pingIntervalMs }),
+            extension,
         });
-        const rootReady = stat(this.root).then((rootStat) => { if (!rootStat.isDirectory())
-            throw new Error("vault root is not a directory"); });
-        this.ready = Promise.all([watcherReady, rootReady]).then(async () => {
-            while (this.pendingIndexRefreshes.size > 0)
-                await Promise.all([...this.pendingIndexRefreshes]);
-            if (this.startupRefreshFailed)
-                throw this.startupRefreshError;
-            this.isReady = true;
+        this.server = this.files.server;
+        const resolvedRoot = realpath(root);
+        this.ready = Promise.all([this.files.ready, resolvedRoot]).then(async ([, canonicalRoot]) => {
+            this.root = canonicalRoot;
+            const bodyFormat = this.bodyFormat;
+            this.index = new VaultIndex(canonicalRoot, undefined, this.linkFormat, typeof bodyFormat === "function" ? bodyFormat : () => bodyFormat);
+            this.resolveIndex();
+            await this.bootstrap(canonicalRoot, this.index);
+            await this.drainBootstrapChanges();
+            this.bootstrapComplete = true;
+            this.bootstrapPathGenerations.clear();
         });
-        this.server.on("upgrade", async (request, socket, head) => {
-            const path = decodeRequestPath(request.url ?? "/");
-            if (path === null || hasHiddenUrlSegment(path) || !rawPathname(request.url ?? "/").endsWith("/")) {
-                socket.destroy();
-                return;
+        void this.ready.catch(() => { });
+        // FileServer deliberately validates methods and OPTIONS before invoking an
+        // extension hook. This thin mount wrapper makes the vault's additional
+        // index readiness gate apply to those requests too, without copying the
+        // base router or any of its resource dispatch.
+        this.app = express();
+        this.app.disable("x-powered-by");
+        this.app.use(async (request, response, next) => {
+            try {
+                await this.ready;
             }
-            const absolutePath = resolveVaultPath(this.root, path);
-            if (!absolutePath || !await isVaultPathConfined(this.root, absolutePath)) {
-                socket.destroy();
+            catch (error) {
+                // A base readiness failure is still best mapped by FileServer itself.
+                // Only vault-index bootstrap failures need the local error boundary.
+                try {
+                    await this.files.ready;
+                }
+                catch {
+                    this.files.app(request, response, next);
+                    return;
+                }
+                sendReadinessError(request, response, error);
                 return;
             }
-            this.webSockets.handleUpgrade(request, socket, head, (webSocket) => {
-                const subscription = { isAlive: true };
-                this.sockets.set(webSocket, subscription);
-                webSocket.on("pong", () => { subscription.isAlive = true; });
-                webSocket.once("close", () => this.sockets.delete(webSocket));
-                this.webSockets.emit("connection", webSocket, request);
-            });
+            this.files.app(request, response, next);
         });
-        this.watcher.on("add", (path) => this.handleWatcherChange("created", path))
-            .on("change", (path) => this.handleWatcherChange("updated", path))
-            .on("unlink", (path) => {
-            const publish = this.isReady && !this.isClosing;
-            this.cancelPendingWatcherEvent(path);
-            this.index.delete(path);
-            if (publish)
-                this.emitEvent("deleted", path);
-        });
-        this.pingTimer = setInterval(() => {
-            for (const [socket, subscription] of this.sockets) {
-                if (socket.readyState !== WebSocket.OPEN)
-                    continue;
-                if (!subscription.isAlive) {
-                    socket.terminate();
-                    continue;
-                }
-                subscription.isAlive = false;
-                socket.ping();
-            }
-        }, pingIntervalMs);
-    }
-    /** The address the server is bound to, or undefined before listening. */
-    get url() {
-        const port = this.port;
-        return port === undefined || this.boundHost === undefined ? undefined : `http://${this.boundHost}:${port}`;
-    }
-    /** The port actually bound, which for port 0 is the one the OS chose. */
-    get port() {
-        const address = this.server.address();
-        return address !== null && typeof address === "object" ? address.port : undefined;
     }
-    /** Every visible disk path currently held by the live index. */
-    get paths() { return this.index; }
-    /** Replace runtime formatting settings, rebuilding data derived from bodies. */
+    /** The URL currently bound, or undefined before listening and after closing. */
+    get url() { return this.files.url; }
+    /** The port currently bound, including an operating-system-selected port. */
+    get port() { return this.files.port; }
+    /** Every visible regular-file disk path currently held by the live index. */
+    get paths() { return this.pathView; }
+    /** Replace runtime formatting settings, rebuilding data derived from bodies synchronously. */
     configure(options) {
         rejectUnknownOptions(options, ["linkFormat", "bodyFormat"]);
-        this.index.configure(options);
+        if (options.linkFormat !== undefined)
+            this.linkFormat = options.linkFormat;
+        if (options.bodyFormat !== undefined)
+            this.bodyFormat = options.bodyFormat;
+        this.index?.configure(options);
     }
-    /** Accept connections, once the vault is indexed. Resolves with the server. */
+    /** Start accepting connections after the base watcher and record index are ready. */
     async listen(options = {}) {
         await this.ready;
-        const host = options.host ?? "127.0.0.1";
-        const firstPort = options.port ?? 4747;
-        const attempts = options.port === undefined ? 100 : 1;
-        for (let offset = 0; offset < attempts; offset += 1) {
-            const port = firstPort + offset;
+        await this.files.listen(options);
+        return this;
+    }
+    /** Release the embedded file server resources. */
+    close() { return this.files.close(); }
+    /** Delegate a mount-relative WebSocket upgrade after the record index is ready. */
+    async handleUpgrade(request, socket, head, requestTarget = request.url ?? "") {
+        try {
+            await this.ready;
+        }
+        catch (error) {
+            try {
+                await this.files.ready;
+            }
+            catch {
+                await this.files.handleUpgrade(request, socket, head, requestTarget);
+                return;
+            }
+            await sendUpgradeReadinessError(socket, error);
+            return;
+        }
+        await this.files.handleUpgrade(request, socket, head, requestTarget);
+    }
+    async bootstrap(root, index) {
+        await this.refreshTree(root, index);
+    }
+    async refreshTree(root, index) {
+        const walk = async (directory) => {
+            let entries;
             try {
-                await new Promise((resolve, reject) => {
-                    const onError = (error) => { this.server.removeListener("listening", onListening); reject(error); };
-                    const onListening = () => { this.server.removeListener("error", onError); resolve(); };
-                    this.server.once("error", onError);
-                    this.server.once("listening", onListening);
-                    this.server.listen(port, host);
-                });
-                break;
+                entries = await readdir(directory, { withFileTypes: true, encoding: "buffer" });
             }
             catch (error) {
-                if (!isObject(error) || error.code !== "EADDRINUSE" || offset === attempts - 1)
+                if (isMissing(error))
+                    return;
+                throw error;
+            }
+            for (const entry of entries) {
+                const name = decodeDirectoryName(entry.name);
+                if (name === undefined || name.startsWith(".") || name.includes("\\"))
+                    continue;
+                const path = join(directory, name);
+                const diskPath = index.pathFor(path);
+                const generation = this.bootstrapGenerationFor(diskPath);
+                let current;
+                try {
+                    current = await lstat(path);
+                }
+                catch (error) {
+                    if (isMissing(error))
+                        continue;
                     throw error;
-                await new Promise((resolve) => setImmediate(resolve));
+                }
+                if (this.bootstrapGenerationFor(diskPath) !== generation)
+                    continue;
+                if (current.isDirectory()) {
+                    this.directories.add(diskPath);
+                    await walk(path);
+                }
+                else if (current.isFile()) {
+                    if (name.endsWith(".md"))
+                        await index.refresh(path);
+                    else
+                        index.add(path);
+                }
+            }
+        };
+        await walk(root);
+    }
+    bootstrapGenerationFor(path) {
+        let generation = 0;
+        let prefix = "";
+        for (const segment of path.split("/")) {
+            prefix = prefix === "" ? segment : `${prefix}/${segment}`;
+            generation = Math.max(generation, this.bootstrapPathGenerations.get(prefix) ?? 0);
+        }
+        return generation;
+    }
+    async drainBootstrapChanges() {
+        const deadline = Date.now() + bootstrapQuietLimitMs;
+        while (true) {
+            while (this.activeChanges.size > 0)
+                await Promise.all([...this.activeChanges]);
+            const observedGeneration = this.changeGeneration;
+            const quietMs = Math.min(bootstrapQuietMs, Math.max(0, deadline - Date.now()));
+            if (quietMs === 0)
+                return;
+            await new Promise((resolve) => setTimeout(resolve, quietMs));
+            if (this.activeChanges.size === 0 && this.changeGeneration === observedGeneration)
+                return;
+            if (Date.now() >= deadline) {
+                while (this.activeChanges.size > 0)
+                    await Promise.all([...this.activeChanges]);
+                return;
             }
         }
-        this.boundHost = host;
-        return this;
-    }
-    async close() {
-        this.isClosing = true;
-        for (const path of this.pendingWatcherEvents.keys())
-            this.cancelPendingWatcherEvent(path);
-        clearInterval(this.pingTimer);
-        for (const socket of this.sockets.keys())
-            socket.terminate();
-        await this.watcher.close();
-        this.webSockets.close();
-        if (this.server.listening)
-            await new Promise((resolve, reject) => this.server.close((error) => error ? reject(error) : resolve()));
-        this.boundHost = undefined;
     }
-    context() {
-        return { root: this.root, index: this.index, validate: this.validate, runMutation: this.runMutation };
+    async handle(request, response, context) {
+        await this.ready;
+        const index = this.index;
+        const root = this.root;
+        try {
+            if (request.method === "DELETE") {
+                if (context.trailingSlash) {
+                    if (context.resource.type === "dir")
+                        this.directories.add(context.path);
+                    return false;
+                }
+                if (context.resource.type === "file")
+                    return false;
+                const sourcePath = `${context.path}.md`;
+                if ((await context.inspect(sourcePath)).type !== "file") {
+                    if (context.resource.type === "dir")
+                        this.directories.add(context.path);
+                    return false;
+                }
+                await context.remove(sourcePath);
+                response.status(204).end();
+                return true;
+            }
+            const recordMutation = (request.method === "PUT" || request.method === "PATCH")
+                && isRecordContentType(request.get("Content-Type"))
+                && !context.trailingSlash
+                && !context.path.endsWith(".md");
+            if (recordMutation) {
+                if (context.resource.type === "file") {
+                    sendError(request, response, 409, "literal file occupies record URL");
+                    return true;
+                }
+                await this.mutateRecord(request, response, context, root, index);
+                return true;
+            }
+            if (request.method !== "GET" && request.method !== "HEAD")
+                return false;
+            if (!context.trailingSlash && context.resource.type !== "file") {
+                const sourcePath = `${context.path}.md`;
+                if ((await context.inspect(sourcePath)).type === "file") {
+                    try {
+                        sendRecord(request, response, 200, index.read(join(root, ...sourcePath.split("/"))));
+                    }
+                    catch (error) {
+                        if (error instanceof InvalidUtf8Error)
+                            sendError(request, response, 422, error.message);
+                        else
+                            throw error;
+                    }
+                    return true;
+                }
+            }
+            return false;
+        }
+        catch (error) {
+            if (error instanceof InvalidReferenceError) {
+                sendError(request, response, 400, error.message);
+                return true;
+            }
+            if (error instanceof ValidationError) {
+                sendError(request, response, 422, error.message);
+                return true;
+            }
+            if (error instanceof InvalidUtf8Error) {
+                sendError(request, response, 422, error.message);
+                return true;
+            }
+            throw error;
+        }
     }
-    runMutation = async (type, absolutePath, action) => {
-        const result = await action();
-        this.cancelPendingWatcherEvent(absolutePath);
-        this.emitEvent(type, absolutePath);
-        return result;
-    };
-    emitEvent(type, absolutePath) {
-        const diskPath = toVaultPath(relative(this.root, absolutePath));
-        const path = diskPath.endsWith(".md") ? diskPath.slice(0, -3) : diskPath;
-        if (hasDotSegment(path))
+    async mutateRecord(request, response, context, root, index) {
+        const document = await readRecordDocument(request, this.maximumJsonBytes, response);
+        if (document === undefined)
             return;
-        for (const socket of this.sockets.keys())
-            if (socket.readyState === WebSocket.OPEN)
-                socket.send(JSON.stringify({ type, path }));
-    }
-    handleWatcherChange(type, path) {
-        if (this.isClosing)
+        if (Object.hasOwn(document, "fields") && !isObject(document.fields)) {
+            sendError(request, response, 400, "fields must be an object");
             return;
-        if (!this.isReady) {
-            void this.refreshIndex(path);
+        }
+        if (Object.hasOwn(document, "body") && document.body !== null && typeof document.body !== "string") {
+            sendError(request, response, 400, "body must be a string or null");
             return;
         }
-        const existing = this.pendingWatcherEvents.get(path);
-        if (existing?.timer)
-            clearTimeout(existing.timer);
-        const pending = {
-            type: existing?.type === "created" || type === "created" ? "created" : "updated",
-        };
-        pending.timer = setTimeout(() => { delete pending.timer; void this.flushWatcherEvent(path, pending); }, watcherDebounceMs);
-        pending.timer.unref();
-        this.pendingWatcherEvents.set(path, pending);
-    }
-    async flushWatcherEvent(path, pending) {
-        const outcome = await this.refreshIndex(path);
-        if (this.pendingWatcherEvents.get(path) !== pending)
+        const sourcePath = `${context.path}.md`;
+        const source = await context.inspect(sourcePath);
+        if (source.type === "dir") {
+            sendError(request, response, 409, "cannot replace a directory");
             return;
-        this.pendingWatcherEvents.delete(path);
-        if (outcome === "committed" && !this.isClosing)
-            this.emitEvent(pending.type, path);
-    }
-    cancelPendingWatcherEvent(path) {
-        const pending = this.pendingWatcherEvents.get(path);
-        if (pending?.timer)
-            clearTimeout(pending.timer);
-        this.pendingWatcherEvents.delete(path);
-    }
-    refreshIndex(path) {
-        const startup = !this.isReady;
-        const refresh = this.index.refresh(path).catch((error) => {
-            if (startup) {
-                if (!this.startupRefreshFailed)
-                    this.startupRefreshError = error;
-                this.startupRefreshFailed = true;
+        }
+        const exists = source.type === "file";
+        const absolutePath = join(root, ...sourcePath.split("/"));
+        const linkingPath = sourcePath;
+        if (request.method === "PUT") {
+            let previous;
+            if (exists) {
+                try {
+                    previous = await readRawRecord(absolutePath);
+                }
+                catch (error) {
+                    if (!(error instanceof InvalidUtf8Error))
+                        throw error;
+                }
             }
-            else
-                console.error("sv-vault index refresh error", error);
-            return "failed";
-        });
-        this.pendingIndexRefreshes.add(refresh);
-        void refresh.finally(() => this.pendingIndexRefreshes.delete(refresh));
-        return refresh;
-    }
-}
-async function handleRequest(context, request, response) {
-    const path = decodeRequestPath(request.originalUrl);
-    if (path === null) {
-        sendError(response, 400, "invalid path");
-        return;
-    }
-    if (hasHiddenUrlSegment(path)) {
-        sendError(response, 404, "not found");
-        return;
-    }
-    const absolutePath = resolveVaultPath(context.root, path);
-    if (!absolutePath) {
-        sendError(response, 400, "path escapes vault");
-        return;
-    }
-    if (!await isVaultPathConfined(context.root, absolutePath)) {
-        sendError(response, 400, "path escapes vault");
-        return;
-    }
-    try {
-        if (request.method === "GET") {
-            await handleGet(context, absolutePath, request, response);
+            const fields = storedFields((document.fields ?? {}), previous?.fields, index, linkingPath);
+            const body = typeof document.body === "string"
+                ? storedBody(document.body, previous?.body, index, linkingPath)
+                : undefined;
+            const record = { fields, ...(body === undefined ? {} : { body }) };
+            await this.approve(context.path, record);
+            const bytes = Buffer.from(await serializeNote(absolutePath, record));
+            const result = await context.replace(sourcePath, bytes);
+            sendRecord(request, response, result === "created" ? 201 : 200, index.read(absolutePath));
             return;
         }
-        if (["PUT", "PATCH", "DELETE"].includes(request.method)) {
-            await handleWrite(context, absolutePath, request, response);
+        if (!exists) {
+            sendError(request, response, 404, "record not found");
             return;
         }
-        sendError(response, 405, "method not allowed");
-    }
-    catch (error) {
-        if (error instanceof ValidationError)
-            sendError(response, 422, error.message);
-        else if (error instanceof InvalidReferenceError)
-            sendError(response, 400, error.message);
-        else if (error instanceof InvalidUtf8Error)
-            sendError(response, 422, error.message);
-        else if (isMissing(error))
-            sendError(response, 404, "not found");
-        else if (error instanceof SyntaxError)
-            sendError(response, 400, "malformed JSON");
-        else {
-            console.error(error);
-            sendError(response, 500, "internal server error");
-        }
-    }
-}
-async function handleGet(context, absolutePath, request, response) {
-    if (rawPathname(request.originalUrl).endsWith("/")) {
-        if (!(await isDirectory(absolutePath))) {
-            sendError(response, 404, "directory not found");
+        const current = index.read(absolutePath);
+        const fieldPatch = document.fields;
+        const bodyTouched = Object.hasOwn(document, "body");
+        if ((fieldPatch === undefined || Object.keys(fieldPatch).length === 0) && !bodyTouched) {
+            sendRecord(request, response, 200, current);
             return;
         }
-        response.json(listNotes(context.index, canonicalPath(context.root, absolutePath)));
-        return;
-    }
-    if (await isFile(absolutePath)) {
-        response.sendFile(absolutePath);
-        return;
+        const previous = await readRawRecord(absolutePath);
+        const fields = fieldPatch === undefined
+            ? previous.fields
+            : storedFields(mergeFields(current.fields, fieldPatch), previous.fields, index, linkingPath, fieldPatch);
+        const body = bodyTouched
+            ? typeof document.body === "string"
+                ? storedBody(document.body, previous.body, index, linkingPath)
+                : undefined
+            : previous.body;
+        const record = { fields, ...(body === undefined ? {} : { body }) };
+        await this.approve(context.path, record);
+        const bytes = Buffer.from(await serializeNote(absolutePath, record, fieldPatch ?? {}, bodyTouched, previous.rawBody));
+        await context.replace(sourcePath, bytes);
+        sendRecord(request, response, 200, index.read(absolutePath));
     }
-    if (await isFile(`${absolutePath}.md`)) {
-        if (!await isVaultPathConfined(context.root, `${absolutePath}.md`)) {
-            sendError(response, 400, "path escapes vault");
+    async approve(path, record) {
+        if (this.validate === undefined)
             return;
+        try {
+            await this.validate({ path, ...record });
         }
-        response.json(await readNote(context.root, `${absolutePath}.md`, context.index));
-        return;
-    }
-    if (await isDirectory(absolutePath)) {
-        response.redirect(308, `${request.path}/`);
-        return;
-    }
-    sendError(response, 404, "not found");
-}
-async function handleWrite(context, absolutePath, request, response) {
-    const path = decodeRequestPath(request.originalUrl) ?? "";
-    if (rawPathname(request.originalUrl).endsWith("/") || path.endsWith(".md")) {
-        sendError(response, 405, "path is read-only");
-        return;
-    }
-    if (request.method !== "DELETE" && !request.is(noteContentType)) {
-        sendError(response, 415, "unsupported content type");
-        return;
-    }
-    if (await isFile(absolutePath)) {
-        sendError(response, 409, "literal file occupies record URL");
-        return;
-    }
-    const notePath = `${absolutePath}.md`;
-    if (!await isVaultPathConfined(context.root, notePath)) {
-        sendError(response, 400, "path escapes vault");
-        return;
-    }
-    const exists = await isFile(notePath);
-    if (request.method === "DELETE") {
-        if (!exists) {
-            sendError(response, 404, "record not found");
-            return;
+        catch (error) {
+            throw new ValidationError(error instanceof Error ? error.message : String(error));
         }
-        await context.runMutation("deleted", notePath, () => deleteNote(notePath, context.index));
-        response.status(204).end();
-        return;
-    }
-    if (!isObject(request.body)) {
-        sendError(response, 400, "body must be an object");
-        return;
-    }
-    if ("fields" in request.body && !isObject(request.body.fields)) {
-        sendError(response, 400, "fields must be an object");
-        return;
     }
-    if ("body" in request.body && request.body.body !== null && typeof request.body.body !== "string") {
-        sendError(response, 400, "body must be a string");
-        return;
-    }
-    const linkingNotePath = canonicalPath(context.root, notePath);
-    if (request.method === "PUT") {
-        let previous;
-        if (exists) {
+    change(event) {
+        this.changeGeneration += 1;
+        if (!this.bootstrapComplete)
+            this.bootstrapPathGenerations.set(event.path, this.changeGeneration);
+        const previous = this.changesByPath.get(event.path);
+        const change = (previous === undefined ? Promise.resolve() : previous.then(() => undefined, () => undefined))
+            .then(() => this.refreshChange(event));
+        this.changesByPath.set(event.path, change);
+        this.activeChanges.add(change);
+        const cleanup = () => {
+            this.activeChanges.delete(change);
+            if (this.changesByPath.get(event.path) === change)
+                this.changesByPath.delete(event.path);
+        };
+        void change.then(cleanup, cleanup);
+        return change;
+    }
+    async refreshChange(event) {
+        await this.indexAvailable;
+        const index = this.index;
+        const root = this.root;
+        const absolutePath = join(root, ...event.path.split("/"));
+        try {
+            let current;
             try {
-                previous = await readRawRecord(notePath);
+                current = await lstat(absolutePath);
             }
             catch (error) {
-                if (!(error instanceof InvalidUtf8Error))
+                if (!isMissing(error))
                     throw error;
+                const wasDirectory = this.directories.has(event.path) || index.hasDescendant(event.path);
+                this.forgetDirectoryTree(event.path);
+                index.deleteTree(absolutePath);
+                if (wasDirectory)
+                    return event;
+            }
+            if (current?.isDirectory()) {
+                this.forgetDirectoryTree(event.path);
+                this.directories.add(event.path);
+                index.deleteTree(absolutePath);
+                await this.refreshTree(absolutePath, index);
+                return event;
+            }
+            if (current?.isFile()) {
+                const replacedDirectory = this.directories.has(event.path) || index.hasDescendant(event.path);
+                this.forgetDirectoryTree(event.path);
+                if (replacedDirectory)
+                    index.deleteTree(absolutePath);
+                if (event.path.endsWith(".md"))
+                    await index.refresh(absolutePath);
+                else
+                    index.add(absolutePath);
+                for (let separator = event.path.lastIndexOf("/"); separator >= 0; separator = event.path.lastIndexOf("/", separator - 1)) {
+                    this.directories.add(event.path.slice(0, separator));
+                }
             }
         }
-        const fields = storedFields((request.body.fields ?? {}), previous?.fields, context.index, linkingNotePath);
-        const body = typeof request.body.body === "string"
-            ? storedBody(request.body.body, previous?.body, context.index, linkingNotePath)
-            : undefined;
-        const record = { fields, ...(body === undefined ? {} : { body }) };
-        await approve(context, notePath, record);
-        const note = await context.runMutation(exists ? "updated" : "created", notePath, () => writeNote(context.root, notePath, context.index, record));
-        response.status(exists ? 200 : 201).json(note);
-        return;
-    }
-    if (!exists) {
-        sendError(response, 404, "record not found");
-        return;
+        catch (error) {
+            if (isDirectoryRead(error)) {
+                this.directories.add(event.path);
+                index.delete(absolutePath);
+                return event;
+            }
+            if (isMissing(error))
+                index.deleteTree(absolutePath);
+            else {
+                console.error("sv-vault index refresh error", error);
+                // A cache failure must not erase the base protocol's dirty signal.
+                // Publishing the literal event lets clients refetch and preserves the
+                // extension seam's fail-open guarantee for change hooks.
+                return event;
+            }
+        }
+        if (!event.path.endsWith(".md"))
+            return event;
+        const recordPath = event.path.slice(0, -3);
+        try {
+            const exact = await lstat(join(root, ...recordPath.split("/")));
+            if (exact.isFile())
+                return event;
+        }
+        catch (error) {
+            if (!isMissing(error))
+                console.error("sv-vault shadow inspection error", error);
+        }
+        return { ...event, path: recordPath };
     }
-    const current = await readNote(context.root, notePath, context.index);
-    const fieldPatch = request.body.fields;
-    const bodyTouched = Object.hasOwn(request.body, "body");
-    if ((fieldPatch === undefined || Object.keys(fieldPatch).length === 0) && !bodyTouched) {
-        response.json(current);
-        return;
+    forgetDirectoryTree(path) {
+        const prefix = `${path}/`;
+        for (const directory of this.directories) {
+            if (directory === path || directory.startsWith(prefix))
+                this.directories.delete(directory);
+        }
     }
-    const previous = await readRawRecord(notePath);
-    const fields = fieldPatch === undefined
-        ? previous.fields
-        : storedFields(mergeFields(current.fields, fieldPatch), previous.fields, context.index, linkingNotePath, fieldPatch);
-    const body = bodyTouched
-        ? typeof request.body.body === "string"
-            ? storedBody(request.body.body, previous.body, context.index, linkingNotePath)
-            : undefined
-        : previous.body;
-    const record = { fields, ...(body === undefined ? {} : { body }) };
-    await approve(context, notePath, record);
-    response.json(await context.runMutation("updated", notePath, () => writeNote(context.root, notePath, context.index, record, fieldPatch ?? {}, bodyTouched, previous.rawBody)));
 }
-/**
- * Offer the record a write would produce to the caller's `validate`, before any
- * of it reaches disk — so a refusal leaves nothing behind, not even a temp file.
- * The fields are the ones that will be stored, not the ones a read would give
- * back: a rule is judged against what the write actually persists.
- */
-async function approve(context, notePath, content) {
-    if (!context.validate)
-        return;
-    const diskPath = canonicalPath(context.root, notePath);
-    const record = { path: diskPath.slice(0, -3), ...content };
+function decorateListing(listing, index) {
+    const exactFiles = new Set(listing.entries.filter(({ type }) => type === "file").map(({ name }) => name));
+    const entries = listing.entries.map((entry) => {
+        if (entry.type !== "file" || !entry.name.endsWith(".md"))
+            return entry;
+        const name = entry.name.slice(0, -3);
+        if (exactFiles.has(name))
+            return entry;
+        const diskPath = listing.path === "" ? entry.name : `${listing.path}/${entry.name}`;
+        const record = index.listingEntry(diskPath);
+        if (record === undefined)
+            return entry;
+        return {
+            name,
+            type: "record",
+            modified: record.updated,
+            fields: record.fields,
+            ...(record.body === undefined ? {} : { body: record.body }),
+            ...(record.error === undefined ? {} : { error: record.error }),
+        };
+    });
+    entries.sort(compareDirectoryEntries);
+    return { path: listing.path, entries };
+}
+function compareDirectoryEntries(left, right) {
+    return left.name < right.name ? -1
+        : left.name > right.name ? 1
+            : left.type < right.type ? -1
+                : left.type > right.type ? 1
+                    : 0;
+}
+async function readRecordDocument(request, maximumBytes, response) {
+    const declaredLength = request.headers["content-length"];
+    if (typeof declaredLength === "string" && Number(declaredLength) > maximumBytes) {
+        rejectOversizedBody(request, response);
+        return undefined;
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const value of request) {
+        const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+        size += chunk.length;
+        if (size > maximumBytes) {
+            rejectOversizedBody(request, response);
+            return undefined;
+        }
+        chunks.push(chunk);
+    }
+    let value;
     try {
-        await context.validate(record);
+        value = JSON.parse(utf8Decoder.decode(Buffer.concat(chunks, size)));
     }
-    catch (error) {
-        throw new ValidationError(error instanceof Error ? error.message : String(error));
+    catch {
+        sendError(request, response, 400, "malformed JSON");
+        return undefined;
+    }
+    if (!isObject(value)) {
+        sendError(request, response, 400, "body must be an object");
+        return undefined;
     }
+    return value;
 }
-function isObject(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
-function rejectUnknownOptions(options, knownOptions) {
-    const unknownOption = Object.keys(options).find((key) => !knownOptions.includes(key));
-    if (unknownOption)
-        throw new Error(`unknown VaultServer option "${unknownOption}"`);
+function rejectOversizedBody(request, response) {
+    request.pause();
+    response.shouldKeepAlive = false;
+    response.set("Connection", "close");
+    response.once("finish", () => setImmediate(() => request.destroy()));
+    sendError(request, response, 413, "request body is too large");
+}
+function sendRecord(request, response, status, value) {
+    sendSerialized(request, response, status, value, recordResponseContentType);
+}
+function sendSerialized(request, response, status, value, contentType) {
+    const body = Buffer.from(JSON.stringify(value));
+    response.set({ "Content-Type": contentType, "Content-Length": String(body.length) });
+    response.status(status);
+    if (request.method === "HEAD")
+        response.end();
+    else
+        response.end(body);
+}
+function sendError(request, response, status, message) {
+    sendSerialized(request, response, status, { error: message }, jsonContentType);
+}
+function sendReadinessError(request, response, error) {
+    const { status, message } = mapReadinessError(error);
+    response.set({
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Expose-Headers": exposedResponseHeaders,
+    });
+    sendError(request, response, status, message);
 }
-async function isFile(path) { try {
-    return (await stat(path)).isFile();
+async function sendUpgradeReadinessError(socket, error) {
+    if (socket.closed)
+        return;
+    const { status, message } = mapReadinessError(error);
+    const body = Buffer.from(JSON.stringify({ error: message }));
+    const response = Buffer.from([
+        `HTTP/1.1 ${status} ${STATUS_CODES[status] ?? "Error"}`,
+        `Content-Type: ${jsonContentType}`,
+        `Content-Length: ${body.length}`,
+        "Connection: close",
+        "",
+        "",
+    ].join("\r\n"));
+    await new Promise((resolve) => {
+        let settled = false;
+        const close = () => {
+            if (settled)
+                return;
+            settled = true;
+            socket.removeListener("finish", finish);
+            socket.removeListener("close", close);
+            socket.removeListener("error", fail);
+            resolve();
+        };
+        const finish = () => { socket.destroy(); };
+        const fail = () => { socket.destroy(); };
+        socket.once("finish", finish);
+        socket.once("close", close);
+        socket.once("error", fail);
+        if (!socket.destroyed)
+            socket.end(Buffer.concat([response, body]));
+        if (socket.closed)
+            close();
+        else if (socket.writableFinished)
+            finish();
+    });
 }
-catch {
-    return false;
-} }
-async function isDirectory(path) { try {
-    return (await stat(path)).isDirectory();
+function mapReadinessError(error) {
+    const code = error !== null && typeof error === "object" && "code" in error ? error.code : undefined;
+    if (code === "ENOENT" || code === "ENOTDIR")
+        return { status: 404, message: "not found" };
+    if (code === "EACCES" || code === "EPERM")
+        return { status: 403, message: "forbidden" };
+    return { status: 500, message: "internal server error" };
 }
-catch {
-    return false;
-} }
-function isMissing(error) { return isObject(error) && "code" in error && error.code === "ENOENT"; }
-function isPayloadTooLarge(error) {
-    return isObject(error) && (("status" in error && error.status === 413) || ("type" in error && error.type === "entity.too.large"));
+function isRecordContentType(contentType) {
+    return contentType?.split(";", 1)[0]?.trim().toLowerCase() === recordContentType;
 }
-function rawPathname(url) { return url.split("?", 1)[0] ?? ""; }
-function decodeRequestPath(url) {
+function parseByteLimit(limit) {
+    if (typeof limit === "number") {
+        if (!Number.isFinite(limit) || limit < 0)
+            throw new Error("jsonLimit must be a non-negative byte count");
+        return Math.floor(limit);
+    }
+    const match = /^\s*(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?\s*$/i.exec(limit);
+    if (match === null)
+        throw new Error("jsonLimit must be a byte count such as 32mb");
+    const units = { b: 1, kb: 1024, mb: 1024 ** 2, gb: 1024 ** 3 };
+    return Math.floor(Number(match[1]) * units[(match[2] ?? "b").toLowerCase()]);
+}
+function decodeDirectoryName(name) {
     try {
-        const path = decodeURIComponent(rawPathname(url)).replace(/^\/+/, "");
-        return path.includes("\0") ? null : path;
+        return utf8Decoder.decode(name);
     }
     catch {
-        return null;
+        return undefined;
     }
 }
-function hasHiddenUrlSegment(path) {
-    return path.split("/").some((segment) => segment !== "." && segment !== ".." && segment.startsWith("."));
+function rejectUnknownOptions(options, knownOptions) {
+    const unknownOption = Object.keys(options).find((key) => !knownOptions.includes(key));
+    if (unknownOption)
+        throw new Error(`unknown VaultServer option "${unknownOption}"`);
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isMissing(error) {
+    return error !== null && typeof error === "object" && "code" in error
+        && (error.code === "ENOENT" || error.code === "ENOTDIR");
 }
-function shouldParseNoteBody(request) {
-    if (request.method !== "PUT" && request.method !== "PATCH")
-        return false;
-    if (request.headers["content-type"]?.split(";", 1)[0]?.trim().toLowerCase() !== noteContentType)
-        return false;
-    const url = request.url ?? "/";
-    const path = decodeRequestPath(url);
-    return path !== null && !hasHiddenUrlSegment(path) && !rawPathname(url).endsWith("/") && !path.endsWith(".md");
+function isDirectoryRead(error) {
+    return error !== null && typeof error === "object" && "code" in error && error.code === "EISDIR";
 }
-function canonicalPath(root, absolutePath) { return toVaultPath(relative(root, absolutePath)); }
-function sendError(response, status, message) { response.status(status).json({ error: message }); }
 //# sourceMappingURL=server.js.map