wiki-viewer 1.5.1 → 1.6.0

package/.next/standalone/packages/wiki-viewer-mcp/bench-latency.mjs

@@ -0,0 +1,87 @@
+/**
+ * Latency-model benchmark: proves how per-call TCP/TLS handshakes (no keep-alive)
+ * vs pooled keep-alive connections behave under WAN-like RTT.
+ *
+ * It does NOT need the full Next server — it runs a tiny local HTTP server that
+ * sleeps RTT/2 before responding (modeling one-way latency), then compares:
+ *   A) fetch with a fresh connection each call (no keep-alive)
+ *   B) fetch over a pooled keep-alive agent (undici)
+ *
+ * For each, it models a "write" (1 request) and an "edit" (2 requests: GET+PUT).
+ *
+ * Run: node packages/wiki-viewer-mcp/bench-latency.mjs [rttMs]
+ */
+import http from "node:http";
+import { Agent, fetch as undiciFetch } from "undici";
+
+const RTT = Number(process.argv[2] ?? process.env.RTT_MS ?? 80); // round-trip ms
+const ITERS = Number(process.env.ITERS ?? 30);
+const ONE_WAY = RTT / 2;
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+// Local server that injects one-way latency on both receive and send.
+const server = http.createServer(async (req, res) => {
+	// drain body
+	for await (const _ of req) { /* consume */ }
+	await sleep(ONE_WAY);           // network: client -> server
+	res.writeHead(200, { "Content-Type": "application/json", ETag: '"sha256:abc"', "X-File-Size": "1024" });
+	res.end(JSON.stringify({ sha256: "sha256:abc", size: 1024 }));
+});
+
+function pct(s, p) { return s[Math.min(s.length - 1, Math.floor((p / 100) * s.length))]; }
+function summarize(label, samples) {
+	const s = [...samples].sort((a, b) => a - b);
+	const mean = s.reduce((a, b) => a + b, 0) / s.length;
+	return `${label.padEnd(40)} p50=${pct(s, 50).toFixed(0)}ms  p95=${pct(s, 95).toFixed(0)}ms  mean=${mean.toFixed(0)}ms`;
+}
+
+async function bench(label, doCall) {
+	const samples = [];
+	for (let i = 0; i < ITERS + 5; i++) {
+		const t = performance.now();
+		await doCall();
+		if (i >= 5) samples.push(performance.now() - t);
+	}
+	return summarize(label, samples);
+}
+
+async function main() {
+	await new Promise((r) => server.listen(0, "127.0.0.1", r));
+	const port = server.address().port;
+	const base = `http://127.0.0.1:${port}/x`;
+
+	// A) No keep-alive: force a fresh connection per request.
+	const noKa = new Agent({ pipelining: 0, connections: 1, keepAliveTimeout: 1, keepAliveMaxTimeout: 1 });
+	// B) Pooled keep-alive.
+	const ka = new Agent({ keepAliveTimeout: 30_000, keepAliveMaxTimeout: 60_000, connections: 10 });
+
+	const req = (dispatcher, method) =>
+		undiciFetch(base, { method, dispatcher, headers: { "content-type": "application/octet-stream" }, body: method === "PUT" ? "x".repeat(1024) : undefined })
+			.then((r) => r.arrayBuffer());
+
+	// Model a COLD connection: TCP(1 RTT) + TLS(≈2 RTT) handshake before the
+	// request even goes out. Real HTTPS over WAN pays this on every call when
+	// the client doesn't reuse connections. We add it explicitly because
+	// loopback can't reproduce handshake cost.
+	const HANDSHAKE_RTTS = Number(process.env.HANDSHAKE_RTTS ?? 3); // TCP+TLS ≈ 3 RTT
+	const freshReq = async (method) => {
+		await sleep(HANDSHAKE_RTTS * RTT); // cold-connection handshake penalty
+		const d = new Agent({ keepAliveTimeout: 1, connections: 1 });
+		await req(d, method);
+		await d.close();
+	};
+
+	console.log(`\nlatency model — RTT=${RTT}ms, iters=${ITERS}\n`);
+	console.log(await bench("write  · fresh conn per call (no keep-alive)", () => freshReq("PUT")));
+	console.log(await bench("write  · pooled keep-alive", () => req(ka, "PUT")));
+	console.log(await bench("edit   · fresh conn per call (GET+PUT)", async () => { await freshReq("GET"); await freshReq("PUT"); }));
+	console.log(await bench("edit   · pooled keep-alive (GET+PUT)", async () => { await req(ka, "GET"); await req(ka, "PUT"); }));
+	console.log("");
+	console.log("Note: 'fresh conn' pays TCP handshake (+~1 RTT) per call; real HTTPS adds TLS (+1-2 RTT).");
+	console.log("");
+
+	await noKa.close(); await ka.close();
+	server.close();
+}
+main().catch((e) => { console.error(e); process.exit(1); });

