@seanhogg/builderforce-webcontainers-core 2026.10.6 → 2026.10.8

package/src/node/http/messages.ts

@@ -0,0 +1,150 @@
+/**
+ * The message and socket objects both halves of `http` share: the socket
+ * stand-in frameworks read connection details from, IncomingMessage (a request
+ * a server receives, or a response a client receives) and the header store
+ * behind ServerResponse and ClientRequest.
+ */
+import { EventEmitterBase } from '../events.js';
+import { Buffer } from '../buffer.js';
+import { Readable } from '../stream/readable.js';
+import { Writable } from '../stream/writable.js';
+
+/** Enough of net.Socket for frameworks that read connection details. */
+export class FakeSocket extends EventEmitterBase {
+  remoteAddress = '127.0.0.1';
+  remotePort = 50000 + Math.floor(Math.random() * 10000);
+  remoteFamily = 'IPv4';
+  localAddress = '127.0.0.1';
+  localPort: number;
+  encrypted = false;
+  readable = true;
+  writable = true;
+  destroyed = false;
+  bytesRead = 0;
+  bytesWritten = 0;
+  constructor(port = 0) {
+    super();
+    this.localPort = port;
+  }
+  setTimeout(_ms: number, cb?: () => void): this { if (cb) this.once('timeout', cb); return this; }
+  setNoDelay(): this { return this; }
+  setKeepAlive(): this { return this; }
+  address() { return { address: this.localAddress, family: 'IPv4', port: this.localPort }; }
+  ref(): this { return this; }
+  unref(): this { return this; }
+  cork(): void {}
+  uncork(): void {}
+  write(): boolean { return true; }
+  end(): this { return this; }
+  destroy(): this {
+    this.destroyed = true;
+    return this;
+  }
+}
+
+export function lowerHeaders(headers: Record<string, string>): { headers: Record<string, string | string[]>; raw: string[] } {
+  const out: Record<string, string | string[]> = {};
+  const raw: string[] = [];
+  for (const [key, value] of Object.entries(headers)) {
+    const k = key.toLowerCase();
+    raw.push(key, value);
+    out[k] = k === 'set-cookie' ? [value] : value;
+  }
+  return { headers: out, raw };
+}
+
+export class IncomingMessage extends Readable {
+  httpVersion = '1.1';
+  httpVersionMajor = 1;
+  httpVersionMinor = 1;
+  method?: string;
+  url?: string;
+  statusCode?: number;
+  statusMessage?: string;
+  headers: Record<string, string | string[]> = {};
+  rawHeaders: string[] = [];
+  trailers: Record<string, string> = {};
+  rawTrailers: string[] = [];
+  complete = false;
+  aborted = false;
+  socket: FakeSocket;
+  connection: FakeSocket;
+
+  constructor(socket: FakeSocket = new FakeSocket()) {
+    super();
+    this.socket = socket;
+    this.connection = socket;
+  }
+
+  override _read(): void {
+    // the body is pushed up front
+  }
+
+  setTimeout(_ms: number, cb?: () => void): this {
+    if (cb) this.once('timeout', cb);
+    return this;
+  }
+
+  /** Fill from wire data; `body` null means none. */
+  _fill(headers: Record<string, string>, body: Uint8Array | null): void {
+    this._setHeaders(headers);
+    if (body?.length) this.push(Buffer.from(body));
+    this._complete();
+  }
+
+  /** Headers first, for a body that streams in through `push` and ends with `_complete`. */
+  _setHeaders(headers: Record<string, string>): void {
+    const { headers: lower, raw } = lowerHeaders(headers);
+    this.headers = lower;
+    this.rawHeaders = raw;
+  }
+
+  _complete(): void {
+    this.push(null);
+    this.complete = true;
+  }
+}
+
+export class OutgoingHeaders extends Writable {
+  protected _headers = new Map<string, { name: string; value: string | string[] }>();
+  headersSent = false;
+  sendDate = true;
+
+  setHeader(name: string, value: string | number | readonly string[]): this {
+    if (this.headersSent) throw Object.assign(new Error('Cannot set headers after they are sent to the client'), { code: 'ERR_HTTP_HEADERS_SENT' });
+    this._headers.set(name.toLowerCase(), { name, value: Array.isArray(value) ? value.map(String) : String(value) });
+    return this;
+  }
+  appendHeader(name: string, value: string | readonly string[]): this {
+    const existing = this.getHeader(name);
+    const list = [...(existing === undefined ? [] : Array.isArray(existing) ? existing : [String(existing)]), ...(Array.isArray(value) ? value : [value as string])];
+    return this.setHeader(name, list);
+  }
+  getHeader(name: string): string | string[] | undefined {
+    return this._headers.get(name.toLowerCase())?.value;
+  }
+  getHeaders(): Record<string, string | string[]> {
+    const out: Record<string, string | string[]> = Object.create(null);
+    for (const [key, { value }] of this._headers) out[key] = value;
+    return out;
+  }
+  getHeaderNames(): string[] {
+    return [...this._headers.keys()];
+  }
+  getRawHeaderNames(): string[] {
+    return [...this._headers.values()].map((h) => h.name);
+  }
+  hasHeader(name: string): boolean {
+    return this._headers.has(name.toLowerCase());
+  }
+  removeHeader(name: string): void {
+    this._headers.delete(name.toLowerCase());
+  }
+  flushHeaders(): void {
+    this.headersSent = true;
+  }
+  setTimeout(_ms: number, cb?: () => void): this {
+    if (cb) this.once('timeout', cb);
+    return this;
+  }
+}

