types.ts

import type { IncomingMessage } from "node:http";
import type { Socket } from "node:net";
import type { VirtualModuleUpdates } from "./virtual-loader.ts";

/** Proxy a request to the worker; relative inputs resolve against `http://localhost`. */
export type FetchHandler = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;

/** Callback for receiving messages from the worker. */
export type RunnerMessageListener = (data: unknown) => void;

/** Raw Node.js upgrade request context. */
export interface NodeUpgradeContext {
  req: IncomingMessage;
  socket: Socket;
  head: any;
}

/** Context passed to the upgrade handler for WebSocket upgrades. */
export interface UpgradeContext {
  node: NodeUpgradeContext;
}

/** Handler for proxying WebSocket upgrade requests to the worker. */
export type UpgradeHandler = (context: UpgradeContext) => void;

/** Bidirectional RPC messaging interface between the runner and worker. */
export interface RunnerRPCHooks {
  /** Send a message to the worker. */
  sendMessage: (message: unknown) => void;

  /** Register a listener for messages from the worker. */
  onMessage: (listener: RunnerMessageListener) => void;

  /** Remove a previously registered message listener. */
  offMessage: (listener: RunnerMessageListener) => void;
}

/**
 * Address reported by the worker once it is ready. `host` is reachable from
 * the host (wildcard listeners report loopback); `protocol` is `https` for a
 * TLS `listen` option.
 */
export type WorkerAddress =
  | { host?: string; port: number; protocol?: "http" | "https"; socketPath?: undefined }
  | { host?: undefined; port?: undefined; protocol?: undefined; socketPath: string };

/**
 * The `listen` runner option: the worker's server binds this public address
 * instead of a random loopback port, so clients reach it directly (no proxy
 * hop through the host). Like srvx's options of the same names; the values
 * must be JSON-serializable.
 */
export interface ListenOptions {
  /** Port (default: the `PORT` env var, else `3000`); `0` picks a free one. */
  port?: number | string;
  /** Hostname (default: the `HOST` env var, else all interfaces). */
  hostname?: string;
  /** `https` when `tls` has a `cert` and `key` (default). */
  protocol?: "http" | "https";
  /** PEM contents or file paths. */
  tls?: { cert?: string; key?: string; passphrase?: string };
  /** Let several processes bind the same port. */
  reusePort?: boolean;
  /** `false` prints the listening address from the worker (default `true`). */
  silent?: boolean;
}

/** Lifecycle hooks for observing runner state changes. */
export interface WorkerHooks {
  /** Called when the worker closes, optionally with the cause. */
  onClose?: (worker: EnvRunner, cause?: unknown) => void;

  /** Called when the worker is ready and listening at the given address. */
  onReady?: (worker: EnvRunner, address?: WorkerAddress) => void;
}

/** Options for the `rpc()` method. */
export interface RPCOptions {
  /** Timeout in milliseconds before the RPC call rejects. Default: 3000. */
  timeout?: number;
}

/** Core runner interface combining lifecycle hooks, RPC, and request proxying. */
export interface EnvRunner extends RunnerRPCHooks, AsyncDisposable {
  /** Whether the worker is ready to accept requests. */
  readonly ready: boolean;

  /** Whether the runner has been closed. */
  readonly closed: boolean;

  /** Address the worker is listening at, once ready (`undefined` before then). */
  readonly address?: WorkerAddress;

  /** Proxy an HTTP request to the worker. */
  fetch: FetchHandler;

  /** Proxy a WebSocket upgrade request to the worker. */
  upgrade?: UpgradeHandler;

  /** Returns a promise that resolves when the runner becomes ready. */
  waitForReady(timeout?: number): Promise<void>;

  /** Send an RPC request and wait for the response. */
  rpc<T = unknown>(name: string, data?: unknown, opts?: RPCOptions): Promise<T>;

  /** Re-import the entry module without restarting the worker/process. */
  reloadModule?(timeout?: number): Promise<void>;

  /**
   * Set (add or replace) and remove (`null`) virtual modules in one round trip.
   * Changed and removed modules, and their importers, evaluate fresh on the
   * next `reloadModule()`; a removed key falls through to normal resolution.
   */
  updateVirtualModules?(changes: VirtualModuleUpdates, timeout?: number): Promise<void>;

  /**
   * Invalidate a virtual module so the next `reloadModule()` re-evaluates it.
   * A factory-valued source is re-run for fresh contents.
   */
  invalidateModule?(specifier: string, timeout?: number): Promise<void>;

  /**
   * Shut down gracefully, then close: the worker runs `ipc.onClose`, stops
   * accepting connections and waits for in-flight requests (at most
   * `timeout` ms, default 5000).
   */
  shutdown?(timeout?: number): Promise<void>;

  /** Close the runner, terminating the worker immediately. */
  close(): Promise<void>;

  /** Alias for `close()`, enabling `await using` (explicit resource management). */
  [Symbol.asyncDispose](): Promise<void>;
}