@telorun/runner-core 0.5.2

package/src/session/bundle-path.ts

@@ -0,0 +1,27 @@
+import { posix } from "node:path";
+
+export class BundlePathError extends Error {}
+
+/**
+ * Bundle file paths arrive POSIX-style and untrusted. Guard against traversal
+ * explicitly rather than trusting `path.resolve` — an `entryRelativePath` or
+ * `files[].relativePath` of `../foo` would escape the session's own directory.
+ * Backend-neutral: every backend normalizes paths the same way before placing
+ * files, regardless of how it ultimately delivers the bundle.
+ */
+export function normalizeBundlePath(p: string): string {
+  const normalized = posix.normalize(p).replace(/^\/+/, "");
+  if (normalized === "" || normalized === "." || normalized.startsWith("../") || normalized === "..") {
+    throw new BundlePathError(`invalid bundle relativePath '${p}'`);
+  }
+  for (const part of normalized.split("/")) {
+    if (part === "..") throw new BundlePathError(`invalid bundle relativePath '${p}'`);
+  }
+  return normalized;
+}
+
+export function validateSessionId(id: string): void {
+  if (!/^[a-zA-Z0-9_-]+$/.test(id)) {
+    throw new BundlePathError(`invalid sessionId '${id}' (must match /^[a-zA-Z0-9_-]+$/)`);
+  }
+}

package/src/session/byte-ring-buffer.ts

@@ -0,0 +1,62 @@
+export interface BufferedBytes {
+  seq: number;
+  bytes: Buffer;
+}
+
+/**
+ * Byte-capped FIFO ring buffer for raw PTY output replay. Mirrors
+ * EventRingBuffer's eviction-with-gap semantics but stores Buffer slices keyed
+ * by a monotonic seq number — never reused, never reset.
+ *
+ * A client's `?lastSeq=<n>` asks for chunks with seq > n; if the oldest
+ * remaining seq is still > n+1, the gap must be signaled separately.
+ */
+export class ByteRingBuffer {
+  private readonly entries: BufferedBytes[] = [];
+  private totalBytes = 0;
+  private nextSeq = 1;
+
+  constructor(private readonly maxBytes: number) {
+    if (!Number.isInteger(maxBytes) || maxBytes <= 0) {
+      throw new Error(`ByteRingBuffer maxBytes must be a positive integer, got ${maxBytes}`);
+    }
+  }
+
+  push(bytes: Buffer): BufferedBytes {
+    const seq = this.nextSeq++;
+    const entry: BufferedBytes = { seq, bytes };
+    this.entries.push(entry);
+    this.totalBytes += bytes.byteLength;
+    this.evict();
+    return entry;
+  }
+
+  private evict(): void {
+    // Always retain at least the most-recent entry, even if it alone exceeds
+    // maxBytes — same invariant as EventRingBuffer.
+    while (this.totalBytes > this.maxBytes && this.entries.length > 1) {
+      const dropped = this.entries.shift();
+      if (!dropped) break;
+      this.totalBytes -= dropped.bytes.byteLength;
+    }
+  }
+
+  replay(afterSeq: number): { entries: BufferedBytes[]; hasGap: boolean } {
+    const entries = this.entries.filter((e) => e.seq > afterSeq);
+    const oldestSeq = this.entries[0]?.seq ?? this.nextSeq;
+    const hasGap = afterSeq + 1 < oldestSeq;
+    return { entries, hasGap };
+  }
+
+  get size(): number {
+    return this.entries.length;
+  }
+
+  get bytes(): number {
+    return this.totalBytes;
+  }
+
+  get latestSeq(): number {
+    return this.nextSeq - 1;
+  }
+}

