Skip to content

Commit 9482773

Browse files
fix(server): coalesce queued shell updates for slow clients (#14859)
Co-authored-by: maria-rcks <[email protected]> Co-authored-by: Julius Marminge <[email protected]>
1 parent 1ba3c78 commit 9482773

5 files changed

Lines changed: 362 additions & 3 deletions

File tree

‎apps/server/src/orchestration-v2/LiveStreamBudget.test.ts‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import { describe, expect } from "vite-plus/test";
99

1010
import {
1111
bufferLiveStream,
12+
bufferLatestLiveStream,
1213
makeLiveStreamBudget,
1314
replayAndBufferLiveEvents,
1415
type RetainedLiveItem,
@@ -75,6 +76,39 @@ it.effect("stops draining a slow subscriber when its unacknowledged tail fills",
7576

7677
type Event = { readonly sequence: number; readonly text: string; readonly threadId?: string };
7778

79+
describe("bufferLatestLiveStream", () => {
80+
it.effect.each(["items", "bytes"] as const)(
81+
"counts an unacknowledged state against the %s limit when its replacement arrives",
82+
(limit) =>
83+
Effect.scoped(
84+
Effect.gen(function* () {
85+
const releaseUpdate = yield* Deferred.make<void>();
86+
const closed = yield* Deferred.make<void>();
87+
const first = { sequence: 1, text: "é".repeat(20) };
88+
const next = { ...first, sequence: 2 };
89+
const pull = yield* Stream.toPull(
90+
bufferLatestLiveStream(
91+
Stream.concat(
92+
Stream.succeed(first),
93+
Stream.fromEffect(Deferred.await(releaseUpdate)).pipe(Stream.map(() => next)),
94+
).pipe(Stream.ensuring(Deferred.succeed(closed, undefined))),
95+
() => "same-thread",
96+
limit === "items"
97+
? { maxItems: 1 }
98+
: { maxSerializedBytes: Buffer.byteLength(JSON.stringify(first)) },
99+
),
100+
);
101+
expect(yield* pull).toEqual([first]);
102+
yield* Deferred.succeed(releaseUpdate, undefined);
103+
yield* Deferred.await(closed);
104+
const result = yield* pull.pipe(Effect.result);
105+
expect(result._tag).toBe("Failure");
106+
if (result._tag === "Failure") expect(result.failure._tag).toBe("LiveStreamBufferError");
107+
}),
108+
),
109+
);
110+
});
111+
78112
describe("replayAndBufferLiveEvents", () => {
79113
it.effect.each(["high-water", "replay"] as const)(
80114
"unsubscribes and cancels a blocked %s read on live overflow",

‎apps/server/src/orchestration-v2/LiveStreamBudget.ts‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import * as Exit from "effect/Exit";
77
import * as Queue from "effect/Queue";
88
import * as PubSub from "effect/PubSub";
99
import * as Scope from "effect/Scope";
10+
import * as Semaphore from "effect/Semaphore";
1011
import * as Stream from "effect/Stream";
1112

1213
export class LiveStreamBufferError extends Schema.TaggedError<LiveStreamBufferError>()(
@@ -254,6 +255,83 @@ export const bufferLiveStream = <A extends object, E, R>(
254255
}),
255256
);
256257

258+
/** Coalesce queued full states; delivered states stay charged until the next pull ACKs them. */
259+
export const bufferLatestLiveStream = <A extends { readonly sequence: number }, E, R>(
260+
source: Stream.Stream<A, E, R>,
261+
key: (value: A) => string,
262+
limits?: LiveStreamLimits,
263+
) =>
264+
Stream.unwrap(
265+
Effect.gen(function* () {
266+
const budget = yield* makeLiveStreamBudget(limits);
267+
const ready = yield* Queue.bounded<void, E | LiveStreamBufferError | Cause.Done>(1);
268+
const mutex = yield* Semaphore.make(1);
269+
const pending = new Map<string, RetainedLiveItem<A>>();
270+
let closed = false;
271+
const close = (error?: LiveStreamBufferError) =>
272+
mutex.withPermit(
273+
Effect.gen(function* () {
274+
if (closed) return;
275+
closed = true;
276+
budget.release(pending.values());
277+
pending.clear();
278+
if (error) yield* Queue.fail(ready, error);
279+
yield* Queue.shutdown(ready);
280+
}),
281+
);
282+
yield* Effect.addFinalizer(() => close());
283+
yield* budget.failed.pipe(
284+
Effect.catchTags({ LiveStreamBufferError: close }),
285+
Effect.forkScoped,
286+
);
287+
yield* source.pipe(
288+
Stream.runForEach((value) =>
289+
mutex.withPermit(
290+
Effect.gen(function* () {
291+
yield* budget.check;
292+
if (closed) return;
293+
const identity = key(value);
294+
const previous = pending.get(identity);
295+
if (previous && previous.value.sequence >= value.sequence) return;
296+
const wasEmpty = pending.size === 0;
297+
const [item] = yield* budget.replace(previous ? [previous] : [], [value]);
298+
pending.set(identity, item!);
299+
// Only the empty-to-nonempty transition needs a wakeup; replacements
300+
// must not leave another token after this batch has drained.
301+
if (wasEmpty) yield* Queue.offer(ready, undefined);
302+
}).pipe(Effect.uninterruptible),
303+
),
304+
),
305+
Effect.raceFirst(budget.failed),
306+
Effect.exit,
307+
Effect.flatMap((exit) =>
308+
Exit.isFailure(exit) ? Queue.failCause(ready, exit.cause) : Queue.end(ready),
309+
),
310+
Effect.forkScoped({ startImmediately: true }),
311+
);
312+
return budget.deliver(
313+
Stream.fromPull(
314+
Effect.succeed(
315+
Queue.take(ready).pipe(
316+
Effect.andThen(
317+
mutex.withPermit(
318+
Effect.sync(() => {
319+
const items = Array.from(pending.values()).sort(
320+
(left, right) => left.value.sequence - right.value.sequence,
321+
);
322+
pending.clear();
323+
// Moving to delivery preserves the budget charge until ACK.
324+
return items as Arr.NonEmptyArray<RetainedLiveItem<A>>;
325+
}),
326+
),
327+
),
328+
),
329+
),
330+
),
331+
);
332+
}),
333+
);
334+
257335
/**
258336
* Subscribe and start draining before reading the high-water mark. A blocked
259337
* catch-up query or an unacknowledged replay batch must not strand an unbounded

‎apps/server/src/orchestration-v2/ShellStream.test.ts‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,22 @@ import type {
88
} from "@t3tools/contracts";
99
import { ProjectId, ProviderInstanceId, ThreadId } from "@t3tools/contracts";
1010
import * as NodeSqliteClient from "@t3tools/shared/nodeSqliteClient";
11+
import type * as Cause from "effect/Cause";
1112
import * as DateTime from "effect/DateTime";
13+
import * as Deferred from "effect/Deferred";
1214
import * as Duration from "effect/Duration";
1315
import * as Effect from "effect/Effect";
1416
import * as Option from "effect/Option";
17+
import * as PubSub from "effect/PubSub";
18+
import * as Queue from "effect/Queue";
1519
import * as SqlClient from "effect/sql/SqlClient";
1620
import * as Stream from "effect/Stream";
1721
import * as TestClock from "effect/testing/TestClock";
1822

1923
import {
2024
archivedShellStreamItemFromThreadShell,
2125
buildActiveShellSnapshot,
26+
bufferShellLiveStream,
2227
coalesceShellApplicationEvents,
2328
coalesceStoredThreadEvents,
2429
composeShellStreamWithEnrichment,
@@ -54,6 +59,64 @@ const emptyShellSnapshot = {
5459
archivedThreads: [],
5560
} as OrchestrationV2ShellSnapshot;
5661

62+
it.effect("coalesces a slow shell subscriber by identity and location in sequence order", () =>
63+
Effect.scoped(
64+
Effect.gen(function* () {
65+
const input = yield* Queue.unbounded<
66+
Extract<OrchestrationV2ShellStreamItem, { readonly sequence: number }>,
67+
Cause.Done
68+
>();
69+
const drained = yield* Deferred.make<void>();
70+
const shell = shellFixture({ id: ThreadId.make("same"), title: "Before" });
71+
const project = {
72+
id: ProjectId.make("same"),
73+
title: "Before",
74+
workspaceRoot: "/workspace/same",
75+
repositoryIdentity: null,
76+
defaultModelSelection: null,
77+
scripts: [],
78+
createdAt: "2026-09-01T00:00:00Z",
79+
updatedAt: "2026-09-01T00:00:00Z",
80+
};
81+
const initial = {
82+
kind: "thread.updated" as const,
83+
sequence: 1,
84+
location: "active" as const,
85+
thread: shell,
86+
};
87+
const updates = [
88+
{ kind: "project.updated", sequence: 2, project },
89+
{ ...initial, sequence: 3 },
90+
{ ...initial, sequence: 4, location: "archive" },
91+
{ ...initial, sequence: 5, thread: { ...shell, id: ThreadId.make("other") } },
92+
{
93+
kind: "project.updated",
94+
sequence: 6,
95+
project: { ...project, id: ProjectId.make("other") },
96+
},
97+
{ kind: "project.removed", sequence: 7, projectId: project.id },
98+
{ kind: "thread.removed", sequence: 8, location: "active", threadId: shell.id },
99+
{ kind: "project.updated", sequence: 9, project: { ...project, title: "Recreated" } },
100+
{ ...initial, sequence: 10, thread: { ...shell, title: "Recreated" } },
101+
{ kind: "thread.removed", sequence: 11, location: "archive", threadId: shell.id },
102+
] satisfies Array<Extract<OrchestrationV2ShellStreamItem, { readonly sequence: number }>>;
103+
const pull = yield* Stream.toPull(
104+
bufferShellLiveStream(
105+
Stream.fromQueue(input).pipe(Stream.ensuring(Deferred.succeed(drained, undefined))),
106+
{ maxItems: 6, maxSerializedBytes: 1_500 },
107+
),
108+
);
109+
yield* Queue.offer(input, initial);
110+
expect(yield* pull).toEqual([initial]);
111+
yield* Queue.offerAll(input, updates);
112+
yield* Queue.end(input);
113+
// Finish producing the burst while the first batch is still awaiting its ACK.
114+
yield* Deferred.await(drained);
115+
expect(yield* pull).toEqual([updates[3], updates[4], updates[7], updates[8], updates[9]]);
116+
}),
117+
),
118+
);
119+
57120
describe("buildActiveShellSnapshot", () => {
58121
it("never duplicates archived rows into the regular shell", () => {
59122
const active = shellFixture({ archivedAt: null });
@@ -356,6 +419,104 @@ describe("shellStreamItemsFromResumeSnapshot", () => {
356419
});
357420

358421
describe("composeShellStreamWithEnrichment", () => {
422+
it.effect("preserves pending repository resolutions while an enrichment ACK is withheld", () =>
423+
Effect.scoped(
424+
Effect.gen(function* () {
425+
// Match ProjectEnrichmentService's sliding notifications and the WS batching path.
426+
const changes = yield* Effect.acquireRelease(
427+
PubSub.sliding<{ readonly workspaceRoot: string }>(256),
428+
PubSub.shutdown,
429+
);
430+
const subscription = yield* PubSub.subscribe(changes);
431+
const pull = yield* Stream.toPull(
432+
composeShellStreamWithEnrichment({
433+
initial: Stream.empty,
434+
tail: Stream.empty,
435+
enrichment: Stream.fromSubscription(subscription).pipe(
436+
Stream.groupedWithin(64, Duration.millis(25)),
437+
Stream.map((changes) =>
438+
shellStreamItemFromEnrichmentRefresh({
439+
snapshot: emptyShellSnapshot,
440+
changes,
441+
}),
442+
),
443+
),
444+
}),
445+
);
446+
447+
const firstRoots = Array.from({ length: 64 }, (_, index) => `/workspace/first-${index}`);
448+
yield* PubSub.publishAll(
449+
changes,
450+
firstRoots.map((workspaceRoot) => ({ workspaceRoot })),
451+
);
452+
expect(yield* pull).toMatchObject([{ resolvedRepositoryIdentityRoots: firstRoots }]);
453+
454+
// The next completion can be batched before the client acknowledges the first.
455+
yield* PubSub.publish(changes, { workspaceRoot: "/workspace/pending" });
456+
yield* Effect.yieldNow;
457+
yield* TestClock.adjust(Duration.millis(25));
458+
const laterRoots = Array.from({ length: 256 }, (_, index) => `/workspace/later-${index}`);
459+
yield* PubSub.publishAll(
460+
changes,
461+
laterRoots.map((workspaceRoot) => ({ workspaceRoot })),
462+
);
463+
464+
const resumed = yield* Stream.fromPull(Effect.succeed(pull)).pipe(
465+
Stream.takeUntil(
466+
(item) =>
467+
item.resolvedRepositoryIdentityRoots?.includes("/workspace/later-255") ?? false,
468+
),
469+
Stream.runCollect,
470+
);
471+
expect(resumed.flatMap((item) => item.resolvedRepositoryIdentityRoots ?? [])).toEqual([
472+
"/workspace/pending",
473+
...laterRoots,
474+
]);
475+
}),
476+
),
477+
);
478+
479+
it.effect("keeps a merged shell batch charged while the client withholds its ACK", () =>
480+
Effect.scoped(
481+
Effect.gen(function* () {
482+
const update = yield* Deferred.make<void>();
483+
const closed = yield* Deferred.make<void>();
484+
const initial = {
485+
kind: "thread.removed" as const,
486+
sequence: 1,
487+
location: "active" as const,
488+
threadId: ThreadId.make("thread-a"),
489+
};
490+
const pull = yield* Stream.toPull(
491+
composeShellStreamWithEnrichment({
492+
initial: Stream.empty,
493+
tail: bufferShellLiveStream(
494+
Stream.concat(
495+
Stream.succeed(initial),
496+
Stream.fromEffect(Deferred.await(update)).pipe(
497+
Stream.map(() => ({ ...initial, sequence: 2 })),
498+
),
499+
).pipe(Stream.ensuring(Deferred.succeed(closed, undefined))),
500+
{ maxItems: 1 },
501+
),
502+
enrichment: Stream.empty,
503+
}),
504+
);
505+
expect(yield* pull).toEqual([initial]);
506+
// Let the merge producer run while the client still withholds its ACK.
507+
yield* Effect.yieldNow;
508+
yield* Deferred.succeed(update, undefined);
509+
yield* Deferred.await(closed);
510+
const result = yield* Stream.fromPull(Effect.succeed(pull)).pipe(
511+
Stream.runDrain,
512+
Effect.result,
513+
);
514+
expect(result._tag).toBe("Failure");
515+
if (result._tag === "Failure") expect(result.failure._tag).toBe("LiveStreamBufferError");
516+
}),
517+
),
518+
);
519+
359520
it.effect(
360521
"emits every initial item before enrichment even when enrichment is already ready",
361522
() =>

0 commit comments

Comments
 (0)