refactor(server): extract terminal stream state manager from daemon client
Move terminal stream buffering, handler fanout, and ack offset state out of DaemonClient into a focused TerminalStreamManager.\n\nReasoning:\n- daemon-client.ts mixed RPC transport concerns with terminal stream state machine details.\n- terminal buffering/ack logic is cohesive and testable in isolation, so splitting it lowers logic density and makes future stream changes safer.\n\nWhat changed:\n- Added daemon-client-terminal-stream-manager.ts to own stream handlers, buffered chunks, and ack monotonicity.\n- Updated DaemonClient to delegate terminal stream state transitions (subscribe, receive chunk, clear stream/all, note ack).\n- Preserved public API by re-exporting TerminalStreamChunk from daemon-client.ts.\n- Hardened daemon-client tests to assert behavior (no delivery/ack after detach or stream_exit) rather than private internal maps.\n- Added dedicated manager unit tests for buffering, eviction, handler-failure behavior, and stale ack suppression.\n\nVerification:\n- npm run test --workspace=@getpaseo/server -- src/client/daemon-client.test.ts src/client/daemon-client-terminal-stream-manager.test.ts\n- npm run typecheck\n\nNext-agent notes:\n- Accomplishment: terminal stream state is now isolated; daemon-client.ts is slimmer and easier to extend.\n- Challenge: daemon-client.ts is still large (~3k lines) with other cohesive seams remaining (dictation flow and checkout RPC groups).
This commit is contained in:
Mohamed Boudra
@@ -0,0 +1,180 @@
|
||||
export type TerminalStreamChunk = {
|
||||
streamId: number;
|
||||
offset: number;
|
||||
endOffset: number;
|
||||
replay: boolean;
|
||||
data: Uint8Array;
|
||||
};
|
||||
|
||||
type TerminalChunkHandler = (chunk: TerminalStreamChunk) => void;
|
||||
|
||||
type BufferedTerminalStreamQueue = {
|
||||
chunks: TerminalStreamChunk[];
|
||||
bytes: number;
|
||||
};
|
||||
|
||||
type TerminalStreamAck = {
|
||||
streamId: number;
|
||||
offset: number;
|
||||
};
|
||||
|
||||
export type TerminalStreamManagerConfig = {
|
||||
sendAck: (ack: TerminalStreamAck) => void;
|
||||
maxBufferedChunks?: number;
|
||||
maxBufferedBytes?: number;
|
||||
};
|
||||
|
||||
const DEFAULT_MAX_BUFFERED_CHUNKS = 2048;
|
||||
const DEFAULT_MAX_BUFFERED_BYTES = 2 * 1024 * 1024;
|
||||
|
||||
export class TerminalStreamManager {
|
||||
private readonly handlers: Map<number, Set<TerminalChunkHandler>> = new Map();
|
||||
private readonly bufferedChunks: Map<number, BufferedTerminalStreamQueue> = new Map();
|
||||
private readonly ackOffsets: Map<number, number> = new Map();
|
||||
private readonly maxBufferedChunks: number;
|
||||
private readonly maxBufferedBytes: number;
|
||||
|
||||
constructor(private readonly config: TerminalStreamManagerConfig) {
|
||||
this.maxBufferedChunks =
|
||||
config.maxBufferedChunks ?? DEFAULT_MAX_BUFFERED_CHUNKS;
|
||||
this.maxBufferedBytes =
|
||||
config.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
|
||||
}
|
||||
|
||||
clearAll(): void {
|
||||
this.handlers.clear();
|
||||
this.bufferedChunks.clear();
|
||||
this.ackOffsets.clear();
|
||||
}
|
||||
|
||||
clearStream(input: { streamId: number }): void {
|
||||
this.handlers.delete(input.streamId);
|
||||
this.bufferedChunks.delete(input.streamId);
|
||||
this.ackOffsets.delete(input.streamId);
|
||||
}
|
||||
|
||||
subscribe(input: {
|
||||
streamId: number;
|
||||
handler: TerminalChunkHandler;
|
||||
}): () => void {
|
||||
const { streamId, handler } = input;
|
||||
if (!this.handlers.has(streamId)) {
|
||||
this.handlers.set(streamId, new Set());
|
||||
}
|
||||
|
||||
const streamHandlers = this.handlers.get(streamId)!;
|
||||
streamHandlers.add(handler);
|
||||
this.flushBufferedChunks({ streamId, handler });
|
||||
|
||||
return () => {
|
||||
streamHandlers.delete(handler);
|
||||
if (streamHandlers.size === 0) {
|
||||
this.handlers.delete(streamId);
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
receiveChunk(input: { chunk: TerminalStreamChunk }): void {
|
||||
const { chunk } = input;
|
||||
const streamHandlers = this.handlers.get(chunk.streamId);
|
||||
if (!streamHandlers || streamHandlers.size === 0) {
|
||||
this.bufferChunk({ chunk });
|
||||
return;
|
||||
}
|
||||
|
||||
let delivered = false;
|
||||
for (const handler of streamHandlers) {
|
||||
try {
|
||||
handler(chunk);
|
||||
delivered = true;
|
||||
} catch {
|
||||
// no-op
|
||||
}
|
||||
}
|
||||
if (delivered) {
|
||||
this.maybeAckChunk({
|
||||
streamId: chunk.streamId,
|
||||
endOffset: chunk.endOffset,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
noteAck(input: TerminalStreamAck): void {
|
||||
const normalizedOffset = Math.max(0, Math.floor(input.offset));
|
||||
const previousAck = this.ackOffsets.get(input.streamId) ?? -1;
|
||||
if (normalizedOffset > previousAck) {
|
||||
this.ackOffsets.set(input.streamId, normalizedOffset);
|
||||
}
|
||||
}
|
||||
|
||||
private flushBufferedChunks(input: {
|
||||
streamId: number;
|
||||
handler: TerminalChunkHandler;
|
||||
}): void {
|
||||
const buffered = this.bufferedChunks.get(input.streamId);
|
||||
if (!buffered || buffered.chunks.length === 0) {
|
||||
return;
|
||||
}
|
||||
|
||||
for (const chunk of buffered.chunks) {
|
||||
try {
|
||||
input.handler(chunk);
|
||||
this.maybeAckChunk({
|
||||
streamId: input.streamId,
|
||||
endOffset: chunk.endOffset,
|
||||
});
|
||||
} catch {
|
||||
// no-op
|
||||
}
|
||||
}
|
||||
this.bufferedChunks.delete(input.streamId);
|
||||
}
|
||||
|
||||
private bufferChunk(input: { chunk: TerminalStreamChunk }): void {
|
||||
const queue = this.bufferedChunks.get(input.chunk.streamId) ?? {
|
||||
chunks: [],
|
||||
bytes: 0,
|
||||
};
|
||||
|
||||
queue.chunks.push(input.chunk);
|
||||
queue.bytes += input.chunk.data.byteLength;
|
||||
|
||||
while (
|
||||
queue.chunks.length > this.maxBufferedChunks ||
|
||||
queue.bytes > this.maxBufferedBytes
|
||||
) {
|
||||
const removed = queue.chunks.shift();
|
||||
if (!removed) {
|
||||
break;
|
||||
}
|
||||
queue.bytes -= removed.data.byteLength;
|
||||
if (queue.bytes < 0) {
|
||||
queue.bytes = 0;
|
||||
}
|
||||
}
|
||||
|
||||
this.bufferedChunks.set(input.chunk.streamId, queue);
|
||||
}
|
||||
|
||||
private maybeAckChunk(input: { streamId: number; endOffset: number }): void {
|
||||
if (!Number.isFinite(input.endOffset) || input.endOffset < 0) {
|
||||
return;
|
||||
}
|
||||
|
||||
const normalizedEndOffset = Math.floor(input.endOffset);
|
||||
const previousAck = this.ackOffsets.get(input.streamId) ?? -1;
|
||||
if (normalizedEndOffset <= previousAck) {
|
||||
return;
|
||||
}
|
||||
|
||||
this.ackOffsets.set(input.streamId, normalizedEndOffset);
|
||||
try {
|
||||
this.config.sendAck({
|
||||
streamId: input.streamId,
|
||||
offset: normalizedEndOffset,
|
||||
});
|
||||
} catch {
|
||||
// no-op
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user