fix(triage): review round for the route store
The file owner check has its own test through a file-owner seam, for route.json on read and write and for route-receipts.jsonl on write. The directory, temp file and a new receipts file get their modes on the open descriptor, so a narrow umask cannot leave a route the next read refuses; an existing receipts file is never repaired. A failed temp write refuses and removes the temp file. A failure after the rename refuses as triage-route-unrecorded and names the new revision. The input zone check uses the stored cap's rule, so +05:00 refuses as an unknown zone. A changed cap keeps its since, as an organization's token limits do, so lowering the cap never drops tokens already counted (#1873, lane triage-route-store).
This commit was merged in pull request #1989.
This commit is contained in:
1 parent
4c8527fcd3
commit
c9fad00d25
3 files changed
+104
-33
No files matched your search
@@ -1437,12 +1437,16 @@ The file is `<dataRoot>/triage/route.json`
|
||||
(packages/webui/src/triage-route-store.mjs): a catalogue model key, a harness
|
||||
name and a daily cap leaf `{limit, since, reset, timeZone}`. It holds no env
|
||||
value and no key. The day resets at 00:00 in the zone given, which has no
|
||||
default; an unknown zone refuses. The directory is 0700 and the file 0600,
|
||||
default; an unknown zone refuses. The first cap counts from the time it is
|
||||
set; a later change keeps that `since`, as an organization's token limits do,
|
||||
so lowering the cap never drops tokens already spent. The directory is 0700 and the file 0600,
|
||||
owned by the running user; a link, a non-file, a wrong mode or owner, or an
|
||||
unknown field refuses (exit 3). A write is compare-and-set on `revision`
|
||||
(`--revision 0`: only when nothing is set), atomic, and appends one line with
|
||||
the old and new values to `route-receipts.jsonl`. A write that died leaves
|
||||
`route.lock`; the next write refuses and names it, and you remove it by hand.
|
||||
If the route changed but its receipt line could not be written, the write
|
||||
refuses with `triage-route-unrecorded` (exit 3) and names the new revision.
|
||||
`set` checks the harness against packages/plugins/harness/; it does not check
|
||||
the model key against a catalogue yet.
|
||||
|
||||
|
||||
@@ -11,12 +11,13 @@
|
||||
// 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
|
||||
// to route-receipts.jsonl. Files and the directory the store makes get their modes set on the open
|
||||
// descriptor, so the owner's umask cannot leave them unreadable. 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 { closeSync, constants, fchmodSync, 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";
|
||||
@@ -53,20 +54,19 @@ export function routePaths(dataRoot) {
|
||||
}
|
||||
|
||||
// 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.
|
||||
// A first cap counts from now; a changed cap keeps its stored `since`, as an organization's token
|
||||
// limits do (packages/organization/src/launch-settings.mjs stamp), so lowering the cap never drops
|
||||
// the tokens already spent today. Only a reset would move it, and this slice has no reset verb.
|
||||
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 };
|
||||
return { limit, since: previous ? previous.since : now, reset: "00:00", 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; }
|
||||
};
|
||||
// The same zone rule the stored cap is held to (isDailyModelQuota: its zone shape, then Intl).
|
||||
const knownZone = (zone) => typeof zone === "string"
|
||||
&& isDailyModelQuota(LEAF_KEY, { limit: 0, since: "2000-01-01T00:00:00.000Z", reset: "00:00", timeZone: zone });
|
||||
|
||||
export function validRoute(doc) {
|
||||
return exactKeys(doc, ROUTE_FIELDS)
|
||||
@@ -81,6 +81,8 @@ export function validRoute(doc) {
|
||||
}
|
||||
|
||||
const uidOf = (opts) => opts.uid ?? process.getuid();
|
||||
// The owner the files are held to: the same user, unless a test checks the file owner alone.
|
||||
const fileUidOf = (opts) => opts.fileUid ?? uidOf(opts);
|
||||
|
||||
// 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).
|
||||
@@ -91,6 +93,11 @@ function checkDir(dir, uid, { create }) {
|
||||
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"); }
|
||||
// The umask may have narrowed the mode; set it on the directory just made, never through a link.
|
||||
try {
|
||||
const fd = openSync(dir, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
|
||||
try { fchmodSync(fd, 0o700); } finally { closeSync(fd); }
|
||||
} catch { throw unreadable("the triage directory cannot be made"); }
|
||||
st = lstatSync(dir);
|
||||
}
|
||||
if (st.isSymbolicLink()) throw unreadable("the triage directory is a link");
|
||||
@@ -131,9 +138,8 @@ function readFile(file, uid) {
|
||||
// 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);
|
||||
if (!checkDir(dir, uidOf(opts), { create: false })) return null;
|
||||
return readFile(file, fileUidOf(opts));
|
||||
}
|
||||
|
||||
function checkInput(input) {
|
||||
@@ -186,13 +192,18 @@ function dropLock(lock, held) {
|
||||
closeSync(held.fd);
|
||||
}
|
||||
|
||||
// The receipts file, opened for append before the route changes, so a bad one refuses first.
|
||||
// The receipts file, opened for append before the route changes, so a bad one refuses first. An
|
||||
// existing file is held to its checks as it is; only a file made here gets its mode set.
|
||||
function openReceipts(receipts, uid) {
|
||||
const flags = constants.O_WRONLY | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK;
|
||||
let fd;
|
||||
try { fd = openSync(receipts, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600); }
|
||||
try { fd = openSync(receipts, flags); }
|
||||
catch (e) {
|
||||
if (e.code === "ELOOP") throw unreadable("route-receipts.jsonl is a link");
|
||||
throw unreadable("route-receipts.jsonl cannot be opened");
|
||||
if (e.code !== "ENOENT") throw unreadable("route-receipts.jsonl cannot be opened");
|
||||
try { fd = openSync(receipts, flags | constants.O_CREAT | constants.O_EXCL, 0o600); }
|
||||
catch { throw unreadable("route-receipts.jsonl cannot be made"); }
|
||||
try { fchmodSync(fd, 0o600); } catch { closeSync(fd); throw unreadable("route-receipts.jsonl cannot be made"); }
|
||||
}
|
||||
try { checkFile(fd, uid, "route-receipts.jsonl"); } catch (e) { closeSync(fd); throw e; }
|
||||
return fd;
|
||||
@@ -203,18 +214,21 @@ const summary = (doc) => (doc ? { model: doc.model, harness: doc.harness, cap: d
|
||||
// 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".
|
||||
// opts.now, opts.uid and opts.fileUid are for tests; opts.hook(stage) is a test seam at "write"
|
||||
// (inside the temp write), "crash" (after the temp file is written), "before-rename" and
|
||||
// "after-rename" (before the receipt line). A failure after the rename refuses as
|
||||
// triage-route-unrecorded: the route did change, and its receipt line is missing.
|
||||
export function writeRoute(dataRoot, input, opts = {}) {
|
||||
checkInput(input);
|
||||
const { dir, file, receipts, lock } = routePaths(dataRoot);
|
||||
const uid = uidOf(opts);
|
||||
const fileUid = fileUidOf(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 current = readFile(file, fileUid);
|
||||
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}`);
|
||||
@@ -225,21 +239,32 @@ export function writeRoute(dataRoot, input, opts = {}) {
|
||||
updatedAt: now, updatedBy: input.by,
|
||||
};
|
||||
if (!validRoute(next)) throw invalid("the new route does not match the route shape");
|
||||
const receiptFd = openReceipts(receipts, uid);
|
||||
const receiptFd = openReceipts(receipts, fileUid);
|
||||
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);
|
||||
let tfd;
|
||||
try { tfd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
|
||||
catch { throw unreadable("route.json cannot be written"); }
|
||||
try {
|
||||
writeSync(tfd, `${JSON.stringify(next, null, 2)}\n`);
|
||||
fsyncSync(tfd);
|
||||
} finally { closeSync(tfd); }
|
||||
try {
|
||||
fchmodSync(tfd, 0o600);
|
||||
hook("write");
|
||||
writeSync(tfd, `${JSON.stringify(next, null, 2)}\n`);
|
||||
fsyncSync(tfd);
|
||||
} finally { closeSync(tfd); }
|
||||
} catch { try { unlinkSync(temp); } catch {} throw unreadable("route.json cannot be written"); }
|
||||
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);
|
||||
try {
|
||||
hook("after-rename");
|
||||
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);
|
||||
} catch {
|
||||
throw new RouteStoreError("triage-route-unrecorded", `the Triage route changed to revision ${next.revision}, but its receipt line was not written`);
|
||||
}
|
||||
} finally { closeSync(receiptFd); }
|
||||
return next;
|
||||
} finally { dropLock(lock, held); }
|
||||
|
||||
@@ -48,11 +48,12 @@ test("paths, field names and the reset rule each live in one place", () => {
|
||||
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.
|
||||
// A later cap keeps its since, changed or not, as an organization's token limits do: lowering
|
||||
// the cap never drops the tokens already counted.
|
||||
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);
|
||||
assert.equal(capFor({ limit: 2, timeZone: "UTC", previous: prev, now: LATER }).since, NOW);
|
||||
assert.equal(capFor({ limit: 5, timeZone: "Europe/Berlin", previous: prev, now: LATER }).since, NOW);
|
||||
});
|
||||
|
||||
test("no file reads as not set; a write then reads back the same route", (t) => {
|
||||
@@ -88,7 +89,7 @@ test("each write appends one receipt line with the old and the new value", (t) =
|
||||
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(lines[1].to.cap.since, NOW);
|
||||
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"));
|
||||
@@ -121,6 +122,7 @@ test("refused input shapes on a write", (t) => {
|
||||
[{ ...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, timeZone: "+05:00" }, /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/],
|
||||
@@ -221,6 +223,14 @@ test("a wrong owner refuses on the directory and the file", (t) => {
|
||||
plant(d, good());
|
||||
// Pretend to be another user: the store compares with the uid it is given.
|
||||
const other = process.getuid() + 1;
|
||||
// The files alone owned by someone else: route.json on read and write, the receipts on write.
|
||||
assert.throws(() => readRoute(d, { fileUid: other }), unreadableFor(/route\.json is not owned by this user/));
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(NOW), fileUid: other }), unreadableFor(/route\.json is not owned by this user/));
|
||||
const e = root(t);
|
||||
writeRoute(e, INPUT, { now: at(NOW) });
|
||||
unlinkSync(routePaths(e).file);
|
||||
assert.throws(() => writeRoute(e, INPUT, { now: at(NOW), fileUid: other }), unreadableFor(/route-receipts\.jsonl is not owned by this user/));
|
||||
assert.equal(existsSync(routePaths(e).file), false);
|
||||
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);
|
||||
@@ -277,6 +287,38 @@ test("a link at the file, the directory or the receipts refuses; so does a non-f
|
||||
assert.equal(existsSync(join(d, "nowhere")), false);
|
||||
});
|
||||
|
||||
test("a write under a narrow umask still leaves 0700 and 0600, so the next read works", (t) => {
|
||||
const d = root(t);
|
||||
const old = process.umask(0o277);
|
||||
let written;
|
||||
try { written = writeRoute(d, INPUT, { now: at(NOW) }); } finally { process.umask(old); }
|
||||
const { dir, file, receipts: r } = routePaths(d);
|
||||
assert.equal(lstatSync(dir).mode & 0o777, 0o700);
|
||||
assert.equal(lstatSync(file).mode & 0o777, 0o600);
|
||||
assert.equal(lstatSync(r).mode & 0o777, 0o600);
|
||||
assert.deepEqual(readRoute(d), written);
|
||||
// An existing receipts file is never repaired: a wrong mode still refuses.
|
||||
chmodSync(r, 0o644);
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, revision: 1 }, { now: at(LATER) }), unreadableFor(/route-receipts\.jsonl mode is not 0600/));
|
||||
});
|
||||
|
||||
test("a failed temp write refuses and leaves the route; a failed receipt after the rename says so", (t) => {
|
||||
const d = root(t);
|
||||
writeRoute(d, INPUT, { now: at(NOW) });
|
||||
const before = readFileSync(routePaths(d).file, "utf8");
|
||||
const fail = (stage) => (s) => { if (s === stage) throw Object.assign(new Error("no space"), { code: "ENOSPC" }); };
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, limit: 1, revision: 1 }, { now: at(LATER), hook: fail("write") }), unreadableFor(/route\.json cannot be written/));
|
||||
assert.equal(readFileSync(routePaths(d).file, "utf8"), before);
|
||||
assert.deepEqual(readdirSync(routePaths(d).dir).sort(), ["route-receipts.jsonl", "route.json"]);
|
||||
assert.equal(receipts(d).length, 1);
|
||||
// After the rename the route has changed; the refusal names the new revision and the missing line.
|
||||
assert.throws(() => writeRoute(d, { ...INPUT, limit: 1, revision: 1 }, { now: at(LATER), hook: fail("after-rename") }),
|
||||
(e) => code("triage-route-unrecorded")(e) && /changed to revision 2, but its receipt line was not written/.test(e.message));
|
||||
assert.equal(readRoute(d).revision, 2);
|
||||
assert.equal(receipts(d).length, 1);
|
||||
assert.deepEqual(readdirSync(routePaths(d).dir).sort(), ["route-receipts.jsonl", "route.json"]);
|
||||
});
|
||||
|
||||
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"));
|
||||
|
||||
Reference in new issue
Block a user