package/src/session/registry.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+
+import { SessionLimitError, SessionRegistry } from "./registry.js";
+
+const deps = { maxSessions: 2, exitTtlMs: 60_000, replayBufferBytes: 10_000 };
+
+function markExited(reg: SessionRegistry, sessionId: string): void {
+  reg.emit(sessionId, { type: "status", status: { kind: "exited", code: 0 } });
+}
+
+describe("SessionRegistry capacity", () => {
+  it("evicts the oldest terminal session to admit a new run at capacity", () => {
+    const reg = new SessionRegistry(deps);
+    reg.register({ sessionId: "a" });
+    reg.register({ sessionId: "b" });
+    markExited(reg, "a");
+
+    // At capacity (2). The retained exited session yields to the new run.
+    reg.register({ sessionId: "c" });
+
+    expect(reg.has("a")).toBe(false);
+    expect(reg.has("b")).toBe(true);
+    expect(reg.has("c")).toBe(true);
+  });
+
+  it("rejects a new run when every session is still live", () => {
+    const reg = new SessionRegistry(deps);
+    reg.register({ sessionId: "a" });
+    reg.register({ sessionId: "b" });
+
+    expect(() => reg.register({ sessionId: "c" })).toThrow(SessionLimitError);
+    expect(reg.size()).toBe(2);
+  });
+});

package/src/session/registry.ts

