The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 23:30 UTC
fix(server): stream the usage-scan cache to disk instead of one string (#34030)
Julius Marminge committed
Nov 10, 2026 at 21:32 UTC
c03f84bcde5952a83242652308200a862411eed1
6 files changed
+108
-38
apps/server/src/usage/UsageService.test.ts
+10
-6
@@ -2587,7 +2587,7 @@ describe("UsageService", () => {
2587
);
2588
2589
it.live.each([4, 5, 6, 7, 8, 10])(
2590
- "upgrades a v%s cache: reparses live Codex usage, keeps deleted rollouts and the old file",
2590
+ "upgrades a v%s cache: reparses live Codex usage, keeps deleted rollouts, removes the old file",
2591
(version) =>
2592
Effect.gen(function* () {
2593
const { home, settings } = yield* setup;
@@ -2636,7 +2636,7 @@ describe("UsageService", () => {
2636
yield* first.readSummary(WINDOW);
2637
yield* first.awaitPersisted;
2638
2639
- const legacy = yield* Effect.promise(async () => {
2639
+ yield* Effect.promise(async () => {
2640
const livePath = await NodeFSP.realpath(live);
2641
const document = decodeUnknownJsonString(await NodeFSP.readFile(cachePath, "utf8")) as {
2642
files: Record<string, { r: unknown[][]; mr: number; cs: Record<string, unknown> }>;
@@ -2674,7 +2674,9 @@ describe("UsageService", () => {
2674
}
2675
}
2676
await NodeFSP.rm(deleted);
2677
- return text;
2677
+ await NodeFSP.mkdir(`${cachePath}.stale`);
2678
+ await NodeFSP.utimes(`${cachePath}.stale`, 0, 0);
2679
+ await NodeFSP.mkdir(`${cachePath}.active`);
2680
});
2681
2682
const upgraded = yield* UsageService.make;
@@ -2686,9 +2688,11 @@ describe("UsageService", () => {
2688
);
2689
yield* upgraded.awaitPersisted;
2690
assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v11.json");
2689
- assert.strictEqual(
2690
- yield* Effect.promise(() => NodeFSP.readFile(legacyPath, "utf8")),
2691
- legacy,
2691
+ assert.deepStrictEqual(
2692
+ (yield* Effect.promise(() => NodeFSP.readdir(stateDir)))
2693
+ .filter((name) => name.startsWith("usage-scan-cache"))
2694
+ .toSorted(),
2695
+ [SCAN_CACHE_FILE_NAME, `${SCAN_CACHE_FILE_NAME}.active`],
2696
);
2697
}).pipe(
2698
Effect.provide(
apps/server/src/usage/UsageService.ts
+35
-1
@@ -71,6 +71,7 @@ const MTIME_SLACK_MS = 36 * 60 * 60 * 1000;
71
const MAX_HOURLY_WINDOW_MS = 24 * 60 * 60 * 1000;
72
73
const CACHE_RETENTION_DAYS = 92;
74
+const STALE_TEMP_DIRECTORY_MS = 60 * 60 * 1000;
75
76
const TRANSCRIPT_READ_CONCURRENCY = 4;
77
@@ -172,7 +173,7 @@ export const make = Effect.gen(function* () {
173
174
const ratesCachePath = path.join(config.stateDir, "usage-model-rates.json");
175
const scanCachePath = path.join(config.stateDir, SCAN_CACHE_FILE_NAME);
175
- const writeCacheFile = (filePath: string, contents: string) =>
176
+ const writeCacheFile = (filePath: string, contents: string | Iterable<string>) =>
177
writeFileStringAtomically({ filePath, contents }).pipe(
178
Effect.provideService(FileSystem.FileSystem, fileSystem),
179
Effect.provideService(Path.Path, path),
@@ -407,6 +408,32 @@ export const make = Effect.gen(function* () {
408
// Serialize writes so concurrently finished window scans cannot overwrite newer snapshots.
409
const persistLock = yield* Semaphore.make(1);
410
411
+ // The saved cache supersedes older versions. Temp folders an aborted write left behind are
412
+ // removed once idle for an hour, so a write in progress from another server survives.
413
+ let supersededFilesRemoved = false;
414
+ const removeSupersededCacheFiles = Effect.gen(function* () {
415
+ for (const fileName of LEGACY_SCAN_CACHE_FILE_NAMES) {
416
+ yield* fileSystem.remove(path.join(config.stateDir, fileName)).pipe(Effect.ignore);
417
+ }
418
+ const tempPrefixes = [SCAN_CACHE_FILE_NAME, ...LEGACY_SCAN_CACHE_FILE_NAMES].map(
419
+ (fileName) => `${fileName}.`,
420
+ );
421
+ const staleBeforeMs = (yield* Clock.currentTimeMillis) - STALE_TEMP_DIRECTORY_MS;
422
+ for (const name of yield* fileSystem.readDirectory(config.stateDir)) {
423
+ if (!tempPrefixes.some((prefix) => name.startsWith(prefix))) continue;
424
+ const tempPath = path.join(config.stateDir, name);
425
+ yield* fileSystem.stat(tempPath).pipe(
426
+ Effect.flatMap((info) => {
427
+ const mtimeMs = Option.getOrUndefined(info.mtime)?.getTime();
428
+ return info.type === "Directory" && mtimeMs !== undefined && mtimeMs <= staleBeforeMs
429
+ ? fileSystem.remove(tempPath, { recursive: true })
430
+ : Effect.void;
431
+ }),
432
+ Effect.ignore,
433
+ );
434
+ }
435
+ }).pipe(Effect.ignore);
436
+
437
// Clear dirty before encoding to retain concurrent changes; restore it on failure for retry.
438
const persistCaches = Effect.gen(function* () {
439
if (cacheDirty) {
@@ -415,6 +442,13 @@ export const make = Effect.gen(function* () {
442
writeScanCache(fileCache, { sources: Object.fromEntries(sourceCache) }),
443
).pipe(
444
Effect.flatMap((contents) => writeCacheFile(scanCachePath, contents)),
445
+ Effect.andThen(
446
+ Effect.suspend(() => {
447
+ if (supersededFilesRemoved) return Effect.void;
448
+ supersededFilesRemoved = true;
449
+ return removeSupersededCacheFiles;
450
+ }),
451
+ ),
452
Effect.catchCause(() =>
453
Effect.sync(() => {
454
cacheDirty = true;
apps/server/src/usage/usageScanCache.test.ts
+9
-12
@@ -11,6 +11,8 @@ import type { UsageRecord } from "@t3tools/provider-core/server/usage";
11
import { TEST_FORMAT_MAP } from "./usageTestFormats.ts";
12
import { initialCodexScanState, parseCodexLine } from "../provider/Drivers/codexUsage.ts";
13
14
+const parse = (parts: Iterable<string>) => JSON.parse([...parts].join(""));
15
+
16
function record(overrides: Partial<UsageRecord> = {}): UsageRecord {
17
return {
18
provider: "claude",
@@ -152,10 +154,7 @@ describe("scan cache round trip", () => {
154
record({ model: "<synthetic>", dedupeKey: "msg_tail:" }),
155
],
156
});
155
- const restored = decodeScanCache(
156
- JSON.parse(makeScanCacheWriter()(cached, {})),
157
- TEST_FORMAT_MAP,
158
- );
157
+ const restored = decodeScanCache(parse(makeScanCacheWriter()(cached, {})), TEST_FORMAT_MAP);
158
159
expect(restored.size).toBe(4);
160
expect(restored).toEqual(original);
@@ -196,7 +195,7 @@ describe("scan cache round trip", () => {
195
malformedRecords: 0,
196
};
197
original.set("/clean-codex.jsonl", cleanCodex);
199
- const encoded = JSON.parse(makeScanCacheWriter()(original, {}));
198
+ const encoded = parse(makeScanCacheWriter()(original, {}));
199
const entry = encoded.files["/gone.jsonl"]!;
200
const legacy = {
201
...encoded,
@@ -251,7 +250,7 @@ describe("scan cache round trip", () => {
250
251
it("re-parses a Claude transcript cached before advisor usage was counted", () => {
252
const original = cacheWith([["/claude.jsonl", 100, [record()]]]);
254
- const v9 = { ...JSON.parse(makeScanCacheWriter()(original, {})), version: 9 };
253
+ const v9 = { ...parse(makeScanCacheWriter()(original, {})), version: 9 };
254
255
const restored = decodeScanCache(JSON.parse(JSON.stringify(v9)), TEST_FORMAT_MAP);
256
expect(restored.get("/claude.jsonl")).toEqual({
@@ -269,7 +268,7 @@ describe("scan cache round trip", () => {
268
]);
269
cache.set("/b.jsonl", { ...cache.get("/b.jsonl")!, malformedRecords: 2 });
270
const sources = { "claude\u0000/projects": { dir: "/projects", volumeId: "1:2" } };
272
- expect(decodeScanCache(JSON.parse(write(cache, { sources })), TEST_FORMAT_MAP)).toEqual(cache);
271
+ expect(decodeScanCache(parse(write(cache, { sources })), TEST_FORMAT_MAP)).toEqual(cache);
272
273
cache.set("/b.jsonl", {
274
...cache.get("/b.jsonl")!,
@@ -277,7 +276,7 @@ describe("scan cache round trip", () => {
276
malformedRecords: 4,
277
records: [record({ sessionId: "session-c", model: "claude-opus-5-5", dedupeKey: "msg_3:" })],
278
});
280
- const document = JSON.parse(write(cache, { sources }));
279
+ const document = parse(write(cache, { sources }));
280
expect(decodeScanCache(document, TEST_FORMAT_MAP)).toEqual(cache);
281
expect(document.sources).toEqual(sources);
282
});
@@ -291,9 +290,7 @@ describe("scan cache round trip", () => {
290
});
291
292
it("skips malformed file entries but keeps good ones", () => {
294
- const encoded = JSON.parse(
295
- makeScanCacheWriter()(cacheWith([["/good.jsonl", 100, [record()]]]), {}),
296
- );
293
+ const encoded = parse(makeScanCacheWriter()(cacheWith([["/good.jsonl", 100, [record()]]]), {}));
294
const withJunk = {
295
...encoded,
296
files: { ...encoded.files, "/bad.jsonl": { s: "nope", m: 1, p: "claude", r: [] } },
@@ -304,7 +301,7 @@ describe("scan cache round trip", () => {
301
});
302
303
it("drops the whole entry when any row is corrupt, forcing a cold re-parse", () => {
307
- const encoded = JSON.parse(
304
+ const encoded = parse(
305
makeScanCacheWriter()(
306
cacheWith([["/a.jsonl", 100, [record(), record({ dedupeKey: "msg_2:" })]]]),
307
{},
apps/server/src/usage/usageScanCache.ts
+12
-16
@@ -15,7 +15,7 @@ const SPEED_COMPATIBLE_SINCE_VERSION = 4;
15
/**
16
* An older server sharing that directory cannot read a newer cache and would
17
* replace it, dropping saved usage for deleted transcripts. Separate files keep
18
- * both.
18
+ * the newer one; older files are removed once it is saved.
19
*/
20
export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v11.json";
21
export const LEGACY_SCAN_CACHE_FILE_NAMES = [
@@ -134,32 +134,28 @@ function serializeFile(entry: CachedFile, tables: InternTables): SerializedFile
134
};
135
}
136
137
-/** Memoizes immutable entries by identity; growing intern tables preserve indexes, retaining unused strings until restart. */
137
+/** Yields the document in pieces so large caches never become one string; growing intern tables preserve indexes, retaining unused strings until restart. */
138
export function makeScanCacheWriter(): (
139
cache: ScanCache,
140
extra: Readonly<Record<string, unknown>>,
141
-) => string {
141
+) => Iterable<string> {
142
const tables = makeInternTables();
143
- const fragments = new WeakMap<CachedFile, string>();
144
- return (cache, extra) => {
145
- const files: string[] = [];
146
- for (const [path, entry] of cache) {
147
- let fragment = fragments.get(entry);
148
- if (fragment === undefined) {
149
- fragment = JSON.stringify(serializeFile(entry, tables));
150
- fragments.set(entry, fragment);
151
- }
152
- files.push(`${JSON.stringify(path)}:${fragment}`);
143
+ function* encode(entries: readonly (readonly [string, CachedFile])[], extra: object) {
144
+ yield '{"files":{';
145
+ for (const [index, [path, entry]] of entries.entries()) {
146
+ yield `${index === 0 ? "" : ","}${JSON.stringify(path)}:${JSON.stringify(serializeFile(entry, tables))}`;
147
}
148
// Encoded after the files, which may have added to the intern tables.
155
- const head = JSON.stringify({
149
+ const tail = JSON.stringify({
150
...extra,
151
version: USAGE_SCAN_CACHE_VERSION,
152
models: tables.models,
153
sessions: tables.sessions,
154
});
161
- return `${head.slice(0, -1)},"files":{${files.join(",")}}}`;
162
- };
155
+ yield `},${tail.slice(1)}`;
156
+ }
157
+ // Snapshot now: the encoding runs later, while the file is written.
158
+ return (cache, extra) => encode([...cache], extra);
159
}
160
161
function isRecordArray(value: unknown): value is readonly unknown[] {
packages/shared/src/atomicWrite.test.ts
+16
@@ -44,6 +44,22 @@ it.layer(NodeServices.layer)("writeFileStringAtomically", (it) => {
44
}),
45
);
46
47
+ it.effect("streams iterable contents across write batches", () =>
48
+ Effect.gen(function* () {
49
+ const fs = yield* FileSystem.FileSystem;
50
+ const path = yield* Path.Path;
51
+ const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-atomic-write-" });
52
+ const filePath = path.join(root, "cache.json");
53
+ yield* fs.writeFileString(filePath, "a much longer previous document");
54
+ const chunks = ["é".repeat(700_000), "🙂".repeat(400_000), "end"];
55
+
56
+ yield* writeFileStringAtomically({ filePath, contents: chunks.values() });
57
+
58
+ assert.strictEqual(yield* fs.readFileString(filePath), chunks.join(""));
59
+ assert.deepStrictEqual(yield* fs.readDirectory(root), ["cache.json"]);
60
+ }),
61
+ );
62
+
63
it.effect("keeps a symlinked file linked and rewrites its destination", () =>
64
Effect.gen(function* () {
65
const fs = yield* FileSystem.FileSystem;
packages/shared/src/atomicWrite.ts
+26
-3
@@ -16,11 +16,12 @@ export const isWindowsRenameLock = (error: PlatformError.PlatformError) => {
16
// Bound denial delays to about two seconds because settings saves hold their write lock.
17
const LOCKED_RENAME_RETRIES = 20;
18
const LOCKED_RENAME_RETRY_DELAY = "100 millis";
19
+const CHUNK_WRITE_LENGTH = 1 << 20;
20
20
-/** Resolves symlink targets before renaming so writes preserve the link. */
21
+/** Resolves symlink targets before renaming so writes preserve the link. Iterable contents stream in bounded batches. */
22
export const writeFileStringAtomically = (input: {
23
readonly filePath: string;
23
- readonly contents: string;
24
+ readonly contents: string | Iterable<string>;
25
}) =>
26
Effect.scoped(
27
Effect.gen(function* () {
@@ -41,7 +42,29 @@ export const writeFileStringAtomically = (input: {
42
);
43
const tempPath = path.join(tempDirectory, "contents.tmp");
44
44
- yield* fs.writeFileString(tempPath, input.contents);
45
+ const contents = input.contents;
46
+ if (typeof contents === "string") {
47
+ yield* fs.writeFileString(tempPath, contents);
48
+ } else {
49
+ // Closed before the rename, which Windows refuses for open files.
50
+ yield* Effect.scoped(
51
+ Effect.gen(function* () {
52
+ const file = yield* fs.open(tempPath, { flag: "w" });
53
+ const encoder = new TextEncoder();
54
+ let batch: string[] = [];
55
+ let batchLength = 0;
56
+ for (const chunk of contents) {
57
+ batch.push(chunk);
58
+ batchLength += chunk.length;
59
+ if (batchLength < CHUNK_WRITE_LENGTH) continue;
60
+ yield* file.writeAll(encoder.encode(batch.join("")));
61
+ batch = [];
62
+ batchLength = 0;
63
+ }
64
+ if (batchLength > 0) yield* file.writeAll(encoder.encode(batch.join("")));
65
+ }),
66
+ );
67
+ }
68
if (platform !== "win32") return yield* fs.rename(tempPath, targetPath);
69
70
// Stop retrying if another save changes the target; read-only targets also return permanent EPERM.