package/src/node/http/server.ts

@@ -1,205 +1,23 @@
 /**
  * `http.createServer` on a virtual port. `listen(port)` registers a handler with
  * the system; each request arrives as plain data (from the preview service
- * worker, or `loopback` from inside the runtime), becomes an IncomingMessage /
- * ServerResponse pair for the app, and the finished response goes back as data.
- * Responses are buffered: streaming (SSE, long-polling) arrives in one piece.
+ * worker, or `loopback` from inside the runtime) and becomes an IncomingMessage /
+ * ServerResponse pair for the app. The response streams back as it is written
+ * (see serverResponse.ts). Requests that ask to upgrade (WebSockets) go to the
+ * `upgrade` listeners with a socket over the raw connection (upgradeSocket.ts).
  */
 import { EventEmitterBase } from '../events.js';
 import { Buffer } from '../buffer.js';
-import { Readable } from '../stream/readable.js';
-import { Writable } from '../stream/writable.js';
 import type { EventLoop } from '../loop.js';
-import type { HttpRequestData, HttpResponseData, System } from '../../system/types.js';
-import { STATUS_CODES } from './status.js';
+import type { ByteChannel, HttpRequestData, HttpStreamResponse, System } from '../../system/types.js';
+import { pushStream } from '../../system/httpStream.js';
+import { FakeSocket, IncomingMessage } from './messages.js';
+import { ServerResponse } from './serverResponse.js';
+import { UpgradeSocket } from './upgradeSocket.js';
 
