arm64js 0.6.0 → 0.7.0

package/README.md

@@ -268,6 +268,76 @@ const newSnapshot = vm.snapshot();
 localStorage.set('snapshotId', newSnapshot.id);
 ```
 
+Creating snapshot for a larger VM may take some time, you can track progress using the `onProgress` callback:
+
+```ts
+const snapshot = await vm.snapshot({
+  name: 'my snapshot',
+  onProgress: (done, total) => console.log(`${Math.round((done / total) * 100)}%`),
+});
+```
+
+### `vm.listen(port, onConnection)` → `{ port, close() }`
+
+Creates a TCP server emulation on the webpage side "listening" to a specific port where VM can connect to. The application from inside the VM can open a TCP connection to `host.internal:<port>` and talk to it as it would to a normal TCP server.
+
+Until the page "listens" on a port, connections to it are refused.
+
+```js
+const listener = await vm.listen(9000, async (conn) => {
+  for await (const chunk of conn) {
+    // chunk is a Uint8Array with the bytes the program sent
+    await conn.write(chunk); // send bytes (or a string) back
+  }
+  await conn.end(); // no more data from the page
+});
+
+await vm.exec('echo hello | nc host.internal 9000');
+
+// to stop taking new connections (open ones keep going):
+await listener.close();
+```
+
+`onConnection` is a callback that returns the TCP `Connection`.
+
+A `Connection` has:
+
+- `readable` and `writable`: standard web streams of `Uint8Array`. The connection itself is also async-iterable.
+- `write(data)`: sends bytes or a string. It resolves once the data fits in the 1 MiB send window, so awaiting each write keeps memory bounded.
+- `end()`: tells the VM "the page has nothing more to send" without cutting off what the VM sends back. In TCP terms it is a half close, the same as shutdown(SHUT_WR).
+- `close()`: ends the connection both ways. What the page already wrote still reaches the VM, then it reads end-of-file. Anything the VM sends after that is dropped. `closed` is a promise that resolves when the connection is over.
+
+Both directions have flow control: if the page reads slowly, the VM's writes slow down, and the other way around.
+
+Listeners and connections end when the VM stops or is disposed. They are not part of snapshots: after booting one, call `listen` again.
+
+### `vm.serveHttp(port, handler, { maxBodyBytes? })` → `{ port, close() }`
+
+An HTTP server on top of `vm.listen`. Each request from the VM becomes a standard `Request`, and the `Response` your handler returns goes back. A response body is streamed as it is produced, so server-sent events work. Each connection carries one request.
+
+For example, a page that tells the VM the time and echoes what it posts:
+
+```js
+await vm.serveHttp(8080, async (req) => {
+  if (req.method === 'POST') {
+    return new Response(`you sent: ${await req.text()}\n`);
+  }
+  return new Response(`${new Date().toISOString()}\n`);
+});
+
+await vm.exec('wget -qO- http://host.internal:8080/');
+// → { output: '2026-10-16T19:03:11.123Z', exitCode: 0, … }
+
+await vm.exec("wget -qO- --post-data='hello' http://host.internal:8080/");
+// → { output: 'you sent: hello', exitCode: 0, … }
+```
+
+Some details:
+
+- The request body is read in full before the handler runs. Bodies over `maxBodyBytes` (default 64 MiB) get a 413 without being read.
+- `request.url` is always `http://host.internal:<port>/<path>`. What the VM puts in the `Host` header is in `request.headers`. It does not change the URL, so passing the request on with `fetch(request)` cannot be pointed somewhere else by the VM.
+- A response without `Content-Length` is sent chunked, so a body that fails halfway reaches the VM as an incomplete response rather than a short one. If the VM disconnects, the response body is cancelled, so whatever produces it can stop.
+
 ### `vm.dispose()`
 
 Stops the VM and frees its workers.
@@ -298,7 +368,7 @@ Disposes every VM and, in frame mode, the frames.
 
 ### Errors
 
