feat(triage): the owner-only route store and mosaic triage route show|set
<dataRoot>/triage/route.json holds Triage's model route and daily cap as names only: a catalogue model key, a harness name and a daily-quota cap leaf, with no env value and no key. The directory is 0700 and the file 0600, owned by the running user; a link, a hard link, a non-file, a wrong mode or owner, an unknown field or an unknown time zone refuses. A write is compare-and-set on revision under an exclusive lock, atomic (temp file, fsync, rename, directory fsync), and appends one receipt line. The reset is 00:00 in a zone the owner gives, with no default. The file location, field names and reset rule each live in one place. mosaic triage route show|set are human verbs and refuse an agent run before any read. Nothing is wired into the Triage host: the Console keeps route: null. Held for Jason's ruling on the design's four questions (#1873, lane triage-route-store).
This commit is contained in:
1 parent
2d44750b96
commit
4c8527fcd3
7 files changed
+906
-1
No files matched your search
@@ -0,0 +1,246 @@
|
||||
// #1873 triage-route-store: the owner-only file that holds Triage's model route and daily cap,
|
||||
// <dataRoot>/triage/route.json (design report reports/triage-route-design.md section 1, option C).
|
||||
//
|
||||
// { version, revision, model, harness, cap: { limit, since, reset, timeZone }, updatedAt, updatedBy }
|
||||
//
|
||||
// Names only: a catalogue model key and a harness name. No env value and no key ever enter this
|
||||
// file; the host derives env, mounts and the adapter itself (a later slice). Nothing here is wired
|
||||
// into the Triage host or the Console yet: the Console keeps `route: null`.
|
||||
//
|
||||
// Fail closed. The triage directory is 0700 and route.json 0600, both owned by the running user;
|
||||
// a link, a hard link, a non-file, a wrong mode or owner, an unknown field or an unknown time zone
|
||||
// refuses. A write is compare-and-set on `revision` under an exclusive lock file, atomic (a 0600
|
||||
// temp file in the same directory, fsync, rename, fsync of the directory), and appends one line
|
||||
// to route-receipts.jsonl. A writer that dies leaves its lock; the next write refuses and names
|
||||
// it, and the person removes it by hand, as with the organization lifecycle fence.
|
||||
//
|
||||
// Choices Jason may still reverse each live in one place: the file location (routePaths), the
|
||||
// field names (ROUTE_FIELDS, CAP_FIELDS) and the reset rule (capFor).
|
||||
import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
|
||||
import { randomBytes } from "node:crypto";
|
||||
import { join } from "node:path";
|
||||
import { isDailyModelQuota } from "../../plugins/src/model-quota.mjs";
|
||||
import { processState } from "../../seat/src/process-state.mjs";
|
||||
|
||||
export const ROUTE_VERSION = 1;
|
||||
export const ROUTE_FIELDS = Object.freeze(["version", "revision", "model", "harness", "cap", "updatedAt", "updatedBy"]);
|
||||
export const CAP_FIELDS = Object.freeze(["limit", "since", "reset", "timeZone"]);
|
||||
// The catalogue's model key shape (packages/bus/src/model-catalogue.mjs validId) and the Triage
|
||||
// host's harness name shape (packages/webui/src/triage-host.mjs HARNESS_NAME).
|
||||
const MODEL_KEY = /^[a-z0-9][a-z0-9._-]{0,63}$/;
|
||||
const HARNESS_NAME = /^[a-z][a-z0-9-]{0,31}$/;
|
||||
const ACTOR = /^[a-z][a-z0-9-]{0,31}$/;
|
||||
const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
|
||||
// isDailyModelQuota checks one leaf under a twelve-hex key; the Triage cap has no key of its own.
|
||||
const LEAF_KEY = "000000000000";
|
||||
const MAX_BYTES = 64 * 1024;
|
||||
const INPUT_FIELDS = Object.freeze(["model", "harness", "limit", "timeZone", "by", "revision"]);
|
||||
|
||||
export class RouteStoreError extends Error {
|
||||
constructor(code, message) {
|
||||
super(message);
|
||||
this.name = "RouteStoreError";
|
||||
this.code = code;
|
||||
}
|
||||
}
|
||||
const unreadable = (why) => new RouteStoreError("triage-route-unreadable", `the Triage route store is unreadable: ${why}`);
|
||||
const invalid = (why) => new RouteStoreError("triage-route-invalid", `the Triage route is invalid: ${why}`);
|
||||
|
||||
// The file location, in one place.
|
||||
export function routePaths(dataRoot) {
|
||||
const dir = join(dataRoot, "triage");
|
||||
return { dir, file: join(dir, "route.json"), receipts: join(dir, "route-receipts.jsonl"), lock: join(dir, "route.lock") };
|
||||
}
|
||||
|
||||
// The reset rule, in one place: the day resets at 00:00 in the owner's zone, which has no default.
|
||||
// A cap whose limit, reset and zone are unchanged keeps its `since`; any other cap counts from now.
|
||||
export function capFor({ limit, timeZone, previous, now }) {
|
||||
const reset = "00:00";
|
||||
const same = previous && previous.limit === limit && previous.reset === reset && previous.timeZone === timeZone;
|
||||
return { limit, since: same ? previous.since : now, reset, timeZone };
|
||||
}
|
||||
|
||||
const plain = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
|
||||
const exactKeys = (v, keys) => plain(v) && Object.keys(v).length === keys.length && keys.every((k) => Object.hasOwn(v, k));
|
||||
const canonicalTime = (s) => typeof s === "string" && ISO.test(s) && !Number.isNaN(Date.parse(s)) && new Date(s).toISOString() === s;
|
||||
const knownZone = (zone) => {
|
||||
if (typeof zone !== "string" || zone === "") return false;
|
||||
try { new Intl.DateTimeFormat("en-US", { timeZone: zone }); return true; } catch { return false; }
|
||||
};
|
||||
|
||||
export function validRoute(doc) {
|
||||
return exactKeys(doc, ROUTE_FIELDS)
|
||||
&& doc.version === ROUTE_VERSION
|
||||
&& Number.isSafeInteger(doc.revision) && doc.revision >= 1
|
||||
&& typeof doc.model === "string" && MODEL_KEY.test(doc.model)
|
||||
&& typeof doc.harness === "string" && HARNESS_NAME.test(doc.harness)
|
||||
// isDailyModelQuota also checks that the zone is one Intl knows.
|
||||
&& exactKeys(doc.cap, CAP_FIELDS) && isDailyModelQuota(LEAF_KEY, doc.cap)
|
||||
&& canonicalTime(doc.updatedAt)
|
||||
&& typeof doc.updatedBy === "string" && ACTOR.test(doc.updatedBy);
|
||||
}
|
||||
|
||||
const uidOf = (opts) => opts.uid ?? process.getuid();
|
||||
|
||||
// The triage directory: a real directory, the running user's, mode 0700. Returns false when it is
|
||||
// missing and `create` is off; with `create` it makes it (never the data root above it).
|
||||
function checkDir(dir, uid, { create }) {
|
||||
let st;
|
||||
try { st = lstatSync(dir); }
|
||||
catch (e) {
|
||||
if (e.code !== "ENOENT") throw unreadable("the triage directory cannot be read");
|
||||
if (!create) return false;
|
||||
try { mkdirSync(dir, { mode: 0o700 }); } catch { throw unreadable("the triage directory cannot be made"); }
|
||||
st = lstatSync(dir);
|
||||
}
|
||||
if (st.isSymbolicLink()) throw unreadable("the triage directory is a link");
|
||||
if (!st.isDirectory()) throw unreadable("the triage directory is not a directory");
|
||||
if (st.uid !== uid) throw unreadable("the triage directory is not owned by this user");
|
||||
if ((st.mode & 0o777) !== 0o700) throw unreadable("the triage directory mode is not 0700");
|
||||
return true;
|
||||
}
|
||||
|
||||
// An opened file's own checks: a regular file, one link, the running user's, mode 0600.
|
||||
function checkFile(fd, uid, what) {
|
||||
const st = fstatSync(fd);
|
||||
if (!st.isFile()) throw unreadable(`${what} is not a regular file`);
|
||||
if (st.nlink !== 1) throw unreadable(`${what} has more than one link`);
|
||||
if (st.uid !== uid) throw unreadable(`${what} is not owned by this user`);
|
||||
if ((st.mode & 0o777) !== 0o600) throw unreadable(`${what} mode is not 0600`);
|
||||
return st;
|
||||
}
|
||||
|
||||
function readFile(file, uid) {
|
||||
let fd;
|
||||
try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
|
||||
catch (e) {
|
||||
if (e.code === "ENOENT") return null;
|
||||
if (e.code === "ELOOP") throw unreadable("route.json is a link");
|
||||
throw unreadable("route.json cannot be opened");
|
||||
}
|
||||
try {
|
||||
const st = checkFile(fd, uid, "route.json");
|
||||
if (st.size > MAX_BYTES) throw unreadable("route.json is too large");
|
||||
let doc;
|
||||
try { doc = JSON.parse(readFileSync(fd, "utf8")); } catch { throw unreadable("route.json is not JSON"); }
|
||||
if (!validRoute(doc)) throw unreadable("route.json does not match the route shape");
|
||||
return doc;
|
||||
} finally { closeSync(fd); }
|
||||
}
|
||||
|
||||
// The stored route, or null when none is set. Throws triage-route-unreadable on anything unsafe.
|
||||
export function readRoute(dataRoot, opts = {}) {
|
||||
const { dir, file } = routePaths(dataRoot);
|
||||
const uid = uidOf(opts);
|
||||
if (!checkDir(dir, uid, { create: false })) return null;
|
||||
return readFile(file, uid);
|
||||
}
|
||||
|
||||
function checkInput(input) {
|
||||
if (!plain(input)) throw invalid("the input is not an object");
|
||||
for (const k of Object.keys(input)) if (!INPUT_FIELDS.includes(k)) throw invalid(`unknown field ${k}`);
|
||||
if (typeof input.model !== "string" || !MODEL_KEY.test(input.model)) throw invalid("model must be a catalogue model key");
|
||||
if (typeof input.harness !== "string" || !HARNESS_NAME.test(input.harness)) throw invalid("harness must be a harness name");
|
||||
if (!Number.isSafeInteger(input.limit) || input.limit < 0) throw invalid("the cap must be a whole number of tokens, 0 or more");
|
||||
if (input.timeZone === undefined) throw invalid("a time zone is required");
|
||||
if (!knownZone(input.timeZone)) throw invalid("the time zone is unknown");
|
||||
if (typeof input.by !== "string" || !ACTOR.test(input.by)) throw invalid("the actor name is invalid");
|
||||
if (input.revision !== undefined && (!Number.isSafeInteger(input.revision) || input.revision < 0)) throw invalid("revision must be a whole number, 0 or more");
|
||||
}
|
||||
|
||||
function holderLine(lock) {
|
||||
let holder = null;
|
||||
try {
|
||||
const fd = openSync(lock, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
|
||||
try { holder = JSON.parse(readFileSync(fd, "utf8")); } finally { closeSync(fd); }
|
||||
} catch { holder = null; }
|
||||
if (!Number.isSafeInteger(holder?.pid) || holder.pid <= 0) return `another write holds ${lock}, or a writer left it; remove it by hand once no write is running`;
|
||||
let alive;
|
||||
try { alive = processState(holder.pid).alive; } catch { alive = null; }
|
||||
if (alive === false) return `a writer that is not running (pid ${holder.pid}) left ${lock}; remove it by hand`;
|
||||
return `another write (pid ${holder.pid}) holds ${lock}; try again when it ends`;
|
||||
}
|
||||
|
||||
function takeLock(lock) {
|
||||
let fd;
|
||||
try { fd = openSync(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
|
||||
catch (e) {
|
||||
if (e.code === "EEXIST") throw new RouteStoreError("triage-route-busy", `the Triage route is busy: ${holderLine(lock)}`);
|
||||
throw unreadable("the lock cannot be made");
|
||||
}
|
||||
try {
|
||||
writeSync(fd, `${JSON.stringify({ pid: process.pid, at: new Date().toISOString() })}\n`);
|
||||
return { fd, st: fstatSync(fd) };
|
||||
} catch (e) {
|
||||
closeSync(fd);
|
||||
try { unlinkSync(lock); } catch {}
|
||||
throw unreadable("the lock cannot be written");
|
||||
}
|
||||
}
|
||||
|
||||
function dropLock(lock, held) {
|
||||
try {
|
||||
const now = lstatSync(lock);
|
||||
if (now.dev === held.st.dev && now.ino === held.st.ino) unlinkSync(lock);
|
||||
} catch {}
|
||||
closeSync(held.fd);
|
||||
}
|
||||
|
||||
// The receipts file, opened for append before the route changes, so a bad one refuses first.
|
||||
function openReceipts(receipts, uid) {
|
||||
let fd;
|
||||
try { fd = openSync(receipts, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600); }
|
||||
catch (e) {
|
||||
if (e.code === "ELOOP") throw unreadable("route-receipts.jsonl is a link");
|
||||
throw unreadable("route-receipts.jsonl cannot be opened");
|
||||
}
|
||||
try { checkFile(fd, uid, "route-receipts.jsonl"); } catch (e) { closeSync(fd); throw e; }
|
||||
return fd;
|
||||
}
|
||||
|
||||
const summary = (doc) => (doc ? { model: doc.model, harness: doc.harness, cap: doc.cap } : null);
|
||||
|
||||
// Set the route. input: { model, harness, limit, timeZone, by, revision? }. With `revision` the
|
||||
// write happens only if the stored revision equals it (0: only when no route is set yet); without
|
||||
// it, the revision read under the lock. Returns the new route.
|
||||
// opts.now and opts.uid are for tests; opts.hook(stage) is a test seam at "crash" (after the temp
|
||||
// file is written) and "before-rename".
|
||||
export function writeRoute(dataRoot, input, opts = {}) {
|
||||
checkInput(input);
|
||||
const { dir, file, receipts, lock } = routePaths(dataRoot);
|
||||
const uid = uidOf(opts);
|
||||
const now = (opts.now ?? (() => new Date()))().toISOString();
|
||||
const hook = opts.hook ?? (() => {});
|
||||
checkDir(dir, uid, { create: true });
|
||||
const held = takeLock(lock);
|
||||
try {
|
||||
const current = readFile(file, uid);
|
||||
const stored = current?.revision ?? 0;
|
||||
if (input.revision !== undefined && input.revision !== stored) {
|
||||
throw new RouteStoreError("triage-route-stale", `the Triage route changed: the stored revision is ${stored}, not ${input.revision}`);
|
||||
}
|
||||
const next = {
|
||||
version: ROUTE_VERSION, revision: stored + 1, model: input.model, harness: input.harness,
|
||||
cap: capFor({ limit: input.limit, timeZone: input.timeZone, previous: current?.cap ?? null, now }),
|
||||
updatedAt: now, updatedBy: input.by,
|
||||
};
|
||||
if (!validRoute(next)) throw invalid("the new route does not match the route shape");
|
||||
const receiptFd = openReceipts(receipts, uid);
|
||||
try {
|
||||
const temp = join(dir, `.route.json.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
|
||||
const tfd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
|
||||
try {
|
||||
writeSync(tfd, `${JSON.stringify(next, null, 2)}\n`);
|
||||
fsyncSync(tfd);
|
||||
} finally { closeSync(tfd); }
|
||||
hook("crash");
|
||||
hook("before-rename");
|
||||
try { renameSync(temp, file); } catch (e) { try { unlinkSync(temp); } catch {} throw unreadable("route.json cannot be replaced"); }
|
||||
const dfd = openSync(dir, constants.O_RDONLY | constants.O_DIRECTORY);
|
||||
try { fsyncSync(dfd); } finally { closeSync(dfd); }
|
||||
writeSync(receiptFd, `${JSON.stringify({ at: now, by: input.by, revision: next.revision, from: summary(current), to: summary(next) })}\n`);
|
||||
fsyncSync(receiptFd);
|
||||
} finally { closeSync(receiptFd); }
|
||||
return next;
|
||||
} finally { dropLock(lock, held); }
|
||||
}
|
||||
@@ -0,0 +1,382 @@
|
||||
// #1873 triage-route-store: the owner-only file that holds Triage's model route and daily cap,
|
||||
// <dataRoot>/triage/route.json (design report section 1, option C). Names only: no env value and
|
||||
// no key. The directory is 0700 and the file 0600, both the running user's; a link, a non-file,
|
||||
// a wrong mode or owner refuses. A write is compare-and-set on revision, atomic (temp file plus
|
||||
// rename in the same directory), and appends one receipt line.
|
||||
import { test } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import { spawn } from "node:child_process";
|
||||
import { chmodSync, existsSync, linkSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import {
|
||||
CAP_FIELDS, ROUTE_FIELDS, ROUTE_VERSION, RouteStoreError, capFor, readRoute, routePaths, validRoute, writeRoute,
|
||||
} from "../src/triage-route-store.mjs";
|
||||
|
||||
const MODULE = new URL("../src/triage-route-store.mjs", import.meta.url).pathname;
|
||||
const NOW = "2026-11-18T12:00:00.000Z";
|
||||
const LATER = "2026-11-18T13:00:00.000Z";
|
||||
const at = (iso) => () => new Date(iso);
|
||||
const INPUT = { model: "glm-5", harness: "claude-code", limit: 200000, timeZone: "America/Chicago", by: "owner" };
|
||||
|
||||
function root(t) {
|
||||
const dir = mkdtempSync(join(process.env.TMPDIR, "trs-"));
|
||||
t.after(() => rmSync(dir, { recursive: true, force: true }));
|
||||
return dir;
|
||||
}
|
||||
const code = (c) => (e) => e instanceof RouteStoreError && e.code === c;
|
||||
// Unreadable with a given reason, so each check is shown to refuse on its own.
|
||||
const unreadableFor = (re) => (e) => code("triage-route-unreadable")(e) && re.test(e.message);
|
||||
const receipts = (dataRoot) => readFileSync(routePaths(dataRoot).receipts, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
|
||||
const good = () => ({
|
||||
version: 1, revision: 1, model: "glm-5", harness: "claude-code",
|
||||
cap: { limit: 200000, since: NOW, reset: "00:00", timeZone: "America/Chicago" }, updatedAt: NOW, updatedBy: "owner",
|
||||
});
|
||||
// Write a doc straight to route.json at the right modes, to test the loader alone.
|
||||
function plant(dataRoot, doc) {
|
||||
const { dir, file } = routePaths(dataRoot);
|
||||
mkdirSync(dir, { recursive: true, mode: 0o700 });
|
||||
chmodSync(dir, 0o700);
|
||||
writeFileSync(file, typeof doc === "string" ? doc : JSON.stringify(doc), { mode: 0o600 });
|
||||
chmodSync(file, 0o600);
|
||||
}
|
||||
|
||||
test("paths, field names and the reset rule each live in one place", () => {
|
||||
const p = routePaths("/d");
|
||||
assert.deepEqual(p, { dir: "/d/triage", file: "/d/triage/route.json", receipts: "/d/triage/route-receipts.jsonl", lock: "/d/triage/route.lock" });
|
||||
assert.deepEqual([...ROUTE_FIELDS].sort(), ["cap", "harness", "model", "revision", "updatedAt", "updatedBy", "version"]);
|
||||
assert.deepEqual([...CAP_FIELDS].sort(), ["limit", "reset", "since", "timeZone"]);
|
||||
assert.equal(ROUTE_VERSION, 1);
|
||||
// A new cap starts its count now and resets at 00:00 in the owner's zone.
|
||||
assert.deepEqual(capFor({ limit: 5, timeZone: "UTC", previous: null, now: NOW }), { limit: 5, since: NOW, reset: "00:00", timeZone: "UTC" });
|
||||
// The same cap keeps its since; a changed limit or zone starts again.
|
||||
const prev = { limit: 5, since: NOW, reset: "00:00", timeZone: "UTC" };
|
||||
assert.equal(capFor({ limit: 5, timeZone: "UTC", previous: prev, now: LATER }).since, NOW);
|
||||
assert.equal(capFor({ limit: 6, timeZone: "UTC", previous: prev, now: LATER }).since, LATER);
|
||||
assert.equal(capFor({ limit: 5, timeZone: "Europe/Berlin", previous: prev, now: LATER }).since, LATER);
|
||||
});
|
||||
|
||||
test("no file reads as not set; a write then reads back the same route", (t) => {
|
||||
const d = root(t);
|
||||
assert.equal(readRoute(d), null);
|
||||
const written = writeRoute(d, INPUT, { now: at(NOW) });
|
||||
assert.deepEqual(written, good());
|
||||
assert.deepEqual(readRoute(d), good());
|
||||
const { dir, file } = routePaths(d);
|
||||
assert.equal(lstatSync(dir).mode & 0o777, 0o700);
|
||||
assert.equal(lstatSync(file).mode & 0o777, 0o600);
|
||||
// The store holds names only: nothing shaped like an env value or a key.
|
||||
const text = readFileSync(file, "utf8");
|
||||
assert.doesNotMatch(text, /ANTHROPIC|_KEY|TOKEN|mst-|msk-|env/i);
|
||||
// A second write bumps the revision and keeps the cap's since when the cap is the same.
|
||||
const second = writeRoute(d, { ...INPUT, model: "glm-5.3-flash", revision: 1 }, { now: at(LATER) });
|
||||
assert.equal(second.revision, 2);
|
||||
assert.equal(second.model, "glm-5.3-flash");
|
||||
assert.equal(second.cap.since, NOW);
|
||||
assert.equal(second.updatedAt, LATER);
|
||||
assert.deepEqual(readRoute(d), second);
|
||||
// No temp file or lock is left behind.
|
||||
assert.deepEqual(readdirSync(dir).sort(), ["route-receipts.jsonl", "route.json"]);
|
||||
});
|
||||
|
||||
test("each write appends one receipt line with the old and the new value", (t) => {
|
||||
const d = root(t);
|
||||
writeRoute(d, INPUT, { now: at(NOW) });
|
||||
writeRoute(d, { ...INPUT, limit: 1000 }, { now: at(LATER) });
|
||||
const lines = receipts(d);
|
||||
assert.equal(lines.length, 2);
|
||||
assert.deepEqual(lines[0], { at: NOW, by: "owner", revision: 1, from: null, to: { model: "glm-5", harness: "claude-code", cap: good().cap } });
|
||||
assert.equal(lines[1].revision, 2);
|
||||
assert.deepEqual(lines[1].from, { model: "glm-5", harness: "claude-code", cap: good().cap });
|
||||
assert.equal(lines[1].to.cap.limit, 1000);
|
||||
assert.equal(lines[1].to.cap.since, LATER);
|
||||
assert.equal(lstatSync(routePaths(d).receipts).mode & 0o777, 0o600);
|
||||
// A refused write appends nothing.
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(LATER) }), code("triage-route-stale"));
|
||||
assert.equal(receipts(d).length, 2);
|
||||
});
|
||||
|
||||
test("a stale revision refuses and leaves the file alone", (t) => {
|
||||
const d = root(t);
|
||||
writeRoute(d, INPUT, { now: at(NOW) });
|
||||
writeRoute(d, { ...INPUT, limit: 7, revision: 1 }, { now: at(NOW) });
|
||||
const before = readFileSync(routePaths(d).file, "utf8");
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, limit: 9, revision: 1 }, { now: at(LATER) }), code("triage-route-stale"));
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, limit: 9, revision: 3 }, { now: at(LATER) }), code("triage-route-stale"));
|
||||
assert.equal(readFileSync(routePaths(d).file, "utf8"), before);
|
||||
// Revision 0 means "only if there is no route yet".
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, revision: 0 }, { now: at(LATER) }), code("triage-route-stale"));
|
||||
const e = root(t);
|
||||
assert.equal(writeRoute(e, { ...INPUT, revision: 0 }, { now: at(NOW) }).revision, 1);
|
||||
});
|
||||
|
||||
test("refused input shapes on a write", (t) => {
|
||||
const d = root(t);
|
||||
// Each input check refuses with its own message, so none rests only on the final shape check.
|
||||
const bad = [
|
||||
[{ ...INPUT, model: "" }, /model must be/], [{ ...INPUT, model: "Has Space" }, /model must be/],
|
||||
[{ ...INPUT, model: "x".repeat(65) }, /model must be/], [{ ...INPUT, model: 5 }, /model must be/],
|
||||
[{ ...INPUT, harness: "" }, /harness must be/], [{ ...INPUT, harness: "Claude" }, /harness must be/],
|
||||
[{ ...INPUT, harness: "../pi" }, /harness must be/], [{ ...INPUT, harness: "x".repeat(33) }, /harness must be/],
|
||||
[{ ...INPUT, limit: -1 }, /the cap must be/], [{ ...INPUT, limit: 1.5 }, /the cap must be/],
|
||||
[{ ...INPUT, limit: "100" }, /the cap must be/], [{ ...INPUT, limit: 2 ** 53 }, /the cap must be/],
|
||||
[{ ...INPUT, timeZone: undefined }, /a time zone is required/], [{ ...INPUT, timeZone: "" }, /time zone is unknown/],
|
||||
[{ ...INPUT, timeZone: "Mars/Olympus_Mons" }, /time zone is unknown/], [{ ...INPUT, timeZone: "../etc" }, /time zone is unknown/],
|
||||
[{ ...INPUT, by: "" }, /actor name/], [{ ...INPUT, by: "Owner Person" }, /actor name/],
|
||||
[{ ...INPUT, revision: -1 }, /revision must be/], [{ ...INPUT, revision: "1" }, /revision must be/], [{ ...INPUT, revision: 1.5 }, /revision must be/],
|
||||
[{ ...INPUT, env: { A: "b" } }, /unknown field env/], [{ ...INPUT, key: "mst-x" }, /unknown field key/],
|
||||
[null, /not an object/], [[INPUT], /not an object/],
|
||||
];
|
||||
for (const [input, message] of bad) {
|
||||
assert.throws(() => writeRoute(d, input, { now: at(NOW) }), (e) => code("triage-route-invalid")(e) && message.test(e.message), JSON.stringify(input));
|
||||
}
|
||||
// No time zone default: leaving it out refuses.
|
||||
const { timeZone, ...noZone } = INPUT;
|
||||
assert.throws(() => writeRoute(d, noZone, { now: at(NOW) }), (e) => code("triage-route-invalid")(e) && /a time zone is required/.test(e.message));
|
||||
assert.equal(readRoute(d), null);
|
||||
});
|
||||
|
||||
test("an unknown time zone refuses on write and on read", (t) => {
|
||||
const d = root(t);
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, timeZone: "Atlantis/Lost" }, { now: at(NOW) }), code("triage-route-invalid"));
|
||||
plant(d, { ...good(), cap: { ...good().cap, timeZone: "Atlantis/Lost" } });
|
||||
assert.throws(() => readRoute(d), code("triage-route-unreadable"));
|
||||
});
|
||||
|
||||
test("each refused stored shape reads as unreadable", (t) => {
|
||||
const g = good();
|
||||
const shapes = {
|
||||
"not json": "{",
|
||||
"an array": [g],
|
||||
"null": null,
|
||||
"unknown field": { ...g, env: {} },
|
||||
"unknown cap field": { ...g, cap: { ...g.cap, perTurn: 5 } },
|
||||
"missing version": (({ version, ...r }) => r)(g),
|
||||
"missing revision": (({ revision, ...r }) => r)(g),
|
||||
"missing model": (({ model, ...r }) => r)(g),
|
||||
"missing harness": (({ harness, ...r }) => r)(g),
|
||||
"missing cap": (({ cap, ...r }) => r)(g),
|
||||
"missing updatedAt": (({ updatedAt, ...r }) => r)(g),
|
||||
"missing updatedBy": (({ updatedBy, ...r }) => r)(g),
|
||||
"missing cap.limit": { ...g, cap: (({ limit, ...r }) => r)(g.cap) },
|
||||
"missing cap.since": { ...g, cap: (({ since, ...r }) => r)(g.cap) },
|
||||
"missing cap.reset": { ...g, cap: (({ reset, ...r }) => r)(g.cap) },
|
||||
"missing cap.timeZone": { ...g, cap: (({ timeZone, ...r }) => r)(g.cap) },
|
||||
"version 2": { ...g, version: 2 },
|
||||
"revision 0": { ...g, revision: 0 },
|
||||
"revision text": { ...g, revision: "1" },
|
||||
"bad model": { ...g, model: "A B" },
|
||||
"bad harness": { ...g, harness: "A/B" },
|
||||
"cap an array": { ...g, cap: [1] },
|
||||
"negative limit": { ...g, cap: { ...g.cap, limit: -1 } },
|
||||
"bad reset": { ...g, cap: { ...g.cap, reset: "24:00" } },
|
||||
"bad since": { ...g, cap: { ...g.cap, since: "2026-11-18" } },
|
||||
"bad updatedAt": { ...g, updatedAt: "yesterday" },
|
||||
"bad updatedBy": { ...g, updatedBy: "A B" },
|
||||
};
|
||||
for (const [name, doc] of Object.entries(shapes)) {
|
||||
const d = root(t);
|
||||
plant(d, doc);
|
||||
assert.throws(() => readRoute(d), code("triage-route-unreadable"), name);
|
||||
if (typeof doc !== "string") assert.equal(validRoute(doc), false, name);
|
||||
}
|
||||
assert.equal(validRoute(g), true);
|
||||
// A write over an unreadable file refuses too; it never replaces what it could not read.
|
||||
const d = root(t);
|
||||
plant(d, { ...g, env: {} });
|
||||
assert.throws(() => writeRoute(d, INPUT, { now: at(NOW) }), code("triage-route-unreadable"));
|
||||
});
|
||||
|
||||
test("an oversized file is refused before it is parsed", (t) => {
|
||||
const d = root(t);
|
||||
plant(d, JSON.stringify(good()) + " ".repeat(70000));
|
||||
assert.throws(() => readRoute(d), code("triage-route-unreadable"));
|
||||
});
|
||||
|
||||
test("a wrong mode on the directory or the file refuses", (t) => {
|
||||
for (const mode of [0o755, 0o750, 0o711, 0o500]) {
|
||||
const d = root(t);
|
||||
plant(d, good());
|
||||
chmodSync(routePaths(d).dir, mode);
|
||||
assert.throws(() => readRoute(d), code("triage-route-unreadable"), `dir ${mode.toString(8)}`);
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(NOW) }), code("triage-route-unreadable"), `dir ${mode.toString(8)}`);
|
||||
chmodSync(routePaths(d).dir, 0o700);
|
||||
}
|
||||
for (const mode of [0o644, 0o640, 0o604, 0o400, 0o700]) {
|
||||
const d = root(t);
|
||||
plant(d, good());
|
||||
chmodSync(routePaths(d).file, mode);
|
||||
assert.throws(() => readRoute(d), code("triage-route-unreadable"), `file ${mode.toString(8)}`);
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(NOW) }), code("triage-route-unreadable"), `file ${mode.toString(8)}`);
|
||||
}
|
||||
// A receipts file with the wrong mode refuses the write before the route changes.
|
||||
const d = root(t);
|
||||
writeRoute(d, INPUT, { now: at(NOW) });
|
||||
chmodSync(routePaths(d).receipts, 0o644);
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, limit: 1, revision: 1 }, { now: at(LATER) }), code("triage-route-unreadable"));
|
||||
assert.equal(readRoute(d).revision, 1);
|
||||
});
|
||||
|
||||
test("a wrong owner refuses on the directory and the file", (t) => {
|
||||
const d = root(t);
|
||||
plant(d, good());
|
||||
// Pretend to be another user: the store compares with the uid it is given.
|
||||
const other = process.getuid() + 1;
|
||||
assert.throws(() => readRoute(d, { uid: other }), unreadableFor(/the triage directory is not owned by this user/));
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(NOW), uid: other }), unreadableFor(/the triage directory is not owned by this user/));
|
||||
assert.equal(readRoute(d, { uid: process.getuid() }).revision, 1);
|
||||
});
|
||||
|
||||
test("a link at the file, the directory or the receipts refuses; so does a non-file", (t) => {
|
||||
// Symlink at route.json, to a valid route elsewhere.
|
||||
let d = root(t);
|
||||
plant(d, good());
|
||||
const elsewhere = join(d, "elsewhere.json");
|
||||
renameSync(routePaths(d).file, elsewhere);
|
||||
symlinkSync(elsewhere, routePaths(d).file);
|
||||
assert.throws(() => readRoute(d), code("triage-route-unreadable"));
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(NOW) }), code("triage-route-unreadable"));
|
||||
// A hard link at route.json.
|
||||
d = root(t);
|
||||
plant(d, good());
|
||||
linkSync(routePaths(d).file, join(d, "hard.json"));
|
||||
assert.throws(() => readRoute(d), code("triage-route-unreadable"));
|
||||
// Symlink at the triage directory, to a real 0700 directory holding a valid route.
|
||||
d = root(t);
|
||||
const real = join(d, "real");
|
||||
mkdirSync(real, { mode: 0o700 });
|
||||
writeFileSync(join(real, "route.json"), JSON.stringify(good()), { mode: 0o600 });
|
||||
symlinkSync(real, routePaths(d).dir);
|
||||
assert.throws(() => readRoute(d), unreadableFor(/the triage directory is a link/));
|
||||
assert.throws(() => writeRoute(d, INPUT, { now: at(NOW) }), unreadableFor(/the triage directory is a link/));
|
||||
// A directory where route.json should be.
|
||||
d = root(t);
|
||||
mkdirSync(routePaths(d).file, { recursive: true, mode: 0o700 });
|
||||
chmodSync(routePaths(d).dir, 0o700);
|
||||
assert.throws(() => readRoute(d), unreadableFor(/route\.json is not a regular file/));
|
||||
// A file where the triage directory should be, at 0700 so only the directory check refuses it.
|
||||
d = root(t);
|
||||
writeFileSync(routePaths(d).dir, "x", { mode: 0o700 });
|
||||
chmodSync(routePaths(d).dir, 0o700);
|
||||
assert.throws(() => readRoute(d), unreadableFor(/the triage directory is not a directory/));
|
||||
assert.throws(() => writeRoute(d, INPUT, { now: at(NOW) }), unreadableFor(/the triage directory is not a directory/));
|
||||
// A symlink at the receipts file refuses the write and never follows it.
|
||||
d = root(t);
|
||||
writeRoute(d, INPUT, { now: at(NOW) });
|
||||
const target = join(d, "target.jsonl");
|
||||
writeFileSync(target, "", { mode: 0o600 });
|
||||
unlinkSync(routePaths(d).receipts);
|
||||
symlinkSync(target, routePaths(d).receipts);
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(LATER) }), code("triage-route-unreadable"));
|
||||
assert.equal(readFileSync(target, "utf8"), "");
|
||||
assert.equal(readRoute(d).revision, 1);
|
||||
// A symlink at the lock path is not followed: the write refuses as busy.
|
||||
d = root(t);
|
||||
writeRoute(d, INPUT, { now: at(NOW) });
|
||||
symlinkSync(join(d, "nowhere"), routePaths(d).lock);
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(LATER) }), code("triage-route-busy"));
|
||||
assert.equal(existsSync(join(d, "nowhere")), false);
|
||||
});
|
||||
|
||||
test("the store makes its directory 0700 but never the data root", (t) => {
|
||||
const d = root(t);
|
||||
assert.throws(() => writeRoute(join(d, "missing"), INPUT, { now: at(NOW) }), code("triage-route-unreadable"));
|
||||
assert.equal(existsSync(join(d, "missing")), false);
|
||||
});
|
||||
|
||||
test("two writers in one process: the second, while the first holds the lock, refuses busy", (t) => {
|
||||
const d = root(t);
|
||||
writeRoute(d, INPUT, { now: at(NOW) });
|
||||
let inner = null;
|
||||
const won = writeRoute(d, { ...INPUT, limit: 1, revision: 1 }, {
|
||||
now: at(LATER),
|
||||
hook: (stage) => {
|
||||
if (stage !== "before-rename") return;
|
||||
try { writeRoute(d, { ...INPUT, limit: 2, revision: 1 }, { now: at(LATER) }); } catch (e) { inner = e; }
|
||||
},
|
||||
});
|
||||
assert.equal(won.cap.limit, 1);
|
||||
assert.ok(code("triage-route-busy")(inner), String(inner));
|
||||
assert.equal(readRoute(d).cap.limit, 1);
|
||||
assert.equal(receipts(d).length, 2);
|
||||
});
|
||||
|
||||
// A child process that loads the store and writes once; prints {ok, code}. `wait` makes it hold
|
||||
// at the given stage until the file `go` appears, so two children overlap for real.
|
||||
const CHILD = `
|
||||
import { writeRoute } from ${JSON.stringify(MODULE)};
|
||||
import { existsSync, writeFileSync } from "node:fs";
|
||||
const [dataRoot, limit, revision, wait, go, ready] = process.argv.slice(1);
|
||||
try {
|
||||
const r = writeRoute(dataRoot, { model: "glm-5", harness: "claude-code", limit: Number(limit), timeZone: "UTC", by: "owner", revision: Number(revision) }, {
|
||||
hook: (stage) => {
|
||||
if (stage === "crash") { if (wait === "crash") process.kill(process.pid, "SIGKILL"); return; }
|
||||
if (stage !== wait) return;
|
||||
writeFileSync(ready, "");
|
||||
const end = Date.now() + 20000;
|
||||
while (!existsSync(go) && Date.now() < end) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
|
||||
},
|
||||
});
|
||||
console.log(JSON.stringify({ ok: true, limit: r.cap.limit }));
|
||||
} catch (e) { console.log(JSON.stringify({ ok: false, code: e.code ?? String(e) })); }
|
||||
`;
|
||||
function child(args) {
|
||||
return new Promise((resolve, reject) => {
|
||||
const p = spawn(process.execPath, ["--input-type=module", "-e", CHILD, ...args], { stdio: ["ignore", "pipe", "pipe"] });
|
||||
let out = "", err = "";
|
||||
p.stdout.setEncoding("utf8").on("data", (c) => { out += c; });
|
||||
p.stderr.setEncoding("utf8").on("data", (c) => { err += c; });
|
||||
p.on("error", reject);
|
||||
p.on("close", (status, signal) => resolve({ status, signal, out: out.trim(), err }));
|
||||
});
|
||||
}
|
||||
async function until(path) {
|
||||
const end = Date.now() + 20000;
|
||||
while (!existsSync(path)) {
|
||||
if (Date.now() > end) throw new Error(`timed out waiting for ${path}`);
|
||||
await new Promise((r) => setTimeout(r, 20));
|
||||
}
|
||||
}
|
||||
|
||||
test("two writer processes racing on one revision: one wins, one refuses", async (t) => {
|
||||
const d = root(t);
|
||||
writeRoute(d, { ...INPUT, timeZone: "UTC" }, { now: at(NOW) });
|
||||
const go = join(d, "go"), ready = join(d, "ready");
|
||||
// The first holds just before its rename; the second starts then, with the same revision.
|
||||
const first = child([d, "11", "1", "before-rename", go, ready]);
|
||||
await until(ready);
|
||||
const second = await child([d, "22", "1", "none", join(d, "unused"), join(d, "unused-ready")]);
|
||||
writeFileSync(go, "");
|
||||
const a = JSON.parse((await first).out), b = JSON.parse(second.out);
|
||||
assert.deepEqual(a, { ok: true, limit: 11 });
|
||||
assert.equal(b.ok, false);
|
||||
assert.equal(b.code, "triage-route-busy");
|
||||
assert.equal(readRoute(d).cap.limit, 11);
|
||||
assert.equal(readRoute(d).revision, 2);
|
||||
// After the winner, the loser's revision is stale.
|
||||
const again = JSON.parse((await child([d, "22", "1", "none", join(d, "u2"), join(d, "u3")])).out);
|
||||
assert.deepEqual(again, { ok: false, code: "triage-route-stale" });
|
||||
// Started together with no pause, exactly one of two wins.
|
||||
const both = await Promise.all([child([d, "33", "2", "none", join(d, "u4"), join(d, "u5")]), child([d, "44", "2", "none", join(d, "u6"), join(d, "u7")])]);
|
||||
const results = both.map((r) => JSON.parse(r.out));
|
||||
assert.equal(results.filter((r) => r.ok).length, 1, JSON.stringify(results));
|
||||
assert.ok(results.filter((r) => !r.ok).every((r) => ["triage-route-busy", "triage-route-stale"].includes(r.code)), JSON.stringify(results));
|
||||
assert.equal(readRoute(d).revision, 3);
|
||||
assert.equal(receipts(d).length, 3);
|
||||
});
|
||||
|
||||
test("a crash between the temp write and the rename leaves the old file", async (t) => {
|
||||
const d = root(t);
|
||||
const old = writeRoute(d, { ...INPUT, timeZone: "UTC" }, { now: at(NOW) });
|
||||
const r = await child([d, "99", "1", "crash", join(d, "go"), join(d, "ready")]);
|
||||
assert.equal(r.signal, "SIGKILL", r.err);
|
||||
assert.deepEqual(readRoute(d), old);
|
||||
assert.equal(receipts(d).length, 1);
|
||||
// The temp file is still there, and the dead writer's lock refuses the next write, naming it.
|
||||
const { dir, lock } = routePaths(d);
|
||||
assert.ok(readdirSync(dir).some((n) => n.endsWith(".tmp")), readdirSync(dir).join(","));
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(LATER) }), (e) => code("triage-route-busy")(e) && /not running/.test(e.message) && /route\.lock/.test(e.message));
|
||||
// The person removes the lock by hand; the next write works and the read ignores the temp file.
|
||||
unlinkSync(lock);
|
||||
assert.equal(writeRoute(d, { ...INPUT, revision: 1 }, { now: at(LATER) }).revision, 2);
|
||||
assert.equal(readRoute(d).revision, 2);
|
||||
});
|
||||
Reference in new issue
Block a user