sailfork / t3code-github / apps/ server/ src/ terminal/ OutputProtocol.test.ts

import { assert, describe, it } from "@effect/vitest";
import {
  ORCHESTRATION_V2_WS_METHODS,
  type TerminalAttachStreamEvent,
  TerminalAttachStreamEvent as TerminalAttachStreamEventSchema,
  WS_METHODS,
} from "@t3tools/contracts";
import * as Deferred from "effect/Deferred";
import * as Effect from "effect/Effect";
import * as Fiber from "effect/Fiber";
import * as Queue from "effect/Queue";
import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";
import * as TestClock from "effect/testing/TestClock";
import { Rpc, RpcGroup, RpcMessage, RpcSerialization, RpcServer } from "effect/rpc";

import { terminalOutputStream, withOutputWindow } from "./OutputProtocol.ts";

describe("terminal output window", () => {
  it.effect.each([
    { tag: WS_METHODS.terminalAttach, size: 1, limit: 8 },
    { tag: WS_METHODS.terminalObserve, size: 1, limit: 8 },
    { tag: WS_METHODS.terminalAttach, size: 64 * 1024, limit: 1 },
    { tag: WS_METHODS.terminalObserve, size: 64 * 1024, limit: 1 },
    { tag: WS_METHODS.subscribeServerConfig, size: 1, limit: 8 },
    { tag: ORCHESTRATION_V2_WS_METHODS.subscribeShell, size: 1, limit: 8 },
    { tag: ORCHESTRATION_V2_WS_METHODS.subscribeThread, size: 64 * 1024, limit: 8 },
    { tag: WS_METHODS.subscribeTerminalMetadata, size: 1, limit: 1 },
  ])("limits $tag with $size-byte values to $limit pending chunks", ({ tag, size, limit }) =>
    Effect.gen(function* () {
      const group = RpcGroup.make(Rpc.make(tag, { success: Schema.String, stream: true }));
      const output = yield* Queue.unbounded<string>();
      const responses = yield* Queue.unbounded<RpcMessage.FromServerEncoded>();
      const receive = yield* Deferred.make<Parameters<RpcServer.Protocol["Service"]["run"]>[0]>();
      const protocol = yield* RpcServer.Protocol.make((write) =>
        Effect.gen(function* () {
          yield* Deferred.succeed(receive, write);
          const serialization = yield* RpcSerialization.RpcSerialization;
          return {
            disconnects: yield* Queue.unbounded<number>(),
            send: (_clientId, response) => Queue.offer(responses, response),
            end: () => Effect.void,
            clientIds: Effect.succeed(new Set([0])),
            initialMessage: Effect.succeedNone,
            supportsAck: true,
            supportsTransferables: false,
            supportsSpanPropagation: false,
            supportsNotifications: true,
            codecFor: serialization.codecFor,
          };
        }),
      );
      yield* RpcServer.make(group).pipe(
        Effect.provide(group.toLayerHandler(tag, () => Stream.fromQueue(output))),
        Effect.provideService(RpcServer.Protocol, withOutputWindow(protocol)),
        Effect.forkScoped,
      );
      const write = yield* Deferred.await(receive);
      yield* write(0, { _tag: "Request", id: "1", tag, payload: null, headers: [] });

      for (let index = 0; index < limit; index++) {
        const value = String(index).repeat(size);
        yield* Queue.offer(output, value);
        yield* TestClock.adjust(0);
        assert.equal(yield* Queue.size(responses), 1);
        assert.deepEqual(yield* Queue.take(responses), {
          _tag: "Chunk",
          requestId: "1",
          values: [value],
        });
      }
      yield* Queue.offer(output, "i".repeat(size));
      yield* TestClock.adjust(0);
      assert.equal(yield* Queue.size(responses), 0);
      yield* write(0, { _tag: "Ack", requestId: "1" });
      const resumed = yield* Queue.take(responses);
      assert.equal(resumed._tag, "Chunk");
      if (resumed._tag === "Chunk") assert.deepEqual(resumed.values, ["i".repeat(size)]);

      yield* Queue.offer(output, "j");
      yield* TestClock.adjust(0);
      assert.equal(yield* Queue.size(responses), 0);
      yield* write(0, { _tag: "Interrupt", requestId: "1" });
      assert.equal((yield* Queue.take(responses))._tag, "Exit");
    }).pipe(Effect.provide(RpcSerialization.layerJson), Effect.scoped),
  );
});

const output = (data: string): TerminalAttachStreamEvent => ({
  type: "output",
  threadId: "thread-1",
  terminalId: "default",
  data,
});

const snapshot = (history: string): TerminalAttachStreamEvent => ({
  type: "snapshot",
  snapshot: {
    threadId: "thread-1",
    terminalId: "default",
    cwd: "/repo",
    worktreePath: null,
    status: "running",
    pid: 1,
    history,
    exitCode: null,
    exitSignal: null,
    label: "bash",
    updatedAt: "2026-01-01T00:00:00.000Z",
  },
});