-Everything rejects with an `Arm64JSError` carrying a `code`: `unsupported-browser`, `protocol-mismatch`, `engine-mismatch`, `image-not-found`, `boot-failed`, `exec-timeout`, `exec-failed`, `vm-exited`, `vm-lost`, `storage-unavailable`, `quota`, `snapshot-failed`, `snapshot-not-found`, `snapshot-in-use`, `snapshot-corrupt`, `invalid-input`, `share-unavailable`, `mount-failed`, `unmount-failed`, `write-failed`, `read-failed`.
+Everything rejects with an `Arm64JSError` carrying a `code`: `unsupported-browser`, `protocol-mismatch`, `engine-mismatch`, `image-not-found`, `boot-failed`, `exec-timeout`, `exec-failed`, `vm-exited`, `vm-lost`, `storage-unavailable`, `quota`, `snapshot-failed`, `snapshot-not-found`, `snapshot-in-use`, `snapshot-corrupt`, `invalid-input`, `share-unavailable`, `mount-failed`, `unmount-failed`, `write-failed`, `read-failed`, `listen-failed`.
 
 ## Terminal (optional)
 
@@ -322,6 +392,8 @@ It shows the VM console, sends what is typed to the VM, and sizes itself to the
 
 The VM has an emulated network card, DNS, and can install Alpine packages with `apk` through the CDN's package mirror. It has no general internet access.
 
