@seanhogg/builderforce-webcontainers-core 2026.10.7 → 2026.10.8

package/src/shell/tokenize.ts

@@ -0,0 +1,257 @@
+/**
+ * Shell tokens: words (with their quoting, as segments) and operators. Here-
+ * documents are read here too — `<<EOF` is followed, after the end of its line,
+ * by body lines up to the delimiter — so the parser sees each body attached to
+ * its redirect.
+ */
+import type { Segment, Word } from './ast.js';
+
+export type Token =
+  | { type: 'word'; word: Word; raw: string }
+  | { type: 'op'; op: string }
+  | { type: 'heredoc'; body?: Word };
+
+export class ShellSyntaxError extends Error {
+  /** The input ended inside a quote, a block or a here-document: an interactive shell asks for more. */
+  constructor(message: string, readonly incomplete = false) {
+    super(message);
+  }
+}
+
+const OPERATORS = ['2>&1', '>&2', '2>>', '<<-', '&&', '||', ';;', '>>', '<<', '2>', '&>', '|', '&', ';', '>', '<', '(', ')', '\n'];
+const SPECIAL_VARS = /^[?$#@*!0-9]/;
+/** Unquoted characters that end a word. */
+const WORD_BREAK = /[;|&<>()]/;
+
+/** Find the `)` closing a `$(` at `start` (just after the paren), honouring quotes and nesting. */
+function matchParen(input: string, start: number): number {
+  let depth = 1;
+  for (let i = start; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === '\\') i++;
+    else if (ch === "'") i = input.indexOf("'", i + 1) < 0 ? input.length : input.indexOf("'", i + 1);
+    else if (ch === '"') {
+      for (i++; i < input.length && input[i] !== '"'; i++) if (input[i] === '\\') i++;
+    } else if (ch === '(') depth++;
+    else if (ch === ')' && --depth === 0) return i;
+  }
+  throw new ShellSyntaxError('unexpected end of input: missing )', true);
+}
+
+/** Parse `$…` at `i` (pointing at `$`); returns the segment and the index after it. */
+function readDollar(input: string, i: number, quoted: boolean): [Segment, number] {
+  const next = input[i + 1];
+  if (next === '(') {
+    const end = matchParen(input, i + 2);
+    return [{ kind: 'cmd', source: input.slice(i + 2, end), quoted }, end + 1];
+  }
+  if (next === '{') {
+    const end = input.indexOf('}', i + 2);
+    if (end < 0) throw new ShellSyntaxError('unexpected end of input: missing }', true);
+    const body = input.slice(i + 2, end);
+    const m = /^([A-Za-z_][\w]*|[?$#@*!0-9])(?:(:-|-|:=|:\+)(.*))?$/s.exec(body);
+    if (!m) throw new ShellSyntaxError(`bad substitution: \${${body}}`);
+    const seg: Segment = { kind: 'var', name: m[1]!, quoted };
+    if (m[2]) {
+      seg.op = m[2] as ':-';
+      seg.arg = tokenizeWord(m[3] ?? '', quoted);
+    }
+    return [seg, end + 1];
+  }
+  if (next && SPECIAL_VARS.test(next)) return [{ kind: 'var', name: next, quoted }, i + 2];
+  const m = /^[A-Za-z_]\w*/.exec(input.slice(i + 1));
+  if (!m) return [{ kind: 'text', value: '$', quoted }, i + 1];
+  return [{ kind: 'var', name: m[0], quoted }, i + 1 + m[0].length];
+}
+
+/** Segments of a word body (used for `${x:-default}` arguments). */
+function tokenizeWord(text: string, quoted: boolean): Word {
+  const tokens = tokenize(text, true);
+  const word: Word = [];
+  for (const t of tokens) if (t.type === 'word') word.push(...t.word.map((s) => (s.kind === 'tilde' ? s : { ...s, quoted: quoted || ('quoted' in s && s.quoted) } as Segment)));
+  return word;
+}
+
+/** A here-document body as a word: `$VAR`, `$(…)` and backticks expand, nothing splits or globs. */
+function heredocWord(body: string): Word {
+  const word: Word = [];
+  let text = '';
+  const flush = () => {
+    if (text) word.push({ kind: 'text', value: text, quoted: true });
+    text = '';
+  };
+  for (let i = 0; i < body.length;) {
+    const c = body[i]!;
+    if (c === '\\' && /[$`\\\n]/.test(body[i + 1] ?? '')) {
+      if (body[i + 1] !== '\n') text += body[i + 1];
+      i += 2;
+    } else if (c === '$') {
+      flush();
+      const [seg, next] = readDollar(body, i, true);
+      word.push(seg);
+      i = next;
+    } else if (c === '`') {
+      flush();
+      const end = body.indexOf('`', i + 1);
+      if (end < 0) throw new ShellSyntaxError('unterminated ` in here-document');
+      word.push({ kind: 'cmd', source: body.slice(i + 1, end), quoted: true });
+      i = end + 1;
+    } else {
+      text += c;
+      i++;
+    }
+  }
+  flush();
+  return word.length ? word : [{ kind: 'text', value: '', quoted: true }];
+}
+
+interface PendingHeredoc {
+  token: { type: 'heredoc'; body?: Word };
+  delimiter: string;
+  strip: boolean;
+  quoted: boolean;
+}
+
+/** Read the bodies of pending here-documents starting at `i` (the start of a line); returns the index after them. */
+function readHeredocs(input: string, i: number, pending: PendingHeredoc[]): number {
+  for (const doc of pending) {
+    const lines: string[] = [];
+    for (;;) {
+      if (i >= input.length) throw new ShellSyntaxError(`unexpected end of input: here-document delimited by ${doc.delimiter}`, true);
+      const end = input.indexOf('\n', i);
+      let line = input.slice(i, end < 0 ? input.length : end).replace(/\r$/, '');
+      i = end < 0 ? input.length : end + 1;
+      if (doc.strip) line = line.replace(/^\t+/, '');
+      if (line === doc.delimiter) break;
+      if (end < 0) throw new ShellSyntaxError(`unexpected end of input: here-document delimited by ${doc.delimiter}`, true);
+      lines.push(line);
+    }
+    const body = lines.map((l) => l + '\n').join('');
+    doc.token.body = doc.quoted ? [{ kind: 'text', value: body, quoted: true }] : heredocWord(body);
+  }
+  pending.length = 0;
+  return i;
+}
+
+export function tokenize(input: string, wordOnly = false): Token[] {
+  const tokens: Token[] = [];
+  const pending: PendingHeredoc[] = [];
+  let i = 0;
+  while (i < input.length) {
+    const ch = input[i]!;
+    if (ch === ' ' || ch === '\t' || ch === '\r') {
+      i++;
+      continue;
+    }
+    if (ch === '\\' && input[i + 1] === '\n') {
+      i += 2;
+      continue;
+    }
+    if (ch === '#') {
+      while (i < input.length && input[i] !== '\n') i++;
+      continue;
+    }
+    if (!wordOnly) {
+      const op = OPERATORS.find((o) => input.startsWith(o, i));
+      if (op) {
+        tokens.push({ type: 'op', op });
+        i += op.length;
+        if (op === '\n' && pending.length) i = readHeredocs(input, i, pending);
+        if (op === '<<' || op === '<<-') {
+          while (input[i] === ' ' || input[i] === '\t') i++;
+          const start = i;
+          while (i < input.length && !/[\s;|&<>()]/.test(input[i]!)) i++;
+          const raw = input.slice(start, i);
+          if (!raw) throw new ShellSyntaxError('syntax error: here-document needs a delimiter');
+          const token: PendingHeredoc['token'] = { type: 'heredoc' };
+          tokens.push(token);
+          pending.push({ token, delimiter: raw.replace(/["'\\]/g, ''), strip: op === '<<-', quoted: /["'\\]/.test(raw) });
+        }
+        continue;
+      }
+    }
+    // A word: runs until unquoted whitespace or an operator character.
+    const word: Word = [];
+    const start = i;
+    let text = '';
+    const flush = () => {
+      if (text) word.push({ kind: 'text', value: text, quoted: false });
+      text = '';
+    };
+    if (input[i] === '~' && (i + 1 >= input.length || /[\s/;|&<>()]/.test(input[i + 1]!))) {
+      word.push({ kind: 'tilde' });
+      i++;
+    }
+    while (i < input.length) {
+      const c = input[i]!;
+      if (/[\s]/.test(c) && !wordOnly) break;
+      if (!wordOnly && WORD_BREAK.test(c)) break;
+      if (c === '\\') {
+        text += input[i + 1] ?? '';
+        i += 2;
+      } else if (c === "'") {
+        const end = input.indexOf("'", i + 1);
+        if (end < 0) throw new ShellSyntaxError('unexpected end of input: unterminated quote', true);
+        flush();
+        word.push({ kind: 'text', value: input.slice(i + 1, end), quoted: true });
+        i = end + 1;
+      } else if (c === '"') {
+        flush();
+        i++;
+        let inner = '';
+        const pushInner = () => {
+          if (inner) word.push({ kind: 'text', value: inner, quoted: true });
+          inner = '';
+        };
+        let closed = false;
+        while (i < input.length) {
+          const d = input[i]!;
+          if (d === '"') {
+            closed = true;
+            i++;
+            break;
+          }
+          if (d === '\\' && /["\\$`\n]/.test(input[i + 1] ?? '')) {
+            inner += input[i + 1];
+            i += 2;
+          } else if (d === '$') {
+            pushInner();
+            const [seg, next] = readDollar(input, i, true);
+            word.push(seg);
+            i = next;
+          } else if (d === '`') {
+            pushInner();
+            const end = input.indexOf('`', i + 1);
+            if (end < 0) throw new ShellSyntaxError('unexpected end of input: unterminated `', true);
+            word.push({ kind: 'cmd', source: input.slice(i + 1, end), quoted: true });
+            i = end + 1;
+          } else {
+            inner += d;
+            i++;
+          }
+        }
+        if (!closed) throw new ShellSyntaxError('unexpected end of input: unterminated quote', true);
+        pushInner();
+        if (!word.length || word[word.length - 1]!.kind !== 'text') word.push({ kind: 'text', value: '', quoted: true });
+      } else if (c === '$') {
+        flush();
+        const [seg, next] = readDollar(input, i, false);
+        word.push(seg);
+        i = next;
+      } else if (c === '`') {
+        flush();
+        const end = input.indexOf('`', i + 1);
+        if (end < 0) throw new ShellSyntaxError('unexpected end of input: unterminated `', true);
+        word.push({ kind: 'cmd', source: input.slice(i + 1, end), quoted: false });
+        i = end + 1;
+      } else {
+        text += c;
+        i++;
+      }
+    }
+    flush();
+    tokens.push({ type: 'word', word, raw: input.slice(start, i) });
+  }
+  if (pending.length) throw new ShellSyntaxError(`unexpected end of input: here-document delimited by ${pending[0]!.delimiter}`, true);
+  return tokens;
+}

package/src/system/cookieJar.ts

@@ -0,0 +1,187 @@
+/**
+ * Cookies for virtual servers. A service worker cannot hand `Set-Cookie` to
+ * the browser (it is a forbidden header on a synthesized response), so the
+ * host keeps the jar itself: it stores what a server sets and sends it back as
+ * the `Cookie` header on later requests — per preview and per port, which is
+ * the origin a server would have had. Paths, `Max-Age`/`Expires` and deletion
+ * follow RFC 6265; `HttpOnly` cookies are stored and sent but never shown to
+ * page script; `Domain`, `Secure` and `SameSite` have nothing to choose between
+ * (every request goes to the one server) and are kept only as metadata.
+ */
+
+export interface StoredCookie {
+  name: string;
+  value: string;
+  path: string;
+  /** Epoch ms; undefined for a session cookie (lives as long as the runtime). */
+  expires?: number;
+  httpOnly: boolean;
+  secure: boolean;
+  sameSite?: string;
+}
+
+/** RFC 6265 §5.1.4: the directory of the request path. */
+export function defaultCookiePath(requestPath: string): string {
+  const path = requestPath.split('?')[0] ?? '/';
+  if (!path.startsWith('/')) return '/';
+  const slash = path.lastIndexOf('/');
+  return slash <= 0 ? '/' : path.slice(0, slash);
+}
+
+/** RFC 6265 §5.1.4 path-match. */
+export function cookiePathMatches(cookiePath: string, requestPath: string): boolean {
+  const path = requestPath.split('?')[0] || '/';
+  if (path === cookiePath) return true;
+  if (!path.startsWith(cookiePath)) return false;
+  return cookiePath.endsWith('/') || path[cookiePath.length] === '/';
+}
+
+/** Parse one `Set-Cookie` value; undefined when malformed. `deleted` marks an already-expired cookie (a deletion). */
+export function parseSetCookie(header: string, requestPath: string, now = Date.now()): (StoredCookie & { deleted: boolean }) | undefined {
+  const [pair = '', ...attributes] = header.split(';');
+  const eq = pair.indexOf('=');
+  if (eq < 0) return undefined;
+  const name = pair.slice(0, eq).trim();
+  if (!name) return undefined;
+  const cookie: StoredCookie & { deleted: boolean } = { name, value: pair.slice(eq + 1).trim(), path: defaultCookiePath(requestPath), httpOnly: false, secure: false, deleted: false };
+  let maxAge: number | undefined;
+  let expires: number | undefined;
+  for (const attribute of attributes) {
+    const i = attribute.indexOf('=');
+    const key = (i < 0 ? attribute : attribute.slice(0, i)).trim().toLowerCase();
+    const value = i < 0 ? '' : attribute.slice(i + 1).trim();
+    if (key === 'path' && value.startsWith('/')) cookie.path = value;
+    else if (key === 'max-age' && /^-?\d+$/.test(value)) maxAge = Number(value);
+    else if (key === 'expires') {
+      const at = Date.parse(value);
+      if (!Number.isNaN(at)) expires = at;
+    } else if (key === 'httponly') cookie.httpOnly = true;
+    else if (key === 'secure') cookie.secure = true;
+    else if (key === 'samesite') cookie.sameSite = value;
+  }
+  // Max-Age wins over Expires (§5.3 step 3).
+  if (maxAge !== undefined) cookie.expires = maxAge <= 0 ? 0 : now + maxAge * 1000;
+  else if (expires !== undefined) cookie.expires = expires;
+  cookie.deleted = cookie.expires !== undefined && cookie.expires <= now;
+  return cookie;
+}
+
+export class CookieJar {
+  private cookies: StoredCookie[] = [];
+  private readonly listeners = new Set<() => void>();
+
+  /** Store `Set-Cookie` values from a response to `requestPath`; returns whether anything changed. */
+  store(setCookie: string | readonly string[] | undefined, requestPath: string, now = Date.now()): boolean {
+    if (!setCookie) return false;
+    let changed = false;
+    for (const header of typeof setCookie === 'string' ? [setCookie] : setCookie) {
+      const cookie = parseSetCookie(header, requestPath, now);
+      if (cookie) changed = this.put(cookie, now, true) || changed;
+    }
+    if (changed) this.notify();
+    return changed;
+  }
+
+  /** A `document.cookie = '…'` assignment from a page at `pagePath`. Script cannot create or replace an `HttpOnly` cookie. */
+  setFromDocument(assignment: string, pagePath: string, now = Date.now()): boolean {
+    const cookie = parseSetCookie(assignment, pagePath, now);
+    if (!cookie || cookie.httpOnly) return false;
+    const changed = this.put(cookie, now, false);
+    if (changed) this.notify();
+    return changed;
+  }
+
+  /** The `Cookie` header for a request to `path`; undefined when no cookie applies. Longer paths first. */
+  header(path: string, now = Date.now()): string | undefined {
+    const text = this.matching(path, now, true);
+    return text || undefined;
+  }
+
+  /** What `document.cookie` reads on a page at `path`: the same cookies, minus `HttpOnly` ones. */
+  documentCookie(path: string, now = Date.now()): string {
+    return this.matching(path, now, false);
+  }
+
+  /** Every live cookie. */
+  list(now = Date.now()): StoredCookie[] {
+    this.expire(now);
+    return this.cookies.map((c) => ({ ...c }));
+  }
+
+  clear(): void {
+    if (!this.cookies.length) return;
+    this.cookies = [];
+    this.notify();
+  }
+
+  /** The jar changed (a server or a page set or deleted a cookie). */
+  onChange(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private put(cookie: StoredCookie & { deleted: boolean }, now: number, fromHttp: boolean): boolean {
+    this.expire(now);
+    const index = this.cookies.findIndex((c) => c.name === cookie.name && c.path === cookie.path);
+    const existing = index < 0 ? undefined : this.cookies[index];
+    if (existing?.httpOnly && !fromHttp) return false;
+    const { deleted, ...stored } = cookie;
+    if (deleted) {
+      if (index < 0) return false;
+      this.cookies.splice(index, 1);
+      return true;
+    }
+    if (existing && existing.value === stored.value && existing.expires === stored.expires && existing.httpOnly === stored.httpOnly) return false;
+    if (index < 0) this.cookies.push(stored);
+    else this.cookies[index] = stored;
+    return true;
+  }
+
+  private matching(path: string, now: number, includeHttpOnly: boolean): string {
+    this.expire(now);
+    return this.cookies
+      .filter((c) => (includeHttpOnly || !c.httpOnly) && cookiePathMatches(c.path, path))
+      .sort((a, b) => b.path.length - a.path.length)
+      .map((c) => `${c.name}=${c.value}`)
+      .join('; ');
+  }
+
+  private expire(now: number): void {
+    const live = this.cookies.filter((c) => c.expires === undefined || c.expires > now);
+    if (live.length === this.cookies.length) return;
+    this.cookies = live;
+    this.notify();
+  }
+
+  private notify(): void {
+    for (const listener of this.listeners) listener();
+  }
+}
+
+/** One jar per virtual server port — what the preview host keeps for its runtime. */
+export class PortCookieJars {
+  private readonly jars = new Map<number, CookieJar>();
+  private readonly listeners = new Set<(port: number) => void>();
+
+  jar(port: number): CookieJar {
+    let jar = this.jars.get(port);
+    if (!jar) {
+      jar = new CookieJar();
+      jar.onChange(() => {
+        for (const listener of this.listeners) listener(port);
+      });
+      this.jars.set(port, jar);
+    }
+    return jar;
+  }
+
+  /** Some port's jar changed. */
+  onChange(listener: (port: number) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  clear(): void {
+    for (const jar of this.jars.values()) jar.clear();
+  }
+}

package/src/system/httpStream.ts

@@ -0,0 +1,168 @@
+/**
+ * Building blocks for streamed HTTP between programs and hosts: a body stream
+ * fed by pushes (a server's `res.write`, chunks arriving over postMessage),
+ * buffering helpers for callers that want the whole response, and the in-memory
+ * byte pipe an upgraded connection runs over.
+ */
+import type { ByteChannel, HttpResponseData, HttpResponseHead, HttpStreamResponse } from './types.js';
+
+export interface PushStream {
+  readonly stream: ReadableStream<Uint8Array>;
+  /** Queue a chunk; ignored once the stream is closed or cancelled. */
+  push(chunk: Uint8Array): void;
+  end(): void;
+  /** End with an error: the reader sees a failed read (a truncated response). */
+  fail(error: unknown): void;
+  /** True once ended, failed or cancelled. */
+  readonly done: boolean;
+}
+
+/** A body stream fed from outside. `onCancel` runs when the reader hangs up before the end. */
+export function pushStream(onCancel?: (reason: unknown) => void): PushStream {
+  let controller!: ReadableStreamDefaultController<Uint8Array>;
+  let done = false;
+  const stream = new ReadableStream<Uint8Array>({
+    start: (c) => void (controller = c),
+    cancel: (reason) => {
+      if (done) return;
+      done = true;
+      onCancel?.(reason);
+    },
+  });
+  return {
+    stream,
+    push(chunk) {
+      if (!done && chunk.byteLength) controller.enqueue(chunk);
+    },
+    end() {
+      if (done) return;
+      done = true;
+      controller.close();
+    },
+    fail(error) {
+      if (done) return;
+      done = true;
+      controller.error(error);
+    },
+    get done() {
+      return done;
+    },
+  };
+}
+
+/** A stream holding exactly `bytes`. */
+export function bytesStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      if (bytes.byteLength) controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+/** A complete plain-text response (errors: nothing listening, the server exited). */
+export function textResponse(status: number, text: string): HttpStreamResponse {
+  return { status, headers: { 'content-type': 'text/plain; charset=utf-8' }, body: bytesStream(new TextEncoder().encode(text)) };
+}
+
+/** Read a body stream to the end. */
+export async function readBody(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  let length = 0;
+  const reader = stream.getReader();
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    length += value.byteLength;
+  }
+  if (chunks.length === 1) return chunks[0]!;
+  const out = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}
+
+/** Wait for a streamed response's whole body. */
+export async function bufferResponse(response: HttpStreamResponse): Promise<HttpResponseData> {
+  return { ...headOf(response), body: await readBody(response.body) };
+}
+
+/** The status line and headers alone (plain data, safe to post). */
+export function headOf(response: HttpResponseHead): HttpResponseHead {
+  return { status: response.status, statusText: response.statusText, headers: response.headers };
+}
+
+/**
+ * Feed a body stream to `sink` chunk by chunk. Returns a cancel that hangs up
+ * on the producer; `sink.end` gets the error message when the stream failed.
+ */
+export function drainBody(stream: ReadableStream<Uint8Array>, sink: { chunk(data: Uint8Array): void; end(error?: string): void }): () => void {
+  const reader = stream.getReader();
+  let cancelled = false;
+  void (async () => {
+    try {
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done || cancelled) break;
+        sink.chunk(value);
+      }
+      if (!cancelled) sink.end();
+    } catch (error) {
+      if (!cancelled) sink.end(error instanceof Error ? error.message : String(error));
+    }
+  })();
+  return () => {
+    if (cancelled) return;
+    cancelled = true;
+    void reader.cancel().catch(() => undefined);
+  };
+}
+
+class ChannelEnd implements ByteChannel {
+  peer!: ChannelEnd;
+  closed = false;
+  private readonly data = new Set<(data: Uint8Array) => void>();
+  private readonly closes = new Set<() => void>();
+
+  send(data: Uint8Array): void {
+    if (this.closed) return;
+    const copy = new Uint8Array(data); // a copy (a Buffer's slice would be a view)
+    queueMicrotask(() => {
+      if (!this.peer.closed) for (const listener of this.peer.data) listener(copy);
+    });
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    // Delivered after any data already sent, like a FIN after the last segment.
+    queueMicrotask(() => {
+      if (this.peer.closed) return; // both hung up at once: neither needs telling
+      this.peer.closed = true;
+      for (const listener of this.peer.closes) listener();
+    });
+  }
+
+  onData(listener: (data: Uint8Array) => void): () => void {
+    this.data.add(listener);
+    return () => this.data.delete(listener);
+  }
+
+  onClose(listener: () => void): () => void {
+    this.closes.add(listener);
+    return () => this.closes.delete(listener);
+  }
+}
+
+/** Two connected ends: bytes sent on one arrive (asynchronously, in order) on the other. */
+export function createChannelPair(): [ByteChannel, ByteChannel] {
+  const a = new ChannelEnd();
+  const b = new ChannelEnd();
+  a.peer = b;
+  b.peer = a;
+  return [a, b];
+}

package/src/system/index.ts

@@ -1,7 +1,30 @@
 export { Kernel, DEFAULT_ENV } from './kernel.js';
 export type { KernelOptions } from './kernel.js';
-export type { System, Program, ProgramContext, ProgramIO, TerminalPort, ProcessOptions, ChildHandle, HttpRequestData, HttpResponseData, HttpHandler } from './types.js';
+export type {
+  System,
+  Program,
+  ProgramContext,
+  ProgramIO,
+  TerminalPort,
+  ProcessOptions,
+  ChildHandle,
+  HttpRequestData,
+  HttpResponseHead,
+  HttpResponseData,
+  HttpStreamResponse,
+  HttpHandler,
+  ByteChannel,
+  UpgradeHandler,
+} from './types.js';
 export { PortRegistry, parsePortPath } from './ports.js';
+export { pushStream, bytesStream, textResponse, readBody, bufferResponse, headOf, drainBody, createChannelPair } from './httpStream.js';
+export type { PushStream } from './httpStream.js';
+export { connectWebSocket } from './webSocketClient.js';
+export type { WebSocketConnection, WebSocketConnectOptions, WebSocketCloseInfo } from './webSocketClient.js';
+export { FrameDecoder, Opcode, encodeFrame, encodeClosePayload, decodeClosePayload, webSocketAccept, webSocketKey, WEBSOCKET_GUID } from './webSocketFrames.js';
+export type { WebSocketFrame } from './webSocketFrames.js';
+export { CookieJar, PortCookieJars, parseSetCookie, defaultCookiePath, cookiePathMatches } from './cookieJar.js';
+export type { StoredCookie } from './cookieJar.js';
 export type { PortEvent } from './ports.js';
 export { runProgram, runArguments, toRuntimeProcess, allocatePid } from './process.js';
 export type { RuntimeProcess, RunProgramOptions } from './process.js';

package/src/system/kernel.ts

@@ -7,7 +7,7 @@
  */
 import { VirtualFileSystem } from '../vfs.js';
 import type { PackageCache } from '../installer/registry.js';
-import type { ChildHandle, HttpRequestData, HttpResponseData, Program, ProcessOptions, System } from './types.js';
+import type { ByteChannel, ChildHandle, HttpRequestData, HttpResponseData, HttpStreamResponse, Program, ProcessOptions, System } from './types.js';
 import { PortRegistry } from './ports.js';
 import { ServerEvents } from './serverEvents.js';
 import { commandNotFound, resolveCommand } from './commands.js';
@@ -55,7 +55,7 @@ export class Kernel {
       fs: this.fs,
       fetch: options.fetch ?? ((input, init) => globalThis.fetch(input, init)),
       spawn: (command, args, spawnOptions) => this.spawnChild(command, args, spawnOptions),
-      listen: (port, handler) => this.ports.listen(port, handler),
+      listen: (port, handler, upgrade) => this.ports.listen(port, handler, upgrade),
       loopback: (port, request) => this.ports.request(port, request),
       serverUrl,
       announceServer: (port, url) => this.servers.announce({ port, url }),
@@ -82,8 +82,20 @@ export class Kernel {
     return runProgram({ program: resolved.program, args: resolved.args, system: this.system, cwd, env, terminal: options.terminal });
   }
 
-  /** Send an HTTP request to a virtual server (what the preview service worker does in the browser). */
+  /** Send an HTTP request to a virtual server (what the preview service worker does in the browser); resolves with the whole response. */
   request(port: number, request: Partial<HttpRequestData> & { url: string }): Promise<HttpResponseData | undefined> {
-    return this.ports.request(port, { method: 'GET', headers: {}, body: null, ...request });
+    return this.ports.requestBuffered(port, withDefaults(request));
+  }
+
+  /** {@link request}, resolving at the head with the body streaming (Server-Sent Events, chunked progress). */
+  requestStream(port: number, request: Partial<HttpRequestData> & { url: string }): Promise<HttpStreamResponse | undefined> {
+    return this.ports.request(port, withDefaults(request));
+  }
+
+  /** Open an upgraded connection (a WebSocket, via `connectWebSocket`); undefined when nothing on `port` takes upgrades. */
+  upgrade(port: number, request: Partial<HttpRequestData> & { url: string }): ByteChannel | undefined {
+    return this.ports.upgrade(port, withDefaults(request));
   }
 }
+
+const withDefaults = (request: Partial<HttpRequestData> & { url: string }): HttpRequestData => ({ method: 'GET', headers: {}, body: null, ...request });