@devries-cameron20 / t3code-1 / commits / 8bfb723dc1
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

perf(server): stop serializing terminal chunks just to measure them (#24179)

Co-authored-by: Julius Marminge <julius0216@outlook.com>

Aaron Queen committed Nov 12, 2026 at 15:46 UTC 8bfb723dc173f94dc955c572cb2ff6adc8996a8c
2 files changed +115 -77
apps/server/src/terminal/OutputProtocol.test.ts
+82 -63
@@ -9,80 +9,99 @@ import * as Deferred from "effect/Deferred";
9 import * as Effect from "effect/Effect";
10 import * as Fiber from "effect/Fiber";
11 import * as Queue from "effect/Queue";
12 -import * as Schema from "effect/Schema";
12 import * as Stream from "effect/Stream";
13 import * as TestClock from "effect/testing/TestClock";
14 import { Rpc, RpcGroup, RpcMessage, RpcSerialization, RpcServer } from "effect/rpc";
15
16 import { terminalOutputStream, withOutputWindow } from "./OutputProtocol.ts";
17
18 +const eventWith = (
19 + field: "data" | "message" | "threadId",
20 + text: string,
21 +): TerminalAttachStreamEvent =>
22 + field === "message"
23 + ? { threadId: "thread-1", terminalId: "default", type: "error", message: text }
24 + : {
25 + threadId: field === "threadId" ? text : "thread-1",
26 + terminalId: "default",
27 + type: "output",
28 + data: field === "data" ? text : "x",
29 + };
30 +
31 describe("terminal output window", () => {
32 it.effect.each([
21 - { tag: WS_METHODS.terminalAttach, size: 1, limit: 8 },
22 - { tag: WS_METHODS.terminalObserve, size: 1, limit: 8 },
23 - { tag: WS_METHODS.terminalAttach, size: 64 * 1024, limit: 1 },
24 - { tag: WS_METHODS.terminalObserve, size: 64 * 1024, limit: 1 },
25 - { tag: WS_METHODS.subscribeServerConfig, size: 1, limit: 8 },
26 - { tag: ORCHESTRATION_V2_WS_METHODS.subscribeShell, size: 1, limit: 8 },
27 - { tag: ORCHESTRATION_V2_WS_METHODS.subscribeThread, size: 64 * 1024, limit: 8 },
28 - { tag: WS_METHODS.subscribeTerminalMetadata, size: 1, limit: 1 },
29 - ])("limits $tag with $size-byte values to $limit pending chunks", ({ tag, size, limit }) =>
30 - Effect.gen(function* () {
31 - const group = RpcGroup.make(Rpc.make(tag, { success: Schema.String, stream: true }));
32 - const output = yield* Queue.unbounded<string>();
33 - const responses = yield* Queue.unbounded<RpcMessage.FromServerEncoded>();
34 - const receive = yield* Deferred.make<Parameters<RpcServer.Protocol["Service"]["run"]>[0]>();
35 - const protocol = yield* RpcServer.Protocol.make((write) =>
36 - Effect.gen(function* () {
37 - yield* Deferred.succeed(receive, write);
38 - const serialization = yield* RpcSerialization.RpcSerialization;
39 - return {
40 - disconnects: yield* Queue.unbounded<number>(),
41 - send: (_clientId, response) => Queue.offer(responses, response),
42 - end: () => Effect.void,
43 - clientIds: Effect.succeed(new Set([0])),
44 - initialMessage: Effect.succeedNone,
45 - supportsAck: true,
46 - supportsTransferables: false,
47 - supportsSpanPropagation: false,
48 - supportsNotifications: true,
49 - codecFor: serialization.codecFor,
50 - };
51 - }),
52 - );
53 - yield* RpcServer.make(group).pipe(
54 - Effect.provide(group.toLayerHandler(tag, () => Stream.fromQueue(output))),
55 - Effect.provideService(RpcServer.Protocol, withOutputWindow(protocol)),
56 - Effect.forkScoped,
57 - );
58 - const write = yield* Deferred.await(receive);
59 - yield* write(0, { _tag: "Request", id: "1", tag, payload: null, headers: [] });
33 + { tag: WS_METHODS.terminalAttach, field: "data", size: 1, limit: 8 },
34 + { tag: WS_METHODS.terminalObserve, field: "data", size: 1, limit: 8 },
35 + { tag: WS_METHODS.terminalAttach, field: "data", size: 64 * 1024, limit: 1 },
36 + { tag: WS_METHODS.terminalObserve, field: "data", size: 64 * 1024, limit: 1 },
37 + { tag: WS_METHODS.terminalAttach, field: "message", size: 64 * 1024, limit: 1 },
38 + { tag: WS_METHODS.terminalAttach, field: "threadId", size: 64 * 1024, limit: 1 },
39 + { tag: WS_METHODS.subscribeServerConfig, field: "data", size: 1, limit: 8 },
40 + { tag: ORCHESTRATION_V2_WS_METHODS.subscribeShell, field: "data", size: 1, limit: 8 },
41 + { tag: ORCHESTRATION_V2_WS_METHODS.subscribeThread, field: "data", size: 64 * 1024, limit: 8 },
42 + { tag: WS_METHODS.subscribeTerminalMetadata, field: "data", size: 1, limit: 1 },
43 + ] as const)(
44 + "limits $tag with $size-byte $field values to $limit pending chunks",
45 + ({ tag, field, size, limit }) =>
46 + Effect.gen(function* () {
47 + const group = RpcGroup.make(
48 + Rpc.make(tag, { success: TerminalAttachStreamEventSchema, stream: true }),
49 + );
50 + const output = yield* Queue.unbounded<TerminalAttachStreamEvent>();
51 + const responses = yield* Queue.unbounded<RpcMessage.FromServerEncoded>();
52 + const receive = yield* Deferred.make<Parameters<RpcServer.Protocol["Service"]["run"]>[0]>();
53 + const protocol = yield* RpcServer.Protocol.make((write) =>
54 + Effect.gen(function* () {
55 + yield* Deferred.succeed(receive, write);
56 + const serialization = yield* RpcSerialization.RpcSerialization;
57 + return {
58 + disconnects: yield* Queue.unbounded<number>(),
59 + send: (_clientId, response) => Queue.offer(responses, response),
60 + end: () => Effect.void,
61 + clientIds: Effect.succeed(new Set([0])),
62 + initialMessage: Effect.succeedNone,
63 + supportsAck: true,
64 + supportsTransferables: false,
65 + supportsSpanPropagation: false,
66 + supportsNotifications: true,
67 + codecFor: serialization.codecFor,
68 + };
69 + }),
70 + );
71 + yield* RpcServer.make(group).pipe(
72 + Effect.provide(group.toLayerHandler(tag, () => Stream.fromQueue(output))),
73 + Effect.provideService(RpcServer.Protocol, withOutputWindow(protocol)),
74 + Effect.forkScoped,
75 + );
76 + const write = yield* Deferred.await(receive);
77 + yield* write(0, { _tag: "Request", id: "1", tag, payload: null, headers: [] });
78
61 - for (let index = 0; index < limit; index++) {
62 - const value = String(index).repeat(size);
63 - yield* Queue.offer(output, value);
79 + for (let index = 0; index < limit; index++) {
80 + const value = eventWith(field, String(index).repeat(size));
81 + yield* Queue.offer(output, value);
82 + yield* TestClock.adjust(0);
83 + assert.equal(yield* Queue.size(responses), 1);
84 + assert.deepEqual(yield* Queue.take(responses), {
85 + _tag: "Chunk",
86 + requestId: "1",
87 + values: [value],
88 + });
89 + }
90 + const resumedValue = eventWith(field, "i".repeat(size));
91 + yield* Queue.offer(output, resumedValue);
92 yield* TestClock.adjust(0);
65 - assert.equal(yield* Queue.size(responses), 1);
66 - assert.deepEqual(yield* Queue.take(responses), {
67 - _tag: "Chunk",
68 - requestId: "1",
69 - values: [value],
70 - });
71 - }
72 - yield* Queue.offer(output, "i".repeat(size));
73 - yield* TestClock.adjust(0);
74 - assert.equal(yield* Queue.size(responses), 0);
75 - yield* write(0, { _tag: "Ack", requestId: "1" });
76 - const resumed = yield* Queue.take(responses);
77 - assert.equal(resumed._tag, "Chunk");
78 - if (resumed._tag === "Chunk") assert.deepEqual(resumed.values, ["i".repeat(size)]);
93 + assert.equal(yield* Queue.size(responses), 0);
94 + yield* write(0, { _tag: "Ack", requestId: "1" });
95 + const resumed = yield* Queue.take(responses);
96 + assert.equal(resumed._tag, "Chunk");
97 + if (resumed._tag === "Chunk") assert.deepEqual(resumed.values, [resumedValue]);
98
80 - yield* Queue.offer(output, "j");
81 - yield* TestClock.adjust(0);
82 - assert.equal(yield* Queue.size(responses), 0);
83 - yield* write(0, { _tag: "Interrupt", requestId: "1" });
84 - assert.equal((yield* Queue.take(responses))._tag, "Exit");
85 - }).pipe(Effect.provide(RpcSerialization.layerJson), Effect.scoped),
99 + yield* Queue.offer(output, eventWith(field, "j"));
100 + yield* TestClock.adjust(0);
101 + assert.equal(yield* Queue.size(responses), 0);
102 + yield* write(0, { _tag: "Interrupt", requestId: "1" });
103 + assert.equal((yield* Queue.take(responses))._tag, "Exit");
104 + }).pipe(Effect.provide(RpcSerialization.layerJson), Effect.scoped),
105 );
106 });
107
apps/server/src/terminal/OutputProtocol.ts
+33 -14
@@ -13,6 +13,8 @@ import type { RpcServer } from "effect/rpc";
13
14 const MAX_PENDING_CHUNKS = 8;
15 const MAX_PENDING_BYTES = 64 * 1024;
16 +// Charge an envelope so tiny events cannot bypass the byte budget.
17 +const EVENT_OVERHEAD = 128;
18 const isFull = (sizes: number[]) =>
19 sizes.length >= MAX_PENDING_CHUNKS ||
20 sizes.reduce((total, size) => total + size, 0) >= MAX_PENDING_BYTES;
@@ -29,6 +31,36 @@ const COUNT_WINDOWED_STREAMS: ReadonlySet<string> = new Set([
31 ORCHESTRATION_V2_WS_METHODS.subscribeThread,
32 ]);
33
34 +const byteLengthOf = (value: unknown) => (typeof value === "string" ? Buffer.byteLength(value) : 0);
35 +
36 +// Charges every variable-size field a terminal event can carry, so the byte
37 +// budgets below cannot be bypassed by a large payload in an uncharged field.
38 +const queuedSize = (event: TerminalEvent | TerminalAttachStreamEvent) =>
39 + EVENT_OVERHEAD +
40 + ("threadId" in event ? byteLengthOf(event.threadId) + byteLengthOf(event.terminalId) : 0) +
41 + (event.type === "output"
42 + ? byteLengthOf(event.data)
43 + : event.type === "error"
44 + ? byteLengthOf(event.message)
45 + : event.type === "activity"
46 + ? byteLengthOf(event.label)
47 + : "snapshot" in event
48 + ? byteLengthOf(event.snapshot.threadId) +
49 + byteLengthOf(event.snapshot.terminalId) +
50 + byteLengthOf(event.snapshot.history) +
51 + byteLengthOf(event.snapshot.cwd) +
52 + byteLengthOf(event.snapshot.worktreePath) +
53 + byteLengthOf(event.snapshot.label)
54 + : 0);
55 +
56 +// Byte-windowed streams carry TerminalAttachStreamEvent, whose encoded form is the
57 +// event itself, so charge it like the output queue does instead of serializing twice.
58 +const chunkSize = (values: ReadonlyArray<unknown>) =>
59 + values.reduce<number>(
60 + (total, value) => total + queuedSize(value as TerminalAttachStreamEvent),
61 + EVENT_OVERHEAD,
62 + );
63 +
64 interface Window {
65 readonly bytes: boolean;
66 readonly sizes: number[];
@@ -86,10 +118,7 @@ export function withOutputWindow(
118 } else if (response._tag === "Chunk") {
119 const window = windowFor(clientId, String(response.requestId));
120 if (window) {
89 - window.sizes.push(
90 - // @effect-diagnostics-next-line globalJsonInEffect:off
91 - window.bytes ? Buffer.byteLength(JSON.stringify(response)) : 0,
92 - );
121 + window.sizes.push(window.bytes ? chunkSize(response.values) : 0);
122 if (!isFull(window.sizes)) {
123 return send.pipe(
124 Effect.andThen(() =>
@@ -108,8 +137,6 @@ export function withOutputWindow(
137 }
138
139 const MAX_QUEUED_OUTPUT = 8 * 1024 * 1024;
111 -// Charge an envelope so tiny events cannot bypass the byte budget.
112 -const EVENT_OVERHEAD = 128;
140
141 type Listener<A> = (event: A) => Effect.Effect<void>;
142 // Acquisition must register cleanup synchronously with installing the listener.
@@ -118,14 +145,6 @@ type Subscribe<A, E> = (
145 registerCleanup: (stop: () => void) => void,
146 ) => Effect.Effect<() => void, E>;
147
121 -const queuedSize = (event: TerminalEvent | TerminalAttachStreamEvent) =>
122 - EVENT_OVERHEAD +
123 - (event.type === "output"
124 - ? Buffer.byteLength(event.data)
125 - : "snapshot" in event
126 - ? Buffer.byteLength(event.snapshot.history)
127 - : 0);
128 -
148 export function terminalOutputStream<A extends TerminalEvent | TerminalAttachStreamEvent, E>(
149 subscribe: Subscribe<A, E>,
150 resync?: Subscribe<A, E>,