+The name `host.internal` is the page itself: see `vm.listen` and `vm.serveHttp`.
+
 ## Development
 
 ```sh

package/dist/connection.d.ts

@@ -0,0 +1,39 @@
+/** What `write` takes. Strings are sent as UTF-8. */
+export type ConnectionData = ArrayBuffer | ArrayBufferView | string;
+/** One TCP connection the guest opened to `host.internal:<port>`. */
+export declare class Connection implements AsyncIterable<Uint8Array> {
+    private readonly port;
+    /** The port the guest dialed. */
+    readonly localPort: number;
+    /** The guest's bytes, in order. Ends when the guest closes its side. */
+    readonly readable: ReadableStream<Uint8Array>;
+    /** Writes go to the guest. Closing it is `end()`, aborting it is `close()`. */
+    readonly writable: WritableStream<Uint8Array>;
+    /** Resolves when the connection has ended both ways. */
+    readonly closed: Promise<void>;
+    private readonly inbox;
+    private remoteEnded;
+    private isClosed;
+    private localEnded;
+    private readCancelled;
+    private unacked;
+    private wake;
+    private resolveClosed;
+    /** Writes in call order. */
+    private writes;
+    /** Send `data` to the guest. Resolves once it fits the window. */
+    write(data: ConnectionData): Promise<void>;
+    /** Half close after pending writes: the guest reads end-of-file but can still send. */
+    end(): Promise<void>;
+    /** End both ways now. Bytes already sent still reach the guest; writes waiting
+     *  for the window and later guest bytes are dropped. Idempotent. */
+    close(): void;
+    /** Leaving a `for await` loop early keeps the connection open. */
+    [Symbol.asyncIterator](): AsyncGenerator<Uint8Array, void, undefined>;
+    private onMessage;
+    private ackAll;
+    private finish;
+    private post;
+    private waitForChange;
+    private notify;
+}

package/dist/connection.js

@@ -0,0 +1,213 @@
+// A guest connection to `host.internal` as a byte stream. Writes wait while
+// `HOST_CONN_WINDOW` bytes are unacknowledged; guest bytes are acknowledged only
+// when read, so a slow page slows the guest.
+import { Arm64JSError, HOST_CONN_CHUNK, HOST_CONN_WINDOW } from '@arm64js/protocol';
+/** One TCP connection the guest opened to `host.internal:<port>`. */
+export class Connection {
+    port;
+    localPort;
+    /** The guest's bytes, in order. Ends when the guest closes its side. */
+    readable;
+    /** Writes go to the guest. Closing it is `end()`, aborting it is `close()`. */
+    writable;
+    /** Resolves when the connection has ended both ways. */
+    closed;
+    inbox = [];
+    remoteEnded = false;
+    isClosed = false;
+    localEnded = false;
+    readCancelled = false;
+    unacked = 0;
+    wake = null;
+    resolveClosed;
+    /** Writes in call order. */
+    writes = Promise.resolve();
+    /** @internal */
+    constructor(port, 
+    /** The port the guest dialed. */
+    localPort) {
+        this.port = port;
+        this.localPort = localPort;
+        this.closed = new Promise((resolve) => {
+            this.resolveClosed = resolve;
+        });
+        port.onmessage = (ev) => {
+            this.onMessage(ev.data);
+        };
+        this.readable = new ReadableStream({
+            pull: async (controller) => {
+                for (;;) {
+                    const chunk = this.inbox.shift();
+                    if (chunk) {
+                        this.post({ type: 'ack', bytes: chunk.length });
+                        controller.enqueue(chunk);
+                        return;
+                    }
+                    if (this.remoteEnded || this.isClosed) {
+                        controller.close();
+                        return;
+                    }
+                    await this.waitForChange();
+                }
+            },
+            // Writing goes on; guest bytes are dropped.
+            cancel: () => {
+                this.readCancelled = true;
+                this.ackAll();
+            },
+        }, { highWaterMark: 0 });
+        this.writable = new WritableStream({
+            abort: () => {
+                this.close();
+            },
+            close: async () => this.end(),
+            write: async (chunk) => this.write(chunk),
+        });
+    }
+    /** Send `data` to the guest. Resolves once it fits the window. */
+    async write(data) {
+        const bytes = toBytes(data);
+        const run = async () => {
+            for (let at = 0; at < bytes.length; at += HOST_CONN_CHUNK) {
+                const piece = bytes.slice(at, at + HOST_CONN_CHUNK);
+                while (!this.isClosed && this.unacked > 0 && this.unacked + piece.length > HOST_CONN_WINDOW) {
+                    await this.waitForChange();
+                }
+                if (this.isClosed) {
+                    throw new Arm64JSError('invalid-input', 'the connection is closed');
+                }
+                if (this.localEnded) {
+                    throw new Arm64JSError('invalid-input', 'write after end()');
+                }
+                this.unacked += piece.length;
+                this.post({ type: 'data', data: piece }, [piece.buffer]);
+            }
+        };
+        const next = this.writes.then(run);
+        this.writes = next.catch(() => { });
+        return next;
+    }
+    /** Half close after pending writes: the guest reads end-of-file but can still send. */
+    async end() {
+        const run = () => {
+            if (this.localEnded || this.isClosed) {
+                return;
+            }
+            this.localEnded = true;
+            this.post({ type: 'end' });
+        };
+        const next = this.writes.then(run);
+        this.writes = next.catch(() => { });
+        return next;
+    }
+    /** End both ways now. Bytes already sent still reach the guest; writes waiting
+     *  for the window and later guest bytes are dropped. Idempotent. */
+    close() {
+        if (this.isClosed) {
+            return;
+        }
+        this.post({ type: 'close' });
+        this.finish();
+    }
+    /** @internal The VM went away; nothing more will arrive or leave. */
+    lost() {
+        if (!this.isClosed) {
+            this.finish();
+        }
+    }
+    /** Leaving a `for await` loop early keeps the connection open. */
+    async *[Symbol.asyncIterator]() {
+        const reader = this.readable.getReader();
+        try {
+            for (;;) {
+                const r = await reader.read();
+                if (r.done) {
+                    return;
+                }
+                yield r.value;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    onMessage(msg) {
+        if (this.isClosed) {
+            return;
+        }
+        switch (msg?.type) {
+            case 'data':
+                if (msg.data instanceof Uint8Array && msg.data.length > 0 && !this.remoteEnded) {
+                    this.inbox.push(msg.data);
+                    if (this.readCancelled) {
+                        this.ackAll();
+                    }
+                }
+                break;
+            case 'ack':
+                this.unacked = Math.max(0, this.unacked - (Number(msg.bytes) || 0));
+                break;
+            case 'end':
+                this.remoteEnded = true;
+                break;
+            case 'close':
+                this.finish();
+                return;
+            default:
+                return;
+        }
+        this.notify();
+    }
+    ackAll() {
+        const bytes = this.inbox.reduce((n, c) => n + c.length, 0);
+        this.inbox.length = 0;
+        if (bytes > 0) {
+            this.post({ type: 'ack', bytes });
+        }
+    }
+    finish() {
+        this.isClosed = true;
+        this.port.onmessage = null;
+        this.port.close();
+        this.notify();
+        this.resolveClosed();
+    }
+    post(msg, transfer = []) {
+        if (this.isClosed) {
+            return;
+        }
+        try {
+            this.port.postMessage(msg, transfer);
+        }
+        catch {
+            this.finish();
+        }
+    }
+    async waitForChange() {
+        return new Promise((resolve) => {
+            const prev = this.wake;
+            this.wake = () => {
+                prev?.();
+                resolve();
+            };
+        });
+    }
+    notify() {
+        const wake = this.wake;
+        this.wake = null;
+        wake?.();
+    }
+}
+/** A copy of `data`; it is transferred away. */
+function toBytes(data) {
+    if (typeof data === 'string') {
+        return new TextEncoder().encode(data);
+    }
+    if (data instanceof ArrayBuffer) {
+        return new Uint8Array(data.slice(0));
+    }
+    if (ArrayBuffer.isView(data)) {
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice();
+    }
+    throw new Arm64JSError('invalid-input', 'write takes bytes or a string');
+}

package/dist/http.d.ts

@@ -0,0 +1,7 @@
+import type { Connection } from './connection.js';
+/** Answers one guest request. */
+export type HttpHandler = (request: Request) => Promise<Response> | Response;
+/** Serve one request on `conn`, then close it. */
+export declare function serveConnection(conn: Connection, handler: HttpHandler, opts: {
+    maxBodyBytes: number;
+}): Promise<void>;

package/dist/http.js

@@ -0,0 +1,314 @@
+// HTTP/1.1 for `vm.serveHttp`: one request per connection, streamed responses.
+// Bodies without `Content-Length` go chunked, so a cut-off body is detectable.
+import { HOST_INTERNAL_NAME } from '@arm64js/protocol';
+const HEAD_MAX = 64 * 1024;
+const CRLF = new Uint8Array([13, 10]);
+const HEAD_END = new Uint8Array([13, 10, 13, 10]);
+/** Headers about the connection itself, which this server sets. */
+const HOP_HEADERS = new Set(['connection', 'keep-alive', 'transfer-encoding', 'upgrade', 'proxy-connection']);
+const REASONS = {
+    200: 'OK',
+    201: 'Created',
+    204: 'No Content',
+    206: 'Partial Content',
+    301: 'Moved Permanently',
+    302: 'Found',
+    304: 'Not Modified',
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    413: 'Content Too Large',
+    429: 'Too Many Requests',
+    431: 'Request Header Fields Too Large',
+    500: 'Internal Server Error',
+    501: 'Not Implemented',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+};
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Serve one request on `conn`, then close it. */
+export async function serveConnection(conn, handler, opts) {
+    const reader = new ByteReader(conn.readable.getReader());
+    let response;
+    let method = 'GET';
+    let http10 = false;
+    try {
+        const head = await reader.readUntil(HEAD_END, HEAD_MAX);
+        if (head === null) {
+            conn.close();
+            return;
+        }
+        const req = parseHead(head);
+        method = req.method;
+        http10 = req.version === 'HTTP/1.0';
+        const body = await readBody(reader, req.headers, opts.maxBodyBytes, async () => {
+            if (req.headers.get('expect')?.toLowerCase() === '100-continue') {
+                await conn.write('HTTP/1.1 100 Continue\r\n\r\n');
+            }
+        });
+        // The guest must not choose the URL's origin (`Host`, absolute-form target).
+        const request = new Request(`http://${HOST_INTERNAL_NAME}:${conn.localPort}${pathOf(req.target)}`, {
+            body: method === 'GET' || method === 'HEAD' ? undefined : body,
+            headers: req.headers,
+            method,
+        });
+        try {
+            response = await handler(request);
+            if (!(response instanceof Response)) {
+                throw new Error('the handler must return a Response');
+            }
+        }
+        catch (e) {
+            console.error('[arm64js] serveHttp handler failed', e);
+            response = new Response(`handler failed: ${String(e?.message ?? e)}\n`, { status: 500 });
+        }
+    }
+    catch (e) {
+        const status = e instanceof HttpError ? e.status : 400;
+        response = new Response(`${String(e?.message ?? e)}\n`, { status });
+    }
+    // Drop unread guest bytes, or they fill the window and block the guest.
+    await reader.cancel();
+    try {
+        await writeResponse(conn, response, method === 'HEAD', http10);
+        await conn.end();
+    }
+    catch {
+        conn.close();
+        // The guest is gone: stop the body's producer.
+        await response.body?.cancel().catch(() => { });
+    }
+}
+/** The path and query of a request target, whatever its form. */
+function pathOf(target) {
+    if (target.startsWith('/')) {
+        return target;
+    }
+    try {
+        const u = new URL(target);
+        return `${u.pathname}${u.search}`;
+    }
+    catch {
+        throw new HttpError(400, 'bad request target');
+    }
+}
+function parseHead(bytes) {
+    const text = new TextDecoder('latin1').decode(bytes);
+    const lines = text.split('\r\n');
+    const [method, target, version] = (lines.shift() ?? '').split(' ');
+    if (!method || !target || !version?.startsWith('HTTP/1.')) {
+        throw new HttpError(400, 'bad request line');
+    }
+    const headers = new Headers();
+    for (const line of lines) {
+        if (line === '') {
+            continue;
+        }
+        const colon = line.indexOf(':');
+        if (colon <= 0) {
+            throw new HttpError(400, 'bad header line');
+        }
+        try {
+            headers.append(line.slice(0, colon).trim(), line.slice(colon + 1).trim());
+        }
+        catch {
+            throw new HttpError(400, 'bad header line');
+        }
+    }
+    return { headers, method: method.toUpperCase(), target, version };
+}
+async function readBody(reader, headers, max, beforeBody) {
+    const tooLarge = () => new HttpError(413, `the request body is over ${max} bytes`);
+    if (headers.get('transfer-encoding')?.toLowerCase().includes('chunked')) {
+        await beforeBody();
+        const parts = [];
+        let total = 0;
+        for (;;) {
+            const line = await reader.readUntil(CRLF, 1024);
+            if (line === null) {
+                throw new HttpError(400, 'the request body ended early');
+            }
+            const size = parseInt(new TextDecoder().decode(line).split(';')[0].trim(), 16);
+            if (!Number.isFinite(size) || size < 0) {
+                throw new HttpError(400, 'bad chunk size');
+            }
+            if (size === 0) {
+                // Trailers, up to the empty line.
+                while ((await reader.readUntil(CRLF, HEAD_MAX))?.length) {
+                    // skip
+                }
+                return concat(parts);
+            }
+            total += size;
+            if (total > max) {
+                throw tooLarge();
+            }
+            parts.push(await reader.readExact(size));
+            await reader.readExact(2);
+        }
+    }
+    const length = headers.get('content-length');
+    if (length === null) {
+        return null;
+    }
+    if (!/^\d+$/.test(length.trim())) {
+        throw new HttpError(400, 'bad Content-Length');
+    }
+    const n = Number(length.trim());
+    // Refuse before `100 Continue` invites the body.
+    if (!Number.isSafeInteger(n) || n > max) {
+        throw tooLarge();
+    }
+    await beforeBody();
+    return reader.readExact(n);
+}
+async function writeResponse(conn, response, head, http10) {
+    const status = response.status;
+    const lines = [`HTTP/1.1 ${status} ${response.statusText || REASONS[status] || ''}`];
+    response.headers.forEach((value, name) => {
+        if (!HOP_HEADERS.has(name) && name !== 'set-cookie') {
+            lines.push(`${name}: ${value}`);
+        }
+    });
+    for (const cookie of response.headers.getSetCookie?.() ?? []) {
+        lines.push(`set-cookie: ${cookie}`);
+    }
+    const noBody = head || status === 204 || status === 304 || (status >= 100 && status < 200);
+    const sized = response.headers.has('content-length');
+    // HTTP/1.0 has no chunked encoding: the connection's end marks the body's.
+    const chunked = !noBody && !!response.body && !sized && !http10;
+    if (!response.body && !noBody && !sized) {
+        lines.push('content-length: 0');
+    }
+    if (chunked) {
+        lines.push('transfer-encoding: chunked');
+    }
+    lines.push('connection: close', '', '');
+    await conn.write(lines.join('\r\n'));
+    if (noBody || !response.body) {
+        await response.body?.cancel();
+        return;
+    }
+    for await (const chunk of iterate(response.body)) {
+        if (chunk.length === 0) {
+            continue;
+        }
+        await conn.write(chunked ? concat([ascii(`${chunk.length.toString(16)}\r\n`), chunk, CRLF]) : chunk);
+    }
+    if (chunked) {
+        await conn.write('0\r\n\r\n');
+    }
+}
+function ascii(text) {
+    return new TextEncoder().encode(text);
+}
+async function* iterate(body) {
+    const reader = body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                return;
+            }
+            yield value;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function concat(parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}
+/** Buffered reads over a byte stream. */
+class ByteReader {
+    reader;
+    buf = new Uint8Array(0);
+    done = false;
+    constructor(reader) {
+        this.reader = reader;
+    }
+    /** Bytes up to `delim` (dropped), or `null` at end of stream before any byte. */
+    async readUntil(delim, max) {
+        let from = 0;
+        for (;;) {
+            const at = indexOf(this.buf, delim, from);
+            if (at >= 0) {
+                const out = this.buf.slice(0, at);
+                this.buf = this.buf.subarray(at + delim.length);
+                return out;
+            }
+            if (this.buf.length > max) {
+                throw new HttpError(431, 'the request head is too large');
+            }
+            from = Math.max(0, this.buf.length - delim.length + 1);
+            const next = await this.next();
+            if (!next) {
+                if (this.buf.length === 0) {
+                    return null;
+                }
+                throw new HttpError(400, 'the request ended early');
+            }
+            this.buf = this.buf.length === 0 ? next : concat([this.buf, next]);
+        }
+    }
+    /** Exactly `n` bytes, copied once. */
+    async readExact(n) {
+        const parts = [];
+        let have = 0;
+        while (have < n) {
+            if (this.buf.length === 0) {
+                const next = await this.next();
+                if (!next) {
+                    throw new HttpError(400, 'the request body ended early');
+                }
+                this.buf = next;
+            }
+            const take = Math.min(n - have, this.buf.length);
+            parts.push(this.buf.subarray(0, take));
+            this.buf = this.buf.subarray(take);
+            have += take;
+        }
+        return concat(parts);
+    }
+    /** Stop reading: the rest of the stream is dropped. */
+    async cancel() {
+        await this.reader.cancel().catch(() => { });
+    }
+    async next() {
+        if (this.done) {
+            return null;
+        }
+        const { done, value } = await this.reader.read();
+        if (done) {
+            this.done = true;
+            return null;
+        }
+        return value;
+    }
+}
+function indexOf(hay, needle, from) {
+    outer: for (let i = from; i <= hay.length - needle.length; i++) {
+        for (let j = 0; j < needle.length; j++) {
+            if (hay[i + j] !== needle[j]) {
+                continue outer;
+            }
+        }
+        return i;
+    }
+    return -1;
+}

