Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

8.0 KB
Raw Blame
/**
 * SSE endpoint adapter:
 * writes the runtime/channel event stream as an SSE response, shared by both the Session
 * channel and the user channel.
 *
 * - Response headers: text/event-stream, no-cache, `X-Accel-Buffering: no` (disables
 *   buffering on reverse proxies);
 * - Heartbeat: a named `ping` event (`data: {}`, no `id:` line) right after the initial
 *   events and every 20s after. A browser hides comment lines from the page, so only an
 *   event lets it tell a quiet stream from a dead one (web api/sse.ts); without an id it
 *   moves neither Last-Event-ID nor the replay cursor. A peer that stops reading is cut off
 *   by the host's idle timeout ({@link STREAM_IDLE_MS}, app.ts);
 * - Replay protocol: a fresh subscription without Last-Event-ID does not replay the buffer
 *   (history is served by the messages endpoint) — it only sends the initial events the
 *   caller supplied (pending approvals / hello). With a Last-Event-ID that hits the buffer,
 *   replay resumes from there; on a miss, `resync_required` is sent first, then the
 *   connection continues. A page cannot set headers on an EventSource it opens itself, so
 *   the id may come as the `lastEventId` query parameter instead; the header wins.
 * - Revocation: a stream is authorised at connect and never again by the request path, so
 *   an authenticated route hands over {@link SseRevocation} — the registry that can end
 *   this stream from outside, and the check the heartbeat runs on it.
 * Docs: /docs/server-api § "Delivery Guarantees".
 */
import type { Context } from "hono";
import { getCookie } from "hono/cookie";
import { streamSSE } from "hono/streaming";
import type { ServerEvent } from "../api/types.js";
import type { Channel, ChannelEvent, ChannelListener } from "../runtime/channel.js";
import type { LiveStreams } from "../auth/live-streams.js";
import type { Auth } from "../mechanisms/identity.js";
import { SESSION_COOKIE, bearerToken } from "../auth/middleware.js";

const HEARTBEAT_MS = 20_000;

/** An event stream's socket that sends nothing for this long is destroyed (app.ts): two missed beats. */
export const STREAM_IDLE_MS = 2 * HEARTBEAT_MS;

/** The heartbeat frame: named so a page can see it, id-less so it moves no cursor. */
const PING = { event: "ping", data: "{}" } as const;

/** How the session behind one connection reaches the stream it authorised. */
export interface SseRevocation {
  /** The user this connection was authenticated as. */
  userId: string;
  /** Holds the stream for as long as it is open (auth/live-streams.ts). */
  streams: LiveStreams;
  /** Whether the session behind this connection still exists and has not expired. Never renews it. */
  sessionIsLive(): boolean;
}

export interface SseEndpointOptions {
  /** Initial server events to send privately after the subscription is established (in order): pending-approval replay / user channel hello. */
  initialEvents?: ServerEvent[];
  /** Omitted only where there is no authenticated session to revoke. */
  revocation?: SseRevocation;
}

/**
 * The revocation wiring an authenticated SSE route hands {@link sseEndpoint}. One
 * definition, so a new streaming route cannot be wired half-way — with a registry entry
 * but no re-check, or the other way round.
 */
export function streamRevocation(
  c: Context,
  user: { userId: string },
  deps: { liveStreams: LiveStreams; auth: Auth },
): SseRevocation {
  // Bearer first, cookie otherwise — the precedence authMiddleware authenticated this
  // request with. A Bearer-authenticated stream (the CLI, an Agent's own tools) carries no
  // session row at all: its credential is the boot's local API token, which lives as long
  // as the process does. There is nothing for the heartbeat to re-check there, so it
  // leaves that connection alone instead of ending it on a lookup that can only miss.
  const token =
    bearerToken(c.req.header("authorization")) !== null
      ? null
      : (getCookie(c, SESSION_COOKIE) ?? null);
  return {
    userId: user.userId,
    streams: deps.liveStreams,
    sessionIsLive: () => token === null || deps.auth.sessionIsLive(token),
  };
}

/** Stream out a Channel as an SSE response. */
export function sseEndpoint(c: Context, channel: Channel, opts: SseEndpointOptions = {}): Response {
  // The header wins: the browser sets it on its own reconnects, and it is newer than the id
  // the page wrote into the URL when it opened this EventSource.
  const lastEventId = c.req.header("Last-Event-ID") ?? c.req.query("lastEventId");
  const revocation = opts.revocation;
  c.header("X-Accel-Buffering", "no");
  c.header("Cache-Control", "no-cache");

  return streamSSE(c, async (stream) => {
    let closed = false;
    let finish: () => void = () => {};
    const done = new Promise<void>((resolve) => {
      finish = () => {
        if (closed) return;
        closed = true;
        resolve();
      };
    });

    // Claimed before anything that can throw and released in the finally below, so the
    // registry holds an entry for exactly as long as the connection lives: one left
    // behind would name a stream nobody can close again.
    const release = revocation?.streams.add(revocation.userId, finish) ?? (() => {});
    let unsubscribe: (() => void) | null = null;
    let heartbeat: ReturnType<typeof setInterval> | null = null;
    try {
      // Write serialization: SSE events must be written fully and in order. A write to a peer
      // that stopped reading never completes; the host's idle timeout then destroys the
      // socket, which aborts the stream and lands in finish() below.
      let chain: Promise<void> = Promise.resolve();
      const enqueue = (write: () => Promise<unknown>): void => {
        chain = chain
          .then(async () => {
            if (!closed) await write();
          })
          .catch(() => finish());
      };
      const listener: ChannelListener = (evt: ChannelEvent) => {
        enqueue(() =>
          stream.writeSSE({
            data: evt.data,
            // Event id is an opaque string generated by the channel (`<epoch>-<seq>`), passed through as-is.
            id: evt.id,
            ...(evt.event !== undefined ? { event: evt.event } : {}),
          }),
        );
      };

      unsubscribe = channel.subscribe(listener);
      // Subscribe first (to avoid dropping events in a race with broadcasts), then replay
      // synchronously — event order: buffered replay (or resync_required) -> initial events
      // (task_state snapshot / pending approvals / hello) -> ping -> live stream.
      if (lastEventId !== undefined) {
        const replay = channel.replayAfter(lastEventId);
        if (!replay.hit) {
          const resync: ServerEvent = { type: "resync_required" };
          channel.sendTo(listener, resync, "server_event");
        } else {
          for (const evt of replay.events) listener(evt);
        }
      }
      for (const event of opts.initialEvents ?? []) {
        channel.sendTo(listener, event, "server_event");
      }
      // The first beat goes out at once, so a client knows from the first second that this
      // stream pings — not only after the first interval has passed.
      enqueue(() => stream.writeSSE(PING));

      heartbeat = setInterval(() => {
        // The heartbeat is the one beat an open stream already has, so re-asking whether
        // the session behind it still exists costs nothing extra — and it bounds how long
        // a window whose session was revoked keeps streaming to a single interval, no
        // matter which caller dropped the rows or whether it remembered the registry. The
        // check must not renew the session: sliding the expiry from here would keep a
        // window nobody has touched signed in for as long as it stays open.
        if (revocation !== undefined && !revocation.sessionIsLive()) {
          finish();
          return;
        }
        enqueue(() => stream.writeSSE(PING));
      }, HEARTBEAT_MS);

      stream.onAbort(() => finish());
      await done;
    } finally {
      if (heartbeat !== null) clearInterval(heartbeat);
      unsubscribe?.();
      release();
    }
  });
}