package/.next/standalone/packages/wiki-viewer-mcp/src/index.ts

@@ -29,6 +29,33 @@ import * as z from "zod";
 import { parseArgs } from "node:util";
 import { WikiViewerClient, IfMatchError, CollabActiveError, WikiViewerError } from "./http-client.js";
 import * as stateCache from "./state-cache.js";
+
+/**
+ * Enable pooled HTTP keep-alive for the global fetch the client uses.
+ *
+ * Without this, every tool call opens a fresh connection and pays a full
+ * TCP + TLS handshake (~3 RTT) before the request even goes out. Over a WAN
+ * link that turns a sub-100ms write into 300ms-1s+, and multiplies across the
+ * GET+PUT an edit performs. Reusing connections removes that per-call penalty.
+ *
+ * Wrapped in try/catch + dynamic import so a missing/edge undici never breaks
+ * startup; it just falls back to default (non-pooled) fetch.
+ */
+async function enableKeepAlive(): Promise<void> {
+  try {
+    const { Agent, setGlobalDispatcher } = await import("undici");
+    setGlobalDispatcher(
+      new Agent({
+        keepAliveTimeout: 30_000,
+        keepAliveMaxTimeout: 60_000,
+        connections: 16,
+        pipelining: 1,
+      }),
+    );
+  } catch {
+    // undici unavailable — default fetch still works, just without pooling.
+  }
+}
 import {
   register,
   RegisterScope,
@@ -433,6 +460,7 @@ function buildJsonSchema(val: AnyZodVal): Record<string, unknown> {
 // ─── Entrypoints ─────────────────────────────────────────────────────────────
 
 async function main() {
+  await enableKeepAlive();
   const client = createClient();
   const server = createServer(client);
   const transport = new StdioServerTransport();

package/.next/standalone/src/app/page.tsx

@@ -272,6 +272,7 @@ export default function Page() {
 	const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
 	const [settingsOpen, setSettingsOpen] = useState(false);
 	const [fileContent, setFileContent] = useState<string | null>(null);
+	const [fileRevision, setFileRevision] = useState(0);
 	const [fileLoading, setFileLoading] = useState(false);
 	const [editing, setEditing] = useState(false);
 	const [editContent, setEditContent] = useState("");
@@ -411,6 +412,7 @@ export default function Page() {
 			if (res.ok) {
 				const d: { content: string } = await res.json();
 				setFileContent(d.content);
+				setFileRevision(Number(res.headers.get("X-Wiki-Revision") ?? 0));
 			}
 		} catch {
 			/* ignore */
@@ -536,6 +538,7 @@ export default function Page() {
 		setEditing(false);
 		setSaveError(null);
 		setFileContent(null);
+		setFileRevision(0);
 		const kind = viewerKindFor(node.name, node.type);
 		if (!["editor", "text"].includes(kind) && !isText(node.name)) return;
 		setFileLoading(true);
@@ -546,6 +549,7 @@ export default function Page() {
 			if (res.ok) {
 				const d: { content: string } = await res.json();
 				setFileContent(d.content);
+				setFileRevision(Number(res.headers.get("X-Wiki-Revision") ?? 0));
 			}
 		} catch {
 			/* ignore */
@@ -624,9 +628,15 @@ export default function Page() {
 		const res = await fetch("/api/wiki/content", {
 			method: "PUT",
 			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify({ path: openFile.path, content: editContent }),
+			body: JSON.stringify({
+				path: openFile.path,
+				content: editContent,
+				baseRevision: fileRevision,
+			}),
 		});
 		if (res.ok) {
+			const d: { revision?: number } = await res.json();
+			if (typeof d.revision === "number") setFileRevision(d.revision);
 			setFileContent(editContent);
 			setEditing(false);
 		} else {

package/.next/standalone/src/tests/proof/bench-write.ts

@@ -0,0 +1,179 @@
+/**
+ * Isolated write-path benchmark — NOT a test, NOT touching production state.
+ *
+ * Drives the real Tier-1 route handlers (filePUT / fileGET) against a throwaway
+ * temp rootDir + temp HOME (lock dir), exactly like agent-fs.test.ts, and
+ * measures end-to-end server-side latency for the write path:
+ *   - non-.md overwrite (raw, no lock/sidecar)
+ *   - .md overwrite (cross-proc lock + reconcile + sidecar write + datasync)
+ *   - edit_file equivalent (GET + PUT round-trip on .md)
+ *
+ * Run:  npx tsx src/tests/proof/bench-write.ts
+ * Optional env: BENCH_ITERS (default 300), BENCH_WARMUP (default 30)
+ */
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+
+import { setRootDir } from "../../lib/root-dir.js";
+import { ensureRegistry, addAgent, hashToken } from "../../lib/proof/registry.js";
+
+const ITERS = Number(process.env.BENCH_ITERS) || 300;
+const WARMUP = Number(process.env.BENCH_WARMUP) || 30;
+
+function sha256(buf: Buffer): string {
+	return "sha256:" + createHash("sha256").update(buf).digest("hex");
+}
+function hdrs(token: string, id: string): Record<string, string> {
+	return { Authorization: `Bearer ${token}`, "X-Agent-Id": id };
+}
+function fileUrl(rel: string, qs = ""): string {
+	return `http://localhost/api/agent/fs/file/${rel}${qs}`;
+}
+
+function pct(sorted: number[], p: number): number {
+	const i = Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length));
+	return sorted[i];
+}
+function stats(label: string, samples: number[]) {
+	const s = [...samples].sort((a, b) => a - b);
+	const sum = s.reduce((a, b) => a + b, 0);
+	const mean = sum / s.length;
+	return {
+		label,
+		n: s.length,
+		mean: +mean.toFixed(3),
+		p50: +pct(s, 50).toFixed(3),
+		p95: +pct(s, 95).toFixed(3),
+		p99: +pct(s, 99).toFixed(3),
+		min: +s[0].toFixed(3),
+		max: +s[s.length - 1].toFixed(3),
+	};
+}
+
+async function timeIt(fn: () => Promise<void>): Promise<number> {
+	const t0 = performance.now();
+	await fn();
+	return performance.now() - t0;
+}
+
+async function main() {
+	const tmpHome = await mkdtemp(path.join(tmpdir(), "bench-home-"));
+	const tmpRoot = await mkdtemp(path.join(tmpdir(), "bench-root-"));
+	process.env.HOME = tmpHome;
+	setRootDir(tmpRoot);
+	await ensureRegistry();
+
+	const TOKEN = randomBytes(32).toString("hex");
+	await addAgent({
+		id: "ai:bench",
+		displayName: "Bench",
+		tokenHash: hashToken(TOKEN),
+		scope: { paths: ["**/*"], ops: ["read", "mutate", "delete"] },
+		createdAt: new Date().toISOString(),
+		lastSeen: new Date().toISOString(),
+	});
+
+	const fileRoute = await import("../../app/api/agent/fs/file/[...path]/route.js");
+	const filePUT = fileRoute.PUT;
+	const fileGET = fileRoute.GET;
+	const H = hdrs(TOKEN, "ai:bench");
+
+	const ctx = (rel: string) => ({ params: Promise.resolve({ path: rel.split("/") }) });
+
+	// Seed bodies (~1KB, realistic small doc)
+	const body = Buffer.from("# Doc\n\n" + "lorem ipsum dolor sit amet. ".repeat(40));
+	const txtBody = Buffer.from("config_value = " + "x".repeat(900));
+
+	async function putOnce(rel: string, data: Buffer, ifMatch?: string, ifCollab?: string): Promise<Response> {
+		const headers: Record<string, string> = { ...H, "Content-Type": "application/octet-stream" };
+		if (ifMatch) headers["If-Match"] = ifMatch;
+		if (ifCollab) headers["If-Collab-Match"] = ifCollab;
+		return filePUT(new Request(fileUrl(rel), { method: "PUT", headers, body: new Uint8Array(data) }), ctx(rel));
+	}
+	async function getSha(rel: string): Promise<{ sha: string; collabRev: string | null }> {
+		const res = await fileGET(new Request(fileUrl(rel), { headers: H }), ctx(rel));
+		const etag = (res.headers.get("ETag") ?? "").replace(/"/g, "");
+		return { sha: etag, collabRev: res.headers.get("X-Collab-Revision") };
+	}
+
+	// ── Scenario A: non-.md overwrite (lean path) ──────────────────────────────
+	await putOnce("bench.txt", txtBody, undefined); // create
+	const txtSamples: number[] = [];
+	{
+		let sha = (await getSha("bench.txt")).sha;
+		for (let i = 0; i < WARMUP + ITERS; i++) {
+			const data = Buffer.from(txtBody.toString() + i);
+			const t = await timeIt(async () => {
+				const res = await putOnce("bench.txt", data, sha);
+				if (res.status !== 200) throw new Error("txt PUT " + res.status);
+				sha = (await res.json() as { sha256: string }).sha256;
+			});
+			if (i >= WARMUP) txtSamples.push(t);
+		}
+	}
+
+	// ── Scenario B: .md overwrite (lock + reconcile + sidecar + datasync) ──────
+	await putOnce("bench.md", body, undefined); // create
+	const mdSamples: number[] = [];
+	{
+		let sha = (await getSha("bench.md")).sha;
+		for (let i = 0; i < WARMUP + ITERS; i++) {
+			const data = Buffer.from(body.toString() + "\n\nedit " + i);
+			const t = await timeIt(async () => {
+				const res = await putOnce("bench.md", data, sha);
+				if (res.status !== 200) throw new Error("md PUT " + res.status + " " + await res.text());
+				sha = (await res.json() as { sha256: string }).sha256;
+			});
+			if (i >= WARMUP) mdSamples.push(t);
+		}
+	}
+
+	// ── Scenario C: edit_file equivalent — GET + PUT round-trip on .md ─────────
+	const editSamples: number[] = [];
+	{
+		for (let i = 0; i < WARMUP + ITERS; i++) {
+			const data = Buffer.from(body.toString() + "\n\nrt " + i);
+			const t = await timeIt(async () => {
+				const { sha } = await getSha("bench.md");
+				const res = await putOnce("bench.md", data, sha);
+				if (res.status !== 200) throw new Error("edit PUT " + res.status);
+				await res.json();
+			});
+			if (i >= WARMUP) editSamples.push(t);
+		}
+	}
+
+	const results = [
+		stats("non-.md overwrite (lean)", txtSamples),
+		stats(".md overwrite (lock+reconcile+sidecar+datasync)", mdSamples),
+		stats("edit_file (GET+PUT .md round-trip)", editSamples),
+	];
+
+	console.log(`\nwrite-path benchmark  (iters=${ITERS}, warmup=${WARMUP}, ~1KB bodies)\n`);
+	console.log(
+		["scenario".padEnd(48), "p50", "p95", "p99", "mean", "max"].join("  "),
+	);
+	for (const r of results) {
+		console.log(
+			[
+				r.label.padEnd(48),
+				`${r.p50}ms`.padStart(7),
+				`${r.p95}ms`.padStart(7),
+				`${r.p99}ms`.padStart(7),
+				`${r.mean}ms`.padStart(7),
+				`${r.max}ms`.padStart(7),
+			].join("  "),
+		);
+	}
+	console.log("");
+
+	await rm(tmpHome, { recursive: true, force: true });
+	await rm(tmpRoot, { recursive: true, force: true });
+}
+
+main().catch((e) => {
+	console.error(e);
+	process.exit(1);
+});