-/** Enough of net.Socket for frameworks that read connection details. */
-export class FakeSocket extends EventEmitterBase {
-  remoteAddress = '127.0.0.1';
-  remotePort = 50000 + Math.floor(Math.random() * 10000);
-  remoteFamily = 'IPv4';
-  localAddress = '127.0.0.1';
-  localPort: number;
-  encrypted = false;
-  readable = true;
-  writable = true;
-  destroyed = false;
-  bytesRead = 0;
-  bytesWritten = 0;
-  constructor(port = 0) {
-    super();
-    this.localPort = port;
-  }
-  setTimeout(_ms: number, cb?: () => void): this { if (cb) this.once('timeout', cb); return this; }
-  setNoDelay(): this { return this; }
-  setKeepAlive(): this { return this; }
-  address() { return { address: this.localAddress, family: 'IPv4', port: this.localPort }; }
-  ref(): this { return this; }
-  unref(): this { return this; }
-  cork(): void {}
-  uncork(): void {}
-  write(): boolean { return true; }
-  end(): this { return this; }
-  destroy(): this {
-    this.destroyed = true;
-    return this;
-  }
-}
-
-function lowerHeaders(headers: Record<string, string>): { headers: Record<string, string | string[]>; raw: string[] } {
-  const out: Record<string, string | string[]> = {};
-  const raw: string[] = [];
-  for (const [key, value] of Object.entries(headers)) {
-    const k = key.toLowerCase();
-    raw.push(key, value);
-    out[k] = k === 'set-cookie' ? [value] : value;
-  }
-  return { headers: out, raw };
-}
-
-export class IncomingMessage extends Readable {
-  httpVersion = '1.1';
-  httpVersionMajor = 1;
-  httpVersionMinor = 1;
-  method?: string;
-  url?: string;
-  statusCode?: number;
-  statusMessage?: string;
-  headers: Record<string, string | string[]> = {};
-  rawHeaders: string[] = [];
-  trailers: Record<string, string> = {};
-  rawTrailers: string[] = [];
-  complete = false;
-  aborted = false;
-  socket: FakeSocket;
-  connection: FakeSocket;
-
-  constructor(socket: FakeSocket = new FakeSocket()) {
-    super();
-    this.socket = socket;
-    this.connection = socket;
-  }
-
-  override _read(): void {
-    // the body is pushed up front
-  }
-
-  setTimeout(_ms: number, cb?: () => void): this {
-    if (cb) this.once('timeout', cb);
-    return this;
-  }
-
-  /** Fill from wire data; `body` null means none. */
-  _fill(headers: Record<string, string>, body: Uint8Array | null): void {
-    const { headers: lower, raw } = lowerHeaders(headers);
-    this.headers = lower;
-    this.rawHeaders = raw;
-    if (body?.length) this.push(Buffer.from(body));
-    this.push(null);
-    this.complete = true;
-  }
-}
-
-export class OutgoingHeaders extends Writable {
-  protected _headers = new Map<string, { name: string; value: string | string[] }>();
-  headersSent = false;
-  sendDate = true;
-
-  setHeader(name: string, value: string | number | readonly string[]): this {
-    if (this.headersSent) throw Object.assign(new Error('Cannot set headers after they are sent to the client'), { code: 'ERR_HTTP_HEADERS_SENT' });
-    this._headers.set(name.toLowerCase(), { name, value: Array.isArray(value) ? value.map(String) : String(value) });
-    return this;
-  }
-  appendHeader(name: string, value: string | readonly string[]): this {
-    const existing = this.getHeader(name);
-    const list = [...(existing === undefined ? [] : Array.isArray(existing) ? existing : [String(existing)]), ...(Array.isArray(value) ? value : [value as string])];
-    return this.setHeader(name, list);
-  }
-  getHeader(name: string): string | string[] | undefined {
-    return this._headers.get(name.toLowerCase())?.value;
-  }
-  getHeaders(): Record<string, string | string[]> {
-    const out: Record<string, string | string[]> = Object.create(null);
-    for (const [key, { value }] of this._headers) out[key] = value;
-    return out;
-  }
-  getHeaderNames(): string[] {
-    return [...this._headers.keys()];
-  }
-  getRawHeaderNames(): string[] {
-    return [...this._headers.values()].map((h) => h.name);
-  }
-  hasHeader(name: string): boolean {
-    return this._headers.has(name.toLowerCase());
-  }
-  removeHeader(name: string): void {
-    this._headers.delete(name.toLowerCase());
-  }
-  flushHeaders(): void {
-    this.headersSent = true;
-  }
-  setTimeout(_ms: number, cb?: () => void): this {
-    if (cb) this.once('timeout', cb);
-    return this;
-  }
-}
-
-export class ServerResponse extends OutgoingHeaders {
-  statusCode = 200;
-  statusMessage = '';
-  req: IncomingMessage;
-  socket: FakeSocket;
-  connection: FakeSocket;
-  chunkedEncoding = false;
-  shouldKeepAlive = false;
-  private readonly chunks: Uint8Array[] = [];
-
-  constructor(req: IncomingMessage, private readonly onDone: (response: HttpResponseData) => void) {
-    super({ decodeStrings: true });
-    this.req = req;
-    this.socket = req.socket;
-    this.connection = req.socket;
-  }
-
-  get finished(): boolean {
-    return this.writableEnded;
-  }
-
-  writeHead(status: number, message?: string | Record<string, unknown> | unknown[], headers?: Record<string, unknown> | unknown[]): this {
-    if (typeof message !== 'string') [headers, message] = [message, undefined];
-    this.statusCode = status;
-    if (message) this.statusMessage = message;
-    if (Array.isArray(headers)) {
-      for (let i = 0; i + 1 < headers.length; i += 2) this.setHeader(String(headers[i]), headers[i + 1] as string);
-    } else if (headers) {
-      for (const [k, v] of Object.entries(headers)) if (v !== undefined) this.setHeader(k, v as string);
-    }
-    this.headersSent = true;
-    return this;
-  }
-  writeContinue(): void {}
-  writeProcessing(): void {}
-  writeEarlyHints(): void {}
-  addTrailers(): void {}
-  assignSocket(): void {}
-  detachSocket(): void {}
-
-  override _write(chunk: Uint8Array, _encoding: string, callback: () => void): void {
-    this.headersSent = true;
-    this.chunks.push(chunk);
-    callback();
-  }
-
-  override _final(callback: () => void): void {
-    this.headersSent = true;
-    const headers: Record<string, string | string[]> = {};
-    for (const { name, value } of this._headers.values()) headers[name] = value;
-    const body = Buffer.concat(this.chunks);
-    if (this.req.method === 'HEAD') this.chunks.length = 0;
-    this.onDone({ status: this.statusCode, statusText: this.statusMessage || STATUS_CODES[this.statusCode] || '', headers, body: this.req.method === 'HEAD' ? new Uint8Array() : body });
-    callback();
-  }
-}
+export { FakeSocket, IncomingMessage, OutgoingHeaders } from './messages.js';
+export { ServerResponse } from './serverResponse.js';
+export { UpgradeSocket } from './upgradeSocket.js';
 
 export interface ServerDeps {
   system: System;
@@ -228,7 +46,7 @@ export class Server extends EventEmitterBase {
     const port = typeof first === 'object' && first ? Number((first as { port?: number }).port ?? 0) : Number(first ?? 0);
     if (callback) this.once('listening', callback);
     try {
-      this.registration = this.deps.system.listen(port, (request) => this.handle(request));
+      this.registration = this.deps.system.listen(port, (request) => this.handle(request), (request, socket) => this.upgrade(request, socket));
     } catch (error) {
       queueMicrotask(() => this.emit('error', error));
       return this;
@@ -278,20 +96,29 @@ export class Server extends EventEmitterBase {
     cb(null, 0);
   }
 
-  private handle(request: HttpRequestData): Promise<HttpResponseData> {
+  private toIncoming(request: HttpRequestData, socket: FakeSocket, headers: Record<string, string>, body: Uint8Array | null): IncomingMessage {
+    const req = new IncomingMessage(socket);
+    req.method = request.method.toUpperCase();
+    req.url = request.url;
+    req._fill(headers, body);
+    return req;
+  }
+
+  private handle(request: HttpRequestData): Promise<HttpStreamResponse> {
     return new Promise((resolve) => {
-      const socket = new FakeSocket(this.registration?.port ?? 0);
-      const req = new IncomingMessage(socket);
-      req.method = request.method.toUpperCase();
-      req.url = request.url;
       // Body parsers (body-parser/type-is) only read a body announced by
       // content-length or transfer-encoding; a browser-originated request
       // relayed by the service worker carries neither.
       const headers = { ...request.headers };
       const announced = Object.keys(headers).some((k) => /^(content-length|transfer-encoding)$/i.test(k));
       if (!announced && request.body?.length) headers['content-length'] = String(request.body.length);
-      req._fill(headers, request.body);
-      const res = new ServerResponse(req, resolve);
+      const req = this.toIncoming(request, new FakeSocket(this.registration?.port ?? 0), headers, request.body);
+      const body = pushStream(() => this.deps.loop._run(() => res._hangUp()));
+      const res: ServerResponse = new ServerResponse(req, {
+        head: (head) => resolve({ ...head, body: body.stream }),
+        chunk: (data) => body.push(data),
+        end: () => body.end(),
+      });
       this.deps.loop._run(() => {
         try {
           this.emit('request', req, res);
@@ -305,4 +132,12 @@ export class Server extends EventEmitterBase {
       });
     });
   }
+
+  /** A connection asking to upgrade: Node destroys it when nobody listens for `upgrade`. */
+  private upgrade(request: HttpRequestData, channel: ByteChannel): void {
+    if (!this.listenerCount('upgrade')) return channel.close();
+    const socket = new UpgradeSocket(channel, this.registration?.port ?? 0, () => this.deps.loop.hold());
+    const req = this.toIncoming(request, socket as unknown as FakeSocket, request.headers, null);
+    this.deps.loop._run(() => this.emit('upgrade', req, socket, Buffer.alloc(0)));
+  }
 }

package/src/node/http/serverResponse.ts

@@ -0,0 +1,98 @@
+/**
+ * ServerResponse, streamed: the head goes out on `writeHead`/`flushHeaders` or
+ * the first write, each `write` is a body chunk, `end` ends the body. So
+ * Server-Sent Events and chunked progress reach the client as they happen. A
+ * client that hangs up mid-response is seen the way Node reports it.
+ */
+import type { HttpResponseHead } from '../../system/types.js';
+import { STATUS_CODES } from './status.js';
+import { FakeSocket, IncomingMessage, OutgoingHeaders } from './messages.js';
+
+/** Where a response goes as it is written. */
+export interface ResponseSink {
+  head(head: HttpResponseHead): void;
+  chunk(data: Uint8Array): void;
+  end(): void;
+}
+
+/** Statuses that never carry a body. */
+const NO_BODY = new Set([101, 204, 304]);
+
+export class ServerResponse extends OutgoingHeaders {
+  statusCode = 200;
+  statusMessage = '';
+  req: IncomingMessage;
+  socket: FakeSocket;
+  connection: FakeSocket;
+  chunkedEncoding = false;
+  shouldKeepAlive = false;
+  private headWritten = false;
+  private hungUp = false;
+
+  constructor(req: IncomingMessage, private readonly sink: ResponseSink) {
+    super({ decodeStrings: true });
+    this.req = req;
+    this.socket = req.socket;
+    this.connection = req.socket;
+  }
+
+  get finished(): boolean {
+    return this.writableEnded;
+  }
+
+  writeHead(status: number, message?: string | Record<string, unknown> | unknown[], headers?: Record<string, unknown> | unknown[]): this {
+    if (typeof message !== 'string') [headers, message] = [message, undefined];
+    this.statusCode = status;
+    if (message) this.statusMessage = message;
+    if (Array.isArray(headers)) {
+      for (let i = 0; i + 1 < headers.length; i += 2) this.setHeader(String(headers[i]), headers[i + 1] as string);
+    } else if (headers) {
+      for (const [k, v] of Object.entries(headers)) if (v !== undefined) this.setHeader(k, v as string);
+    }
+    this.sendHead();
+    return this;
+  }
+  override flushHeaders(): void {
+    this.sendHead();
+  }
+  writeContinue(): void {}
+  writeProcessing(): void {}
+  writeEarlyHints(): void {}
+  addTrailers(): void {}
+  assignSocket(): void {}
+  detachSocket(): void {}
+
+  override _write(chunk: Uint8Array, _encoding: string, callback: () => void): void {
+    this.sendHead();
+    if (!this.hungUp && this.req.method !== 'HEAD' && !NO_BODY.has(this.statusCode)) this.sink.chunk(new Uint8Array(chunk));
+    callback();
+  }
+
+  override _final(callback: () => void): void {
+    this.sendHead();
+    if (!this.hungUp) this.sink.end();
+    callback();
+  }
+
+  /** The client went away (closed its EventSource, navigated off): `aborted`/`close` on the request, `close` here; later writes are dropped. */
+  _hangUp(): void {
+    if (this.hungUp || this.writableFinished) return;
+    this.hungUp = true;
+    this._writableState.emitClose = false;
+    this.req.aborted = true;
+    this.req.emit('aborted');
+    this.req.emit('close');
+    this.socket.destroyed = true;
+    this.socket.emit('close', false);
+    this.emit('close');
+  }
+
+  private sendHead(): void {
+    this.headersSent = true;
+    if (this.headWritten) return;
+    this.headWritten = true;
+    const headers: Record<string, string | string[]> = {};
+    for (const { name, value } of this._headers.values()) headers[name] = value;
+    this.sink.head({ status: this.statusCode, statusText: this.statusMessage || STATUS_CODES[this.statusCode] || '', headers });
+  }
+}

package/src/node/http/upgradeSocket.ts

@@ -0,0 +1,79 @@
+/**
+ * The socket an `http.Server` hands its `upgrade` listeners: a real Duplex
+ * over the upgraded connection's byte pipe, with the slice of net.Socket that
+ * WebSocket servers touch (`ws` writes its `101` reply and frames with
+ * `write(data, cb)`, corks, pauses, reads `_readableState`, and calls
+ * `setNoDelay`/`setTimeout`). Raw bytes only — framing is the package's job.
+ */
+import { Buffer } from '../buffer.js';
+import { Duplex } from '../stream/index.js';
+import type { ByteChannel } from '../../system/types.js';
+
+type Callback = (error?: Error | null) => void;
+
+export class UpgradeSocket extends Duplex {
+  remoteAddress = '127.0.0.1';
+  remotePort = 50000 + Math.floor(Math.random() * 10000);
+  remoteFamily = 'IPv4';
+  localAddress = '127.0.0.1';
+  localPort: number;
+  encrypted = false;
+  connecting = false;
+  bytesRead = 0;
+  bytesWritten = 0;
+  private release?: () => void;
+
+  /** `hold` keeps the process alive while the connection is open, as a TCP socket would. */
+  constructor(private readonly channel: ByteChannel, port: number, hold?: () => () => void) {
+    super({ allowHalfOpen: false });
+    this.localPort = port;
+    this.release = hold?.();
+    channel.onData((data) => {
+      this.bytesRead += data.byteLength;
+      this.push(Buffer.from(data.buffer as ArrayBuffer, data.byteOffset, data.byteLength));
+    });
+    channel.onClose(() => {
+      this.push(null);
+      this.end();
+    });
+    this.once('close', () => {
+      this.release?.();
+      this.release = undefined;
+    });
+  }
+
+  override _read(): void {
+    // bytes are pushed as they arrive
+  }
+
+  _write(chunk: Uint8Array, _encoding: string, callback: Callback): void {
+    this.bytesWritten += chunk.byteLength;
+    this.channel.send(chunk);
+    callback();
+  }
+
+  _final(callback: Callback): void {
+    this.channel.close();
+    this.push(null);
+    callback();
+  }
+
+  override _destroy(error: Error | null, callback: Callback): void {
+    this.channel.close();
+    callback(error);
+  }
+
+  setTimeout(_ms: number, cb?: () => void): this {
+    if (cb) this.once('timeout', cb);
+    return this;
+  }
+  setNoDelay(): this { return this; }
+  setKeepAlive(): this { return this; }
+  address() { return { address: this.localAddress, family: 'IPv4', port: this.localPort }; }
+  ref(): this { return this; }
+  unref(): this {
+    this.release?.();
+    this.release = undefined;
+    return this;
+  }
+}

package/src/node/runtime.ts

@@ -57,8 +57,8 @@ export async function startNode(options: NodeOptions): Promise<NodeInstance> {
   // Servers die with the process: wrap listen so exit can close what is left open.
   const processSystem: System = {
     ...system,
-    listen(port, handler) {
-      const registration = system.listen(port, handler);
+    listen(port, handler, upgrade) {
+      const registration = system.listen(port, handler, upgrade);
       const tracked = {
         port: registration.port,
         close() {