@nimbus-sh/core 0.1.0

package/src/runtime/virtual-socket-kernel.ts

@@ -0,0 +1,1370 @@
+/**
+ * virtual-socket-kernel.ts - shared in-facet loopback socket substrate.
+ *
+ * The kernel has two halves, and they are mirror images of each other.
+ *
+ * Inbound (a guest server accepting a connection). The supervisor-facing
+ * surface stays the existing PortRegistry: /port/<n>/ and
+ * /preview/?port=<n> route a real Worker Request to a facet's
+ * handleHttpRequest(Request). Inside the facet this kernel converts that
+ * Request into an accepted HTTP/1.1 byte stream so guest runtimes can
+ * implement normal socket APIs without Cloudflare inbound TCP support.
+ *
+ * Outbound (a guest client dialing 127.0.0.1:<port>). connect() hands back
+ * a connection whose write side parses the HTTP/1.1 request the guest
+ * emits, hands it to the host's loopback router - the same
+ * SUPERVISOR.routeLoopback the shell's curl and node's patched fetch use -
+ * and streams the Response back as HTTP/1.1 response bytes on the read
+ * side. Cloudflare has no outbound TCP to 127.0.0.1, so a loopback client
+ * socket can only ever be HTTP-shaped; see the connect() doc comment for
+ * exactly what that does and does not support.
+ *
+ * Runtime adapters (Python socket.py, Ruby socket.rb, future
+ * wasm32-wasi-nimbus syscalls) call this shared kernel instead of each
+ * implementing their own preview bridge.
+ *
+ * This file is the typed source of truth. scripts/bundle-facet-workers.mjs
+ * bundles it at build time into virtual-socket-kernel.generated.ts as the
+ * self-contained VIRTUAL_SOCKET_KERNEL_SRC string that python-runner and
+ * ruby-runner splice into dynamic worker module sources. Because that
+ * bundle ships as injected source text, this module must stay free of
+ * runtime imports - supervisor modules are unreachable from facet isolates.
+ */
+
+/** Hooks the per-runtime adapter glue installs on the facet global scope. */
+export interface VirtualSocketHost {
+  /** Called when a new port starts listening so the adapter can register it with the supervisor. */
+  __nimbusVirtualSocketDidListen?: (port: number) => void;
+  /** Gives the runtime a chance to (re)create a listener before a request 502s. */
+  __nimbusVirtualSocketEnsureListener?: (port: number) => unknown;
+  /**
+   * Cooperative accept pump. Pyodide/ruby.wasm cannot run a background
+   * accept loop (JSPI suspension is only legal on this dedicated pump),
+   * so the kernel queues the connection and then asks the runtime to
+   * process it. Returning false rejects the queued request.
+   */
+  __nimbusVirtualSocketRequestQueued?: (port: number) => Promise<boolean | undefined> | boolean | undefined;
+  /** Detail string surfaced when the request pump returns false. */
+  __nimbusVirtualSocketLastError?: string;
+  /**
+   * Routes an outbound loopback request to whatever is listening on the
+   * port, by delegating to the supervisor's `routeLoopback` RPC. Absent
+   * when the runtime has no supervisor binding, which makes connect()
+   * fail with a clear diagnostic instead of hanging.
+   */
+  __nimbusVirtualSocketRouteLoopback?: (port: number, request: Request) => Promise<Response>;
+}
+
+/** Facet global scope once the kernel is installed. */
+export interface VirtualSocketGlobalScope extends VirtualSocketHost {
+  __nimbusVirtualSockets?: VirtualSocketKernel;
+}
+
+/** Buffer and timing bounds enforced by the kernel. */
+export interface VirtualSocketKernelLimits {
+  /** How long handleHttpRequest waits for a complete response before answering 504. */
+  responseTimeoutMs: number;
+  /** Largest request body accepted into the inbound read queue (whole-body buffered in stage 1). */
+  maxRequestBodyBytes: number;
+  /** Largest total response byte count accepted into the outbound write queue (whole-response buffered in stage 1). */
+  maxResponseBufferBytes: number;
+}
+
+/** Result shape of accept()/acceptNow(); host/port mirror a loopback peer. */
+export interface AcceptedVirtualConnection {
+  id: number;
+  host: string;
+  port: number;
+}
+
+/** Pyodide proxies cross the FFI boundary with a toJs() converter. */
+interface PyodideProxyLike {
+  toJs(): unknown;
+}
+
+/** Byte payloads accepted by send(); covers JS, Pyodide, and ruby.wasm callers. */
+export type VirtualSocketBytesLike =
+  | Uint8Array
+  | ArrayBuffer
+  | ArrayBufferView
+  | readonly number[]
+  | string
+  | PyodideProxyLike;
+
+/**
+ * Stage 2 contract: what the kernel must grow before request/response
+ * bodies can stream end-to-end instead of being fully buffered. Stage 1
+ * keeps the cooperative accept model (see
+ * VirtualSocketHost.__nimbusVirtualSocketRequestQueued) - it exists
+ * because Pyodide JSPI can only suspend inside the dedicated pump call,
+ * so these members are the seam, not a replacement for that model.
+ */
+export interface VirtualSocketStreamingStage2 {
+  /**
+   * Suspending read for request bodies streamed into the inbound queue
+   * chunk-by-chunk; replaces buffering the whole request before the
+   * connection is pushed to the listener. Resolves null at EOF.
+   */
+  recvAsync(id: number, maxBytes: number): Promise<Uint8Array | null>;
+  /**
+   * Write-side backpressure: resolves once queued response bytes drop
+   * below the high-water mark, replacing the hard
+   * maxResponseBufferBytes cap with flow control.
+   */
+  awaitWritable(id: number): Promise<void>;
+  /**
+   * Headers-first streaming Response whose body is a ReadableStream fed
+   * from the outbound queue. Requires the runtime pump to interleave
+   * body writes with consumer reads instead of completing one whole
+   * request per __nimbusVirtualSocketRequestQueued call.
+   */
+  streamHttpResponse(port: number, request: Request): Promise<Response>;
+}
+
+const DEFAULT_LIMITS: VirtualSocketKernelLimits = {
+  responseTimeoutMs: 30_000,
+  maxRequestBodyBytes: 32 * 1024 * 1024,
+  maxResponseBufferBytes: 64 * 1024 * 1024,
+};
+
+const EMPTY_BYTES = new Uint8Array(0);
+
+class Deferred<T> {
+  readonly promise: Promise<T>;
+  readonly resolve: (value: T) => void;
+  readonly reject: (reason: Error) => void;
+
+  constructor() {
+    let resolve: (value: T) => void = () => {};
+    let reject: (reason: Error) => void = () => {};
+    this.promise = new Promise<T>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    this.resolve = resolve;
+    this.reject = reject;
+  }
+}
+
+function isPyodideProxyLike(value: unknown): value is PyodideProxyLike {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof (value as { toJs?: unknown }).toJs === 'function'
+  );
+}
+
+function toBytes(value: unknown): Uint8Array {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  if (Array.isArray(value)) return Uint8Array.from(value as number[]);
+  if (typeof value === 'string') return new TextEncoder().encode(value);
+  if (isPyodideProxyLike(value)) return toBytes(value.toJs());
+  return EMPTY_BYTES;
+}
+
+function concatBytes(parts: readonly Uint8Array[]): Uint8Array {
+  let length = 0;
+  for (const part of parts) length += part.byteLength;
+  const out = new Uint8Array(length);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.byteLength;
+  }
+  return out;
+}
+
+function responseCanHaveBody(requestMethod: string, status: number): boolean {
+  if (requestMethod.toUpperCase() === 'HEAD') return false;
+  return status !== 204 && status !== 205 && status !== 304;
+}
+
+/** Serialize the Worker Request into HTTP/1.1 request bytes for the guest server. */
+function encodeHttpRequest(request: Request, body: Uint8Array): Uint8Array {
+  const url = new URL(request.url);
+  const path = (url.pathname || '/') + url.search;
+  const headers = new Headers(request.headers);
+  if (!headers.has('Host')) headers.set('Host', url.host || 'nimbus.local');
+  if (body.byteLength > 0 && !headers.has('Content-Length')) {
+    headers.set('Content-Length', String(body.byteLength));
+  }
+  const lines = [`${request.method} ${path} HTTP/1.1`];
+  headers.forEach((value, key) => lines.push(`${key}: ${value}`));
+  lines.push('', '');
+  return concatBytes([new TextEncoder().encode(lines.join('\r\n')), body]);
+}
+
+/**
+ * Serialize a Response's head into HTTP/1.1 bytes for a guest client.
+ *
+ * Bodies always go out chunked rather than with a Content-Length: the
+ * loopback Response may be a stream of unknown length (SSE from the AI
+ * gateway, a Vite HMR channel), and chunked is the one framing that both
+ * delimits the body explicitly and needs no length up front. Every
+ * response also carries `Connection: close` - see LoopbackClientConnection
+ * for why one connection carries exactly one exchange.
+ */
+function encodeHttpResponseHead(
+  status: number,
+  statusText: string,
+  headers: Headers,
+  chunkedBody: boolean,
+): Uint8Array {
+  const lines = [`HTTP/1.1 ${status} ${statusText}`];
+  headers.forEach((value, key) => lines.push(`${key}: ${value}`));
+  if (chunkedBody) lines.push('Transfer-Encoding: chunked');
+  lines.push('Connection: close');
+  lines.push('', '');
+  return new TextEncoder().encode(lines.join('\r\n'));
+}
+
+function encodeChunkedFrame(bytes: Uint8Array): Uint8Array {
+  return concatBytes([
+    new TextEncoder().encode(`${bytes.byteLength.toString(16)}\r\n`),
+    bytes,
+    new TextEncoder().encode('\r\n'),
+  ]);
+}
+
+const CHUNKED_TERMINATOR = new TextEncoder().encode('0\r\n\r\n');
+
+/** Response bytes buffered ahead of a slow guest reader before the body pump pauses. */
+const LOOPBACK_READ_HIGH_WATER_BYTES = 1024 * 1024;
+
+/** Largest slice `connectStream`'s readable hands to one stream read. */
+const LOOPBACK_STREAM_CHUNK_BYTES = 64 * 1024;
+
+/** What the kernel's recv/send/close operate on, in either direction. */
+interface VirtualSocketConnection {
+  readonly id: number;
+  read(maxBytes: number): number[];
+  readAsync(maxBytes: number): Promise<number[]>;
+  /** Byte-array read. Runtimes that own file descriptors read through this. */
+  readBytesAsync(maxBytes: number): Promise<Uint8Array>;
+  /** True once no further bytes can arrive, so an empty read means EOF, not "not yet". */
+  atEof(): boolean;
+  write(bytesLike: VirtualSocketBytesLike): number;
+  close(): void;
+}
+
+/**
+ * Bounded FIFO of byte chunks. One instance carries request bytes from
+ * handleHttpRequest to recv() (inbound) and one carries response bytes
+ * from send() to the HTTP parser (outbound). Stage 1 fills the inbound
+ * queue in one shot and drains the outbound queue synchronously; the
+ * async halves are declared on VirtualSocketStreamingStage2.
+ */
+class ByteChunkQueue {
+  private readonly chunks: Uint8Array[] = [];
+  private headOffset = 0;
+  private enqueuedTotalBytes = 0;
+  private undrainedBytes = 0;
+
+  constructor(
+    private readonly limitTotalBytes: number,
+    private readonly overflowLabel: string,
+  ) {}
+
+  /** Bytes enqueued but not yet read. Drives flow control on streamed queues. */
+  get pendingBytes(): number {
+    return this.undrainedBytes;
+  }
+
+  enqueue(bytes: Uint8Array): void {
+    if (bytes.byteLength === 0) return;
+    if (this.enqueuedTotalBytes + bytes.byteLength > this.limitTotalBytes) {
+      throw new Error(
+        `Nimbus virtual socket: ${this.overflowLabel} exceeds ${this.limitTotalBytes} bytes`,
+      );
+    }
+    this.enqueuedTotalBytes += bytes.byteLength;
+    this.undrainedBytes += bytes.byteLength;
+    this.chunks.push(bytes);
+  }
+
+  /** Drain up to maxBytes from the head chunk; empty result means no data is queued. */
+  readUpTo(maxBytes: number): Uint8Array {
+    const head = this.chunks[0];
+    if (!head) return EMPTY_BYTES;
+    const available = head.byteLength - this.headOffset;
+    const take = Math.min(available, Math.max(1, maxBytes));
+    const out = head.subarray(this.headOffset, this.headOffset + take);
+    this.headOffset += take;
+    this.undrainedBytes -= take;
+    if (this.headOffset >= head.byteLength) {
+      this.chunks.shift();
+      this.headOffset = 0;
+    }
+    return out;
+  }
+}
+
+interface ParsedHttpResponse {
+  status: number;
+  statusText: string;
+  headerPairs: readonly [name: string, value: string][];
+  body: Uint8Array | null;
+}
+
+interface ParsedHttpRequest {
+  method: string;
+  target: string;
+  headerPairs: readonly [name: string, value: string][];
+  body: Uint8Array | null;
+}
+
+type HttpParseOutcome<TMessage> =
+  | { kind: 'message'; message: TMessage }
+  | { kind: 'failed'; message: string };
+
+type HttpBodyFraming = 'none' | 'content-length' | 'chunked' | 'until-close';
+
+/**
+ * Incremental HTTP/1.1 message parser: start line and headers first, then
+ * the body under content-length, chunked, or until-close framing.
+ * Completing or failing is monotonic; later input is ignored.
+ *
+ * Both directions of a loopback connection need exactly this - the server
+ * half parses what a guest server writes, the client half parses what a
+ * guest client writes - so the framing lives here once and the subclasses
+ * supply only what differs: the start line and whether a body is expected.
+ */
+abstract class HttpMessageParser<TMessage> {
+  private phase: 'headers' | 'body' | 'done' = 'headers';
+  private settled: HttpParseOutcome<TMessage> | null = null;
+
+  private headerBuffer: Uint8Array = EMPTY_BYTES;
+  private headerScanOffset = 0;
+
+  protected headerPairs: [string, string][] = [];
+
+  private framing: HttpBodyFraming = 'none';
+  private expectedBodyBytes = 0;
+  private readonly bodyChunks: Uint8Array[] = [];
+  private bodyByteCount = 0;
+
+  private chunkState: 'size' | 'data' | 'data-end' = 'size';
+  private readonly chunkSizeLine: number[] = [];
+  private chunkDataRemaining = 0;
+
+  get outcome(): HttpParseOutcome<TMessage> | null {
+    return this.settled;
+  }
+
+  /** What this parser is reading, for diagnostics the guest ultimately sees. */
+  protected abstract get messageLabel(): string;
+
+  /** Parse the start line; return false to reject the message as malformed. */
+  protected abstract parseStartLine(line: string): boolean;
+
+  /** Whether this message may carry a body at all (HEAD, 204, 304, bodyless methods). */
+  protected abstract bodyAllowed(): boolean;
+
+  /** Absent framing means "no body" for requests but "read until close" for responses. */
+  protected abstract defaultFramingWhenUnframed(): HttpBodyFraming;
+
+  protected abstract buildMessage(body: Uint8Array | null): TMessage;
+
+  feed(chunk: Uint8Array): void {
+    if (this.phase === 'done' || chunk.byteLength === 0) return;
+    if (this.phase === 'headers') {
+      this.feedHeaders(chunk);
+      return;
+    }
+    this.feedBody(chunk);
+  }
+
+  /** EOF from the peer closing the connection (or the request being torn down). */
+  finish(): void {
+    if (this.phase === 'done') return;
+    if (this.phase === 'headers') {
+      this.fail(`connection closed before ${this.messageLabel} headers`);
+      return;
+    }
+    if (this.framing === 'until-close') {
+      this.completeWithBody(concatBytes(this.bodyChunks));
+      return;
+    }
+    this.fail(`connection closed before the ${this.messageLabel} completed`);
+  }
+
+  private feedHeaders(chunk: Uint8Array): void {
+    this.headerBuffer = concatBytes([this.headerBuffer, chunk]);
+    const headerEnd = this.findHeaderEnd();
+    if (headerEnd < 0) {
+      this.headerScanOffset = Math.max(0, this.headerBuffer.byteLength - 3);
+      return;
+    }
+    const parsed = this.parseHeaderBlock(this.headerBuffer.subarray(0, headerEnd));
+    const leftover = this.headerBuffer.subarray(headerEnd);
+    this.headerBuffer = EMPTY_BYTES;
+    if (!parsed) return;
+
+    if (!this.bodyAllowed()) {
+      this.completeWithBody(null);
+      return;
+    }
+    const transferEncoding = this.headerValue('Transfer-Encoding');
+    if (transferEncoding !== null && /chunked/i.test(transferEncoding)) {
+      this.framing = 'chunked';
+    } else {
+      const contentLength = this.headerValue('Content-Length');
+      const expected = contentLength === null ? Number.NaN : parseInt(contentLength, 10);
+      if (Number.isFinite(expected) && expected >= 0) {
+        this.framing = 'content-length';
+        this.expectedBodyBytes = expected;
+        if (expected === 0) {
+          this.completeWithBody(EMPTY_BYTES);
+          return;
+        }
+      } else {
+        this.framing = this.defaultFramingWhenUnframed();
+        if (this.framing === 'none') {
+          this.completeWithBody(null);
+          return;
+        }
+      }
+    }
+    this.phase = 'body';
+    this.feedBody(leftover);
+  }
+
+  private feedBody(chunk: Uint8Array): void {
+    if (this.framing === 'chunked') {
+      this.feedChunkedBody(chunk);
+      return;
+    }
+    if (chunk.byteLength === 0) return;
+    if (this.framing === 'content-length') {
+      const needed = this.expectedBodyBytes - this.bodyByteCount;
+      this.appendBody(chunk.subarray(0, Math.min(needed, chunk.byteLength)));
+      if (this.bodyByteCount >= this.expectedBodyBytes) {
+        this.completeWithBody(concatBytes(this.bodyChunks));
+      }
+      return;
+    }
+    this.appendBody(chunk);
+  }
+
+  private feedChunkedBody(chunk: Uint8Array): void {
+    let i = 0;
+    while (i < chunk.byteLength && this.phase === 'body') {
+      if (this.chunkState === 'size') {
+        const byte = chunk[i++];
+        if (byte === 10) {
+          const line = new TextDecoder().decode(Uint8Array.from(this.chunkSizeLine)).trim();
+          this.chunkSizeLine.length = 0;
+          const size = parseInt(line.split(';', 1)[0], 16);
+          if (!Number.isFinite(size) || size < 0) {
+            this.fail('malformed chunked transfer encoding');
+            return;
+          }
+          if (size === 0) {
+            this.completeWithBody(concatBytes(this.bodyChunks));
+            return;
+          }
+          this.chunkState = 'data';
+          this.chunkDataRemaining = size;
+        } else if (byte !== 13) {
+          this.chunkSizeLine.push(byte);
+        }
+      } else if (this.chunkState === 'data') {
+        const take = Math.min(this.chunkDataRemaining, chunk.byteLength - i);
+        this.appendBody(chunk.subarray(i, i + take));
+        i += take;
+        this.chunkDataRemaining -= take;
+        if (this.chunkDataRemaining === 0) this.chunkState = 'data-end';
+      } else {
+        const byte = chunk[i++];
+        if (byte === 10) {
+          this.chunkState = 'size';
+        } else if (byte !== 13) {
+          this.fail('malformed chunked transfer encoding');
+          return;
+        }
+      }
+    }
+  }
+
+  private appendBody(bytes: Uint8Array): void {
+    if (bytes.byteLength === 0) return;
+    this.bodyChunks.push(bytes);
+    this.bodyByteCount += bytes.byteLength;
+  }
+
+  private findHeaderEnd(): number {
+    const bytes = this.headerBuffer;
+    for (let i = this.headerScanOffset; i + 3 < bytes.byteLength; i++) {
+      if (bytes[i] === 13 && bytes[i + 1] === 10 && bytes[i + 2] === 13 && bytes[i + 3] === 10) {
+        return i + 4;
+      }
+    }
+    return -1;
+  }
+
+  /** Returns false when the start line is malformed (the parser has already failed). */
+  private parseHeaderBlock(headerBytes: Uint8Array): boolean {
+    const headerText = new TextDecoder().decode(headerBytes);
+    const lines = headerText.replace(/\r\n/g, '\n').split('\n').filter((line) => line.length > 0);
+    const startLine = lines.shift() ?? '';
+    if (!this.parseStartLine(startLine)) return false;
+    for (const line of lines) {
+      const separator = line.indexOf(':');
+      if (separator <= 0) continue;
+      this.headerPairs.push([line.slice(0, separator), line.slice(separator + 1).trimStart()]);
+    }
+    return true;
+  }
+
+  protected headerValue(name: string): string | null {
+    const target = name.toLowerCase();
+    for (const [key, value] of this.headerPairs) {
+      if (key.toLowerCase() === target) return value;
+    }
+    return null;
+  }
+
+  private completeWithBody(body: Uint8Array | null): void {
+    this.phase = 'done';
+    this.settled = { kind: 'message', message: this.buildMessage(body) };
+  }
+
+  protected fail(message: string): void {
+    this.phase = 'done';
+    this.settled = { kind: 'failed', message };
+  }
+}
+
+/**
+ * Parses the response a guest server writes onto an accepted connection.
+ * An unframed response reads until the guest closes the connection, which
+ * is how HTTP/1.0-style handlers signal end-of-body.
+ */
+class HttpResponseParser extends HttpMessageParser<ParsedHttpResponse> {
+  private status = 200;
+  private statusText = '';
+
+  constructor(private readonly requestMethod: string) {
+    super();
+  }
+
+  protected get messageLabel(): string {
+    return 'response';
+  }
+
+  protected parseStartLine(line: string): boolean {
+    const match = /^HTTP\/\d(?:\.\d)?\s+(\d{3})(?:\s+(.*))?$/.exec(line || 'HTTP/1.1 200 OK');
+    this.status = match ? parseInt(match[1], 10) : 200;
+    this.statusText = match?.[2] ?? '';
+    return true;
+  }
+
+  protected bodyAllowed(): boolean {
+    return responseCanHaveBody(this.requestMethod, this.status);
+  }
+
+  protected defaultFramingWhenUnframed(): HttpBodyFraming {
+    return 'until-close';
+  }
+
+  protected buildMessage(body: Uint8Array | null): ParsedHttpResponse {
+    return { status: this.status, statusText: this.statusText, headerPairs: this.headerPairs, body };
+  }
+}
+
+/**
+ * Parses the request a guest client writes onto a loopback connection.
+ * An unframed request has no body - unlike a response, a request may not
+ * use connection close to delimit one, since the peer still has to reply.
+ */
+class HttpRequestParser extends HttpMessageParser<ParsedHttpRequest> {
+  private method = 'GET';
+  private target = '/';
+
+  protected get messageLabel(): string {
+    return 'request';
+  }
+
+  protected parseStartLine(line: string): boolean {
+    const match = /^([A-Za-z]+)\s+(\S+)\s+HTTP\/\d(?:\.\d)?$/.exec(line);
+    if (!match) {
+      this.fail(`malformed HTTP request line: ${JSON.stringify(line.slice(0, 120))}`);
+      return false;
+    }
+    this.method = match[1].toUpperCase();
+    this.target = match[2];
+    return true;
+  }
+
+  protected bodyAllowed(): boolean {
+    return true;
+  }
+
+  protected defaultFramingWhenUnframed(): HttpBodyFraming {
+    return 'none';
+  }
+
+  protected buildMessage(body: Uint8Array | null): ParsedHttpRequest {
+    return { method: this.method, target: this.target, headerPairs: this.headerPairs, body };
+  }
+}
+
+/**
+ * What a guest server produced, as plain data.
+ *
+ * A Response is an I/O object, and workerd will not let one created in one
+ * request's context be returned from another's. A guest server's response can
+ * be completed by whichever inbound request happened to resume its thread - not
+ * necessarily the request that owns the connection - so the connection settles
+ * with bytes and headers, and the owning request builds the Response itself.
+ */
+interface SettledResponse {
+  status: number;
+  statusText: string;
+  headerPairs: readonly (readonly [string, string])[];
+  body: Uint8Array | null;
+}
+
+function errorResponse(status: number, message: string): SettledResponse {
+  return {
+    status,
+    statusText: '',
+    headerPairs: [['content-type', 'text/plain; charset=utf-8']],
+    body: new TextEncoder().encode(`Nimbus virtual socket: ${message}`),
+  };
+}
+
+function toResponse(settled: SettledResponse): Response {
+  const headers = new Headers();
+  for (const [key, value] of settled.headerPairs) headers.append(key, value);
+  return new Response(settled.body, {
+    status: settled.status,
+    statusText: settled.statusText,
+    headers,
+  });
+}
+
+class VirtualConnection implements VirtualSocketConnection {
+  /** Request bytes the guest server reads; filled in one shot in stage 1. */
+  private readonly inbound: ByteChunkQueue;
+  /** Response bytes the guest server writes; drained into the parser. */
+  private readonly outbound: ByteChunkQueue;
+  private readonly parser: HttpResponseParser;
+  private readonly responseReady = new Deferred<SettledResponse>();
+  private settled = false;
+  private closed = false;
+
+  constructor(
+    readonly id: number,
+    requestMethod: string,
+    requestBytes: Uint8Array,
+    limits: VirtualSocketKernelLimits,
+  ) {
+    this.inbound = new ByteChunkQueue(requestBytes.byteLength, 'request buffer');
+    this.inbound.enqueue(requestBytes);
+    this.outbound = new ByteChunkQueue(limits.maxResponseBufferBytes, 'response buffer');
+    this.parser = new HttpResponseParser(requestMethod);
+  }
+
+  read(maxBytes: number): number[] {
+    return Array.from(this.inbound.readUpTo(Math.max(1, maxBytes | 0)));
+  }
+
+  /** The whole request is buffered before the connection is accepted, so nothing is ever awaited. */
+  readAsync(maxBytes: number): Promise<number[]> {
+    return Promise.resolve(this.read(maxBytes));
+  }
+
+  readBytesAsync(maxBytes: number): Promise<Uint8Array> {
+    return Promise.resolve(this.inbound.readUpTo(Math.max(1, maxBytes | 0)));
+  }
+
+  /** Same reason: an empty read on an accepted connection is always genuine EOF. */
+  atEof(): boolean {
+    return true;
+  }
+
+  write(bytesLike: VirtualSocketBytesLike): number {
+    const bytes = toBytes(bytesLike);
+    if (bytes.byteLength === 0 || this.settled || this.closed) return bytes.byteLength;
+    // Copy once: Pyodide/ruby.wasm callers reuse their transfer buffers.
+    this.outbound.enqueue(bytes.slice());
+    this.pumpParser();
+    return bytes.byteLength;
+  }
+
+  /** EOF from the server side (or request teardown); completes until-close bodies. */
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.settled) return;
+    this.parser.finish();
+    this.pumpParser();
+  }
+
+  /** Abort propagation: settle the pending preview request with a terminal status. */
+  abort(message: string, status: number): void {
+    this.closed = true;
+    this.settle(errorResponse(status, message));
+  }
+
+  async response(timeoutMs: number): Promise<Response> {
+    const timer = setTimeout(() => {
+      this.settle(errorResponse(504, 'timed out waiting for response'));
+    }, Math.max(1, timeoutMs));
+    try {
+      return toResponse(await this.responseReady.promise);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  private pumpParser(): void {
+    for (;;) {
+      const chunk = this.outbound.readUpTo(Number.MAX_SAFE_INTEGER);
+      if (chunk.byteLength === 0) break;
+      this.parser.feed(chunk);
+    }
+    const outcome = this.parser.outcome;
+    if (!outcome) return;
+    if (outcome.kind === 'failed') {
+      this.settle(errorResponse(502, outcome.message));
+      return;
+    }
+    const { status, statusText, headerPairs, body } = outcome.message;
+    this.settle({
+      status,
+      statusText,
+      // The framing is consumed here; the Worker Response re-frames the body itself.
+      headerPairs: headerPairs.filter(([key]) => !/^transfer-encoding$/i.test(key)),
+      body,
+    });
+  }
+
+  private settle(response: SettledResponse): void {
+    if (this.settled) return;
+    this.settled = true;
+    this.responseReady.resolve(response);
+  }
+}
+
+/**
+ * A guest client's connection to an in-session loopback port - the mirror
+ * of VirtualConnection.
+ *
+ * The guest writes an HTTP/1.1 request; once it parses, the kernel hands
+ * the resulting Request to the host's loopback router and streams the
+ * Response back as response bytes the guest reads. That is the whole of
+ * it, and it is HTTP-only by construction: Cloudflare gives a Worker no
+ * outbound TCP to 127.0.0.1, so the only thing a loopback client socket
+ * can carry is a request/response exchange. A guest that writes a non-HTTP
+ * protocol (Redis, Postgres, a bare `nc` pipe) gets a parse failure rather
+ * than a silent hang.
+ *
+ * One connection carries exactly one exchange. Every response is marked
+ * `Connection: close`, which is the signal every HTTP client understands
+ * to stop reusing the socket, so pooling clients (urllib3, httpcore) open
+ * a fresh connection per request instead of pipelining onto a dead one.
+ */
+class LoopbackClientConnection implements VirtualSocketConnection {
+  private readonly parser = new HttpRequestParser();
+  /** Response bytes the guest client reads. */
+  private readonly inbound = new ByteChunkQueue(Number.MAX_SAFE_INTEGER, 'loopback response buffer');
+  private readable: Deferred<void> | null = null;
+  private drained: Deferred<void> | null = null;
+  private dispatched = false;
+  private eof = false;
+  private closed = false;
+
+  constructor(
+    readonly id: number,
+    private readonly port: number,
+    private readonly route: (port: number, request: Request) => Promise<Response>,
+    private readonly limits: VirtualSocketKernelLimits,
+  ) {}
+
+  write(bytesLike: VirtualSocketBytesLike): number {
+    const bytes = toBytes(bytesLike);
+    if (bytes.byteLength === 0 || this.closed) return bytes.byteLength;
+    if (this.dispatched) {
+      throw new Error(
+        `Nimbus loopback socket: port ${this.port} answered with "Connection: close"; ` +
+          'open a new connection for the next request',
+      );
+    }
+    // Copy once: Pyodide/ruby.wasm callers reuse their transfer buffers.
+    this.parser.feed(bytes.slice());
+    const outcome = this.parser.outcome;
+    if (!outcome) return bytes.byteLength;
+    this.dispatched = true;
+    if (outcome.kind === 'failed') this.failWith(400, outcome.message);
+    else void this.dispatch(outcome.message);
+    return bytes.byteLength;
+  }
+
+  read(maxBytes: number): number[] {
+    return Array.from(this.readBytes(maxBytes));
+  }
+
+  /** Byte-array read. The fd-backed path uses this so a stream never round-trips through number[]. */
+  readBytes(maxBytes: number): Uint8Array {
+    const out = this.inbound.readUpTo(Math.max(1, maxBytes | 0));
+    if (this.drained && this.inbound.pendingBytes <= LOOPBACK_READ_HIGH_WATER_BYTES) {
+      const waiter = this.drained;
+      this.drained = null;
+      waiter.resolve();
+    }
+    return out;
+  }
+
+  atEof(): boolean {
+    return (this.eof || this.closed) && this.inbound.pendingBytes === 0;
+  }
+
+  /** Blocks the guest until response bytes arrive; an empty result is EOF. */
+  async readAsync(maxBytes: number): Promise<number[]> {
+    return Array.from(await this.readBytesAsync(maxBytes));
+  }
+
+  async readBytesAsync(maxBytes: number): Promise<Uint8Array> {
+    for (;;) {
+      const chunk = this.readBytes(maxBytes);
+      if (chunk.byteLength > 0) return chunk;
+      if (this.eof || this.closed) return EMPTY_BYTES;
+      if (!this.dispatched) {
+        throw new Error(
+          'Nimbus loopback socket: read before a complete HTTP request was written ' +
+            '(loopback sockets carry HTTP requests, not arbitrary byte streams)',
+        );
+      }
+      const waiter = (this.readable ??= new Deferred<void>());
+      await waiter.promise;
+    }
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.wakeReader();
+    if (this.drained) {
+      const waiter = this.drained;
+      this.drained = null;
+      waiter.resolve();
+    }
+  }
+
+  private async dispatch(parsed: ParsedHttpRequest): Promise<void> {
+    let request: Request;
+    try {
+      request = this.buildRequest(parsed);
+    } catch (error) {
+      this.failWith(400, describeError(error));
+      return;
+    }
+    let response: Response;
+    try {
+      response = await this.withTimeout(this.route(this.port, request));
+    } catch (error) {
+      this.failWith(502, describeError(error));
+      return;
+    }
+    await this.streamResponse(request.method, response);
+  }
+
+  private buildRequest(parsed: ParsedHttpRequest): Request {
+    const headers = new Headers();
+    let authority = `127.0.0.1:${this.port}`;
+    for (const [key, value] of parsed.headerPairs) {
+      if (/^host$/i.test(key)) {
+        authority = value;
+        continue;
+      }
+      // Hop-by-hop framing is re-derived by the Request itself.
+      if (/^(transfer-encoding|connection|content-length|keep-alive)$/i.test(key)) continue;
+      headers.append(key, value);
+    }
+    const target = parsed.target.startsWith('/') ? parsed.target : `/${parsed.target}`;
+    const url = /^https?:\/\//i.test(parsed.target) ? parsed.target : `http://${authority}${target}`;
+    const body = parsed.body && parsed.body.byteLength > 0 ? parsed.body : null;
+    const methodTakesBody = parsed.method !== 'GET' && parsed.method !== 'HEAD';
+    return new Request(url, {
+      method: parsed.method,
+      headers,
+      body: methodTakesBody ? body : null,
+    });
+  }
+
+  private async streamResponse(method: string, response: Response): Promise<void> {
+    const withBody = responseCanHaveBody(method, response.status) && response.body !== null;
+    const headers = new Headers(response.headers);
+    for (const hopByHop of ['transfer-encoding', 'content-length', 'connection', 'keep-alive']) {
+      headers.delete(hopByHop);
+    }
+    this.pushBytes(encodeHttpResponseHead(response.status, response.statusText, headers, withBody));
+    if (!withBody || !response.body) {
+      this.finishStream();
+      return;
+    }
+    const reader = response.body.getReader();
+    try {
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (this.closed) return;
+        const bytes = value instanceof Uint8Array ? value : new Uint8Array(value as ArrayBufferLike);
+        if (bytes.byteLength === 0) continue;
+        this.pushBytes(encodeChunkedFrame(bytes));
+        await this.awaitDrain();
+      }
+      this.pushBytes(CHUNKED_TERMINATOR);
+    } catch {
+      // A truncated body is what a real peer would deliver on a mid-stream
+      // failure: stop here and let the guest see the short read.
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {}
+      this.finishStream();
+    }
+  }
+
+  /** Synthesize a complete response so the guest sees an HTTP error, never a hang. */
+  private failWith(status: number, detail: string): void {
+    const body = new TextEncoder().encode(`Nimbus loopback socket: ${detail}`);
+    const headers = new Headers({
+      'content-type': 'text/plain; charset=utf-8',
+      'content-length': String(body.byteLength),
+    });
+    this.pushBytes(encodeHttpResponseHead(status, '', headers, false));
+    this.pushBytes(body);
+    this.finishStream();
+  }
+
+  private pushBytes(bytes: Uint8Array): void {
+    if (this.closed) return;
+    this.inbound.enqueue(bytes);
+    this.wakeReader();
+  }
+
+  private finishStream(): void {
+    this.eof = true;
+    this.wakeReader();
+  }
+
+  private wakeReader(): void {
+    const waiter = this.readable;
+    if (!waiter) return;
+    this.readable = null;
+    waiter.resolve();
+  }
+
+  /** Pause the body pump while the guest is behind, so a big stream cannot grow unbounded. */
+  private awaitDrain(): Promise<void> {
+    if (this.inbound.pendingBytes <= LOOPBACK_READ_HIGH_WATER_BYTES) return Promise.resolve();
+    return (this.drained ??= new Deferred<void>()).promise;
+  }
+
+  private withTimeout(promise: Promise<Response>): Promise<Response> {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const timeout = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`port ${this.port} did not respond within ${this.limits.responseTimeoutMs}ms`)),
+        Math.max(1, this.limits.responseTimeoutMs),
+      );
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+      if (timer !== null) clearTimeout(timer);
+    });
+  }
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * The subset of Cloudflare's `Socket` that a WASI socket file descriptor needs.
+ *
+ * Every connection the kernel owns can be handed back in this shape, which is
+ * what lets a runtime with real file descriptors keep ONE socket fd kind:
+ * `fd_read`/`fd_write`/`poll_oneoff`/`sock_shutdown`/`fd_close` never learn
+ * whether the peer is a remote host reached through `cloudflare:sockets`, an
+ * in-session port this process dialed, or a connection it accepted.
+ */
+export interface VirtualSocketStream {
+  readonly opened: Promise<void>;
+  readonly readable: ReadableStream<Uint8Array>;
+  readonly writable: WritableStream<Uint8Array>;
+  close(): Promise<void>;
+}
+
+function socketStreamFor(conn: VirtualSocketConnection): VirtualSocketStream {
+  return {
+    // Neither direction has a handshake: an accepted connection already holds
+    // the request, and a dialed one starts its exchange on the first write.
+    opened: Promise.resolve(),
+    readable: new ReadableStream<Uint8Array>(
+      {
+        async pull(controller) {
+          const bytes = await conn.readBytesAsync(LOOPBACK_STREAM_CHUNK_BYTES);
+          if (bytes.byteLength === 0) controller.close();
+          else controller.enqueue(bytes);
+        },
+        cancel() {
+          conn.close();
+        },
+      },
+      // highWaterMark 0 so the stream never pulls speculatively. A default
+      // strategy pulls once at construction, which on a client connection
+      // means reading before the guest has written its request.
+      { highWaterMark: 0 },
+    ),
+    writable: new WritableStream<Uint8Array>({
+      write(chunk) {
+        conn.write(chunk);
+      },
+      abort() {
+        conn.close();
+      },
+    }),
+    close() {
+      conn.close();
+      return Promise.resolve();
+    },
+  };
+}
+
+class VirtualListener {
+  private readonly queue: VirtualConnection[] = [];
+  private readonly acceptWaiters: Deferred<VirtualConnection>[] = [];
+
+  constructor(readonly port: number) {}
+
+  push(conn: VirtualConnection): void {
+    const waiter = this.acceptWaiters.shift();
+    if (waiter) waiter.resolve(conn);
+    else this.queue.push(conn);
+  }
+
+  accept(): Promise<VirtualConnection> {
+    const queued = this.queue.shift();
+    if (queued) return Promise.resolve(queued);
+    const waiter = new Deferred<VirtualConnection>();
+    this.acceptWaiters.push(waiter);
+    return waiter.promise;
+  }
+
+  take(): VirtualConnection | null {
+    return this.queue.shift() ?? null;
+  }
+
+  pending(): number {
+    return this.queue.length;
+  }
+
+  drainQueued(): VirtualConnection[] {
+    return this.queue.splice(0);
+  }
+
+  rejectPendingAccepts(error: Error): void {
+    for (const waiter of this.acceptWaiters.splice(0)) waiter.reject(error);
+  }
+}
+
+interface ReadableWaiter {
+  ports: readonly number[];
+  deferred: Deferred<number[]>;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class VirtualSocketKernel {
+  /** Public: runner glue inspects listeners.keys() for the default preview port. */
+  readonly listeners = new Map<number, VirtualListener>();
+  private readonly connections = new Map<number, VirtualSocketConnection>();
+  private readonly limits: VirtualSocketKernelLimits;
+  private nextConnectionId = 1;
+  private nextEphemeralPort = 49152;
+  private listenWaiters: Deferred<number>[] = [];
+  private readonly readableWaiters = new Set<ReadableWaiter>();
+
+  constructor(
+    private readonly host: VirtualSocketHost,
+    limits?: Partial<VirtualSocketKernelLimits>,
+  ) {
+    this.limits = { ...DEFAULT_LIMITS, ...limits };
+  }
+
+  listen(port: number): number {
+    let n = Number(port);
+    if (!Number.isInteger(n) || n < 0 || n >= 65536) throw new Error(`invalid port: ${port}`);
+    if (n === 0) {
+      while (this.listeners.has(this.nextEphemeralPort)) {
+        this.nextEphemeralPort++;
+        if (this.nextEphemeralPort >= 65535) this.nextEphemeralPort = 49152;
+      }
+      n = this.nextEphemeralPort++;
+      if (this.nextEphemeralPort >= 65535) this.nextEphemeralPort = 49152;
+    }
+    if (!this.listeners.has(n)) {
+      this.listeners.set(n, new VirtualListener(n));
+      try {
+        this.host.__nimbusVirtualSocketDidListen?.(n);
+      } catch {}
+      for (const waiter of this.listenWaiters.splice(0)) waiter.resolve(n);
+    }
+    return n;
+  }
+
+  closeListener(port: number): void {
+    const n = Number(port);
+    const listener = this.listeners.get(n);
+    if (!listener) return;
+    this.listeners.delete(n);
+    for (const conn of listener.drainQueued()) {
+      this.connections.delete(conn.id);
+      conn.abort(`listener closed on port ${n}`, 502);
+    }
+    listener.rejectPendingAccepts(new Error(`port is not listening: ${n}`));
+  }
+
+  async accept(port: number): Promise<AcceptedVirtualConnection> {
+    const listener = this.listeners.get(Number(port));
+    if (!listener) throw new Error(`port is not listening: ${port}`);
+    const conn = await listener.accept();
+    return { id: conn.id, host: '127.0.0.1', port: 0 };
+  }
+
+  acceptNow(port: number): AcceptedVirtualConnection | null {
+    const listener = this.listeners.get(Number(port));
+    if (!listener) throw new Error(`port is not listening: ${port}`);
+    const conn = listener.take();
+    return conn ? { id: conn.id, host: '127.0.0.1', port: 0 } : null;
+  }
+
+  /**
+   * Open a client connection to `port` on the session's loopback.
+   *
+   * The returned id is an ordinary connection id: send() writes the
+   * request, recv()/recvAsync() read the response, close() releases it.
+   * Only HTTP/1.1 crosses a loopback connection - see
+   * LoopbackClientConnection for why - and each one carries a single
+   * request/response exchange.
+   */
+  connect(port: number): number {
+    const conn = this.openLoopbackClient(port);
+    this.connections.set(conn.id, conn);
+    return conn.id;
+  }
+
+  /**
+   * The same client connection as `connect`, handed back in Cloudflare's
+   * `Socket` shape.
+   *
+   * Guests whose sockets are real WASI file descriptors (ruby.wasm, and any
+   * future wasm32-wasi program) reach loopback through this: the WASI shim
+   * stores it in exactly the fd slot a `cloudflare:sockets` connection would
+   * occupy, so `fd_read` on an in-session port is the same suspending read as
+   * `fd_read` on a remote host.
+   */
+  connectStream(port: number): VirtualSocketStream {
+    return socketStreamFor(this.openLoopbackClient(port));
+  }
+
+  /**
+   * An already-accepted connection in the same `Socket` shape, so a server's
+   * accepted socket is the same kind of file descriptor as a client's dialed
+   * one. `accept`/`acceptNow` still hand out the connection id, because accept
+   * itself stays on the cooperative pump - this only binds the result.
+   */
+  streamFor(id: number): VirtualSocketStream {
+    const conn = this.connections.get(Number(id));
+    if (!conn) throw new Error(`connection is closed: ${id}`);
+    return socketStreamFor(conn);
+  }
+
+  private openLoopbackClient(port: number): LoopbackClientConnection {
+    const n = Number(port);
+    if (!Number.isInteger(n) || n <= 0 || n >= 65536) throw new Error(`invalid port: ${port}`);
+    const route = this.host.__nimbusVirtualSocketRouteLoopback;
+    if (typeof route !== 'function') {
+      throw new Error('Nimbus loopback sockets are unavailable in this runtime');
+    }
+    return new LoopbackClientConnection(this.nextConnectionId++, n, route, this.limits);
+  }
+
+  /** Plain number array: Pyodide bytes() and the ruby.wasm base64 bridge both consume it. */
+  recv(id: number, maxBytes: number): number[] {
+    const conn = this.connections.get(Number(id));
+    if (!conn) return [];
+    return conn.read(Number(maxBytes));
+  }
+
+  /**
+   * Suspending read. A client connection has nothing to hand back until
+   * the loopback response arrives, so guests that can suspend (Pyodide
+   * `run_sync`, a JSPI-suspending WASI call) await this instead of
+   * spinning on recv(). An empty result is EOF.
+   */
+  async recvAsync(id: number, maxBytes: number): Promise<number[]> {
+    const conn = this.connections.get(Number(id));
+    if (!conn) return [];
+    return conn.readAsync(Number(maxBytes));
+  }
+
+  /**
+   * Whether an empty recv() means end-of-response rather than "not yet".
+   * Guests that poll instead of suspending (ruby.wasm, whose JS bridge is
+   * synchronous) need the two apart to avoid truncating a response.
+   */
+  atEof(id: number): boolean {
+    const conn = this.connections.get(Number(id));
+    return conn ? conn.atEof() : true;
+  }
+
+  send(id: number, bytesLike: VirtualSocketBytesLike): number {
+    const conn = this.connections.get(Number(id));
+    if (!conn) throw new Error(`connection is closed: ${id}`);
+    return conn.write(bytesLike);
+  }
+
+  close(id: number): void {
+    const conn = this.connections.get(Number(id));
+    if (!conn) return;
+    conn.close();
+    this.connections.delete(Number(id));
+  }
+
+  pending(port: number): number {
+    return this.listeners.get(Number(port))?.pending() ?? 0;
+  }
+
+  firstListeningPort(): number | null {
+    for (const port of this.listeners.keys()) return port;
+    return null;
+  }
+
+  /** select()-style readiness: resolves ports with queued connections, [] on timeout. */
+  waitReadable(ports: readonly number[], timeoutSeconds?: number | null): Promise<number[]> {
+    const normalized = (Array.isArray(ports) ? ports : [])
+      .map((p) => Number(p))
+      .filter((p) => Number.isInteger(p));
+    const readyNow = normalized.filter((port) => this.pending(port) > 0);
+    if (readyNow.length > 0) return Promise.resolve(readyNow);
+    const timeoutMs =
+      timeoutSeconds == null
+        ? this.limits.responseTimeoutMs
+        : Math.max(0, Number(timeoutSeconds) * 1000);
+    const deferred = new Deferred<number[]>();
+    const waiter: ReadableWaiter = {
+      ports: normalized,
+      deferred,
+      timer: setTimeout(() => {
+        this.readableWaiters.delete(waiter);
+        deferred.resolve([]);
+      }, timeoutMs),
+    };
+    this.readableWaiters.add(waiter);
+    return deferred.promise;
+  }
+
+  async waitForListen(timeoutMs?: number): Promise<number | null> {
+    const existing = this.firstListeningPort();
+    if (existing) return existing;
+    const waiter = new Deferred<number>();
+    this.listenWaiters.push(waiter);
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const timeout = new Promise<null>((resolve) => {
+      timer = setTimeout(() => resolve(null), Math.max(1, timeoutMs ?? 5_000));
+    });
+    try {
+      return await Promise.race([waiter.promise, timeout]);
+    } finally {
+      if (timer !== null) clearTimeout(timer);
+    }
+  }
+
+  async handleHttpRequest(port: number, request: Request): Promise<Response> {
+    const n = Number(port);
+    let listener = this.listeners.get(n);
+    if (!listener) {
+      try {
+        await this.host.__nimbusVirtualSocketEnsureListener?.(n);
+      } catch {}
+      listener = this.listeners.get(n);
+    }
+    if (!listener) {
+      return new Response(`Nimbus virtual socket: no listener on port ${port}`, { status: 502 });
+    }
+
+    const body =
+      request.method === 'GET' || request.method === 'HEAD'
+        ? EMPTY_BYTES
+        : new Uint8Array(await request.arrayBuffer());
+    if (body.byteLength > this.limits.maxRequestBodyBytes) {
+      return new Response(
+        `Nimbus virtual socket: request body exceeds ${this.limits.maxRequestBodyBytes} bytes`,
+        { status: 413 },
+      );
+    }
+
+    const id = this.nextConnectionId++;
+    const conn = new VirtualConnection(id, request.method, encodeHttpRequest(request, body), this.limits);
+    this.connections.set(id, conn);
+    listener.push(conn);
+    this.notifyReadable(n);
+
+    const signal: AbortSignal | undefined = request.signal;
+    const onAbort = () => conn.abort('client aborted the request', 499);
+    if (signal?.aborted) onAbort();
+    else signal?.addEventListener('abort', onAbort);
+    try {
+      try {
+        const accepted = await this.host.__nimbusVirtualSocketRequestQueued?.(n);
+        if (accepted === false) {
+          const detail =
+            typeof this.host.__nimbusVirtualSocketLastError === 'string'
+              ? this.host.__nimbusVirtualSocketLastError.trim()
+              : '';
+          const suffix = detail ? `: ${detail}` : '';
+          return new Response(
+            `Nimbus virtual socket: runtime handler did not accept the request${suffix}`,
+            { status: 502 },
+          );
+        }
+      } catch {}
+      return await conn.response(this.limits.responseTimeoutMs);
+    } finally {
+      signal?.removeEventListener('abort', onAbort);
+      conn.close();
+      this.connections.delete(id);
+    }
+  }
+
+  private notifyReadable(port: number): void {
+    for (const waiter of Array.from(this.readableWaiters)) {
+      if (!waiter.ports.includes(port)) continue;
+      const ready = waiter.ports.filter((p) => this.pending(p) > 0);
+      if (ready.length === 0) continue;
+      clearTimeout(waiter.timer);
+      this.readableWaiters.delete(waiter);
+      waiter.deferred.resolve(ready);
+    }
+  }
+}
+
+/**
+ * Install the kernel on the facet global scope. The generated injection
+ * bundle (VIRTUAL_SOCKET_KERNEL_SRC) is exactly this call against
+ * globalThis, wrapped in an IIFE so no identifiers leak into the dynamic
+ * worker module scope.
+ */
+export function installVirtualSocketKernel(
+  scope: VirtualSocketGlobalScope = globalThis as VirtualSocketGlobalScope,
+): VirtualSocketKernel {
+  if (!scope.__nimbusVirtualSockets) {
+    scope.__nimbusVirtualSockets = new VirtualSocketKernel(scope);
+  }
+  return scope.__nimbusVirtualSockets;
+}