@shiyuphan/follow-me 0.1.0 → 0.1.1

package/dist/src/server.js

@@ -1,12 +1,27 @@
-import { spawn } from "node:child_process";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isPlanVersion } from "./plan.js";
+import { isLockToken } from "./session.js";
+/** The requested port is taken; host.ts decides whether that is our server or a stranger. */
+export class PortInUseError extends Error {
+    name = "PortInUseError";
+    port;
+    constructor(port) {
+        super(`port ${port} is in use`);
+        this.port = port;
+    }
+}
+/** A session the server cannot host, with the reason the CLI shows. */
+export class RegistrationError extends Error {
+    name = "RegistrationError";
+}
+/** GET /api/health answers with this, so a CLI can tell our server from another program. */
+export const HEALTH_APP = "follow-me";
 const UI_DIR = new URL("../ui/", import.meta.url);
 const STATIC_FILES = new Map([
-    ["/", { file: "index.html", type: "text/html; charset=utf-8" }],
     ["/app.js", { file: "app.js", type: "text/javascript; charset=utf-8" }],
     ["/playback.js", { file: "playback.js", type: "text/javascript; charset=utf-8" }],
     ["/style.css", { file: "style.css", type: "text/css; charset=utf-8" }],
@@ -15,6 +30,7 @@ const MAX_BODY_BYTES = 1_000_000;
 const BASE32 = "abcdefghijklmnopqrstuvwxyz234567";
 const COMMENT_ID = /^c_[a-z2-7]{6}$/;
 const UNIT_ID = /^[hfm]_[0-9a-f]{12}(~\d+)?$/;
+const SESSION_ID = /^[0-9a-f]{12}$/;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -30,6 +46,19 @@ function isRepoPath(value) {
 function isIndex(value) {
     return typeof value === "number" && Number.isInteger(value) && value >= 0;
 }
+export function isSessionId(value) {
+    return typeof value === "string" && SESSION_ID.test(value);
+}
+/** Derived from the session directory, so registering one session twice yields one id. */
+export function sessionIdOf(dir) {
+    const id = createHash("sha256").update(dir).digest("hex").slice(0, 12);
+    if (!isSessionId(id))
+        throw new Error(`sha256 produced ${id}`);
+    return id;
+}
+export function sessionPath(id) {
+    return `/s/${id}/`;
+}
 function parseAnchor(raw) {
     if (!isRecord(raw))
         return null;
@@ -74,6 +103,21 @@ export function parseComment(raw) {
         return null;
     return { id, anchor, context: { commitMessage, path }, body, createdAt };
 }
+/** The one place untrusted JSON becomes a Registration. */
+export function parseRegistration(raw) {
+    if (!isRecord(raw))
+        return null;
+    const { dir, mode, version, hash, lockToken } = raw;
+    if (typeof dir !== "string" || !isAbsolute(dir))
+        return null;
+    if (mode !== "split" && mode !== "walk")
+        return null;
+    if (!isPlanVersion(version) || typeof hash !== "string" || hash === "")
+        return null;
+    if (lockToken !== null && !isLockToken(lockToken))
+        return null;
+    return { dir, mode, version, hash, lockToken };
+}
 function draftPath(reviewsDir, version) {
     return join(reviewsDir, `v${version}.draft.json`);
 }
@@ -98,7 +142,8 @@ export async function loadDraftComments(reviewsDir, version) {
     });
 }
 async function writeAtomic(path, text) {
-    const temp = `${path}.${randomBytes(4).toString("hex")}.tmp`;
+    // The pid lets `follow-me clean` tell an abandoned temp file from one being written.
+    const temp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
     await writeFile(temp, text);
     await rename(temp, path);
 }
@@ -139,19 +184,53 @@ function sendJson(res, status, body) {
     res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
     res.end(JSON.stringify(body));
 }
-function openBrowser(url) {
-    const command = process.platform === "darwin" ? "open" : "xdg-open";
-    const child = spawn(command, [url], { stdio: "ignore", detached: true });
-    child.on("error", (error) => console.error(`could not open a browser: ${error.message}`));
-    child.unref();
+function sendHtml(res, status, html) {
+    res.writeHead(status, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store",
+    });
+    res.end(html);
+}
+function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
 }
-export function serveReview(state, opts) {
-    const { reviewsDir } = opts;
+function indexPage(sessions) {
+    const rows = sessions.map((s) => {
+        const what = s.mode === "walk" ? "code review" : `review of plan v${s.version}`;
+        const count = `${s.comments} comment${s.comments === 1 ? "" : "s"}`;
+        return `      <li><a href="${s.url}">${escapeHtml(s.branch)}</a> <span class="muted">${what} · ${count} · ${escapeHtml(s.repo)}</span></li>`;
+    });
+    const body = rows.length === 0
+        ? '    <p class="muted">No sessions. Run follow-me review or follow-me walk in a repo.</p>'
+        : `    <ul class="session-index">\n${rows.join("\n")}\n    </ul>`;
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
+    <title>follow-me sessions</title>
+    <link rel="stylesheet" href="/style.css" />
+  </head>
+  <body class="index">
+    <h1>follow-me sessions</h1>
+${body}
+  </body>
+</html>
+`;
+}
+/** One hosted review: its comments, its autosave chain, and how it ends. */
+function hostSession(id, registration, loaded) {
+    const { state, reviewsDir } = loaded;
     const comments = new Map(state.comments.map((c) => [c.id, c]));
     const unitIds = new Set(state.units.map((u) => u.id));
     const draftFile = draftPath(reviewsDir, state.version);
     const reviewFile = join(reviewsDir, `v${state.version}.json`);
-    let boundPort = 0;
+    let finish = () => { };
+    const done = new Promise((resolve) => {
+        finish = resolve;
+    });
+    let ending = false;
     // Writes are chained so two rapid edits never race on the same file.
     let writes = Promise.resolve();
     const saveDraft = () => {
@@ -178,95 +257,242 @@ export function serveReview(state, opts) {
         }
         return comment;
     };
-    return new Promise((resolve, reject) => {
-        const server = createServer((req, res) => {
-            route(req, res).catch((error) => {
-                if (error instanceof HttpError)
-                    return sendJson(res, error.status, { error: error.message });
-                console.error(error);
-                sendJson(res, 500, { error: "internal error" });
-            });
+    return {
+        id,
+        registration,
+        done,
+        summary: () => ({
+            id,
+            url: sessionPath(id),
+            repo: loaded.repo,
+            branch: state.anchor.branch,
+            mode: state.mode,
+            version: state.version,
+            comments: comments.size,
+        }),
+        snapshot: () => ({ ...state, comments: [...comments.values()] }),
+        add: async (raw) => {
+            if (!isRecord(raw))
+                throw new HttpError(400, "malformed comment");
+            const commentId = mintCommentId(new Set(comments.keys()));
+            const comment = accept(parseComment({ ...raw, id: commentId, createdAt: new Date().toISOString() }));
+            comments.set(commentId, comment);
+            await saveDraft();
+            return commentId;
+        },
+        put: async (target, raw) => {
+            const comment = accept(parseComment(raw));
+            if (comment.id !== target)
+                throw new HttpError(400, "comment id does not match the URL");
+            comments.set(comment.id, comment);
+            await saveDraft();
+            return comment;
+        },
+        remove: async (target) => {
+            if (!comments.delete(target))
+                throw new HttpError(404, "no such comment");
+            await saveDraft();
+        },
+        /** Writes reviews/vN.json exactly once and releases the session's lock. */
+        end: async () => {
+            if (ending)
+                throw new HttpError(409, "this review is already ending");
+            ending = true;
+            await writes;
+            const review = {
+                schema: "follow-me/review@1",
+                mode: state.mode,
+                planVersion: state.version,
+                planHash: state.planHash,
+                endedAt: new Date().toISOString(),
+                comments: [...comments.values()],
+            };
+            await mkdir(reviewsDir, { recursive: true });
+            await writeAtomic(reviewFile, `${JSON.stringify(review, null, 2)}\n`);
+            await rm(draftFile, { force: true });
+            loaded.release();
+            return { review, file: reviewFile };
+        },
+        finish: (review) => finish(review),
+        abandon: () => {
+            loaded.release();
+            finish(null);
+        },
+    };
+}
+function sameRegistration(a, b) {
+    return a.dir === b.dir && a.mode === b.mode && a.version === b.version && a.hash === b.hash;
+}
+/**
+ * Starts the server that hosts every review of this user. Sessions live in a registry keyed by
+ * SessionId; each one is served at /s/<id>/ with its API under /s/<id>/api/. The server stops
+ * itself once it has had no session for idleMs.
+ */
+export function startServer(opts) {
+    const registry = new Map();
+    const pending = new Map();
+    let boundPort = 0;
+    let idleTimer;
+    let stopped = false;
+    let markClosed = () => { };
+    const closed = new Promise((resolve) => {
+        markClosed = resolve;
+    });
+    const server = createServer((req, res) => {
+        route(req, res).catch((error) => {
+            if (error instanceof HttpError)
+                return sendJson(res, error.status, { error: error.message });
+            if (error instanceof RegistrationError)
+                return sendJson(res, 409, { error: error.message });
+            console.error(error);
+            sendJson(res, 500, { error: "internal error" });
         });
-        async function route(req, res) {
-            const host = req.headers.host ?? "";
-            // Blocks DNS rebinding and cross-site writes: only our own origin may talk to the API.
-            if (host !== `127.0.0.1:${boundPort}` && host !== `localhost:${boundPort}`) {
-                throw new HttpError(403, "unexpected host");
-            }
-            const origin = req.headers.origin;
-            if (origin !== undefined && origin !== `http://${host}`)
-                throw new HttpError(403, "bad origin");
-            const method = req.method ?? "GET";
-            const path = new URL(req.url ?? "/", "http://localhost").pathname;
-            const asset = method === "GET" ? STATIC_FILES.get(path) : undefined;
-            if (asset) {
-                const bytes = await readFile(fileURLToPath(new URL(asset.file, UI_DIR)));
-                res.writeHead(200, { "content-type": asset.type, "cache-control": "no-store" });
-                res.end(bytes);
-                return;
-            }
-            if (method === "GET" && path === "/api/state") {
-                return sendJson(res, 200, { ...state, comments: [...comments.values()] });
-            }
-            if (method === "POST" && path === "/api/comments") {
-                const raw = await readJson(req);
-                if (!isRecord(raw))
-                    throw new HttpError(400, "malformed comment");
-                const id = mintCommentId(new Set(comments.keys()));
-                const comment = accept(parseComment({ ...raw, id, createdAt: new Date().toISOString() }));
-                comments.set(id, comment);
-                await saveDraft();
-                return sendJson(res, 201, { id });
-            }
-            const target = /^\/api\/comments\/([^/]+)$/.exec(path)?.[1];
-            if (target !== undefined && method === "PUT") {
-                const comment = accept(parseComment(await readJson(req)));
-                if (comment.id !== target)
-                    throw new HttpError(400, "comment id does not match the URL");
-                comments.set(comment.id, comment);
-                await saveDraft();
-                return sendJson(res, 200, comment);
-            }
-            if (target !== undefined && method === "DELETE") {
-                if (!comments.delete(target))
-                    throw new HttpError(404, "no such comment");
-                await saveDraft();
-                return sendJson(res, 200, { deleted: target });
-            }
-            if (method === "POST" && path === "/api/end") {
-                await writes;
-                const review = {
-                    schema: "follow-me/review@1",
-                    mode: state.mode,
-                    planVersion: state.version,
-                    planHash: state.planHash,
-                    endedAt: new Date().toISOString(),
-                    comments: [...comments.values()],
-                };
-                await mkdir(reviewsDir, { recursive: true });
-                await writeAtomic(reviewFile, `${JSON.stringify(review, null, 2)}\n`);
-                await rm(draftFile, { force: true });
-                sendJson(res, 200, { saved: reviewFile });
-                res.on("close", () => {
-                    server.close(() => resolve(review));
-                    server.closeAllConnections();
-                });
-                return;
+    });
+    const close = () => {
+        if (!stopped) {
+            stopped = true;
+            clearTimeout(idleTimer);
+            for (const session of registry.values())
+                session.abandon();
+            registry.clear();
+            server.close(() => markClosed());
+            server.closeAllConnections();
+        }
+        return closed;
+    };
+    const settle = () => {
+        clearTimeout(idleTimer);
+        if (stopped || registry.size > 0 || pending.size > 0)
+            return;
+        idleTimer = setTimeout(() => void close(), opts.idleMs);
+    };
+    const sessions = () => [...registry.values()].map((s) => s.summary());
+    const register = async (registration) => {
+        if (stopped)
+            throw new RegistrationError("the server is stopping");
+        const id = sessionIdOf(registration.dir);
+        const existing = registry.get(id) ?? (await pending.get(id));
+        if (existing) {
+            if (!sameRegistration(existing.registration, registration)) {
+                const { mode, version } = existing.registration;
+                throw new RegistrationError(`this session is already open as a ${mode === "walk" ? "walk" : "review"} of plan v${version}; end it first`);
             }
+            return { summary: existing.summary(), done: existing.done };
+        }
+        clearTimeout(idleTimer);
+        const loading = opts.load(registration).then((loaded) => hostSession(id, registration, loaded));
+        pending.set(id, loading);
+        try {
+            const session = await loading;
+            registry.set(id, session);
+            return { summary: session.summary(), done: session.done };
+        }
+        finally {
+            pending.delete(id);
+            settle();
+        }
+    };
+    const hosted = (raw) => {
+        const session = isSessionId(raw) ? registry.get(raw) : undefined;
+        if (!session)
+            throw new HttpError(404, "no such session; it ended or never existed");
+        return session;
+    };
+    async function route(req, res) {
+        const host = req.headers.host ?? "";
+        // Blocks DNS rebinding and cross-site writes: only our own origin may talk to the API.
+        if (host !== `127.0.0.1:${boundPort}` && host !== `localhost:${boundPort}`) {
+            throw new HttpError(403, "unexpected host");
+        }
+        const origin = req.headers.origin;
+        if (origin !== undefined && origin !== `http://${host}`)
+            throw new HttpError(403, "bad origin");
+        const method = req.method ?? "GET";
+        const path = new URL(req.url ?? "/", "http://localhost").pathname;
+        const asset = method === "GET" ? STATIC_FILES.get(path) : undefined;
+        if (asset) {
+            const bytes = await readFile(fileURLToPath(new URL(asset.file, UI_DIR)));
+            res.writeHead(200, { "content-type": asset.type, "cache-control": "no-store" });
+            res.end(bytes);
+            return;
+        }
+        if (method === "GET" && path === "/")
+            return sendHtml(res, 200, indexPage(sessions()));
+        if (method === "GET" && path === "/api/health") {
+            return sendJson(res, 200, { app: HEALTH_APP, pid: process.pid });
+        }
+        if (method === "GET" && path === "/api/sessions")
+            return sendJson(res, 200, sessions());
+        if (method === "POST" && path === "/api/sessions") {
+            const registration = parseRegistration(await readJson(req));
+            if (!registration)
+                throw new HttpError(400, "malformed registration");
+            const before = registry.has(sessionIdOf(registration.dir));
+            const { summary } = await register(registration);
+            return sendJson(res, before ? 200 : 201, summary);
+        }
+        const match = /^\/s\/([^/]+)(\/.*)?$/.exec(path);
+        if (match === null)
             throw new HttpError(404, "not found");
+        const [, rawId = "", rest] = match;
+        if (rest === undefined && method === "GET") {
+            res.writeHead(308, { location: `/s/${encodeURIComponent(rawId)}/` });
+            res.end();
+            return;
+        }
+        if (method === "GET" && rest === "/") {
+            if (!isSessionId(rawId) || !registry.has(rawId)) {
+                return sendHtml(res, 404, '<!doctype html><title>follow-me</title><p>This session ended or never existed. <a href="/">All sessions</a></p>\n');
+            }
+            return sendHtml(res, 200, await readFile(fileURLToPath(new URL("index.html", UI_DIR)), "utf8"));
+        }
+        const session = hosted(rawId);
+        if (method === "GET" && rest === "/api/state")
+            return sendJson(res, 200, session.snapshot());
+        if (method === "POST" && rest === "/api/comments") {
+            return sendJson(res, 201, { id: await session.add(await readJson(req)) });
+        }
+        const target = /^\/api\/comments\/([^/]+)$/.exec(rest ?? "")?.[1];
+        if (target !== undefined && method === "PUT") {
+            return sendJson(res, 200, await session.put(target, await readJson(req)));
         }
-        server.on("error", reject);
-        server.listen(opts.port ?? 0, "127.0.0.1", () => {
+        if (target !== undefined && method === "DELETE") {
+            await session.remove(target);
+            return sendJson(res, 200, { deleted: target });
+        }
+        if (method === "POST" && rest === "/api/end") {
+            const { review, file } = await session.end();
+            registry.delete(session.id);
+            sendJson(res, 200, { saved: file });
+            res.on("close", () => {
+                session.finish(review);
+                settle();
+            });
+            return;
+        }
+        throw new HttpError(404, "not found");
+    }
+    return new Promise((resolve, reject) => {
+        server.once("error", (error) => {
+            if (isRecord(error) && error["code"] === "EADDRINUSE")
+                reject(new PortInUseError(opts.port));
+            else
+                reject(error);
+        });
+        server.listen(opts.port, "127.0.0.1", () => {
             const address = server.address();
             if (!address || typeof address === "string")
                 return reject(new Error("server has no port"));
             boundPort = address.port;
-            const url = `http://127.0.0.1:${boundPort}/`;
-            const label = state.mode === "walk" ? "code review" : "review";
-            process.stdout.write(`follow-me ${label}: ${url}\n`);
-            opts.onListen?.(url);
-            if (opts.open)
-                openBrowser(url);
+            settle();
+            resolve({
+                port: boundPort,
+                url: `http://127.0.0.1:${boundPort}/`,
+                register,
+                sessions,
+                close,
+                closed,
+            });
         });
     });
 }