@@ -0,0 +1,185 @@
+import { EventEmitter } from "node:events";
+
+import type { BackendSession } from "../backend.js";
+import { isTerminal, type RunEvent, type RunStatus } from "../contract.js";
+import { ByteRingBuffer, type BufferedBytes } from "./byte-ring-buffer.js";
+import { EventRingBuffer, type BufferedEvent } from "./ring-buffer.js";
+
+export interface SessionEntry {
+  readonly sessionId: string;
+  readonly createdAt: Date;
+  readonly buffer: EventRingBuffer;
+  readonly byteBuffer: ByteRingBuffer;
+  readonly emitter: EventEmitter;
+  readonly byteEmitter: EventEmitter;
+
+  /** The live backend workload. Null until `start` resolves; the route writes
+   *  stdin / resize / stop through it. A backend's `writeStdin` is a no-op once
+   *  the workload has terminated, so callers need not null it on exit. */
+  session: BackendSession | null;
+  status: RunStatus;
+  exitedAt: Date | null;
+  userStopped: boolean;
+  evictionTimer: NodeJS.Timeout | null;
+}
+
+export interface RegistryDeps {
+  maxSessions: number;
+  exitTtlMs: number;
+  replayBufferBytes: number;
+}
+
+const EVENT_EMITTED = "event";
+const BYTES_EMITTED = "chunk";
+
+/** Cap on a single buffered byte chunk. Without this, one huge workload
+ *  burst (`cat largefile`) could be admitted as one entry; the ring
+ *  buffer's "retain at least one" invariant would then keep that one
+ *  oversized entry resident regardless of `replayBufferBytes`. Splitting
+ *  on push means the cap actually bounds memory and the eviction loop
+ *  has fine-grained units to drop. */
+const MAX_PUSH_CHUNK = 64 * 1024;
+
+export class SessionLimitError extends Error {}
+export class SessionEvictedError extends Error {}
+
+export class SessionRegistry {
+  private readonly sessions = new Map<string, SessionEntry>();
+
+  constructor(private readonly deps: RegistryDeps) {}
+
+  size(): number {
+    return this.sessions.size;
+  }
+
+  has(sessionId: string): boolean {
+    return this.sessions.has(sessionId);
+  }
+
+  get(sessionId: string): SessionEntry | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  list(): SessionEntry[] {
+    return [...this.sessions.values()];
+  }
+
+  /**
+   * Creates a fresh registry entry. Callers are responsible for guarding against
+   * duplicate insertion. Throws SessionLimitError if we're at capacity.
+   */
+  register(args: { sessionId: string }): SessionEntry {
+    if (this.sessions.size >= this.deps.maxSessions && !this.evictOldestTerminal()) {
+      throw new SessionLimitError(
+        `runner is at its configured max of ${this.deps.maxSessions} concurrent sessions`,
+      );
+    }
+    const entry: SessionEntry = {
+      sessionId: args.sessionId,
+      createdAt: new Date(),
+      buffer: new EventRingBuffer(this.deps.replayBufferBytes),
+      byteBuffer: new ByteRingBuffer(this.deps.replayBufferBytes),
+      emitter: new EventEmitter(),
+      byteEmitter: new EventEmitter(),
+      session: null,
+      status: { kind: "starting" },
+      exitedAt: null,
+      userStopped: false,
+      evictionTimer: null,
+    };
+    // Many transient SSE / WS subscribers per session is normal — bump the
+    // default 10-listener warning to a high cap so the alarm still fires
+    // for a real listener leak. 256 is well above the realistic concurrent-
+    // tab count and well below "obviously a bug".
+    entry.emitter.setMaxListeners(256);
+    entry.byteEmitter.setMaxListeners(256);
+    this.sessions.set(args.sessionId, entry);
+    return entry;
+  }
+
+  pushBytes(sessionId: string, bytes: Buffer): BufferedBytes | undefined {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return undefined;
+    if (bytes.byteLength <= MAX_PUSH_CHUNK) {
+      const buffered = entry.byteBuffer.push(bytes);
+      entry.byteEmitter.emit(BYTES_EMITTED, buffered);
+      return buffered;
+    }
+    // Split the chunk into MAX_PUSH_CHUNK-sized slices, each getting its
+    // own seq. Returns the last buffered piece for the caller's bookkeeping.
+    let last: BufferedBytes | undefined;
+    for (let off = 0; off < bytes.byteLength; off += MAX_PUSH_CHUNK) {
+      const slice = bytes.subarray(off, Math.min(off + MAX_PUSH_CHUNK, bytes.byteLength));
+      // subarray shares memory with the parent buffer; copy so the ring's
+      // entry doesn't pin the original allocation past eviction.
+      last = entry.byteBuffer.push(Buffer.from(slice));
+      entry.byteEmitter.emit(BYTES_EMITTED, last);
+    }
+    return last;
+  }
+
+  subscribeBytes(sessionId: string, listener: (b: BufferedBytes) => void): () => void {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) throw new SessionEvictedError(`session '${sessionId}' not in registry`);
+    entry.byteEmitter.on(BYTES_EMITTED, listener);
+    return () => entry.byteEmitter.off(BYTES_EMITTED, listener);
+  }
+
+  emit(sessionId: string, event: RunEvent): BufferedEvent | undefined {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return undefined;
+    const buffered = entry.buffer.push(event);
+    if (event.type === "status") {
+      entry.status = event.status;
+      if (isTerminal(event.status)) {
+        entry.exitedAt = new Date();
+        this.scheduleEviction(entry);
+      }
+    }
+    entry.emitter.emit(EVENT_EMITTED, buffered);
+    return buffered;
+  }
+
+  subscribe(sessionId: string, listener: (e: BufferedEvent) => void): () => void {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) throw new SessionEvictedError(`session '${sessionId}' not in registry`);
+    entry.emitter.on(EVENT_EMITTED, listener);
+    return () => entry.emitter.off(EVENT_EMITTED, listener);
+  }
+
+  /** Free a slot at capacity by removing the oldest already-terminated session
+   *  (by exit time). Retained exited sessions are history kept for re-attach, so
+   *  they yield to a new run rather than blocking it; live sessions are never
+   *  evicted. Returns false when every session is still live. */
+  private evictOldestTerminal(): boolean {
+    let oldest: SessionEntry | undefined;
+    for (const entry of this.sessions.values()) {
+      if (entry.exitedAt === null) continue;
+      if (!oldest || entry.exitedAt < oldest.exitedAt!) oldest = entry;
+    }
+    if (!oldest) return false;
+    return this.remove(oldest.sessionId);
+  }
+
+  private scheduleEviction(entry: SessionEntry): void {
+    if (entry.evictionTimer) return;
+    entry.evictionTimer = setTimeout(() => {
+      this.sessions.delete(entry.sessionId);
+    }, this.deps.exitTtlMs);
+    // Allow process exit even if evictions are pending — they are pure state,
+    // not work.
+    entry.evictionTimer.unref?.();
+  }
+
+  /**
+   * Remove an entry immediately (used by shutdown sweeps and startup cleanup).
+   * Returns true if it was present.
+   */
+  remove(sessionId: string): boolean {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return false;
+    if (entry.evictionTimer) clearTimeout(entry.evictionTimer);
+    this.sessions.delete(sessionId);
+    return true;
+  }
+}