// Stands in for TerminalManager's fanout: listeners run in publish order and
// may release themselves while it iterates.
const makePublisher = () => {
  const listeners = new Set<(event: TerminalAttachStreamEvent) => Effect.Effect<void>>();
  return {
    listeners,
    subscribe: (
      listener: (event: TerminalAttachStreamEvent) => Effect.Effect<void>,
      registerCleanup?: (stop: () => void) => void,
    ) =>
      Effect.sync(() => {
        listeners.add(listener);
        const stop = () => {
          listeners.delete(listener);
        };
        registerCleanup?.(stop);
        return stop;
      }),
    publish: (event: TerminalAttachStreamEvent) =>
      Effect.forEach(listeners, (listener) => listener(event), { discard: true }),
  };
};

// Like TerminalManager.attachStream: a snapshot, then live events.
const attach =
  (publisher: ReturnType<typeof makePublisher>, history: string) =>
  (
    listener: (event: TerminalAttachStreamEvent) => Effect.Effect<void>,
    registerCleanup: (stop: () => void) => void,
  ) =>
    publisher
      .subscribe(listener, registerCleanup)
      .pipe(Effect.tap(() => listener(snapshot(history))));

const chunkBytes = (message: RpcMessage.FromServerEncoded) =>
  Buffer.byteLength(JSON.stringify(message));

