Skip to content

Commit 65716ba

Browse files
nateEcmaria-rcksjuliusmarminge
authored
fix(server): persist terminal output without rewriting all history (pingdotgg#24019)
Co-authored-by: maria-rcks <[email protected]> Co-authored-by: Julius Marminge <[email protected]>
1 parent 9a614e3 commit 65716ba

2 files changed

Lines changed: 226 additions & 12 deletions

File tree

‎apps/server/src/terminal/Manager.test.ts‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ import * as PlatformError from "effect/PlatformError";
2828
import * as Path from "effect/Path";
2929
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
3030
import * as Ref from "effect/Ref";
31+
import * as Queue from "effect/Queue";
3132
import * as Schema from "effect/Schema";
3233
import * as Scope from "effect/Scope";
3334
import * as Stream from "effect/Stream";
@@ -409,6 +410,41 @@ it("bounds long partial lines and joins surrogate pairs across chunk boundaries"
409410
}
410411
});
411412

413+
it("restores bounded history across append compaction, clears and split Unicode", () => {
414+
const maxBytes = 64;
415+
const history = new TerminalManager.BoundedTerminalHistory(3, "", maxBytes);
416+
let cursor: ReturnType<typeof history.persistenceUpdate>["cursor"] | undefined;
417+
let persisted = "";
418+
let compactions = 0;
419+
const flush = () => {
420+
const update = history.persistenceUpdate(cursor);
421+
if (!update.append) compactions += 1;
422+
const encoded = Buffer.from(update.data).toString();
423+
persisted = update.append ? persisted + encoded : encoded;
424+
cursor = update.cursor;
425+
expect(Buffer.byteLength(persisted)).toBeLessThanOrEqual(maxBytes * 2);
426+
expect(retainedHistory(persisted, 3, maxBytes)).toBe(Buffer.from(history.value()).toString());
427+
};
428+
for (let index = 0; index < 100; index += 1) {
429+
history.append(`line ${index} 名\n`);
430+
flush();
431+
}
432+
expect(compactions).toBeGreaterThan(1);
433+
expect(compactions).toBeLessThan(50);
434+
history.clear();
435+
flush();
436+
expect(persisted).toBe("");
437+
history.append("\ud83d");
438+
flush();
439+
history.append("\ude80");
440+
flush();
441+
expect(persisted).toBe("🚀");
442+
// More output than the retained window between flushes must replace the file.
443+
history.append("z".repeat(maxBytes * 3));
444+
flush();
445+
expect(persisted).toBe("z".repeat(maxBytes));
446+
});
447+
412448
it.layer(
413449
Layer.mergeAll(
414450
NodeServices.layer,
@@ -1045,6 +1081,119 @@ it.layer(
10451081
}),
10461082
);
10471083