package/src/session/ring-buffer.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+
+import { ByteRingBuffer } from "./byte-ring-buffer.js";
+import { EventRingBuffer } from "./ring-buffer.js";
+import { normalizeBundlePath, validateSessionId, BundlePathError } from "./bundle-path.js";
+
+describe("EventRingBuffer", () => {
+  it("assigns monotonic ids starting at 1 and replays after an id", () => {
+    const buf = new EventRingBuffer(1_000_000);
+    buf.push({ type: "stdout", chunk: "a" });
+    buf.push({ type: "stdout", chunk: "b" });
+    const { entries, hasGap } = buf.replay(1);
+    expect(entries.map((e) => e.id)).toEqual([2]);
+    expect(hasGap).toBe(false);
+  });
+
+  it("evicts oldest entries past the byte cap but always retains the last", () => {
+    const buf = new EventRingBuffer(50);
+    for (let i = 0; i < 20; i++) buf.push({ type: "stdout", chunk: "x".repeat(20) });
+    expect(buf.size).toBeGreaterThanOrEqual(1);
+    expect(buf.bytes).toBeLessThanOrEqual(50 + 40);
+    const { hasGap } = buf.replay(0);
+    expect(hasGap).toBe(true);
+  });
+});
+
+describe("ByteRingBuffer", () => {
+  it("replays chunks after a seq and flags gaps when evicted", () => {
+    const buf = new ByteRingBuffer(10);
+    buf.push(Buffer.from("aaaaa"));
+    buf.push(Buffer.from("bbbbb"));
+    buf.push(Buffer.from("ccccc"));
+    const { entries, hasGap } = buf.replay(0);
+    expect(entries.length).toBeGreaterThanOrEqual(1);
+    expect(hasGap).toBe(true);
+  });
+});
+
+describe("normalizeBundlePath", () => {
+  it("strips leading slashes and keeps nested paths", () => {
+    expect(normalizeBundlePath("/a/b.yaml")).toBe("a/b.yaml");
+    expect(normalizeBundlePath("a/b.yaml")).toBe("a/b.yaml");
+  });
+
+  it("rejects traversal", () => {
+    expect(() => normalizeBundlePath("../x")).toThrow(BundlePathError);
+    expect(() => normalizeBundlePath("a/../../x")).toThrow(BundlePathError);
+  });
+
+  it("validates sessionIds", () => {
+    expect(() => validateSessionId("ok-123_AB")).not.toThrow();
+    expect(() => validateSessionId("../bad")).toThrow(BundlePathError);
+  });
+});

package/src/session/ring-buffer.ts

@@ -0,0 +1,75 @@
+import type { RunEvent } from "../contract.js";
+
+export interface BufferedEvent {
+  id: number;
+  event: RunEvent;
+  bytes: number;
+}
+
+/**
+ * Byte-capped FIFO ring buffer for SSE replay. Each entry tracks its
+ * serialized byte size; when a new entry would push total bytes past the cap,
+ * oldest entries are evicted until it fits. Entries are never split.
+ *
+ * Ids are assigned monotonically starting at 1 — never reused, never reset.
+ * A client's `Last-Event-ID: <n>` asks for events with id > n; if the oldest
+ * remaining id is still > n+1, the gap must be signaled separately.
+ */
+export class EventRingBuffer {
+  private readonly entries: BufferedEvent[] = [];
+  private totalBytes = 0;
+  private nextId = 1;
+
+  constructor(private readonly maxBytes: number) {
+    if (!Number.isInteger(maxBytes) || maxBytes <= 0) {
+      throw new Error(`EventRingBuffer maxBytes must be a positive integer, got ${maxBytes}`);
+    }
+  }
+
+  push(event: RunEvent): BufferedEvent {
+    const id = this.nextId++;
+    const bytes = Buffer.byteLength(JSON.stringify(event), "utf8");
+    const entry: BufferedEvent = { id, event, bytes };
+    this.entries.push(entry);
+    this.totalBytes += bytes;
+    this.evict();
+    return entry;
+  }
+
+  private evict(): void {
+    // Invariant: always retain at least the most-recently-pushed entry, even
+    // if it alone exceeds maxBytes. A single oversized event (a huge log
+    // chunk) is still more useful to a reconnecting client than an empty
+    // buffer, and the alternative (drop-and-gap) would surface as a spurious
+    // "earlier output truncated" banner immediately after a big write.
+    while (this.totalBytes > this.maxBytes && this.entries.length > 1) {
+      const dropped = this.entries.shift();
+      if (!dropped) break;
+      this.totalBytes -= dropped.bytes;
+    }
+  }
+
+  /**
+   * Returns entries with id > afterId, in insertion order.
+   * If `hasGap` is true, the caller should emit a `gap` marker before replay
+   * because events between afterId+1 and the first returned id have been evicted.
+   */
+  replay(afterId: number): { entries: BufferedEvent[]; hasGap: boolean } {
+    const entries = this.entries.filter((e) => e.id > afterId);
+    const oldestId = this.entries[0]?.id ?? this.nextId;
+    const hasGap = afterId + 1 < oldestId;
+    return { entries, hasGap };
+  }
+
+  get size(): number {
+    return this.entries.length;
+  }
+
+  get bytes(): number {
+    return this.totalBytes;
+  }
+
+  get latestId(): number {
+    return this.nextId - 1;
+  }
+}

