Skip to content

Commit 6c0f577

Browse files
Yuruzuuclaude
andcommitted
perf(server,client): attaching to a terminal with a large history over a slow link drops from 5,555 ms to 751 ms median (7.4x)
Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 20c3dd3 commit 6c0f577

7 files changed

Lines changed: 137 additions & 34 deletions

File tree

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

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import {
99
ProviderDriverKind,
1010
ProviderInstanceId,
1111
ProjectId,
12+
retainedTerminalHistory,
1213
TerminalProviderInstanceNotFoundError,
1314
} from "@t3tools/contracts";
1415
import * as HostProcess from "@t3tools/shared/HostProcess";
@@ -2262,6 +2263,57 @@ it.layer(
22622263
}).pipe(Effect.scoped),
22632264
);
22642265

2266+
it.effect("sends bounded attach streams only the history the client retains", () =>
2267+
Effect.gen(function* () {
2268+
const { manager, ptyAdapter } = yield* createManager();
2269+
const maxHistoryBytes = 9;
2270+
yield* manager.open(openInput());
2271+
const process = ptyAdapter.processes[0]!;
2272+
const published = yield* Deferred.make<void>();
2273+
const unsubscribe = yield* manager.subscribe((event) =>
2274+
event.type === "output" && event.data === "yz\n"
2275+
? Deferred.succeed(published, undefined).pipe(Effect.asVoid)
2276+
: Effect.void,
2277+
);
2278+
process.emitData("aaaa\nx名😀");
2279+
process.emitData("yz\n");
2280+
yield* Deferred.await(published);
2281+
unsubscribe();
2282+
2283+
const full = yield* Stream.toPull(manager.attachOutputStream(openInput(), "full"));
2284+
const bounded = yield* Stream.toPull(
2285+
manager.attachOutputStream({ ...openInput(), maxHistoryBytes }, "bounded"),
2286+
);
2287+
const expectRetained = Effect.fnUntraced(function* () {
2288+
const [fullEvents, boundedEvents] = [yield* full, yield* bounded];
2289+
const fullSnapshot = fullEvents.at(-1);
2290+
if (fullSnapshot?.type !== "snapshot") throw new Error("Expected a full snapshot");
2291+
expect(boundedEvents.at(-1)).toEqual({
2292+
...fullSnapshot,
2293+
snapshot: {
2294+
...fullSnapshot.snapshot,
2295+
history: retainedTerminalHistory(fullSnapshot.snapshot.history, maxHistoryBytes),
2296+
},
2297+
});
2298+
return fullSnapshot.snapshot.history;
2299+
});
2300+
2301+
expect(yield* expectRetained()).toBe("aaaa\nx名😀yz\n");
2302+
// The cap starts inside 名, so the tail begins at the next code point.
2303+
expect(retainedTerminalHistory("aaaa\nx名😀yz\n", maxHistoryBytes)).toBe("😀yz\n");
2304+
process.emitData("after\n");
2305+
expect(yield* full).toEqual(yield* bounded);
2306+
2307+
yield* publishPastOutputBudget(manager, process);
2308+
expect(yield* expectRetained()).toMatch(/last\n$/);
2309+
2310+
process.emitExit({ exitCode: 0, signal: 0 });
2311+
expect(yield* full).toEqual(yield* bounded);
2312+
yield* manager.attachStream({ ...openInput(), restartIfNotRunning: true }, () => Effect.void);
2313+
yield* expectRetained();
2314+
}).pipe(Effect.scoped),
2315+
);
2316+
22652317
it.effect("does not replay in-flight output already included in an observer snapshot", () =>
22662318
Effect.gen(function* () {
22672319
const { manager, ptyAdapter } = yield* createManager();

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

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { withWorkspaceLease } from "../workspace/workspaceLease.ts";
55
import {
66
DEFAULT_TERMINAL_ID,
77
DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
8+
retainedTerminalHistory,
89
TerminalCwdError,
910
TerminalCwdNotDirectoryError,
1011
TerminalCwdNotFoundError,
@@ -3224,20 +3225,41 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
32243225
registerCleanup,
32253226
);
32263227

3227-
const attachOutputStream: TerminalManager["Service"]["attachOutputStream"] = (input, viewerId) =>
3228-
Stream.unwrap(
3228+
const attachOutputStream: TerminalManager["Service"]["attachOutputStream"] = (
3229+
input,
3230+
viewerId,
3231+
) => {
3232+
const { maxHistoryBytes } = input;
3233+
const retained = (listener: (event: TerminalAttachStreamEvent) => Effect.Effect<void>) =>
3234+
maxHistoryBytes === undefined
3235+
? listener
3236+
: (event: TerminalAttachStreamEvent) =>
3237+
listener(
3238+
"snapshot" in event
3239+
? {
3240+
...event,
3241+
snapshot: {
3242+
...event.snapshot,
3243+
history: retainedTerminalHistory(event.snapshot.history, maxHistoryBytes),
3244+
},
3245+
}
3246+
: event,
3247+
);
3248+
return Stream.unwrap(
32293249
Effect.acquireRelease(
32303250
Effect.sync(() => retainViewerOnce(input, viewerId, null)),
32313251
(release) => Effect.sync(release),
32323252
).pipe(
32333253
Effect.as(
32343254
terminalOutputStream(
3235-
(listener, registerCleanup) => attachStream(input, listener, registerCleanup, viewerId),
3236-
(listener, registerCleanup) => resyncStream(input, listener, registerCleanup),
3255+
(listener, registerCleanup) =>
3256+
attachStream(input, retained(listener), registerCleanup, viewerId),
3257+
(listener, registerCleanup) => resyncStream(input, retained(listener), registerCleanup),
32373258
),
32383259
),
32393260
),
32403261
);
3262+
};
32413263

32423264
const metadataEventFromTerminalEvent = (
32433265
event: TerminalEvent,

‎packages/client-runtime/src/state/runtime.test.ts‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { describe, expect, it } from "@effect/vitest";
22
import {
3+
DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
34
EnvironmentId,
45
ORCHESTRATION_V2_WS_METHODS,
56
ThreadId,
@@ -493,6 +494,7 @@ describe("environment query lifecycle", () => {
493494
cwd: "/tmp/project",
494495
restartIfNotRunning: true,
495496
};
497+
const sent = { ...input, maxHistoryBytes: DEFAULT_MAX_TERMINAL_BUFFER_BYTES };
496498
const atoms = createTerminalEnvironmentAtoms(harness.runtime);
497499
const registry = AtomRegistry.make();
498500
const atom = atoms.attach({ environmentId: QUERY_ENVIRONMENT.environmentId, input });
@@ -512,9 +514,9 @@ describe("environment query lifecycle", () => {
512514
}),
513515
);
514516

515-
expect(yield* Queue.take(inputs)).toEqual(input);
517+
expect(yield* Queue.take(inputs)).toEqual(sent);
516518
yield* SubscriptionRef.set(harness.supervisorSession, Option.some({ ...firstSession }));
517-
expect(yield* Queue.take(inputs)).toEqual(input);
519+
expect(yield* Queue.take(inputs)).toEqual(sent);
518520
yield* Queue.offer(events, {
519521
type: "closed",
520522
threadId: input.threadId,
@@ -523,10 +525,10 @@ describe("environment query lifecycle", () => {
523525
yield* Deferred.await(received);
524526

525527
yield* SubscriptionRef.set(harness.supervisorSession, Option.some({ ...firstSession }));
526-
expect(yield* Queue.take(inputs)).toEqual({ ...input, resume: true });
528+
expect(yield* Queue.take(inputs)).toEqual({ ...sent, resume: true });
527529
// Catalog replacements rerun the same stream through followStream's switchMap.
528530
yield* SubscriptionRef.update(harness.streamGeneration, (generation) => generation + 1);
529-
expect(yield* Queue.take(inputs)).toEqual({ ...input, resume: true });
531+
expect(yield* Queue.take(inputs)).toEqual({ ...sent, resume: true });
530532

531533
unmount();
532534
registry.dispose();
@@ -538,7 +540,7 @@ describe("environment query lifecycle", () => {
538540
remountedRegistry.dispose();
539541
}),
540542
);
541-
expect(yield* Queue.take(inputs)).toEqual(input);
543+
expect(yield* Queue.take(inputs)).toEqual(sent);
542544
}),
543545
);
544546

‎packages/client-runtime/src/state/terminal.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import {
2+
DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
23
type EnvironmentId,
34
type TerminalAttachInput,
45
type TerminalCloseInput,
@@ -67,7 +68,11 @@ export function createTerminalEnvironmentAtoms<R, E>(
6768
// Retry an unanswered first attach unchanged so it can still open the shell.
6869
let replied = false;
6970
return subscribeDynamic(WS_METHODS.terminalAttach, () =>
70-
Effect.sync(() => (replied ? { ...input, resume: true } : input)),
71+
Effect.sync(() => ({
72+
...input,
73+
...(replied ? { resume: true } : {}),
74+
maxHistoryBytes: DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
75+
})),
7176
).pipe(
7277
Stream.onFirst(() =>
7378
Effect.sync(() => {

‎packages/client-runtime/src/state/terminalOutput.ts‎

Lines changed: 3 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
import { retainedTerminalHistory } from "@t3tools/contracts";
2+
13
export interface TerminalOutputChunk {
24
readonly startOffset: number;
35
readonly data: string;
@@ -90,28 +92,6 @@ function splitStringByUtf8Bytes(data: string, maxBytes: number): ReadonlyArray<U
9092
return chunks;
9193
}
9294

93-
function trimBufferToBytes(buffer: string, maxBufferBytes: number): string {
94-
if (maxBufferBytes <= 0) {
95-
return "";
96-
}
97-
98-
const encoded = textEncoder.encode(buffer);
99-
if (encoded.byteLength <= maxBufferBytes) {
100-
return buffer;
101-
}
102-
103-
let start = encoded.byteLength - maxBufferBytes;
104-
while (start < encoded.length) {
105-
const byte = encoded[start];
106-
if (byte === undefined || (byte & 0b1100_0000) !== 0b1000_0000) {
107-
break;
108-
}
109-
start += 1;
110-
}
111-
112-
return textDecoder.decode(encoded.subarray(start));
113-
}
114-
11595
function splitOutputChunks(
11696
data: string,
11797
firstOffset: number,
@@ -249,7 +229,7 @@ function resetOutput(
249229
data: string,
250230
maxBufferBytes: number,
251231
): TerminalOutputState {
252-
const retained = trimBufferToBytes(data, maxBufferBytes);
232+
const retained = retainedTerminalHistory(data, maxBufferBytes);
253233
const reset = splitOutputChunks(
254234
retained,
255235
0,

‎packages/client-runtime/src/state/terminalSession.test.ts‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
import { describe, expect, it } from "vite-plus/test";
22

3-
import { EnvironmentId, TerminalSessionSnapshot, ThreadId } from "@t3tools/contracts";
3+
import {
4+
EnvironmentId,
5+
retainedTerminalHistory,
6+
TerminalSessionSnapshot,
7+
ThreadId,
8+
} from "@t3tools/contracts";
49

510
import {
611
applyTerminalAttachStreamEvent,
@@ -119,6 +124,14 @@ describe("terminal session reducers", () => {
119124

120125
expect(terminalOutputText(state.output)).toBe("\uFEFFtail");
121126
expect(state.output.retainedBytes).toBe(7);
127+
const serverTail = retainedTerminalHistory("discardtail", 7);
128+
expect(
129+
applyTerminalAttachStreamEvent(
130+
EMPTY_TERMINAL_BUFFER_STATE,
131+
{ type: "snapshot", snapshot: { ...BASE_SNAPSHOT, history: serverTail } },
132+
7,
133+
),
134+
).toEqual(state);
122135
});
123136

124137
it("trims whole Unicode code points from a partially retained chunk", () => {

‎packages/contracts/src/terminal.ts‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,33 @@ import { ProviderInstanceId } from "./providerInstance.ts";
55
export const DEFAULT_TERMINAL_ID = "term-1";
66
export const DEFAULT_MAX_TERMINAL_BUFFER_BYTES = 512 * 1024;
77

8+
const historyEncoder = new TextEncoder();
9+
// A BOM at a retained chunk boundary is terminal data, not an encoding marker.
10+
const historyDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
11+
12+
/** The final `maxBytes` of UTF-8 a client retains, starting at a code point boundary. */
13+
export function retainedTerminalHistory(history: string, maxBytes: number): string {
14+
if (maxBytes <= 0) {
15+
return "";
16+
}
17+
18+
const encoded = historyEncoder.encode(history);
19+
if (encoded.byteLength <= maxBytes) {
20+
return history;
21+
}
22+
23+
let start = encoded.byteLength - maxBytes;
24+
while (start < encoded.length) {
25+
const byte = encoded[start];
26+
if (byte === undefined || (byte & 0b1100_0000) !== 0b1000_0000) {
27+
break;
28+
}
29+
start += 1;
30+
}
31+
32+
return historyDecoder.decode(encoded.subarray(start));
33+
}
34+
835
const TrimmedNonEmptyStringSchema = TrimmedNonEmptyString;
936
const TerminalColsSchema = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)).check(
1037
Schema.isLessThanOrEqualTo(1000),
@@ -57,6 +84,8 @@ export const TerminalAttachInput = Schema.Struct({
5784
restartIfNotRunning: Schema.optional(Schema.Boolean),
5885
// Resubscriptions preserve stopped terminals; unknown IDs recover after a server restart.
5986
resume: Schema.optional(Schema.Boolean),
87+
// Snapshots carry only the history a client this bounded keeps; older servers ignore it.
88+
maxHistoryBytes: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
6089
});
6190
export type TerminalAttachInput = typeof TerminalAttachInput.Type;
6291

0 commit comments

Comments
 (0)