@linzumi/cli 0.0.20-beta → 0.0.22-beta

package/src/forwardTunnel.ts

@@ -1,859 +0,0 @@
-/*
-- Date: 2026-04-29
-  Spec: plans/2026-04-29-local-runner-streaming-forwarding-rca-plan.md
-  Relationship: Maintains the runner-to-Kandan binary data-plane tunnel and
-  bridges approved loopback HTTP/WebSocket streams without base64 buffering.
-*/
-import { randomUUID } from "node:crypto";
-import http from "node:http";
-import https from "node:https";
-import { type JsonObject, type JsonValue, isJsonObject } from "./protocol";
-import {
-  decodeForwardTunnelFrame,
-  encodeForwardTunnelFrame,
-  forwardTunnelChunkBytes,
-  type ForwardTunnelFrame,
-  type ForwardTunnelWebSocketOpcode,
-} from "./forwardTunnelProtocol";
-
-export type ForwardTunnelHandle = {
-  readonly generation: string;
-  readonly close: () => void;
-};
-
-type ForwardTunnelOptions = {
-  readonly kandanUrl: string;
-  readonly token: string;
-  readonly runnerId: string;
-  readonly allowedPorts: () => readonly number[];
-  readonly log?: ((event: string, payload: JsonObject) => void) | undefined;
-  readonly socketFactory?: ((url: string) => WebSocket) | undefined;
-};
-
-type HttpStream = {
-  readonly kind: "http";
-  readonly abortController: AbortController;
-  readonly requestBodyWriter:
-    | WritableStreamDefaultWriter<Uint8Array>
-    | undefined;
-  readonly rawRequest: http.ClientRequest | undefined;
-};
-
-type WebSocketStream = {
-  readonly kind: "websocket";
-  readonly socket: WebSocket;
-  readonly pendingMessages: WebSocketPendingMessage[];
-};
-
-type OpenRequest = {
-  readonly port: number;
-  readonly method: string;
-  readonly path: string;
-  readonly queryString: string | undefined;
-  readonly headers: Headers;
-};
-
-type LocalStream = HttpStream | WebSocketStream;
-type WebSocketPendingMessage = {
-  readonly opcode: ForwardTunnelWebSocketOpcode;
-  readonly payload: Uint8Array;
-};
-
-export async function connectForwardTunnel(
-  options: ForwardTunnelOptions,
-): Promise<ForwardTunnelHandle> {
-  const generation = randomUUID();
-  const streams = new Map<number, LocalStream>();
-  const state: {
-    websocket: WebSocket | undefined;
-    closed: boolean;
-    reconnectTimer: ReturnType<typeof setTimeout> | undefined;
-  } = {
-    websocket: undefined,
-    closed: false,
-    reconnectTimer: undefined,
-  };
-
-  const send = (frame: ForwardTunnelFrame): void => {
-    const websocket = state.websocket;
-    if (websocket === undefined || websocket.readyState !== WebSocket.OPEN) {
-      return;
-    }
-    websocket.send(encodeForwardTunnelFrame(frame));
-  };
-
-  const closeLocalStreams = (): void => {
-    for (const [streamId, stream] of streams) {
-      closeLocalStream(stream);
-      streams.delete(streamId);
-    }
-  };
-
-  const scheduleReconnect = (): void => {
-    if (state.closed || state.reconnectTimer !== undefined) {
-      return;
-    }
-
-    state.reconnectTimer = setTimeout(() => {
-      state.reconnectTimer = undefined;
-      void openSocket();
-    }, 250);
-  };
-
-  const openSocket = async (): Promise<void> => {
-    if (state.closed) {
-      return;
-    }
-
-    const websocket = (options.socketFactory ?? ((url) => new WebSocket(url)))(
-      forwardTunnelUrl(
-        options.kandanUrl,
-        options.runnerId,
-        options.token,
-        generation,
-      ),
-    );
-    websocket.binaryType = "arraybuffer";
-    state.websocket = websocket;
-    websocket.addEventListener("message", (event) => {
-      void handleMessage(event.data, streams, options.allowedPorts, send);
-    });
-    websocket.addEventListener("close", () => {
-      if (state.websocket === websocket) {
-        closeLocalStreams();
-        scheduleReconnect();
-      }
-    });
-    websocket.addEventListener("error", () => {
-      if (state.websocket === websocket) {
-        options.log?.("kandan.forward_tunnel_error", { generation });
-      }
-    });
-
-    try {
-      await waitForOpen(websocket);
-    } catch (error) {
-      if (state.websocket === websocket) {
-        state.websocket = undefined;
-        options.log?.("kandan.forward_tunnel_open_failed", {
-          generation,
-          error: error instanceof Error ? error.message : "websocket_open_failed",
-        });
-        websocket.close();
-        scheduleReconnect();
-      }
-    }
-  };
-
-  await openSocket();
-
-  return {
-    generation,
-    close: () => {
-      state.closed = true;
-      if (state.reconnectTimer !== undefined) {
-        clearTimeout(state.reconnectTimer);
-      }
-      closeLocalStreams();
-      state.websocket?.close();
-    },
-  };
-}
-
-export function forwardTunnelUrl(
-  baseUrl: string,
-  runnerId: string,
-  token: string,
-  generation: string,
-): string {
-  const parsed = new URL(baseUrl);
-  parsed.protocol =
-    parsed.protocol === "https:" || parsed.protocol === "wss:" ? "wss:" : "ws:";
-  parsed.pathname = `/api/v2/local-codex-runner/tunnel/${encodeURIComponent(runnerId)}`;
-  parsed.search = "";
-  parsed.searchParams.set("token", token);
-  parsed.searchParams.set("generation", generation);
-  return parsed.toString();
-}
-
-async function handleMessage(
-  message: Blob | ArrayBuffer | Uint8Array,
-  streams: Map<number, LocalStream>,
-  allowedPorts: () => readonly number[],
-  send: (frame: ForwardTunnelFrame) => void,
-): Promise<void> {
-  const decoded = await decodeForwardTunnelFrame(message);
-
-  if (!decoded.ok) {
-    return;
-  }
-
-  const frame = decoded.frame;
-  switch (frame.type) {
-    case "open_http":
-      openHttpStream(
-        frame.streamId,
-        frame.payload,
-        streams,
-        allowedPorts,
-        send,
-      );
-      return;
-    case "request_body_chunk":
-      await writeRequestBodyChunk(frame.streamId, frame.payload, streams);
-      return;
-    case "request_body_end":
-      await closeRequestBody(frame.streamId, streams);
-      return;
-    case "open_websocket":
-      openWebSocketStream(
-        frame.streamId,
-        frame.payload,
-        streams,
-        allowedPorts,
-        send,
-        "ws",
-      );
-      return;
-    case "websocket_message":
-      sendWebSocketMessage(
-        frame.streamId,
-        frame.opcode,
-        frame.payload,
-        streams,
-        send,
-      );
-      return;
-    case "websocket_close":
-    case "cancel":
-      closeStream(frame.streamId, streams);
-      return;
-    case "response_headers":
-    case "response_body_chunk":
-    case "response_end":
-    case "stream_error":
-      return;
-  }
-}
-
-function openHttpStream(
-  streamId: number,
-  payload: JsonObject,
-  streams: Map<number, LocalStream>,
-  allowedPorts: () => readonly number[],
-  send: (frame: ForwardTunnelFrame) => void,
-): void {
-  const request = openRequest(payload);
-
-  if (request === undefined) {
-    sendStreamError(streamId, "invalid_forward_request", send);
-    return;
-  }
-
-  if (!allowedPorts().includes(request.port)) {
-    sendStreamError(streamId, "forward_port_not_allowed", send);
-    return;
-  }
-
-  const abortController = new AbortController();
-  const bodyStream =
-    request.method === "GET" || request.method === "HEAD"
-      ? undefined
-      : new TransformStream<Uint8Array>();
-  streams.set(streamId, {
-    kind: "http",
-    abortController,
-    requestBodyWriter: bodyStream?.writable.getWriter(),
-    rawRequest: undefined,
-  });
-
-  switch (bodyStream) {
-    case undefined:
-      void forwardRawHttpResponse(streamId, request, streams, send);
-      return;
-
-    default: {
-      const requestInit: RequestInit & { readonly duplex?: "half" } = {
-        method: request.method,
-        headers: request.headers,
-        signal: abortController.signal,
-        body: bodyStream.readable,
-        duplex: "half",
-      };
-
-      void fetchWithHttpsFallback(request, requestInit)
-        .then((response) =>
-          forwardHttpResponse(streamId, response, request.method, streams, send),
-        )
-        .catch((error) => {
-          if (!abortController.signal.aborted) {
-            sendStreamError(
-              streamId,
-              error instanceof Error &&
-                error.message === "forward_port_not_allowed"
-                ? "forward_port_not_allowed"
-                : "forward_target_unavailable",
-              send,
-            );
-          }
-          streams.delete(streamId);
-        });
-    }
-  }
-}
-
-async function forwardHttpResponse(
-  streamId: number,
-  response: Response,
-  method: string,
-  streams: Map<number, LocalStream>,
-  send: (frame: ForwardTunnelFrame) => void,
-): Promise<void> {
-  send({
-    type: "response_headers",
-    streamId,
-    payload: {
-      status: response.status,
-      headers: responseHeaders(response.headers),
-    },
-  });
-
-  if (method !== "HEAD" && response.body !== null) {
-    const reader = response.body.getReader();
-    while (true) {
-      const result = await reader.read();
-      if (result.done) {
-        break;
-      }
-      sendChunkedBody(streamId, result.value, send);
-    }
-  }
-
-  send({ type: "response_end", streamId });
-  streams.delete(streamId);
-}
-
-function sendChunkedBody(
-  streamId: number,
-  body: Uint8Array,
-  send: (frame: ForwardTunnelFrame) => void,
-): void {
-  for (
-    let offset = 0;
-    offset < body.byteLength;
-    offset += forwardTunnelChunkBytes
-  ) {
-    send({
-      type: "response_body_chunk",
-      streamId,
-      payload: body.subarray(offset, offset + forwardTunnelChunkBytes),
-    });
-  }
-}
-
-async function writeRequestBodyChunk(
-  streamId: number,
-  body: Uint8Array,
-  streams: Map<number, LocalStream>,
-): Promise<void> {
-  const stream = streams.get(streamId);
-  if (stream?.kind === "http" && stream.requestBodyWriter !== undefined) {
-    await stream.requestBodyWriter.write(body);
-  }
-}
-
-async function closeRequestBody(
-  streamId: number,
-  streams: Map<number, LocalStream>,
-): Promise<void> {
-  const stream = streams.get(streamId);
-  if (stream?.kind === "http" && stream.requestBodyWriter !== undefined) {
-    await stream.requestBodyWriter.close();
-  }
-}
-
-function openWebSocketStream(
-  streamId: number,
-  payload: JsonObject,
-  streams: Map<number, LocalStream>,
-  allowedPorts: () => readonly number[],
-  send: (frame: ForwardTunnelFrame) => void,
-  scheme: "ws" | "wss",
-): void {
-  const request = openRequest(payload);
-
-  if (request === undefined) {
-    sendStreamError(streamId, "invalid_forward_request", send);
-    return;
-  }
-
-  if (!allowedPorts().includes(request.port)) {
-    sendStreamError(streamId, "forward_port_not_allowed", send);
-    return;
-  }
-
-  let opened = false;
-  const pendingMessages: WebSocketPendingMessage[] = [];
-  const url = localForwardWebSocketUrl(
-    scheme,
-    request.port,
-    request.path,
-    request.queryString,
-  );
-  const protocols = webSocketProtocols(request.headers);
-  const socket =
-    protocols === undefined ? new WebSocket(url) : new WebSocket(url, protocols);
-  streams.set(streamId, { kind: "websocket", socket, pendingMessages });
-  socket.addEventListener("open", () => {
-    opened = true;
-    send({
-      type: "response_headers",
-      streamId,
-      payload: { status: 101, headers: [] },
-    });
-    flushPendingWebSocketMessages(socket, pendingMessages);
-  });
-  socket.addEventListener("message", (event) => {
-    const body =
-      typeof event.data === "string"
-        ? Buffer.from(event.data)
-        : Buffer.from(event.data as ArrayBuffer);
-    send({
-      type: "websocket_message",
-      streamId,
-      opcode: typeof event.data === "string" ? "text" : "binary",
-      payload: body,
-    });
-  });
-  socket.addEventListener("close", (event) => {
-    const stream = streams.get(streamId);
-    if (stream?.kind !== "websocket" || stream.socket !== socket) {
-      return;
-    }
-
-    streams.delete(streamId);
-    send({
-      type: "websocket_close",
-      streamId,
-      payload: { code: event.code, reason: event.reason },
-    });
-  });
-  socket.addEventListener("error", () => {
-    const stream = streams.get(streamId);
-    if (stream?.kind !== "websocket" || stream.socket !== socket) {
-      return;
-    }
-
-    streams.delete(streamId);
-    if (!opened && scheme === "ws") {
-      openWebSocketStream(
-        streamId,
-        payload,
-        streams,
-        allowedPorts,
-        send,
-        "wss",
-      );
-      return;
-    }
-    sendStreamError(streamId, "websocket_error", send);
-  });
-}
-
-function sendWebSocketMessage(
-  streamId: number,
-  opcode: ForwardTunnelWebSocketOpcode,
-  payload: Uint8Array,
-  streams: Map<number, LocalStream>,
-  send: (frame: ForwardTunnelFrame) => void,
-): void {
-  const stream = streams.get(streamId);
-  if (
-    stream?.kind !== "websocket" ||
-    stream.socket.readyState > WebSocket.OPEN
-  ) {
-    sendStreamError(streamId, "websocket_not_open", send);
-    return;
-  }
-
-  if (stream.socket.readyState === WebSocket.CONNECTING) {
-    queueWebSocketMessage(stream, opcode, payload, streamId, send);
-    return;
-  }
-
-  sendLocalWebSocketMessage(stream.socket, opcode, payload);
-}
-
-function queueWebSocketMessage(
-  stream: WebSocketStream,
-  opcode: ForwardTunnelWebSocketOpcode,
-  payload: Uint8Array,
-  streamId: number,
-  send: (frame: ForwardTunnelFrame) => void,
-): void {
-  const queuedBytes = stream.pendingMessages.reduce(
-    (total, message) => total + message.payload.byteLength,
-    0,
-  );
-
-  if (
-    stream.pendingMessages.length >= 256 ||
-    queuedBytes + payload.byteLength > 4 * 1024 * 1024
-  ) {
-    sendStreamError(streamId, "websocket_pending_queue_full", send);
-    return;
-  }
-
-  stream.pendingMessages.push({ opcode, payload: Buffer.from(payload) });
-}
-
-function flushPendingWebSocketMessages(
-  socket: WebSocket,
-  pendingMessages: WebSocketPendingMessage[],
-): void {
-  for (const message of pendingMessages.splice(0)) {
-    sendLocalWebSocketMessage(socket, message.opcode, message.payload);
-  }
-}
-
-function sendLocalWebSocketMessage(
-  socket: WebSocket,
-  opcode: ForwardTunnelWebSocketOpcode,
-  payload: Uint8Array,
-): void {
-  switch (opcode) {
-    case "text":
-      socket.send(Buffer.from(payload).toString());
-      return;
-    case "binary":
-    case "ping":
-    case "pong":
-      socket.send(payload);
-      return;
-  }
-}
-
-function closeStream(
-  streamId: number,
-  streams: Map<number, LocalStream>,
-): void {
-  const stream = streams.get(streamId);
-  streams.delete(streamId);
-  if (stream !== undefined) {
-    closeLocalStream(stream);
-  }
-}
-
-function closeLocalStream(stream: LocalStream): void {
-  switch (stream.kind) {
-    case "http":
-      stream.abortController.abort();
-      stream.rawRequest?.destroy();
-      void stream.requestBodyWriter?.abort().catch(() => undefined);
-      return;
-    case "websocket":
-      stream.socket.close();
-      return;
-  }
-}
-
-function sendStreamError(
-  streamId: number,
-  error: string,
-  send: (frame: ForwardTunnelFrame) => void,
-): void {
-  send({ type: "stream_error", streamId, payload: { error } });
-}
-
-function openRequest(payload: JsonObject): OpenRequest | undefined {
-  const port = payload.port;
-  const method = payload.method;
-  const path = payload.path;
-  const queryString = payload.queryString;
-
-  if (
-    typeof port !== "number" ||
-    !Number.isInteger(port) ||
-    port < 1 ||
-    port > 65_535 ||
-    typeof method !== "string" ||
-    typeof path !== "string" ||
-    (queryString !== undefined && typeof queryString !== "string")
-  ) {
-    return undefined;
-  }
-
-  return {
-    port,
-    method,
-    path,
-    queryString,
-    headers: requestHeaders(payload.headers),
-  };
-}
-
-async function fetchWithHttpsFallback(
-  request: OpenRequest,
-  requestInit: RequestInit,
-): Promise<Response> {
-  try {
-    return await fetch(
-      localForwardUrl("http", request.port, request.path, request.queryString),
-      requestInit,
-    );
-  } catch (httpError) {
-    if (requestInit.signal?.aborted) {
-      throw httpError;
-    }
-    return await fetch(
-      localForwardUrl("https", request.port, request.path, request.queryString),
-      requestInit,
-    );
-  }
-}
-
-function localForwardUrl(
-  scheme: "http" | "https",
-  port: number,
-  path: string,
-  queryString: string | undefined,
-): string {
-  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-  const url = new URL(`${scheme}://127.0.0.1:${port}${normalizedPath}`);
-
-  if (queryString !== undefined && queryString.trim() !== "") {
-    url.search = queryString;
-  }
-
-  return url.toString();
-}
-
-export function localForwardWebSocketUrl(
-  scheme: "ws" | "wss",
-  port: number,
-  path: string,
-  queryString: string | undefined,
-): string {
-  const httpScheme = scheme === "ws" ? "http" : "https";
-  const url = new URL(localForwardUrl(httpScheme, port, path, queryString));
-  url.protocol = `${scheme}:`;
-  return url.toString();
-}
-
-function requestHeaders(headers: JsonValue | undefined): Headers {
-  const result = new Headers();
-
-  if (!Array.isArray(headers)) {
-    return result;
-  }
-
-  for (const header of headers) {
-    if (
-      isWireHeader(header) &&
-      !blockedRequestHeaderNames.has(header.name.toLowerCase())
-    ) {
-      result.set(header.name, header.value);
-    }
-  }
-
-  return result;
-}
-
-function webSocketProtocols(headers: Headers): string[] | undefined {
-  const protocolHeader = headers.get("sec-websocket-protocol");
-  if (protocolHeader === null) {
-    return undefined;
-  }
-
-  const protocols = protocolHeader
-    .split(",")
-    .map((protocol) => protocol.trim())
-    .filter((protocol) => protocol !== "");
-
-  return protocols.length === 0 ? undefined : protocols;
-}
-
-function responseHeaders(headers: Headers): JsonObject[] {
-  return Array.from(headers.entries())
-    .filter(([name]) => !blockedFetchResponseHeaderNames.has(name.toLowerCase()))
-    .slice(0, 80)
-    .map(([name, value]) => ({ name, value }));
-}
-
-function rawResponseHeaders(headers: http.IncomingHttpHeaders): JsonObject[] {
-  const entries = Object.entries(headers).flatMap(([name, value]) => {
-    if (blockedRawResponseHeaderNames.has(name.toLowerCase())) {
-      return [];
-    }
-
-    switch (typeof value) {
-      case "string":
-        return [{ name, value }];
-      case "undefined":
-        return [];
-      default:
-        return value.map((headerValue) => ({ name, value: headerValue }));
-    }
-  });
-
-  return entries.slice(0, 80);
-}
-
-async function forwardRawHttpResponse(
-  streamId: number,
-  request: OpenRequest,
-  streams: Map<number, LocalStream>,
-  send: (frame: ForwardTunnelFrame) => void,
-): Promise<void> {
-  try {
-    await rawHttpRequest("http", streamId, request, streams, send);
-  } catch (httpError) {
-    const stream = streams.get(streamId);
-    if (stream?.kind === "http" && stream.abortController.signal.aborted) {
-      streams.delete(streamId);
-      return;
-    }
-
-    try {
-      await rawHttpRequest("https", streamId, request, streams, send);
-    } catch (_httpsError) {
-      sendStreamError(
-        streamId,
-        httpError instanceof Error && httpError.message === "aborted"
-          ? "forward_target_unavailable"
-          : "forward_target_unavailable",
-        send,
-      );
-      streams.delete(streamId);
-    }
-  }
-}
-
-function rawHttpRequest(
-  scheme: "http" | "https",
-  streamId: number,
-  request: OpenRequest,
-  streams: Map<number, LocalStream>,
-  send: (frame: ForwardTunnelFrame) => void,
-): Promise<void> {
-  return new Promise((resolve, reject) => {
-    const localStream = streams.get(streamId);
-    if (localStream?.kind !== "http") {
-      reject(new Error("aborted"));
-      return;
-    }
-
-    const url = localForwardUrl(
-      scheme,
-      request.port,
-      request.path,
-      request.queryString,
-    );
-    const client = scheme === "http" ? http : https;
-    const rawRequest = client.request(url, {
-      method: request.method,
-      headers: Object.fromEntries(request.headers.entries()),
-      signal: localStream.abortController.signal,
-    });
-
-    streams.set(streamId, { ...localStream, rawRequest });
-
-    rawRequest.on("response", (response) => {
-      send({
-        type: "response_headers",
-        streamId,
-        payload: {
-          status: response.statusCode ?? 502,
-          headers: rawResponseHeaders(response.headers),
-        },
-      });
-
-      response.on("data", (chunk: Buffer) => {
-        sendChunkedBody(streamId, chunk, send);
-      });
-
-      response.on("end", () => {
-        send({ type: "response_end", streamId });
-        streams.delete(streamId);
-        resolve();
-      });
-
-      response.on("error", reject);
-    });
-
-    rawRequest.on("error", reject);
-    rawRequest.end();
-  });
-}
-
-function isWireHeader(
-  value: JsonValue,
-): value is { readonly name: string; readonly value: string } {
-  return (
-    isJsonObject(value) &&
-    typeof value.name === "string" &&
-    typeof value.value === "string"
-  );
-}
-
-function waitForOpen(websocket: WebSocket): Promise<void> {
-  return new Promise((resolve, reject) => {
-    websocket.addEventListener("open", () => resolve(), { once: true });
-    websocket.addEventListener(
-      "error",
-      () => reject(new Error("websocket open failed")),
-      {
-        once: true,
-      },
-    );
-  });
-}
-
-const blockedRequestHeaderNames = new Set([
-  "authorization",
-  "cache-control",
-  "connection",
-  "content-encoding",
-  "content-length",
-  "cookie",
-  "etag",
-  "host",
-  "if-modified-since",
-  "if-none-match",
-  "keep-alive",
-  "last-modified",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "set-cookie",
-  "te",
-  "trailer",
-  "transfer-encoding",
-  "upgrade",
-]);
-
-const blockedFetchResponseHeaderNames = new Set([
-  "connection",
-  "content-encoding",
-  "content-length",
-  "keep-alive",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "set-cookie",
-  "te",
-  "trailer",
-  "transfer-encoding",
-  "upgrade",
-]);
-
-const blockedRawResponseHeaderNames = new Set([
-  "connection",
-  "content-length",
-  "keep-alive",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "set-cookie",
-  "te",
-  "trailer",
-  "transfer-encoding",
-  "upgrade",
-]);