1084+
it.effect("persists small terminal updates without rewriting the retained history", () =>
1085+
Effect.gen(function* () {
1086+
const fs = yield* FileSystem.FileSystem;
1087+
const writes = yield* Queue.unbounded<number>();
1088+
const maxBytes = 64 * 1024;
1089+
const { manager, ptyAdapter, logsDir } = yield* createManager(5_000, {
1090+
historyByteLimit: maxBytes,
1091+
}).pipe(
1092+
Effect.provideService(FileSystem.FileSystem, {
1093+
...fs,
1094+
writeFileString: (path, data, options) =>
1095+
fs
1096+
.writeFileString(path, data, options)
1097+
.pipe(
1098+
Effect.tap(() =>
1099+
data.length > 0 ? Queue.offer(writes, Buffer.byteLength(data)) : Effect.void,
1100+
),
1101+
),
1102+
}),
1103+
);
1104+
yield* manager.open(openInput());
1105+
const process = ptyAdapter.processes[0]!;
1106+
process.emitData("a".repeat(maxBytes));
1107+
let written = yield* Queue.take(writes);
1108+
for (let index = 0; index < 16; index += 1) {
1109+
process.emitData("b".repeat(1024));
1110+
written += yield* Queue.take(writes);
1111+
}
1112+
expect(written).toBeLessThan(maxBytes * 2);
1113+
const expected = "a".repeat(maxBytes - 16 * 1024) + "b".repeat(16 * 1024);
1114+
const persisted = yield* fs.readFileString(yield* historyLogPath(logsDir));
1115+
expect(Buffer.byteLength(persisted)).toBe(maxBytes + 16 * 1024);
1116+
for (const failure of [undefined, "write", "rename"] as const) {
1117+
let failed = false;
1118+
const fail = () => {
1119+
failed = true;
1120+
return Effect.fail(
1121+
PlatformError.systemError({
1122+
_tag: "Unknown",
1123+
module: "FileSystem",
1124+
method: failure === "write" ? "writeFileString" : "rename",
1125+
cause: { code: "ENOSPC" },
1126+
}),
1127+
);
1128+
};
1129+
const recovered = yield* createManager(5_000, { historyByteLimit: maxBytes }).pipe(
1130+
Effect.provideService(FileSystem.FileSystem, {
1131+
...fs,
1132+
writeFileString: (file, data, options) =>
1133+
failure === "write" && !failed && data === expected
1134+
? fs.writeFileString(file, "partial", options).pipe(Effect.andThen(fail))
1135+
: fs.writeFileString(file, data, options),
1136+
rename: (from, to) => (failure === "rename" && !failed ? fail() : fs.rename(from, to)),
1137+
}),
1138+
);
1139+
const recoveredPath = yield* historyLogPath(recovered.logsDir);
1140+
yield* fs.makeDirectory(recovered.logsDir, { recursive: true });
1141+
yield* fs.writeFileString(recoveredPath, persisted);
1142+
const snapshot = yield* recovered.manager.open(openInput());
1143+
expect(snapshot.status).toBe("running");
1144+
expect(snapshot.history).toBe(expected);
1145+
expect(failed).toBe(failure !== undefined);
1146+
expect(yield* fs.readFileString(recoveredPath)).toBe(
1147+
failure === undefined ? expected : persisted,
1148+
);
1149+
expect(yield* fs.readDirectory(recovered.logsDir)).toHaveLength(1);
1150+
}
1151+
yield* manager.close({ threadId: "thread-1" });
1152+
expect((yield* manager.open(openInput())).history).toBe(expected);
1153+
expect(yield* fs.readFileString(yield* historyLogPath(logsDir))).toBe(expected);
1154+
}),
1155+
);
1156+
1157+
it.effect("rewrites history after an append fails partway through", () =>
1158+
Effect.gen(function* () {
1159+
const fs = yield* FileSystem.FileSystem;
1160+
const writes = yield* Queue.unbounded<void>();
1161+
let failAppend = false;
1162+
const { manager, ptyAdapter, logsDir } = yield* createManager().pipe(
1163+
Effect.provideService(FileSystem.FileSystem, {
1164+
...fs,
1165+
writeFileString: (path, data, options) => {
1166+
if (options?.flag === "a" && failAppend) {
1167+
failAppend = false;
1168+
return fs.writeFileString(path, data.slice(0, 1), options).pipe(
1169+
// The file cannot also be a parent directory: fail after the partial append.
1170+
Effect.andThen(fs.writeFileString(`${path}/missing`, data)),
1171+
Effect.ensuring(Queue.offer(writes, undefined)),
1172+
);
1173+
}
1174+
return fs
1175+
.writeFileString(path, data, options)
1176+
.pipe(
1177+
Effect.tap(() => (data.length > 0 ? Queue.offer(writes, undefined) : Effect.void)),
1178+
);
1179+
},
1180+
}),
1181+
);
1182+
yield* manager.open(openInput());
1183+
const process = ptyAdapter.processes[0]!;
1184+
process.emitData("start:");
1185+
yield* Queue.take(writes);
1186+
failAppend = true;
1187+
process.emitData("middle");
1188+
yield* Queue.take(writes);
1189+
expect(failAppend).toBe(false);
1190+
process.emitData(":end");
1191+
yield* Queue.take(writes);
1192+
expect(yield* fs.readFileString(yield* historyLogPath(logsDir))).toBe("start:middle:end");
1193+
yield* manager.close({ threadId: "thread-1" });
1194+
}),
1195+
);
1196+
10481197
it.effect("releases delivered output while the process queue stays busy", () =>
10491198
Effect.gen(function* () {
10501199
// Observe retained payloads, since delivery and bounded history alone cannot detect a leak.

‎apps/server/src/terminal/Manager.ts‎

Lines changed: 77 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -878,6 +878,12 @@ interface TerminalHistoryChunk {
878878
lineBreaks: number;
879879
}
880880

881+
interface TerminalHistoryPersistenceCursor {
882+
readonly generation: number;
883+
readonly offset: number;
884+
readonly fileBytes: number;
885+
}
886+
881887
export class BoundedTerminalHistory {
882888
private readonly maxLines: number;
883889
private readonly maxBytes: number;
@@ -888,6 +894,8 @@ export class BoundedTerminalHistory {
888894
// Reading the old string's tail on each append can force chunk concatenation.
889895
private lastCodeUnit: number | undefined;
890896
private cachedValue: string | null = "";
897+
private generation = 0;
898+
private appendedLength = 0;
891899

892900
constructor(maxLines: number, initial: string, maxBytes = DEFAULT_HISTORY_BYTE_LIMIT) {
893901
this.maxLines = maxLines;
@@ -897,6 +905,7 @@ export class BoundedTerminalHistory {
897905

898906
append(text: string): void {
899907
if (text.length === 0) return;
908+
this.appendedLength += text.length;
900909
this.cachedValue = null;
901910
if (this.maxBytes <= 0 || this.maxLines <= 0) {
902911
this.clear();
@@ -917,6 +926,8 @@ export class BoundedTerminalHistory {
917926
firstCode <= 0xdfff
918927
) {
919928
// Joining a split surrogate changes its UTF-8 size from 3 to 4 bytes.
929+
// The previous flush may have encoded the lone surrogate as a replacement character.
930+
this.generation += 1;
920931
previous.data += text[0];
921932
previous.byteLength += 1;
922933
this.byteLength += 1;
@@ -1035,6 +1046,8 @@ export class BoundedTerminalHistory {
10351046
}
10361047

10371048
clear(): void {
1049+
this.generation += 1;
1050+
this.appendedLength = 0;
10381051
this.chunks = [];
10391052
this.start = 0;
10401053
this.byteLength = 0;
@@ -1043,6 +1056,38 @@ export class BoundedTerminalHistory {
10431056
this.cachedValue = "";
10441057
}
10451058

1059+
persistenceUpdate(previous?: TerminalHistoryPersistenceCursor) {
1060+
const offset = this.appendedLength;
1061+
let data: string | undefined;
1062+
if (previous?.generation === this.generation) {
1063+
let remaining = offset - previous.offset;
1064+
const tail: string[] = [];
1065+
for (let index = this.chunks.length - 1; remaining > 0 && index >= this.start; index -= 1) {
1066+
const chunk = this.chunks[index]!.data;
1067+
const suffix = chunk.slice(Math.max(0, chunk.length - remaining));
1068+
tail.push(suffix);
1069+
remaining -= suffix.length;
1070+
}
1071+
if (remaining === 0) data = tail.toReversed().join("");
1072+
}
1073+
// Keep the on-disk log bounded while amortizing compaction across new output.
1074+
// Readers already cap the plain-text tail by bytes and lines.
1075+
const append =
1076+
data !== undefined &&
1077+
previous !== undefined &&
1078+
previous.fileBytes + Buffer.byteLength(data) <= this.maxBytes * 2;
1079+
const output = append && data !== undefined ? data : this.value();
1080+
return {
1081+
data: output,
1082+
append,
1083+
cursor: {
1084+
generation: this.generation,
1085+
offset,
1086+
fileBytes: (append ? previous.fileBytes : 0) + Buffer.byteLength(output),
1087+
},
1088+
};
1089+
}
1090+
10461091
value(): string {
10471092
if (this.cachedValue !== null) return this.cachedValue;
10481093
this.cachedValue = this.chunks
@@ -1939,6 +1984,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
19391984
yield* registerKillFiber(process, fiber);
19401985
});
19411986

1987+
const persistedHistory = new WeakMap<BoundedTerminalHistory, TerminalHistoryPersistenceCursor>();
19421988
const persistWorker = yield* makeKeyedCoalescingWorker<
19431989
string,
19441990
PersistHistoryRequest,
@@ -1959,9 +2005,19 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
19592005
return;
19602006
}
19612007

2008+
const update = request.history.persistenceUpdate(
2009+
request.immediate ? undefined : persistedHistory.get(request.history),
2010+
);
2011+
if (update.append && update.data.length === 0) return;
2012+
// An append may partially succeed before failing. Retry from a full snapshot,
2013+
// never from an uncertain file offset.
2014+
persistedHistory.delete(request.history);
19622015
yield* fileSystem
1963-
.writeFileString(historyPath(threadId, terminalId), request.history.value())
2016+
.writeFileString(historyPath(threadId, terminalId), update.data, {
2017+
flag: update.append ? "a" : "w",
2018+
})
19642019
.pipe(
2020+
Effect.tap(() => Effect.sync(() => persistedHistory.set(request.history, update.cursor))),
19652021
Effect.catch((error) =>
19662022
Effect.logWarning("failed to persist terminal history", {
19672023
threadId,
@@ -2052,17 +2108,15 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
20522108
const history = new BoundedTerminalHistory(historyLineLimit, raw, historyByteLimit);
20532109
const capped = history.value();
20542110
if (migrating || truncated || capped !== raw) {
2055-
const write = migrating
2056-
? Effect.gen(function* () {
2057-
const temporaryPath = yield* fileSystem.makeTempFileScoped({
2058-
directory: logsDir,
2059-
prefix: ".history-",
2060-
});
2061-
yield* fileSystem.writeFileString(temporaryPath, capped);
2062-
yield* fileSystem.rename(temporaryPath, nextPath);
2063-
}).pipe(Effect.scoped)
2064-
: fileSystem.writeFileString(nextPath, capped);
2065-
yield* write.pipe(
2111+
const write = Effect.gen(function* () {
2112+
const temporaryPath = yield* fileSystem.makeTempFileScoped({
2113+
directory: logsDir,
2114+
prefix: ".history-",
2115+
});
2116+
yield* fileSystem.writeFileString(temporaryPath, capped);
2117+
yield* fileSystem.rename(temporaryPath, nextPath);
2118+
}).pipe(
2119+
Effect.scoped,
20662120
Effect.mapError(
20672121
(cause) =>
20682122
new TerminalHistoryError({
@@ -2073,6 +2127,17 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
20732127
}),
20742128
),
20752129
);
2130+
yield* migrating
2131+
? write
2132+
: write.pipe(
2133+
Effect.catch((error) =>
2134+
Effect.logWarning("failed to compact terminal history", {
2135+
threadId,
2136+
terminalId,
2137+
error,
2138+
}),
2139+
),
2140+
);
20762141
}
20772142
if (migrating) {
20782143
yield* fileSystem.remove(sourcePath, { force: true }).pipe(

0 commit comments

Comments
 (0)