package/src/session/session-id.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+
+import { generateSessionId } from "./session-id.js";
+
+describe("generateSessionId", () => {
+  it("is a 12-char lowercase base32 string, valid as a DNS label and k8s name", () => {
+    for (let i = 0; i < 1000; i++) {
+      expect(generateSessionId()).toMatch(/^[a-z2-7]{12}$/);
+    }
+  });
+
+  it("does not repeat across many draws", () => {
+    const ids = new Set<string>();
+    for (let i = 0; i < 10000; i++) ids.add(generateSessionId());
+    expect(ids.size).toBe(10000);
+  });
+});

package/src/session/session-id.ts

@@ -0,0 +1,20 @@
+import { randomBytes } from "node:crypto";
+
+// Lowercase RFC 4648 base32 alphabet. Every character is valid in a DNS label
+// and an RFC 1123 Kubernetes resource name, so the id drops straight into both
+// `<id>.<domain>` session hostnames and `telo-run-<id>` container/pod names.
+const ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+
+// 12 chars × 5 bits ≈ 60 bits of entropy. Collisions are negligible across the
+// concurrently-active session set (there is no dedup check, so the id must be
+// unique on its own) while staying far shorter than the previous UUID.
+const SESSION_ID_LENGTH = 12;
+
+/** Generates a short, DNS- and Kubernetes-safe session id. */
+export function generateSessionId(): string {
+  const bytes = randomBytes(SESSION_ID_LENGTH);
+  let id = "";
+  // 256 is a multiple of 32, so `byte % 32` indexes the alphabet without bias.
+  for (let i = 0; i < SESSION_ID_LENGTH; i++) id += ALPHABET[bytes[i] % 32];
+  return id;
+}

package/src/sse/channel.ts

