@henols/c64-re-tools 1.1.0 → 2.0.0-rc.3

package/src/host/main.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env tsx
+
+import { parseArgs } from "node:util";
+
+import { DEFAULT_HOST_PORT } from "../protocol/messages.ts";
+import { ProcessSupervisor } from "../native/processes.ts";
+import { startTrace, trace } from "../trace.ts";
+import { ListenError, parsePort, startHostServer, stopSignal } from "./server.ts";
+import { createToolDispatcher } from "./tools/index.ts";
+import { checkViceStarts, findVice } from "./vice/process.ts";
+import { viceSessionFactory } from "./vice/session.ts";
+
+const HELP = `c64-re-tools-host
+
+Usage:
+  npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host [--port <port>]
+  c64-re-tools-host --help
+
+Runs the c64-re-tools Host Runtime in the foreground. It first starts VICE
+once (x64sc on PATH, or C64RT_VICE) and does not start if VICE cannot run.
+It listens on port ${DEFAULT_HOST_PORT} on every address, so a dev container
+reaches it as host.docker.internal. It starts one VICE emulator for each
+connected c64-re-tools-mcp process, and runs the tools that come with VICE
+(c1541, petcat) for skill scripts. Stop it with Ctrl+C; that stops every
+emulator and tool it started.
+
+Options:
+  --port <port>       Listen on this port instead (0 picks a free port).
+  --help              Show this help.`;
+
+function log(line: string): void {
+  process.stderr.write(`c64-re-tools-host: ${line}\n`);
+  trace().log(line);
+}
+
+async function main(): Promise<number> {
+  let values: { help?: boolean; port?: string };
+  try {
+    ({ values } = parseArgs({ options: { help: { type: "boolean" }, port: { type: "string" } }, strict: true }));
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${HELP}\n`);
+    return 2;
+  }
+  if (values.help) {
+    process.stdout.write(`${HELP}\n`);
+    return 0;
+  }
+  startTrace("host", { warn: log });
+
+  const port = values.port === undefined ? DEFAULT_HOST_PORT : parsePort(values.port);
+  if (port === undefined) {
+    process.stderr.write(`--port must be a number from 0 to 65535, written with digits only. You gave "${values.port}".\n`);
+    return 2;
+  }
+
+  // Without an emulator the runtime is useless: refuse to start, by name and with the remedy.
+  try {
+    findVice(process.env);
+  } catch (error) {
+    process.stderr.write(`${(error as Error).message}\n`);
+    return 1;
+  }
+
+  // Every emulator and tool is started through this one supervisor; however
+  // this process ends, the exit guard takes their process groups down with it,
+  // and the watchdog does the same if this process is killed.
+  const supervisor = new ProcessSupervisor();
+  supervisor.startWatchdog("host");
+
+  // Finding x64sc is not enough: VICE without its ROM files exits at once.
+  try {
+    await checkViceStarts({ supervisor });
+  } catch (error) {
+    process.stderr.write(`${(error as Error).message}\n`);
+    await supervisor.stopAll();
+    return 1;
+  }
+  log("VICE starts");
+
+  let server;
+  try {
+    server = await startHostServer({
+      host: "0.0.0.0",
+      port,
+      log,
+      createViceSession: viceSessionFactory({ supervisor, log }),
+      tools: createToolDispatcher({ supervisor, log }),
+    });
+  } catch (error) {
+    if (error instanceof ListenError && error.code === "EADDRINUSE") {
+      process.stderr.write(`Port ${error.port} on ${error.address} is in use. Is another c64-re-tools-host running?\n`);
+      return 1;
+    }
+    throw error;
+  }
+  const address = `${server.host}:${server.port}`;
+  process.stdout.write(`c64-re-tools-host listening on ${address}\n`);
+  trace().event("host.listening", { addresses: [address] });
+
+  trace().event("host.stop", { signal: await stopSignal(log) });
+  await server.close();
+  await supervisor.stopAll();
+  return 0;
+}
+
+process.exitCode = await main();

package/src/host/server.ts

@@ -0,0 +1,376 @@
+import { createServer, type Server, type Socket } from "node:net";
+
+import { encodeFrame, MessageReader } from "../protocol/framing.ts";
+import { checkHello, isOneOf, HEARTBEAT_TIMEOUT_MS, parseClientMessage, ProtocolError, type HostMessage, type ReceivedRequest, type VideoStandard, type WireError, WireFailure } from "../protocol/messages.ts";
+import { TOOL_OPERATIONS, validateToolParams, type ToolOperation, type ToolOperations } from "../protocol/tools.ts";
+import { attachmentCount, VICE_OPERATIONS, validateViceParams, type ViceOperation, type ViceOperations } from "../protocol/vice.ts";
+import { elapsedMs, trace } from "../trace.ts";
+
+/** One live VICE session, owned by one connection. */
+export interface ViceSessionHandle {
+  /**
+   * Runs one operation. The session serializes its own work. Throws
+   * WireFailure for domain failures. `attachments` holds the bytes the
+   * operation takes (see attachmentCount).
+   */
+  handle<O extends ViceOperation>(op: O, params: ViceOperations[O]["params"], attachments?: Buffer[]): Promise<ViceOperations[O]["result"]>;
+  /** Stops the emulator and drops queued work. Safe to call more than once. */
+  close(): Promise<void>;
+}
+
+/** Starts a VICE session. Throws WireFailure with an actionable code when it cannot. */
+export type ViceSessionFactory = (options: { videoStandard: VideoStandard }) => Promise<ViceSessionHandle>;
+
+/**
+ * Runs one native-tool request. `signal` aborts when the client goes away; the
+ * tool must then stop its children and remove its workspace. Throws WireFailure.
+ */
+export type ToolDispatcher = <O extends ToolOperation>(
+  op: O,
+  params: ToolOperations[O]["params"],
+  attachments: Buffer[],
+  signal: AbortSignal,
+) => Promise<{ result: ToolOperations[O]["result"]; attachments?: Buffer[] }>;
+
+export interface HostServerOptions {
+  createViceSession: ViceSessionFactory;
+  /** Native-tool requests on "tool" connections; without it they are refused. */
+  tools?: ToolDispatcher;
+  /** Defaults to 127.0.0.1; 0.0.0.0 listens on every address, so a container reaches it too. */
+  host?: string;
+  /** 0 picks a free port. */
+  port: number;
+  /** How long a new connection may stay silent before it must send hello. */
+  handshakeTimeoutMs?: number;
+  /** How long a ready connection may send nothing (no request, no ping) before it is closed with its session. */
+  heartbeatTimeoutMs?: number;
+  log?: (line: string) => void;
+}
+
+export interface HostServer {
+  readonly host: string;
+  readonly port: number;
+  /** Stops listening, closes every connection and stops every session. */
+  close(): Promise<void>;
+}
+
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000;
+/** How long a refused client may keep its side of the connection open after the host has ended its side. */
+const REFUSED_CLOSE_MS = 1_000;
+
+/** A caught value for the log, with its stack when it has one. */
+function describe(error: unknown): string {
+  return error instanceof Error ? (error.stack ?? error.message) : String(error);
+}
+
+function toWireError(error: unknown, fallback: WireError): WireError {
+  return error instanceof WireFailure ? error.toWire() : fallback;
+}
+
+/** Numbers the connections of this process, for the trace. */
+let connectionCount = 0;
+
+/** Owns one client connection: handshake, then requests against at most one VICE session. */
+class Connection {
+  readonly closed: Promise<void>;
+  readonly #id = ++connectionCount;
+  #state: "handshake" | "starting" | "open" | "closed" = "handshake";
+  #session: ViceSessionHandle | undefined;
+  #starting: Promise<ViceSessionHandle | undefined> | undefined;
+  #shuttingDown = false;
+  readonly #toolAbort = new AbortController();
+  #isTool = false;
+  readonly #reader = new MessageReader();
+
+  readonly #socket: Socket;
+  readonly #options: HostServerOptions;
+  readonly #log: (line: string) => void;
+  readonly #handshakeTimer: NodeJS.Timeout;
+  /** Runs from ready on; every received frame restarts it. */
+  #heartbeatTimer: NodeJS.Timeout | undefined;
+  #refusedTimer: NodeJS.Timeout | undefined;
+  #resolveClosed!: () => void;
+
+  constructor(socket: Socket, options: HostServerOptions, log: (line: string) => void) {
+    this.#socket = socket;
+    this.#options = options;
+    this.#log = log;
+    this.closed = new Promise((resolve) => (this.#resolveClosed = resolve));
+    trace().event("connection.open", { connection: this.#id, remote: `${socket.remoteAddress}:${socket.remotePort}`, local: socket.localAddress });
+    this.#handshakeTimer = setTimeout(
+      () => this.#abort("no hello before the handshake timeout"),
+      options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS,
+    );
+    socket.setNoDelay(true);
+    // The kernel also probes an idle connection, for a peer that vanished without a close.
+    socket.setKeepAlive(true, 10_000);
+    socket.on("data", (chunk) => this.#receive(chunk));
+    socket.on("error", (error) => this.#log(`connection error: ${error.message}`));
+    socket.on("close", () => void this.#shutdown());
+  }
+
+  /** Closes the connection and its session. */
+  close(): Promise<void> {
+    this.#socket.destroy();
+    return this.closed;
+  }
+
+  /**
+   * A client that sends nothing for the heartbeat timeout is gone or hung (a
+   * half-open connection never closes by itself): close it, and with it its
+   * session and emulator.
+   */
+  #restartHeartbeat(): void {
+    if (this.#state !== "open") return;
+    clearTimeout(this.#heartbeatTimer);
+    const timeout = this.#options.heartbeatTimeoutMs ?? HEARTBEAT_TIMEOUT_MS;
+    this.#heartbeatTimer = setTimeout(() => this.#abort(`no message or ping for ${timeout} ms; the client is gone`), timeout);
+  }
+
+  #send(message: HostMessage, attachments: readonly Uint8Array[] = []): void {
+    if (this.#state !== "closed" && !this.#socket.destroyed) this.#socket.write(encodeFrame(message, attachments));
+  }
+
+  /** Ends the host's side after a refusal; a client that does not close its side in time is cut off. */
+  #endRefused(): void {
+    this.#socket.end();
+    this.#refusedTimer = setTimeout(() => this.#abort("the refused client did not close the connection"), REFUSED_CLOSE_MS);
+  }
+
+  #abort(reason: string): void {
+    this.#log(`closing connection: ${reason}`);
+    this.#socket.destroy();
+  }
+
+  #receive(chunk: Buffer): void {
+    this.#restartHeartbeat();
+    try {
+      for (const { message, attachments } of this.#reader.push(chunk)) {
+        if (this.#state === "closed") return;
+        this.#dispatch(message, attachments);
+      }
+    } catch (error) {
+      // Any failure closes only this connection; the listener and the other connections go on.
+      if (error instanceof ProtocolError) this.#abort(`protocol error: ${error.message}`);
+      else this.#abort(`internal error: ${describe(error)}`);
+    }
+  }
+
+  /** Closes this connection when work that runs after its message fails in an unexpected way. */
+  #contain(work: Promise<void>): void {
+    work.catch((error: unknown) => this.#abort(`internal error: ${describe(error)}`));
+  }
+
+  #dispatch(raw: unknown, attachments: Buffer[]): void {
+    const message = parseClientMessage(raw);
+    if (this.#state === "handshake") {
+      if (message.type !== "hello") throw new ProtocolError("first message is not hello");
+      clearTimeout(this.#handshakeTimer);
+      const mismatch = checkHello(message);
+      if (mismatch !== undefined) {
+        this.#log(`refusing a client: ${mismatch.message}`);
+        trace().event("connection.refused", { connection: this.#id, role: message.role, ...mismatch });
+        this.#send({ type: "error", error: mismatch });
+        this.#endRefused();
+        this.#state = "closed";
+        return;
+      }
+      if (message.role === "tool") {
+        this.#isTool = true;
+        this.#state = "open";
+        this.#send({ type: "ready" });
+        trace().event("connection.ready", { connection: this.#id, role: "tool" });
+        this.#restartHeartbeat();
+        return;
+      }
+      this.#state = "starting";
+      this.#contain(this.#startSession(message.videoStandard ?? "pal"));
+      return;
+    }
+    if (message.type === "hello") throw new ProtocolError("hello sent twice");
+    if (this.#state !== "open") throw new ProtocolError(`${message.type} sent before ready`);
+    if (message.type === "ping") {
+      this.#send({ type: "pong" });
+      return;
+    }
+    this.#contain(this.#answer(message, attachments));
+  }
+
+  async #startSession(videoStandard: VideoStandard): Promise<void> {
+    const started = performance.now();
+    this.#starting = this.#createSession(videoStandard);
+    const session = await this.#starting;
+    // A connection closed while starting is shut down by #shutdown, which awaits #starting.
+    if (session === undefined || this.#state === "closed") return;
+    this.#session = session;
+    this.#state = "open";
+    this.#send({ type: "ready" });
+    trace().event("connection.ready", { connection: this.#id, role: "vice-session", videoStandard, ms: elapsedMs(started) });
+    this.#restartHeartbeat();
+  }
+
+  /** The new session, or undefined after the failure is sent to the client. Never rejects, also when the factory throws at once. */
+  async #createSession(videoStandard: VideoStandard): Promise<ViceSessionHandle | undefined> {
+    try {
+      return await this.#options.createViceSession({ videoStandard });
+    } catch (error) {
+      this.#log(`VICE session failed to start: ${error instanceof Error ? error.message : String(error)}`);
+      trace().event("connection.session-failed", { connection: this.#id, error });
+      this.#send({
+        type: "error",
+        error: toWireError(error, { code: "machine-unavailable", message: "The emulator could not be started." }),
+      });
+      this.#endRefused();
+      return undefined;
+    }
+  }
+
+  async #answer(request: ReceivedRequest, attachments: Buffer[]): Promise<void> {
+    const started = performance.now();
+    const record = (outcome: Record<string, unknown>) =>
+      trace().event("request", { connection: this.#id, op: request.op, id: request.id, params: request.params, attachments: attachments.length, ms: elapsedMs(started), ...outcome });
+    try {
+      let result: unknown;
+      let replyAttachments: Buffer[] = [];
+      if (this.#isTool) {
+        const { op } = request;
+        const tools = this.#options.tools;
+        if (!isOneOf(TOOL_OPERATIONS, op) || tools === undefined) throw new WireFailure("invalid-input", `unknown operation: ${op}`);
+        const params = validateToolParams(op, request.params, attachments);
+        const answer = await tools(op, params, attachments, this.#toolAbort.signal);
+        result = answer.result;
+        replyAttachments = answer.attachments ?? [];
+      } else {
+        const { op } = request;
+        const session = this.#session;
+        if (session === undefined || !isOneOf(VICE_OPERATIONS, op)) throw new WireFailure("invalid-input", `unknown operation: ${op}`);
+        const params = validateViceParams(op, request.params);
+        if (attachments.length !== attachmentCount(op)) {
+          throw new WireFailure("invalid-input", `${op} takes ${attachmentCount(op)} file attachment(s)`);
+        }
+        result = await session.handle(op, params, attachments);
+      }
+      this.#send({ type: "reply", id: request.id, result }, replyAttachments);
+      record({ ok: true, result });
+    } catch (error) {
+      if (!(error instanceof WireFailure)) {
+        this.#log(`operation ${request.op} failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+      }
+      const wire = toWireError(error, { code: "operation-failed", message: "The operation failed inside the host runtime." });
+      this.#send({ type: "reply", id: request.id, error: wire });
+      record({ ok: false, ...wire });
+    }
+  }
+
+  async #shutdown(): Promise<void> {
+    if (this.#shuttingDown) return;
+    this.#shuttingDown = true;
+    this.#state = "closed";
+    trace().event("connection.close", { connection: this.#id });
+    clearTimeout(this.#handshakeTimer);
+    clearTimeout(this.#heartbeatTimer);
+    clearTimeout(this.#refusedTimer);
+    // Tool work for a client that is gone stops: its children and workspaces go too.
+    this.#toolAbort.abort();
+    const session = this.#session ?? (await this.#starting);
+    this.#session = undefined;
+    try {
+      await session?.close();
+    } catch (error) {
+      this.#log(`session close failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    this.#resolveClosed();
+  }
+}
+
+/** A port as the user gives it: decimal digits only, 0 to 65535. Anything else gives undefined. */
+export function parsePort(text: string): number | undefined {
+  if (!/^\d{1,5}$/.test(text)) return undefined;
+  const port = Number(text);
+  return port <= 0xffff ? port : undefined;
+}
+
+/**
+ * Resolves with the first SIGINT or SIGTERM. The handlers stay: a later
+ * signal is logged and ignored, so a second Ctrl+C cannot cut the shutdown
+ * short before every emulator and tool is stopped.
+ */
+export function stopSignal(log: (line: string) => void): Promise<NodeJS.Signals> {
+  return new Promise((resolve) => {
+    let stopping = false;
+    const stop = (signal: NodeJS.Signals) => {
+      if (stopping) {
+        log(`received ${signal} again; the host is already stopping`);
+        return;
+      }
+      stopping = true;
+      log(`received ${signal}, stopping`);
+      resolve(signal);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  });
+}
+
+/** A listener that could not start, with the address and the port it tried and the system error code. */
+export class ListenError extends Error {
+  readonly code: string | undefined;
+  readonly address: string;
+  readonly port: number;
+
+  constructor(cause: unknown, address: string, port: number) {
+    super(`cannot listen on ${address} port ${port}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    this.name = "ListenError";
+    this.code = (cause as NodeJS.ErrnoException | undefined)?.code;
+    this.address = address;
+    this.port = port;
+  }
+}
+
+/** Starts the Host Runtime listener. Each connection owns at most one VICE session. */
+export async function startHostServer(options: HostServerOptions): Promise<HostServer> {
+  const log = options.log ?? (() => {});
+  const host = options.host ?? "127.0.0.1";
+  const connections = new Set<Connection>();
+  const servers: Server[] = [];
+  const listen = (address: string, port: number) => {
+    const server: Server = createServer((socket) => {
+      const connection = new Connection(socket, options, log);
+      connections.add(connection);
+      void connection.closed.then(() => connections.delete(connection));
+    });
+    servers.push(server);
+    return new Promise<number>((resolve, reject) => {
+      const failed = (error: Error) => reject(new ListenError(error, address, port));
+      server.once("error", failed);
+      server.listen({ host: address, port, exclusive: true }, () => {
+        server.off("error", failed);
+        const bound = server.address();
+        if (bound === null || typeof bound === "string") reject(new Error("listener has no TCP address"));
+        else resolve(bound.port);
+      });
+    });
+  };
+
+  let port: number;
+  try {
+    port = await listen(host, options.port);
+  } catch (error) {
+    await Promise.all(servers.map((server) => new Promise<void>((resolve) => server.close(() => resolve()))));
+    throw error;
+  }
+
+  let closing: Promise<void> | undefined;
+  return {
+    host,
+    port,
+    close() {
+      closing ??= (async () => {
+        const stopped = Promise.all(servers.map((server) => new Promise<void>((resolve) => server.close(() => resolve()))));
+        await Promise.all([...connections].map((connection) => connection.close()));
+        await stopped;
+      })();
+      return closing;
+    },
+  };
+}