package/dist/index.d.ts

@@ -3,8 +3,10 @@ export type { Arm64JSApi } from './api.js';
 export type { HostMode } from './hosts.js';
 export type { MountSource } from './mount.js';
 export { VERSION as version } from './version.js';
-export { Vm, type FileData, type Mount } from './vm.js';
+export { Connection, type ConnectionData } from './connection.js';
+export type { HttpHandler } from './http.js';
+export { DEFAULT_MAX_BODY_BYTES, Vm, type FileData, type Listener, type Mount, type ServeHttpOptions } from './vm.js';
 export type { Arm64JSErrorCode, BootOptions, BootProgress, ExecOptions, ExecResult, OutputInfo, ReadFileOptions, SnapshotInfo, SnapshotOptions, StorageStatus, VmExit, WriteFileOptions, } from '@arm64js/protocol';
-export { Arm64JSError } from '@arm64js/protocol';
+export { Arm64JSError, HOST_INTERNAL_NAME } from '@arm64js/protocol';
 export declare const Arm64JS: Arm64JSApi;
 export default Arm64JS;

package/dist/index.js

@@ -1,6 +1,7 @@
 import { createArm64JS } from './api.js';
 export { VERSION as version } from './version.js';
-export { Vm } from './vm.js';
-export { Arm64JSError } from '@arm64js/protocol';
+export { Connection } from './connection.js';
+export { DEFAULT_MAX_BODY_BYTES, Vm } from './vm.js';
+export { Arm64JSError, HOST_INTERNAL_NAME } from '@arm64js/protocol';
 export const Arm64JS = createArm64JS();
 export default Arm64JS;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.6.0";
