import { IncomingMessage } from "node:http";
import { Socket } from "node:net";
/**
 * Handler for proxying HTTP requests to the worker.
 *
 * A relative string input (e.g. `"/path"`) is resolved against a placeholder
 * `http://localhost` origin before dispatching.
 */
type FetchHandler = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
/** Callback for receiving messages from the worker. */
type RunnerMessageListener = (data: unknown) => void;
/** Raw Node.js upgrade request context. */
interface NodeUpgradeContext {
  req: IncomingMessage;
  socket: Socket;
  head: any;
}
/** Context passed to the upgrade handler for WebSocket upgrades. */
interface UpgradeContext {
  node: NodeUpgradeContext;
}
/** Handler for proxying WebSocket upgrade requests to the worker. */
type UpgradeHandler = (context: UpgradeContext) => void;
/** Bidirectional RPC messaging interface between the runner and worker. */
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.
 *
 * Either a TCP `host`/`port` pair or a Unix `socketPath`.
 */
type WorkerAddress = {
  host?: string;
  port: number;
  socketPath?: undefined;
} | {
  host?: undefined;
  port?: undefined;
  socketPath: string;
};
/** Lifecycle hooks for observing runner state changes. */
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. */
interface RPCOptions {
  /** Timeout in milliseconds before the RPC call rejects. Default: 3000. */
  timeout?: number;
}
/** Core runner interface combining lifecycle hooks, RPC, and request proxying. */
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>;
  /**
   * 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>;
  /** Gracefully shut down the worker. */
  close(): Promise<void>;
  /** Alias for `close()`, enabling `await using` (explicit resource management). */
  [Symbol.asyncDispose](): Promise<void>;
}
export { EnvRunner, FetchHandler, NodeUpgradeContext, RPCOptions, RunnerMessageListener, RunnerRPCHooks, UpgradeContext, UpgradeHandler, WorkerAddress, WorkerHooks };