@jmoyers/harness 0.1.0

package/src/pty/pty_host.ts

@@ -0,0 +1,217 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  isPerfCoreEnabled,
+  perfNowNs,
+  recordPerfDuration,
+  recordPerfEvent,
+  startPerfSpan,
+} from '../perf/perf-core.ts';
+
+const OPCODE_DATA = 0x01;
+const OPCODE_RESIZE = 0x02;
+const OPCODE_CLOSE = 0x03;
+
+const DEFAULT_COMMAND = '/bin/sh';
+const DEFAULT_COMMAND_ARGS = ['-i'];
+const DEFAULT_HELPER_PATH_CANDIDATES = [
+  join(dirname(fileURLToPath(import.meta.url)), '../../native/ptyd/target/release/ptyd'),
+  join(dirname(fileURLToPath(import.meta.url)), '../../bin/ptyd'),
+] as const;
+
+interface StartPtySessionOptions {
+  command?: string;
+  commandArgs?: string[];
+  env?: NodeJS.ProcessEnv;
+  cwd?: string;
+  helperPath?: string;
+  initialCols?: number;
+  initialRows?: number;
+}
+
+export interface PtyExit {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+}
+
+export function resolvePtyHelperPath(
+  helperPath: string | undefined,
+  helperPathCandidates: readonly string[] = DEFAULT_HELPER_PATH_CANDIDATES,
+  pathExists: (path: string) => boolean = existsSync,
+): string {
+  if (typeof helperPath === 'string' && helperPath.length > 0) {
+    return helperPath;
+  }
+  for (const candidate of helperPathCandidates) {
+    if (pathExists(candidate)) {
+      return candidate;
+    }
+  }
+  const fallback = helperPathCandidates[0];
+  if (fallback === undefined) {
+    throw new Error('pty helper path candidates must include at least one path');
+  }
+  return fallback;
+}
+
+class PtySession extends EventEmitter {
+  private readonly child: ChildProcessWithoutNullStreams;
+  private readonly pendingRoundtripProbes: Array<{
+    probeId: number;
+    payloadLength: number;
+    matchPayloads: Buffer[];
+    startedAtNs: bigint;
+  }> = [];
+  private nextProbeId = 1;
+  private outputWindow = Buffer.alloc(0);
+  private static readonly MAX_OUTPUT_WINDOW_BYTES = 8192;
+
+  constructor(child: ChildProcessWithoutNullStreams) {
+    super();
+    this.child = child;
+
+    child.stdout.on('data', (chunk: Buffer) => {
+      this.emit('data', chunk);
+      this.trackRoundtrip(chunk);
+    });
+
+    child.on('error', (error: Error) => {
+      this.emit('error', error);
+    });
+
+    child.on('exit', (code: number | null, signal: NodeJS.Signals | null) => {
+      this.emit('exit', { code, signal } satisfies PtyExit);
+    });
+  }
+
+  write(data: string | Uint8Array): void {
+    const payload = typeof data === 'string' ? Buffer.from(data, 'utf8') : Buffer.from(data);
+    const frame = Buffer.alloc(1 + 4 + payload.length);
+    frame[0] = OPCODE_DATA;
+    frame.writeUInt32BE(payload.length, 1);
+    payload.copy(frame, 5);
+
+    if (isPerfCoreEnabled() && payload.length > 0 && payload.length <= 256) {
+      this.pendingRoundtripProbes.push({
+        probeId: this.nextProbeId,
+        payloadLength: payload.length,
+        matchPayloads: PtySession.buildMatchPayloads(payload),
+        startedAtNs: perfNowNs(),
+      });
+      this.nextProbeId += 1;
+    }
+
+    const span = startPerfSpan('pty.stdin.write', { bytes: payload.length });
+    this.child.stdin.write(frame, () => {
+      span.end();
+    });
+  }
+
+  resize(cols: number, rows: number): void {
+    const frame = Buffer.alloc(1 + 2 + 2);
+    frame[0] = OPCODE_RESIZE;
+    frame.writeUInt16BE(cols, 1);
+    frame.writeUInt16BE(rows, 3);
+    this.child.stdin.write(frame);
+  }
+
+  close(): void {
+    const frame = Buffer.from([OPCODE_CLOSE]);
+    this.child.stdin.write(frame);
+  }
+
+  processId(): number | null {
+    return typeof this.child.pid === 'number' ? this.child.pid : null;
+  }
+
+  private trackRoundtrip(chunk: Buffer): void {
+    if (!isPerfCoreEnabled()) {
+      return;
+    }
+
+    recordPerfEvent('pty.stdout.chunk', { bytes: chunk.length });
+
+    if (this.pendingRoundtripProbes.length === 0) {
+      return;
+    }
+
+    this.outputWindow =
+      this.outputWindow.length === 0
+        ? Buffer.from(chunk)
+        : Buffer.concat([this.outputWindow, chunk]);
+    if (this.outputWindow.length > PtySession.MAX_OUTPUT_WINDOW_BYTES) {
+      this.outputWindow = this.outputWindow.subarray(
+        this.outputWindow.length - PtySession.MAX_OUTPUT_WINDOW_BYTES,
+      );
+    }
+
+    let idx = 0;
+    while (idx < this.pendingRoundtripProbes.length) {
+      const probe = this.pendingRoundtripProbes[idx];
+      if (
+        probe !== undefined &&
+        probe.matchPayloads.some((matchPayload) => this.outputWindow.includes(matchPayload))
+      ) {
+        recordPerfDuration('pty.keystroke.roundtrip', probe.startedAtNs, {
+          'probe-id': probe.probeId,
+          bytes: probe.payloadLength,
+        });
+        this.pendingRoundtripProbes.splice(idx, 1);
+        continue;
+      }
+      idx += 1;
+    }
+  }
+
+  private static buildMatchPayloads(payload: Buffer): Buffer[] {
+    if (!payload.includes(0x0a)) {
+      return [payload];
+    }
+
+    const crlfPayload = Buffer.alloc(
+      payload.length + payload.filter((byte) => byte === 0x0a).length,
+    );
+    let writeIdx = 0;
+    for (const byte of payload.values()) {
+      if (byte === 0x0a) {
+        crlfPayload[writeIdx] = 0x0d;
+        writeIdx += 1;
+      }
+      crlfPayload[writeIdx] = byte;
+      writeIdx += 1;
+    }
+
+    return [payload, crlfPayload];
+  }
+}
+
+export function startPtySession(options: StartPtySessionOptions = {}): PtySession {
+  const command = options.command ?? DEFAULT_COMMAND;
+  const commandArgs = options.commandArgs ?? DEFAULT_COMMAND_ARGS;
+  const env = options.env ?? process.env;
+  const cwd = options.cwd;
+  const helperPath = resolvePtyHelperPath(options.helperPath);
+
+  const child = spawn(helperPath, [command, ...commandArgs], {
+    cwd,
+    env,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  const session = new PtySession(child);
+  if (
+    typeof options.initialCols === 'number' &&
+    Number.isFinite(options.initialCols) &&
+    options.initialCols > 0 &&
+    typeof options.initialRows === 'number' &&
+    Number.isFinite(options.initialRows) &&
+    options.initialRows > 0
+  ) {
+    session.resize(Math.floor(options.initialCols), Math.floor(options.initialRows));
+  }
+
+  return session;
+}

package/src/pty/session-broker.ts

@@ -0,0 +1,158 @@
+import { startPtySession, type PtyExit } from './pty_host.ts';
+
+interface BacklogEntry {
+  cursor: number;
+  chunk: Buffer;
+}
+
+export interface BrokerDataEvent {
+  cursor: number;
+  chunk: Buffer;
+}
+
+export interface BrokerAttachmentHandlers {
+  onData: (event: BrokerDataEvent) => void;
+  onExit: (exit: PtyExit) => void;
+}
+
+type StartPtySessionOptions = Parameters<typeof startPtySession>[0];
+type StartSessionFactory = (options?: StartPtySessionOptions) => ReturnType<typeof startPtySession>;
+
+interface StartSingleSessionBrokerDependencies {
+  startSession?: StartSessionFactory;
+}
+
+class SingleSessionBroker {
+  private readonly session: ReturnType<typeof startPtySession>;
+  private readonly maxBacklogBytes: number;
+  private readonly attachments = new Map<string, BrokerAttachmentHandlers>();
+  private readonly backlog: BacklogEntry[] = [];
+  private backlogBytes = 0;
+  private nextAttachmentId = 1;
+  private nextCursor = 1;
+  private latestExit: PtyExit | null = null;
+
+  constructor(
+    options?: StartPtySessionOptions,
+    maxBacklogBytes = 256 * 1024,
+    startSession: StartSessionFactory = startPtySession,
+  ) {
+    this.session = startSession(options);
+    this.maxBacklogBytes = maxBacklogBytes;
+
+    this.session.on('data', (chunk: Buffer) => {
+      this.handleData(chunk);
+    });
+
+    this.session.on('exit', (exit: unknown) => {
+      this.handleExit(exit as PtyExit);
+    });
+
+    this.session.on('error', (error: unknown) => {
+      this.handleError(error as Error);
+    });
+  }
+
+  attach(handlers: BrokerAttachmentHandlers, sinceCursor = 0): string {
+    const attachmentId = `attachment-${this.nextAttachmentId}`;
+    this.nextAttachmentId += 1;
+    this.attachments.set(attachmentId, handlers);
+
+    for (const entry of this.backlog) {
+      if (entry.cursor <= sinceCursor) {
+        continue;
+      }
+      handlers.onData({
+        cursor: entry.cursor,
+        chunk: Buffer.from(entry.chunk),
+      });
+    }
+
+    if (this.latestExit !== null) {
+      handlers.onExit(this.latestExit);
+    }
+
+    return attachmentId;
+  }
+
+  detach(attachmentId: string): void {
+    this.attachments.delete(attachmentId);
+  }
+
+  latestCursorValue(): number {
+    return this.nextCursor - 1;
+  }
+
+  write(data: string | Uint8Array): void {
+    this.session.write(data);
+  }
+
+  resize(cols: number, rows: number): void {
+    this.session.resize(cols, rows);
+  }
+
+  close(): void {
+    this.session.close();
+  }
+
+  processId(): number | null {
+    return this.session.processId();
+  }
+
+  private handleData(chunk: Buffer): void {
+    const fullChunk = Buffer.from(chunk);
+    let storedChunk = fullChunk;
+    if (storedChunk.length > this.maxBacklogBytes) {
+      storedChunk = storedChunk.subarray(storedChunk.length - this.maxBacklogBytes);
+      this.backlog.length = 0;
+      this.backlogBytes = 0;
+    }
+
+    const entry: BacklogEntry = {
+      cursor: this.nextCursor,
+      chunk: storedChunk,
+    };
+    this.nextCursor += 1;
+
+    this.backlog.push(entry);
+    this.backlogBytes += entry.chunk.length;
+    while (this.backlogBytes > this.maxBacklogBytes && this.backlog.length > 0) {
+      const removed = this.backlog.shift()!;
+      this.backlogBytes -= removed.chunk.length;
+    }
+
+    for (const handlers of this.attachments.values()) {
+      handlers.onData({
+        cursor: entry.cursor,
+        chunk: Buffer.from(fullChunk),
+      });
+    }
+  }
+
+  private handleExit(exit: PtyExit): void {
+    if (this.latestExit !== null) {
+      return;
+    }
+    this.latestExit = exit;
+    for (const handlers of this.attachments.values()) {
+      handlers.onExit(exit);
+    }
+  }
+
+  private handleError(error: Error): void {
+    void error;
+    this.handleExit({
+      code: null,
+      signal: null,
+    });
+  }
+}
+
+export function startSingleSessionBroker(
+  options?: StartPtySessionOptions,
+  maxBacklogBytes?: number,
+  dependencies: StartSingleSessionBrokerDependencies = {},
+): SingleSessionBroker {
+  const startSession = dependencies.startSession ?? startPtySession;
+  return new SingleSessionBroker(options, maxBacklogBytes, startSession);
+}