+export declare const VERSION = "0.7.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/stamp-version.mjs from package.json. Do not edit.
-export const VERSION = "0.6.0";
+export const VERSION = "0.7.0";

package/dist/vm.d.ts

@@ -1,4 +1,6 @@
 import { type ExecOptions, type ExecResult, type OutputInfo, type ReadFileOptions, type SnapshotInfo, type SnapshotOptions, type VmExit, type WriteFileOptions } from '@arm64js/protocol';
+import { Connection } from './connection.js';
+import { type HttpHandler } from './http.js';
 import { type MountSource } from './mount.js';
 /** What `writeFile` takes. */
 export type FileData = Blob | BufferSource | string;
@@ -9,6 +11,19 @@ export interface Mount {
     /** Remove the mount. Idempotent. */
     unmount(): Promise<void>;
 }
+/** `serveHttp`'s default request body limit. */
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+export interface ServeHttpOptions {
+    /** Larger request bodies are refused with 413 (default 64 MiB). */
+    maxBodyBytes?: number;
+}
+/** A live `listen`. */
+export interface Listener {
+    /** The port the guest dials on `host.internal`. */
+    readonly port: number;
+    /** Take no new connections. Open ones keep going. Idempotent. */
+    close(): Promise<void>;
+}
 /** A running VM. */
 export declare class Vm {
     readonly id: string;
@@ -21,6 +36,12 @@ export declare class Vm {
     private readonly exitListeners;
     /** The latest `mount` at each path, so an old handle cannot undo a newer one. */
     private readonly mounts;
+    /** Listener ports by guest port. */
+    private readonly listeners;
+    /** Open guest connections, ended when the VM goes away. */
+    private readonly connections;
+    private exitWatched;
+    private exited;
     /** Run a shell command (one or more lines) in the guest and get its output and
      *  exit code. One at a time per VM. */
     exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
@@ -49,9 +70,21 @@ export declare class Vm {
     /** Copy the guest's file `path` out, as a `Blob`. The copy is held in page
      *  memory. */
     readFile(path: string, opts?: ReadFileOptions): Promise<Blob>;
+    /** Take guest connections to `host.internal:<port>`; `onConnection` gets each as
+     *  a byte stream. Ports nobody listens on refuse connections. Not kept in
+     *  snapshots. */
+    listen(port: number, onConnection: (conn: Connection) => unknown): Promise<Listener>;
+    /** Serve HTTP on `host.internal:<port>`: each guest request becomes a `Request`;
+     *  the handler's `Response` streams back. */
+    serveHttp(port: number, handler: HttpHandler, opts?: ServeHttpOptions): Promise<Listener>;
     /** Save the VM to this browser's storage. The VM keeps running. */
     snapshot(opts?: SnapshotOptions): Promise<SnapshotInfo>;
     /** Stop the VM and free its workers. Idempotent. */
     dispose(): Promise<void>;
+    /** The VM is gone and its workers cannot say so: end everything here. */
+    private closeListeners;
+    /** The guest's workers stop without notice, so end everything on exit. */
+    private watchExit;
+    private gone;
     private check;
 }

package/dist/vm.js

@@ -1,8 +1,17 @@
 import { Arm64JSError, } from '@arm64js/protocol';
+import { Connection } from './connection.js';
 import { withSdkErrors } from './errors.js';
+import { serveConnection } from './http.js';
 import { guestPath, mountFiles } from './mount.js';
 /** The `onExit` a VM gets when its frame stops answering. */
 const LOST_EXIT = { reason: 'lost' };
+/** How long `Listener.close` waits for the engine to confirm. */
+const UNLISTEN_WAIT_MS = 5000;
+/** `serveHttp`'s default request body limit. */
+export const DEFAULT_MAX_BODY_BYTES = 64 * 1024 * 1024;
+async function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /** A running VM. */
 export class Vm {
     id;
@@ -14,6 +23,12 @@ export class Vm {
     exitListeners = new Set();
     /** The latest `mount` at each path, so an old handle cannot undo a newer one. */
     mounts = new Map();
+    /** Listener ports by guest port. */
+    listeners = new Map();
+    /** Open guest connections, ended when the VM goes away. */
+    connections = new Set();
+    exitWatched = false;
+    exited = false;
     /** @internal */
     constructor(id, host, 
     /** The engine this VM runs on (`'0.11'`). */
@@ -129,6 +144,115 @@ export class Vm {
         this.check();
         return withSdkErrors(this.host.readFile(this.id, path, opts));
     }
+    /** Take guest connections to `host.internal:<port>`; `onConnection` gets each as
+     *  a byte stream. Ports nobody listens on refuse connections. Not kept in
+     *  snapshots. */
+    async listen(port, onConnection) {
+        this.check();
+        if (typeof onConnection !== 'function') {
+            throw new Arm64JSError('invalid-input', 'listen needs a function to call for each connection');
+        }
+        const host = this.host;
+        if (!host.listen || !host.unlisten) {
+            throw new Arm64JSError('listen-failed', `engine ${this.engine} cannot take connections from the guest; update the arm64js package`);
+        }
+        const unlisten = host.unlisten.bind(host);
+        let listener;
+        try {
+            listener = await withSdkErrors(host.listen(this.id, port));
+        }
+        catch (e) {
+            // An engine from before protocol 1.2 does not know the op.
+            if (e.code === 'invalid-input' && /unknown op/.test(String(e.message))) {
+                throw new Arm64JSError('listen-failed', `engine ${this.engine} cannot take connections from the guest; update the arm64js package`);
+            }
+            throw e;
+        }
+        if (this.gone()) {
+            listener.close();
+            throw new Arm64JSError('vm-lost', 'the VM went away while listen ran');
+        }
+        this.watchExit();
+        let closing = false;
+        let engineDone = null;
+        this.listeners.set(port, listener);
+        listener.onmessage = (ev) => {
+            if (ev.data?.type === 'closed') {
+                engineDone?.();
+                return;
+            }
+            if (ev.data?.type !== 'connect' || !(ev.data.conn instanceof MessagePort)) {
+                return;
+            }
+            const conn = new Connection(ev.data.conn, ev.data.port);
+            // Refuse rather than leave it hanging.
+            if (closing || this.gone()) {
+                conn.close();
+                return;
+            }
+            this.connections.add(conn);
+            void conn.closed.then(() => this.connections.delete(conn));
+            const fail = (e) => {
+                console.error('[arm64js] listen callback failed', e);
+                conn.close();
+            };
+            try {
+                const r = onConnection(conn);
+                if (r && typeof r.then === 'function') {
+                    r.then(undefined, fail);
+                }
+            }
+            catch (e) {
+                fail(e);
+            }
+        };
+        return {
+            close: async () => {
+                if (closing || this.listeners.get(port) !== listener) {
+                    return;
+                }
+                closing = true;
+                try {
+                    if (!this.gone()) {
+                        // Wait for `closed` so no connection in flight is lost.
+                        const done = new Promise((resolve) => {
+                            engineDone = resolve;
+                        });
+                        await withSdkErrors(unlisten(this.id, port));
+                        await Promise.race([done, delay(UNLISTEN_WAIT_MS)]);
+                    }
+                }
+                catch (e) {
+                    // The VM stopped: nothing is listening anyway.
+                    const code = e.code;
+                    if (code !== 'vm-exited' && code !== 'vm-lost') {
+                        throw e;
+                    }
+                }
+                finally {
+                    if (this.listeners.get(port) === listener) {
+                        this.listeners.delete(port);
+                    }
+                    listener.close();
+                }
+            },
+            port,
+        };
+    }
+    /** Serve HTTP on `host.internal:<port>`: each guest request becomes a `Request`;
+     *  the handler's `Response` streams back. */
+    async serveHttp(port, handler, opts = {}) {
+        if (typeof handler !== 'function') {
+            throw new Arm64JSError('invalid-input', 'serveHttp needs a function that answers a Request');
+        }
+        const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+        if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 0) {
+            throw new Arm64JSError('invalid-input', 'maxBodyBytes must be a whole number of bytes');
+        }
+        return this.listen(port, (conn) => {
+            void serveConnection(conn, handler, { maxBodyBytes });
+        });
+    }
     /** Save the VM to this browser's storage. The VM keeps running. */
     async snapshot(opts) {
         this.check();
@@ -140,6 +264,7 @@ export class Vm {
             return;
         }
         this.disposed = true;
+        this.closeListeners();
         this.onDisposed(this);
         await withSdkErrors(this.host.dispose(this.id));
     }
@@ -149,11 +274,42 @@ export class Vm {
             return;
         }
         this.frameLost = true;
+        this.closeListeners();
         for (const cb of [...this.exitListeners]) {
             cb(LOST_EXIT);
         }
         this.exitListeners.clear();
     }
+    /** The VM is gone and its workers cannot say so: end everything here. */
+    closeListeners() {
+        for (const listener of this.listeners.values()) {
+            listener.close();
+        }
+        this.listeners.clear();
+        for (const conn of this.connections) {
+            conn.lost();
+        }
+        this.connections.clear();
+    }
+    /** The guest's workers stop without notice, so end everything on exit. */
+    watchExit() {
+        if (this.exitWatched) {
+            return;
+        }
+        this.exitWatched = true;
+        try {
+            this.host.onExit(this.id, () => {
+                this.exited = true;
+                this.closeListeners();
+            });
+        }
+        catch {
+            // Unknown VM: dispose cleans up.
+        }
+    }
+    gone() {
+        return this.disposed || this.frameLost || this.exited;
+    }
     check() {
         if (this.disposed) {
             throw new Arm64JSError('vm-lost', 'this VM was disposed');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arm64js",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Run a Linux VM inside your web page. Boots Alpine from the arm64js CDN, runs commands, keeps snapshots in the browser.",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "prepare": "npm run stamp && npm run build:protocol && husky"
   },
   "dependencies": {
-    "@arm64js/protocol": "^1.1.0"
+    "@arm64js/protocol": "^1.2.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",