Skip to content

Commit c9f0cac

Browse files
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) (pingdotgg#33942)
Co-authored-by: Julius Marminge <[email protected]>
1 parent fa8949a commit c9f0cac

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
@@ -10,6 +10,7 @@ import {
1010
ProviderDriverKind,
1111
ProviderInstanceId,
1212
ProjectId,
13+
retainedTerminalHistory,
1314
TerminalProviderInstanceNotFoundError,
1415
} from "@t3tools/contracts";
1516
import * as HostProcess from "@t3tools/shared/HostProcess";
@@ -2325,6 +2326,57 @@ it.layer(
23252326
}).pipe(Effect.scoped),
23262327
);
23272328

2329+
it.effect("sends bounded attach streams only the history the client retains", () =>
2330+
Effect.gen(function* () {
2331+
const { manager, ptyAdapter } = yield* createManager();
2332+
const maxHistoryBytes = 9;
2333+
yield* manager.open(openInput());
2334+
const process = ptyAdapter.processes[0]!;
2335+
const published = yield* Deferred.make<void>();
2336+
const unsubscribe = yield* manager.subscribe((event) =>
2337+
event.type === "output" && event.data === "yz\n"
2338+
? Deferred.succeed(published, undefined).pipe(Effect.asVoid)
2339+
: Effect.void,
2340+
);
2341+
process.emitData("aaaa\nx名😀");
2342+
process.emitData("yz\n");
2343+
yield* Deferred.await(published);
2344+
unsubscribe();
2345+
2346+
const full = yield* Stream.toPull(manager.attachOutputStream(openInput(), "full"));
2347+
const bounded = yield* Stream.toPull(
2348+
manager.attachOutputStream({ ...openInput(), maxHistoryBytes }, "bounded"),
2349+
);
2350+
const expectRetained = Effect.fnUntraced(function* () {
2351+
const [fullEvents, boundedEvents] = [yield* full, yield* bounded];
2352+
const fullSnapshot = fullEvents.at(-1);
2353+
if (fullSnapshot?.type !== "snapshot") throw new Error("Expected a full snapshot");
2354+
expect(boundedEvents.at(-1)).toEqual({
2355+
...fullSnapshot,
2356+
snapshot: {
2357+
...fullSnapshot.snapshot,
2358+
history: retainedTerminalHistory(fullSnapshot.snapshot.history, maxHistoryBytes),
2359+
},
2360+
});
2361+
return fullSnapshot.snapshot.history;
2362+
});
2363+
2364+
expect(yield* expectRetained()).toBe("aaaa\nx名😀yz\n");
2365+
// The cap starts inside 名, so the tail begins at the next code point.
2366+
expect(retainedTerminalHistory("aaaa\nx名😀yz\n", maxHistoryBytes)).toBe("😀yz\n");
2367+
process.emitData("after\n");
2368+
expect(yield* full).toEqual(yield* bounded);
2369+
2370+
yield* publishPastOutputBudget(manager, process);
2371+
expect(yield* expectRetained()).toMatch(/last\n$/);
2372+
2373+
process.emitExit({ exitCode: 0, signal: 0 });
2374+
expect(yield* full).toEqual(yield* bounded);
2375+
yield* manager.attachStream({ ...openInput(), restartIfNotRunning: true }, () => Effect.void);
2376+
yield* expectRetained();
2377+
}).pipe(Effect.scoped),
2378+
);
2379+
23282380
it.effect("does not replay in-flight output already included in an observer snapshot", () =>
23292381
Effect.gen(function* () {
23302382
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,
@@ -3240,20 +3241,41 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
32403241
registerCleanup,
32413242
);
32423243

3243-
const attachOutputStream: TerminalManager["Service"]["attachOutputStream"] = (input, viewerId) =>
3244-
Stream.unwrap(
3244+
const attachOutputStream: TerminalManager["Service"]["attachOutputStream"] = (
3245+
input,
3246+
viewerId,
3247+
) => {
3248+
const { maxHistoryBytes } = input;
3249+
const retained = (listener: (event: TerminalAttachStreamEvent) => Effect.Effect<void>) =>
3250+
maxHistoryBytes === undefined
3251+
? listener
3252+
: (event: TerminalAttachStreamEvent) =>
3253+
listener(
3254+
"snapshot" in event
3255+
? {
3256+
...event,
3257+
snapshot: {
3258+
...event.snapshot,
3259+
history: retainedTerminalHistory(event.snapshot.history, maxHistoryBytes),
3260+
},
3261+
}
3262+
: event,
3263+
);
3264+
return Stream.unwrap(
32453265
Effect.acquireRelease(
32463266
Effect.sync(() => retainViewerOnce(input, viewerId, null)),
32473267
(release) => Effect.sync(release),
32483268
).pipe(
32493269
Effect.as(
32503270
terminalOutputStream(
3251-
(listener, registerCleanup) => attachStream(input, listener, registerCleanup, viewerId),
3252-
(listener, registerCleanup) => resyncStream(input, listener, registerCleanup),
3271+
(listener, registerCleanup) =>
3272+
attachStream(input, retained(listener), registerCleanup, viewerId),
3273+
(listener, registerCleanup) => resyncStream(input, retained(listener), registerCleanup),
32533274
),
32543275
),
32553276
),
32563277
);
3278+
};
32573279

32583280
const metadataEventFromTerminalEvent = (
32593281
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
type FilesystemBrowseEntry,
56
ORCHESTRATION_V2_WS_METHODS,
@@ -552,6 +553,7 @@ describe("environment query lifecycle", () => {
552553
cwd: "/tmp/project",
553554
restartIfNotRunning: true,
554555
};
556+
const sent = { ...input, maxHistoryBytes: DEFAULT_MAX_TERMINAL_BUFFER_BYTES };
555557
const atoms = createTerminalEnvironmentAtoms(harness.runtime);
556558
const registry = AtomRegistry.make();
557559
const atom = atoms.attach({ environmentId: QUERY_ENVIRONMENT.environmentId, input });
@@ -571,9 +573,9 @@ describe("environment query lifecycle", () => {
571573
}),
572574
);
573575

574-
expect(yield* Queue.take(inputs)).toEqual(input);
576+
expect(yield* Queue.take(inputs)).toEqual(sent);
575577
yield* SubscriptionRef.set(harness.supervisorSession, Option.some({ ...firstSession }));
576-
expect(yield* Queue.take(inputs)).toEqual(input);
578+
expect(yield* Queue.take(inputs)).toEqual(sent);
577579
yield* Queue.offer(events, {
578580
type: "closed",
579581
threadId: input.threadId,
@@ -582,10 +584,10 @@ describe("environment query lifecycle", () => {
582584
yield* Deferred.await(received);
583585

584586
yield* SubscriptionRef.set(harness.supervisorSession, Option.some({ ...firstSession }));
585-
expect(yield* Queue.take(inputs)).toEqual({ ...input, resume: true });
587+
expect(yield* Queue.take(inputs)).toEqual({ ...sent, resume: true });
586588
// Catalog replacements rerun the same stream through followStream's switchMap.
587589
yield* SubscriptionRef.update(harness.streamGeneration, (generation) => generation + 1);
588-
expect(yield* Queue.take(inputs)).toEqual({ ...input, resume: true });
590+
expect(yield* Queue.take(inputs)).toEqual({ ...sent, resume: true });
589591

590592
unmount();
591593
registry.dispose();
@@ -597,7 +599,7 @@ describe("environment query lifecycle", () => {
597599
remountedRegistry.dispose();
598600
}),
599601
);
600-
expect(yield* Queue.take(inputs)).toEqual(input);
602+
expect(yield* Queue.take(inputs)).toEqual(sent);
601603
}),
602604
);
603605

‎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)