@@ -0,0 +1,154 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+import { isTerminal } from "../contract.js";
+import { SessionEvictedError, type SessionRegistry } from "../session/registry.js";
+import type { BufferedEvent } from "../session/ring-buffer.js";
+
+const HEARTBEAT_MS = 20_000;
+
+export interface SseStreamArgs {
+  registry: SessionRegistry;
+  req: FastifyRequest;
+  reply: FastifyReply;
+  sessionId: string;
+  corsOrigins: string[] | "*";
+}
+
+export async function streamSessionEvents(args: SseStreamArgs): Promise<void> {
+  const { registry, req, reply, sessionId, corsOrigins } = args;
+  const entry = registry.get(sessionId);
+  if (!entry) {
+    reply.code(404).send({ error: "not_found", message: `session '${sessionId}' not in registry` });
+    return;
+  }
+
+  const lastEventId = resolveLastEventId(req);
+  const raw = reply.raw;
+
+  // @fastify/cors adds Access-Control-Allow-Origin via an onSend hook, which
+  // never fires for this route because we bypass reply and write directly to
+  // reply.raw. Inject the CORS headers manually from our config.
+  const headers: Record<string, string> = {
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache, no-transform",
+    connection: "keep-alive",
+    "x-accel-buffering": "no",
+  };
+  const allowOrigin = resolveAllowOrigin(corsOrigins, req.headers.origin);
+  if (allowOrigin) {
+    headers["access-control-allow-origin"] = allowOrigin;
+    headers["vary"] = "Origin";
+  }
+
+  raw.writeHead(200, headers);
+
+  // Replay any buffered history > lastEventId. `hasGap` triggers a synthetic
+  // gap marker so the client knows earlier output was evicted before we could
+  // deliver it.
+  const { entries, hasGap } = entry.buffer.replay(lastEventId);
+  if (hasGap) {
+    writeFrame(raw, "gap", { reason: "buffer_evicted" });
+  }
+  for (const buffered of entries) {
+    writeBufferedEvent(raw, buffered);
+  }
+
+  // If the session already reached a terminal status before the client hit
+  // /events, replay has delivered the terminal status frame and we're done.
+  if (isTerminal(entry.status)) {
+    raw.end();
+    return;
+  }
+
+  let unsubscribe: (() => void) | null = null;
+  let heartbeat: NodeJS.Timeout | null = null;
+  let closed = false;
+
+  const cleanup = (): void => {
+    if (closed) return;
+    closed = true;
+    if (heartbeat) clearInterval(heartbeat);
+    if (unsubscribe) unsubscribe();
+    if (!raw.writableEnded) raw.end();
+  };
+
+  heartbeat = setInterval(() => {
+    if (!raw.writableEnded) raw.write(": heartbeat\n\n");
+  }, HEARTBEAT_MS);
+  heartbeat.unref?.();
+
+  try {
+    unsubscribe = registry.subscribe(sessionId, (buffered) => {
+      writeBufferedEvent(raw, buffered);
+      if (buffered.event.type === "status" && isTerminal(buffered.event.status)) {
+        cleanup();
+      }
+    });
+  } catch (err) {
+    if (err instanceof SessionEvictedError) {
+      cleanup();
+      return;
+    }
+    throw err;
+  }
+
+  req.raw.on("close", cleanup);
+  req.raw.on("end", cleanup);
+
+  // Keep the response alive — Fastify's handler must not return until the
+  // stream closes, otherwise it sends a default end.
+  await new Promise<void>((resolve) => {
+    raw.on("close", resolve);
+    raw.on("finish", resolve);
+  });
+}
+
+function resolveLastEventId(req: FastifyRequest): number {
+  // Spec: header wins over query. EventSource sets the header on native
+  // auto-reconnect; the query param is for fresh instances (tab reload) where
+  // sse-client.ts passes the persisted id explicitly.
+  const header = req.headers["last-event-id"];
+  const fromHeader = parseId(Array.isArray(header) ? header[0] : header);
+  if (fromHeader !== null) return fromHeader;
+
+  const query = req.query as { lastEventId?: string } | undefined;
+  const fromQuery = parseId(query?.lastEventId);
+  return fromQuery ?? 0;
+}
+
+function resolveAllowOrigin(
+  corsOrigins: string[] | "*",
+  requestOrigin: string | string[] | undefined,
+): string | null {
+  if (corsOrigins === "*") return "*";
+  const origin = Array.isArray(requestOrigin) ? requestOrigin[0] : requestOrigin;
+  if (!origin) return null;
+  return corsOrigins.includes(origin) ? origin : null;
+}
+
+function parseId(raw: string | undefined): number | null {
+  if (!raw) return null;
+  const n = Number.parseInt(raw, 10);
+  // `Last-Event-ID: 0` is valid per the SSE spec — it means "resume from the
+  // beginning." Our ids start at 1, so replay(0) returns all buffered entries
+  // and the hasGap check correctly compares against first-resident-id.
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+function writeBufferedEvent(raw: NodeJS.WritableStream, buffered: BufferedEvent): void {
+  writeFrame(raw, buffered.event.type, buffered.event, buffered.id);
+}
+
+function writeFrame(
+  raw: NodeJS.WritableStream,
+  event: string,
+  data: unknown,
+  id?: number,
+): void {
+  if (!("writable" in raw) || (raw as { writableEnded?: boolean }).writableEnded) return;
+  let frame = "";
+  if (id !== undefined) frame += `id: ${id}\n`;
+  frame += `event: ${event}\n`;
+  frame += `data: ${JSON.stringify(data)}\n\n`;
+  raw.write(frame);
+}