@hermit-org/stdio-to-sse 0.0.1-alpha.0

package/src/server.test.ts

@@ -0,0 +1,375 @@
+import { describe, test, expect } from "bun:test";
+import { StdioSseServer, StdioSseClient } from "./index";
+
+async function getFreePort(): Promise<number> {
+  // Use a random high port to avoid collisions during parallel test runs.
+  return 10000 + Math.floor(Math.random() * 30000);
+}
+
+describe("StdioSseServer", () => {
+  test("bridges stdin and stdout over HTTP POST -> SSE", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({ command: "cat", port });
+    const { url, stop } = await server.start();
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("hello\nworld")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual(["hello", "world"]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("supports a custom endpoint path", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({
+      command: "cat",
+      port,
+      endpoint: "/bridge",
+    });
+    const { url, stop } = await server.start();
+
+    try {
+      expect(url).toEndWith("/bridge");
+
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("ping")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual(["ping"]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("returns 404 for unmatched paths", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({ command: "cat", port });
+    const { url, stop } = await server.start();
+
+    try {
+      const response = await fetch(`${url}/not-found`, { method: "POST" });
+      expect(response.status).toBe(404);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("returns 404 for non-POST methods", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({ command: "cat", port });
+    const { url, stop } = await server.start();
+
+    try {
+      const response = await fetch(url, { method: "GET" });
+      expect(response.status).toBe(404);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("responds to CORS preflight requests", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({ command: "cat", port });
+    const { url, stop } = await server.start();
+
+    try {
+      const response = await fetch(url, { method: "OPTIONS" });
+      expect(response.status).toBe(204);
+      expect(response.headers.get("access-control-allow-origin")).toBe("*");
+    } finally {
+      await stop();
+    }
+  });
+
+  test("forwards command arguments to the child process", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({
+      command: "node",
+      args: [
+        "-e",
+        "process.argv.slice(1).forEach(a => console.log(a))",
+        "alpha",
+        "beta",
+      ],
+      port,
+    });
+    const { url, stop } = await server.start();
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("ignored")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual(["alpha", "beta"]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("ends the stream when the child exits with a non-zero code", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({
+      command: "node",
+      args: ["-e", "console.log('ok'); process.exit(1)"],
+      port,
+    });
+    const { url, stop } = await server.start();
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual(["ok"]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("ends the stream when the child crashes", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({
+      command: "node",
+      args: ["-e", "process.stdout.destroy()"],
+      port,
+    });
+    const { url, stop } = await server.start();
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual([]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("does not deadlock when the child writes a large amount to stderr", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({
+      command: "node",
+      args: [
+        "-e",
+        "console.error('x'.repeat(1024 * 1024)); console.log('done')",
+      ],
+      port,
+    });
+    const { url, stop } = await server.start();
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual(["done"]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("kills the child process when the client disconnects", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({
+      command: "node",
+      args: ["-e", "setInterval(() => console.log('tick'), 50)"],
+      port,
+    });
+    const { url, stop } = await server.start();
+
+    const { request } = await import("node:http");
+    const parsedUrl = new URL(url);
+
+    let destroyTimer: ReturnType<typeof setTimeout> | undefined;
+
+    const req = request(
+      {
+        hostname: parsedUrl.hostname,
+        port: parsedUrl.port,
+        path: parsedUrl.pathname,
+        method: "POST",
+        agent: false,
+        headers: { Connection: "close" },
+      },
+      (res) => {
+        res.on("data", () => {
+          // Once we receive the first byte, simulate an abrupt disconnect.
+          if (destroyTimer) clearTimeout(destroyTimer);
+          req.destroy();
+        });
+      },
+    );
+
+    req.end();
+
+    // Fallback destroy in case no data arrives.
+    destroyTimer = setTimeout(() => req.destroy(), 300);
+
+    // Wait for the server to clean up.
+    await new Promise((resolve) => setTimeout(resolve, 400));
+
+    // If the child process were not killed, the request handler would never
+    // finish and stop() would hang. Stopping successfully proves cleanup works.
+    await stop();
+  });
+
+  test("works with an empty request body", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({
+      command: "node",
+      args: [
+        "-e",
+        "process.stdin.resume(); process.stdin.on('end', () => console.log('empty'))",
+      ],
+      port,
+    });
+    const { url, stop } = await server.start();
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual(["empty"]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("isolates concurrent requests", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({
+      command: "node",
+      args: ["-e", "process.stdin.on('data', d => process.stdout.write(d))"],
+      port,
+    });
+    const { url, stop } = await server.start();
+
+    try {
+      const clientA = new StdioSseClient({ url });
+      const clientB = new StdioSseClient({ url });
+
+      const [a, b] = await Promise.all([
+        (async () => {
+          const results: string[] = [];
+          for await (const data of clientA.send("aaa")) {
+            results.push(data);
+          }
+          return results;
+        })(),
+        (async () => {
+          const results: string[] = [];
+          for await (const data of clientB.send("bbb")) {
+            results.push(data);
+          }
+          return results;
+        })(),
+      ]);
+
+      expect(a).toEqual(["aaa"]);
+      expect(b).toEqual(["bbb"]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("terminates the child after the configured timeout", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({
+      command: "node",
+      args: ["-e", "setInterval(() => console.log('tick'), 50)"],
+      port,
+      timeout: 150,
+    });
+    const { url, stop } = await server.start();
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("")) {
+        results.push(data);
+      }
+
+      // The child produces a frame every 50ms and is killed after 150ms.
+      expect(results.length).toBeGreaterThanOrEqual(1);
+      expect(results.length).toBeLessThanOrEqual(5);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("streams a large number of lines without dropping frames", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({
+      command: "node",
+      args: [
+        "-e",
+        "for (let i = 0; i < 100; i++) console.log(String(i).padStart(3, '0'))",
+      ],
+      port,
+    });
+    const { url, stop } = await server.start();
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual(
+        Array.from({ length: 100 }, (_, i) => String(i).padStart(3, "0")),
+      );
+    } finally {
+      await stop();
+    }
+  });
+
+  test("accepts a large request body", async () => {
+    const port = await getFreePort();
+    const server = new StdioSseServer({ command: "cat", port });
+    const { url, stop } = await server.start();
+
+    try {
+      const body = "x".repeat(1024 * 1024);
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send(body)) {
+        results.push(data);
+      }
+
+      expect(results).toEqual([body]);
+    } finally {
+      await stop();
+    }
+  });
+});

package/src/server.ts

@@ -0,0 +1,282 @@
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { spawn, type ChildProcess } from "node:child_process";
+import { createInterface } from "node:readline";
+import { encodeSse, encodeSseKeepAlive } from "./sse";
+
+/**
+ * Configuration for `StdioSseServer`.
+ *
+ * The server spawns a child process (`command` + `args`) and exposes an HTTP
+ * endpoint. Every POST request to that endpoint becomes one invocation: the
+ * request body is written to the child process stdin, and the child process
+ * stdout is streamed back to the client as SSE frames.
+ */
+export interface StdioSseServerOptions {
+  /** Command to spawn (e.g. `"cat"`, `"python"`, `"node"`). */
+  command: string;
+  /** Arguments passed to the command. */
+  args?: string[];
+  /** Port to listen on. */
+  port?: number;
+  /** Hostname to bind to. */
+  hostname?: string;
+  /** HTTP endpoint path (default: `"/"`). */
+  endpoint?: string;
+  /** Enable permissive CORS headers (default: `true`). */
+  cors?: boolean;
+  /** Maximum time in milliseconds to wait for the child process (default: no timeout). */
+  timeout?: number;
+  /**
+   * Heartbeat interval in milliseconds (default: `30000`).
+   *
+   * The server emits SSE comment frames at this interval to keep the HTTP
+   * connection alive through proxies and detect half-open sockets.
+   */
+  heartbeatInterval?: number;
+  /**
+   * Optional hook called for every incoming request before the default
+   * endpoint logic runs. Return `true` (or a promise resolving to `true`) to
+   * indicate that the request has been fully handled and default routing
+   * should be skipped.
+   */
+  onRequest?: (
+    req: IncomingMessage,
+    res: ServerResponse,
+  ) => boolean | Promise<boolean>;
+}
+
+/** State returned after the server starts successfully. */
+export interface StdioSseServerState {
+  /** Full URL of the exposed endpoint. */
+  url: string;
+  /** Stop the HTTP server. */
+  stop: () => Promise<void>;
+}
+
+/**
+ * HTTP server that forwards request bodies to a child process via stdin
+ * and streams the child process stdout back as SSE.
+ *
+ * This class is intentionally protocol-agnostic: it does not parse JSON-RPC,
+ * MCP, ACP, or any other message format. It simply bridges bytes. However, it
+ * does provide transport-level guarantees required by these protocols:
+ *   - UTF-8 integrity of request and response bodies.
+ *   - Line-delimited framing of stdout (one SSE data frame per line).
+ *   - SSE keep-alive heartbeats to survive proxies and idle timeouts.
+ *
+ * Implementation is based on Node.js built-in modules so the package can run
+ * under Node.js as well as Bun.
+ */
+export class StdioSseServer {
+  private server?: Server;
+
+  constructor(private readonly options: StdioSseServerOptions) {}
+
+  /**
+   * Start the HTTP server and spawn the configured child process on each request.
+   */
+  start(): Promise<StdioSseServerState> {
+    const {
+      command,
+      args = [],
+      port = 8080,
+      hostname = "0.0.0.0",
+      endpoint = "/",
+      cors = true,
+      timeout,
+      heartbeatInterval = 30000,
+    } = this.options;
+
+    // Normalize the endpoint path so matching is consistent.
+    const normalizedEndpoint =
+      endpoint === "/" ? "/" : endpoint.replace(/\/$/, "");
+
+    return new Promise((resolve, reject) => {
+      this.server = createServer(async (req, res) => {
+        if (this.options.onRequest) {
+          const handled = await this.options.onRequest(req, res);
+          if (handled) return;
+        }
+
+        let proc: ChildProcess | undefined;
+        let timeoutId: ReturnType<typeof setTimeout> | undefined;
+        let heartbeatId: ReturnType<typeof setInterval> | undefined;
+        let finished = false;
+
+        const finish = (): void => {
+          if (finished) return;
+          finished = true;
+
+          if (timeoutId) {
+            clearTimeout(timeoutId);
+            timeoutId = undefined;
+          }
+
+          if (heartbeatId) {
+            clearInterval(heartbeatId);
+            heartbeatId = undefined;
+          }
+
+          if (!res.writableEnded) {
+            res.end();
+          }
+
+          if (proc && !proc.killed) {
+            proc.kill();
+          }
+        };
+
+        try {
+          // Respond to CORS preflight requests when CORS is enabled.
+          if (cors && req.method === "OPTIONS") {
+            res.writeHead(204, {
+              "Access-Control-Allow-Origin": "*",
+              "Access-Control-Allow-Methods": "POST, OPTIONS",
+              "Access-Control-Allow-Headers": "Content-Type, Authorization",
+            });
+            res.end();
+            return;
+          }
+
+          // Only POST requests to the configured endpoint are accepted.
+          if (req.method !== "POST" || req.url !== normalizedEndpoint) {
+            res.writeHead(404);
+            res.end("Not Found");
+            return;
+          }
+
+          const body = await readRequestBody(req);
+
+          // Spawn one child process per request. Each request is isolated.
+          // stderr is ignored to prevent the child from deadlocking when it
+          // writes large amounts of diagnostic output.
+          proc = spawn(command, args, {
+            stdio: ["pipe", "pipe", "ignore"],
+          });
+
+          // Forward the HTTP body to the child's stdin and close it so the child
+          // knows no more input is coming.
+          if (body) {
+            proc.stdin!.write(body);
+          }
+          proc.stdin!.end();
+
+          const headers: Record<string, string | string[]> = {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+          };
+
+          if (cors) {
+            headers["Access-Control-Allow-Origin"] = "*";
+          }
+
+          res.writeHead(200, headers);
+
+          // Emit periodic SSE comment frames to keep the connection alive.
+          if (heartbeatInterval > 0) {
+            heartbeatId = setInterval(() => {
+              if (!res.writableEnded) {
+                res.write(encodeSseKeepAlive());
+              }
+            }, heartbeatInterval);
+          }
+
+          // If the client disconnects, terminate the child process to avoid
+          // orphan processes and wasted resources.
+          res.once("close", () => {
+            finish();
+          });
+
+          proc.once("error", (error) => {
+            if (!res.writableEnded) {
+              res.write(encodeSse(error.message, { event: "error" }));
+            }
+            finish();
+          });
+
+          proc.once("exit", () => {
+            finish();
+          });
+
+          if (timeout) {
+            timeoutId = setTimeout(() => {
+              if (!res.writableEnded) {
+                res.write(encodeSse("Request timed out", { event: "error" }));
+              }
+              proc?.kill("SIGKILL");
+              finish();
+            }, timeout);
+          }
+
+          // Read stdout line-by-line and re-emit each line as an SSE frame.
+          // `createInterface` handles UTF-8 boundary preservation internally,
+          // so multi-byte characters split across stdout chunks are not cut.
+          const rl = createInterface({
+            input: proc.stdout!,
+            crlfDelay: Infinity,
+          });
+
+          for await (const line of rl) {
+            if (res.writableEnded) break;
+            res.write(encodeSse(line));
+          }
+
+          finish();
+        } catch (error) {
+          finish();
+
+          if (!res.headersSent) {
+            res.writeHead(500);
+          }
+          if (!res.writableEnded) {
+            res.end(
+              error instanceof Error ? error.message : "Internal Server Error",
+            );
+          }
+        }
+      });
+
+      this.server.once("error", reject);
+
+      this.server.listen(port, hostname, () => {
+        this.server!.removeListener("error", reject);
+
+        const displayEndpoint =
+          normalizedEndpoint === "/" ? "" : normalizedEndpoint;
+        const protocol = "http";
+        const host = hostname === "0.0.0.0" ? "localhost" : hostname;
+        const url = `${protocol}://${host}:${port}${displayEndpoint}`;
+
+        resolve({
+          url,
+          stop: () =>
+            new Promise((resolveStop) => {
+              this.server!.close(() => resolveStop());
+              // Forcefully close any open connections so the server can shut
+              // down promptly, even if a client has disconnected abruptly.
+              this.server!.closeAllConnections?.();
+            }),
+        });
+      });
+    });
+  }
+}
+
+function readRequestBody(
+  req: import("node:http").IncomingMessage,
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+
+    req.on("data", (chunk: Buffer) => {
+      chunks.push(chunk);
+    });
+
+    req.on("end", () => {
+      resolve(Buffer.concat(chunks));
+    });
+
+    req.on("error", reject);
+  });
+}