describe("terminal output stream", () => {
  it.effect.each([WS_METHODS.terminalAttach, WS_METHODS.terminalObserve])(
    "releases only the ACK-stalled subscriber on %s and resumes safely",
    (tag) =>
      Effect.gen(function* () {
        const group = RpcGroup.make(
          Rpc.make(tag, {
            success: TerminalAttachStreamEventSchema,
            stream: true,
          }),
        );
        const publisher = makePublisher();
        const stalled = yield* Queue.unbounded<RpcMessage.FromServerEncoded>();
        const healthy = yield* Queue.unbounded<RpcMessage.FromServerEncoded>();
        const receive = yield* Deferred.make<Parameters<RpcServer.Protocol["Service"]["run"]>[0]>();
        const protocol = yield* RpcServer.Protocol.make((write) =>
          Effect.gen(function* () {
            yield* Deferred.succeed(receive, write);
            const serialization = yield* RpcSerialization.RpcSerialization;
            return {
              disconnects: yield* Queue.unbounded<number>(),
              send: (clientId, response) =>
                Queue.offer(clientId === 0 ? stalled : healthy, response),
              end: () => Effect.void,
              clientIds: Effect.succeed(new Set([0, 1])),
              initialMessage: Effect.succeedNone,
              supportsAck: true,
              supportsTransferables: false,
              supportsSpanPropagation: false,
              supportsNotifications: true,
              codecFor: serialization.codecFor,
            };
          }),
        );
        const initial = snapshot("");
        yield* RpcServer.make(group).pipe(
          Effect.provide(
            group.toLayerHandler(tag, () =>
              terminalOutputStream(
                (listener, registerCleanup) =>
                  publisher
                    .subscribe(listener, registerCleanup)
                    .pipe(Effect.tap(() => listener(initial))),
                attach(publisher, "fresh history"),
                256 * 1024,
              ),
            ),
          ),
          Effect.provideService(RpcServer.Protocol, withOutputWindow(protocol)),
          Effect.forkScoped,
        );
        const write = yield* Deferred.await(receive);
        const takeChunk = Effect.fnUntraced(function* (queue: typeof stalled) {
          const response = yield* Queue.take(queue);
          assert.equal(response._tag, "Chunk");
          if (response._tag !== "Chunk") throw new Error("Expected an RPC chunk");
          assert.isAtMost(chunkBytes(response), 70 * 1024);
          return response.values;
        });
        yield* write(0, { _tag: "Request", id: "1", tag, payload: null, headers: [] });
        assert.deepEqual(yield* takeChunk(stalled), [initial]);
        yield* write(1, { _tag: "Request", id: "2", tag, payload: null, headers: [] });
        assert.deepEqual(yield* takeChunk(healthy), [initial]);
        yield* write(1, { _tag: "Ack", requestId: "2" });

        // Eight unacknowledged chunks fill only client 0's output window.
        for (let index = 0; index < 7; index++) {
          const event = output("before-stall-" + index);
          yield* publisher.publish(event);
          assert.deepEqual(yield* takeChunk(stalled), [event]);
          assert.deepEqual(yield* takeChunk(healthy), [event]);
          yield* write(1, { _tag: "Ack", requestId: "2" });
        }
        assert.equal(publisher.listeners.size, 2);
        for (let index = 0; index < 100; index++) {
          const event = output(index + ":" + "界".repeat(1365));
          yield* publisher.publish(event);
          assert.deepEqual(yield* takeChunk(healthy), [event]);
          yield* write(1, { _tag: "Ack", requestId: "2" });
          if (index === 31) assert.equal(publisher.listeners.size, 2);
        }
        assert.equal(yield* Queue.size(stalled), 0);
        assert.equal(publisher.listeners.size, 1);

        yield* write(0, { _tag: "Ack", requestId: "1" });
        assert.deepEqual(yield* takeChunk(stalled), [snapshot("fresh history")]);
        assert.equal(publisher.listeners.size, 2);
        for (let index = 0; index < 7; index++) {
          yield* write(0, { _tag: "Ack", requestId: "1" });
        }
        const after = output("unique output after recovery");
        yield* publisher.publish(after);
        assert.deepEqual(yield* takeChunk(healthy), [after]);
        assert.deepEqual(yield* takeChunk(stalled), [after]);
        assert.equal(yield* Queue.size(stalled), 0);
      }).pipe(Effect.provide(RpcSerialization.layerJson), Effect.scoped),
  );

  it.effect("interrupts recovery while its subscription is still waiting", () =>
    Effect.gen(function* () {
      const publisher = makePublisher();
      const recovering = yield* Deferred.make<void>();
      const interrupted = yield* Deferred.make<void>();
      const pull = yield* Stream.toPull(
        terminalOutputStream(
          attach(publisher, ""),
          () =>
            Deferred.succeed(recovering, undefined).pipe(
              Effect.andThen(Effect.never),
              Effect.onInterrupt(() => Deferred.succeed(interrupted, undefined)),
            ),
          1024,
        ),
      );
      yield* pull;
      yield* publisher.publish(output("x".repeat(1024)));
      yield* publisher.publish(output("x".repeat(1024)));
      assert.equal(publisher.listeners.size, 0);

      const recovery = yield* pull.pipe(Effect.forkChild({ startImmediately: true }));
      yield* Deferred.await(recovering);
      yield* Fiber.interrupt(recovery);
      yield* Deferred.await(interrupted);
      assert.equal(publisher.listeners.size, 0);
    }).pipe(Effect.scoped),
  );

  it.effect("cleans listeners when cancelled during a successful acquisition handoff", () =>
    Effect.gen(function* () {
      const publisher = makePublisher();
      for (const recovering of [false, true, false, true]) {
        const handoff = yield* Deferred.make<void>();
        const complete = yield* Deferred.make<void>();
        const acquire: ReturnType<typeof attach> = (listener, registerCleanup) =>
          attach(publisher, "")(listener, registerCleanup).pipe(
            // Hold the successful exit before its cleanup handle reaches the caller.
            Effect.onExit(() =>
              Deferred.succeed(handoff, undefined).pipe(Effect.andThen(Deferred.await(complete))),
            ),
          );
        const consumer = yield* Effect.gen(function* () {
          const pull = yield* Stream.toPull(
            terminalOutputStream(recovering ? attach(publisher, "") : acquire, acquire, 1024),
          );
          yield* pull;
          yield* publisher.publish(output("x".repeat(1024)));
          yield* publisher.publish(output("x".repeat(1024)));
          yield* pull;
        }).pipe(Effect.scoped, Effect.forkChild({ startImmediately: true }));
        yield* Deferred.await(handoff);
        assert.equal(publisher.listeners.size, 1);
        const cancellation = yield* Fiber.interrupt(consumer).pipe(
          Effect.forkChild({ startImmediately: true }),
        );
        yield* Deferred.succeed(complete, undefined);
        yield* Fiber.join(cancellation);
        assert.equal(publisher.listeners.size, 0);
      }
    }).pipe(Effect.scoped),
  );

  it.effect("caps each delivered batch at the output window in UTF-8 bytes", () =>
    Effect.gen(function* () {
      const publisher = makePublisher();
      const pull = yield* Stream.toPull(terminalOutputStream(attach(publisher, "")));
      assert.deepEqual(yield* pull, [snapshot("")]);
      // 1,024 code units but 3 KiB of UTF-8.
      const data = "界".repeat(1024);
      for (let index = 0; index < 1024; index++) yield* publisher.publish(output(data));

      let delivered = 0;
      while (delivered < 1024) {
        const batch = yield* pull;
        assert.isAtMost(
          batch.reduce(
            (bytes, event) => bytes + (event.type === "output" ? Buffer.byteLength(event.data) : 0),
            0,
          ),
          64 * 1024,
        );
        delivered += batch.length;
      }
      assert.equal(delivered, 1024);
    }).pipe(Effect.scoped),
  );

  it.effect("charges snapshot history but never overflows on one snapshot", () =>
    Effect.gen(function* () {
      const publisher = makePublisher();
      const history = "界".repeat(16 * 1024);
      const events = terminalOutputStream(attach(publisher, history), undefined, 32 * 1024);
      const pull = yield* Stream.toPull(events);
      // A snapshot larger than the budget is still delivered.
      assert.deepEqual(yield* pull, [snapshot(history)]);
      assert.equal(publisher.listeners.size, 1);

      // Queued snapshots count their history: a second one overflows.
      yield* publisher.publish(snapshot(history));
      assert.equal(publisher.listeners.size, 1);
      yield* publisher.publish(snapshot(history));
      assert.equal(publisher.listeners.size, 0);
    }).pipe(Effect.scoped),
  );
});