withruntime 0.11.2 → 0.14.0

package/dist/sprites/index.js

@@ -1,9 +1,244 @@
 import { EventEmitter } from "node:events";
 import { PassThrough, Writable } from "node:stream";
-import { RuntimeError } from "../errors.js";
-import { all, client, CompatibilityError, create, destroy, execOptions, lookup, only, ready, region, } from "../compat/core.js";
+import { NotFoundError, RuntimeError } from "../errors.js";
+import { timeoutSignal } from "../transport.js";
+import { all, client, CompatibilityError, create, destroy, execOptions, lookup, only, ready, refuse, region, } from "../compat/core.js";
 import { GuestFiles } from "../compat/files.js";
 export { CompatibilityError };
+export const ERR_CODE_CREATION_RATE_LIMITED = "sprite_creation_rate_limited";
+export const ERR_CODE_CONCURRENT_LIMIT_EXCEEDED = "concurrent_sprite_limit_exceeded";
+/** A Sprites progress or event stream: the work behind it runs whether or
+ * not anyone reads, as the vendor's server-side operation does; `next()`
+ * answers null at the end, `close()` stops reading (and stops a watch). */
+class Feed {
+    #items = [];
+    #waiters = [];
+    #ended = false;
+    #closed = false;
+    #error;
+    constructor(source) {
+        if (source)
+            void (async () => {
+                try {
+                    for await (const item of source)
+                        this.push(item);
+                    this.end();
+                }
+                catch (error) {
+                    this.end(error);
+                }
+            })();
+    }
+    push(item) {
+        if (this.#ended || this.#closed)
+            return;
+        this.#items.push(item);
+        this.#wake();
+    }
+    end(error) {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        this.#error = error;
+        this.#wake();
+    }
+    /** Called once by close(); a watch stops its native watch here. */
+    stop() { }
+    #wake() {
+        for (const waiter of this.#waiters.splice(0))
+            waiter();
+    }
+    async next() {
+        while (!this.#items.length && !this.#ended && !this.#closed)
+            await new Promise((resolve) => this.#waiters.push(resolve));
+        if (this.#closed)
+            return null;
+        if (this.#items.length)
+            return this.#items.shift();
+        if (this.#error !== undefined) {
+            const error = this.#error;
+            this.#error = undefined;
+            throw error instanceof Error ? error : new Error("The stream failed", { cause: error });
+        }
+        return null;
+    }
+    async processAll(handler) {
+        for await (const item of this)
+            await handler(item);
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.stop();
+        this.#wake();
+    }
+    isClosed() {
+        return this.#closed || (this.#ended && !this.#items.length);
+    }
+    async *[Symbol.asyncIterator]() {
+        let item;
+        while ((item = await this.next()) !== null)
+            yield item;
+    }
+}
+export class CheckpointStream extends Feed {
+}
+export class RestoreStream extends Feed {
+}
+export class ServiceLogStream extends Feed {
+}
+export class SessionKillStream extends Feed {
+}
+export class SpriteListStream extends Feed {
+}
+export class APIError extends Error {
+    errorCode;
+    statusCode;
+    limit;
+    windowSeconds;
+    retryAfterSeconds;
+    currentCount;
+    upgradeAvailable;
+    upgradeUrl;
+    retryAfterHeader;
+    rateLimitLimit;
+    rateLimitRemaining;
+    rateLimitReset;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "APIError";
+        Object.assign(this, options);
+    }
+    isRateLimitError() {
+        return this.statusCode === 429;
+    }
+    isCreationRateLimited() {
+        return this.errorCode === ERR_CODE_CREATION_RATE_LIMITED;
+    }
+    isConcurrentLimitExceeded() {
+        return this.errorCode === ERR_CODE_CONCURRENT_LIMIT_EXCEEDED;
+    }
+    getRetryAfterSeconds() {
+        if (this.retryAfterSeconds !== undefined && this.retryAfterSeconds > 0)
+            return this.retryAfterSeconds;
+        return this.retryAfterHeader;
+    }
+}
+/** The vendor's parser, for callers that read Sprites-shaped answers themselves. */
+export function parseAPIError(statusCode, body, headers = {}) {
+    if (statusCode < 400)
+        return undefined;
+    const header = (name) => {
+        const value = headers[name.toLowerCase()] ?? headers[name];
+        const number = value ? parseInt(value, 10) : NaN;
+        return Number.isNaN(number) ? undefined : number;
+    };
+    const retryAfterHeader = header("Retry-After");
+    let message = "";
+    let data = {};
+    if (body)
+        try {
+            data = JSON.parse(body);
+            message = data.message || "";
+        }
+        catch {
+            message = body;
+        }
+    const errorCode = data.error;
+    const limit = data.limit;
+    const windowSeconds = data.window_seconds;
+    const retryAfterSeconds = data.retry_after_seconds;
+    const currentCount = data.current_count;
+    const upgradeUrl = data.upgrade_url;
+    if (statusCode === 429 && message) {
+        const details = [];
+        if (limit !== undefined && windowSeconds !== undefined)
+            details.push(`limit: ${limit} per ${windowSeconds}s`);
+        if (currentCount !== undefined)
+            details.push(`current: ${currentCount}`);
+        const retry = retryAfterSeconds ?? retryAfterHeader;
+        if (retry !== undefined)
+            details.push(`retry after: ${retry}s`);
+        if (upgradeUrl)
+            details.push(`upgrade: ${upgradeUrl}`);
+        if (details.length)
+            message = `${message} (${details.join(", ")})`;
+    }
+    return new APIError(message || errorCode || `API error (status ${statusCode})`, {
+        errorCode,
+        statusCode,
+        limit,
+        windowSeconds,
+        retryAfterSeconds,
+        currentCount,
+        upgradeAvailable: data.upgrade_available,
+        upgradeUrl,
+        retryAfterHeader,
+        rateLimitLimit: header("X-RateLimit-Limit"),
+        rateLimitRemaining: header("X-RateLimit-Remaining"),
+        rateLimitReset: header("X-RateLimit-Reset"),
+    });
+}
+/** Runtime's refusal as the APIError the vendor's client throws; limits on
+ * running sandboxes are its concurrent limit, the API's rate limit on a
+ * create its creation limit. */
+async function api(run, creating = false) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (!(error instanceof RuntimeError) || error.status < 400)
+            throw error;
+        const errorCode = ["no_credit_running_limit", "quota_exceeded"].includes(error.code)
+            ? ERR_CODE_CONCURRENT_LIMIT_EXCEEDED
+            : creating && error.code === "rate_limited"
+                ? ERR_CODE_CREATION_RATE_LIMITED
+                : error.code;
+        const retry = error.retryAfterMs === undefined ? undefined : Math.ceil(error.retryAfterMs / 1000);
+        throw Object.assign(new APIError(error.message, {
+            errorCode,
+            statusCode: error.status,
+            retryAfterSeconds: retry,
+            retryAfterHeader: retry,
+        }), { cause: error });
+    }
+}
+/** "30s", "500ms", "2m" or "1h", as Sprites' durations are written. */
+function duration(value, name) {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/.exec(value);
+    if (!match)
+        throw new TypeError(`${name} must be a duration such as "10s"`);
+    return Number(match[1]) * { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[match[2]];
+}
+const SIGNALS = [
+    "SIGTERM",
+    "SIGKILL",
+    "SIGINT",
+    "SIGHUP",
+    "SIGQUIT",
+    "SIGUSR1",
+    "SIGUSR2",
+];
+function signalName(signal) {
+    const name = (signal.startsWith("SIG") ? signal : `SIG${signal}`);
+    if (!SIGNALS.includes(name))
+        throw new TypeError(`Unsupported signal ${signal}`);
+    return name;
+}
+/** maxRunAfterDisconnect is left out: a Runtime process runs until it ends
+ * or is killed, whoever is connected. */
+const SPAWN_KEYS = [
+    "cwd",
+    "env",
+    "tty",
+    "rows",
+    "cols",
+    "detachable",
+    "sessionId",
+    "controlMode",
+];
+const EXEC_KEYS = [...SPAWN_KEYS, "encoding", "maxBuffer", "signal", "timeout"];
 function validateURLSettings(settings) {
     only("Sprites URL settings", settings, ["auth"]);
     if (settings.auth !== "public" && settings.auth !== "sprite")
@@ -48,19 +283,58 @@ async function fileOperation(path, syscall, run) {
     }
 }
 export class ExecError extends Error {
-    exitCode;
-    stdout;
-    stderr;
-    constructor(message, exitCode, stdout, stderr) {
+    result;
+    constructor(message, result) {
         super(message);
-        this.exitCode = exitCode;
-        this.stdout = stdout;
-        this.stderr = stderr;
+        this.result = result;
         this.name = "ExecError";
     }
+    get exitCode() {
+        return this.result.exitCode;
+    }
+    get stdout() {
+        return this.result.stdout;
+    }
+    get stderr() {
+        return this.result.stderr;
+    }
+}
+/** The vendor's control-mode wire protocol: multiplexed operations over one
+ * WebSocket. Runtime's own API multiplexes commands without it. */
+const CONTROL = "Runtime runs each command over its own API; use spawn, exec or execFile";
+export class OpConn extends EventEmitter {
 }
+refuse("Sprites", "OpConn", OpConn, Object.fromEntries([
+    "write",
+    "sendEOF",
+    "resize",
+    "signal",
+    "handleData",
+    "handleText",
+    "complete",
+    "close",
+    "isClosed",
+    "getExitCode",
+].map((name) => [name, CONTROL])), { sync: true });
+refuse("Sprites", "OpConn", OpConn, { wait: CONTROL });
+export class ControlConnection extends EventEmitter {
+}
+refuse("Sprites", "ControlConnection", ControlConnection, Object.fromEntries(["isActive", "setActive", "clearOpConn", "sendData", "close", "isClosed"].map((name) => [
+    name,
+    CONTROL,
+])), { sync: true });
+refuse("Sprites", "ControlConnection", ControlConnection, {
+    connect: CONTROL,
+    startOp: CONTROL,
+});
 export class SpritesClient {
     runtime;
+    /** The Runtime API the calls go to. */
+    baseURL;
+    /** The Runtime key given, if any; otherwise RUNTIME_API_KEY or the saved login is used. */
+    token;
+    /** Always false: true is refused (control mode). */
+    controlMode = false;
     constructor(token, options = {}) {
         only("Sprites client", options, [
             "apiKey",
@@ -82,6 +356,8 @@ export class SpritesClient {
             baseUrl: options.baseUrl ?? options.baseURL,
             timeoutMs: options.timeoutMs ?? options.timeout,
         });
+        this.baseURL = this.runtime.transport?.baseUrl ?? options.baseUrl ?? options.baseURL ?? "";
+        this.token = options.apiKey ?? token ?? "";
     }
     sprite(name) {
         return new Sprite(name, this);
@@ -105,7 +381,7 @@ export class SpritesClient {
         validateLabels(o.labels);
         const c = o.config ?? {};
         only("Sprites config", c, ["ramMB", "cpus", "region", "storageGB"]);
-        const s = await create(this.runtime, "sprites", {
+        const s = await api(() => create(this.runtime, "sprites", {
             name,
             persistent: true,
             vcpu: c.cpus,
@@ -113,9 +389,10 @@ export class SpritesClient {
             diskMiB: c.storageGB === undefined ? undefined : Math.ceil((c.storageGB * 1e9) / 1048576),
             region: region("Sprites", c.region),
             labels: { "compat.labels": JSON.stringify(o.labels ?? []) },
-        }, o.environment, undefined, o.waitForCapacity === false ? { waitForCapacityMs: 0 } : {});
+        }, o.environment, undefined, o.waitForCapacity === false ? { waitForCapacityMs: 0 } : {}), true);
         const sprite = new Sprite(name, this);
         sprite.hydrate(s);
+        sprite.environment = { ...o.environment };
         if (o.urlSettings) {
             try {
                 await sprite.updateURLSettings(o.urlSettings);
@@ -129,15 +406,15 @@ export class SpritesClient {
     }
     async getSprite(name) {
         const sprite = this.sprite(name);
-        sprite.hydrate(await lookup(this.runtime, name));
+        sprite.hydrate(await api(() => lookup(this.runtime, name)));
         return sprite;
     }
     async deleteSprite(name) {
-        await destroy(await lookup(this.runtime, name));
+        await api(async () => destroy(await lookup(this.runtime, name)));
     }
     async listSprites(options = {}) {
         only("Sprites list", options, ["prefix", "maxResults", "continuationToken", "bulkLoad"]);
-        const values = (await all(this.runtime, "sprites")).filter((s) => (s.info.name ?? s.id).startsWith(options.prefix ?? ""));
+        const values = (await api(() => all(this.runtime, "sprites"))).filter((s) => (s.info.name ?? s.id).startsWith(options.prefix ?? ""));
         const offset = Number(options.continuationToken ?? 0), limit = options.maxResults ?? 100;
         return {
             sprites: values.slice(offset, offset + limit).map((s) => ({
@@ -158,7 +435,7 @@ export class SpritesClient {
         };
     }
     async listAllSprites(prefix) {
-        return (await all(this.runtime, "sprites"))
+        return (await api(() => all(this.runtime, "sprites")))
             .filter((s) => (s.info.name ?? s.id).startsWith(prefix ?? ""))
             .map((s) => {
             const sprite = this.sprite(s.info.name ?? s.id);
@@ -167,25 +444,65 @@ export class SpritesClient {
         });
     }
     async restartSprite(name) {
-        const s = await lookup(this.runtime, name);
-        await s.stop();
-        await s.restart();
-        return { spriteName: name, machineId: s.id, message: "Restarted" };
+        return api(async () => {
+            const s = await lookup(this.runtime, name);
+            await s.stop();
+            await s.restart();
+            return { spriteName: name, machineId: s.id, message: "Restarted" };
+        });
+    }
+    /** Its state as Runtime reports it now; `elapsed` is the lookup's milliseconds. */
+    async checkSprite(name) {
+        const started = performance.now();
+        const s = await api(() => lookup(this.runtime, name));
+        return {
+            spriteName: name,
+            spriteId: s.id,
+            status: s.state,
+            checkedAt: new Date(),
+            elapsed: Math.round(performance.now() - started),
+        };
+    }
+    /** Runtime keeps each sandbox's system current itself, so there is nothing
+     * to move to: this checks that the Sprite exists, as the vendor's call does. */
+    async upgradeSprite(name) {
+        await api(() => lookup(this.runtime, name));
+    }
+    async updateSprite(name, options) {
+        return (await this.getSprite(name)).update(options);
     }
     updateURLSettings(name, settings) {
         return this.sprite(name).updateURLSettings(settings);
     }
 }
+refuse("Sprites", "SpritesClient", SpritesClient, {
+    watchSprites: "watch sandbox state with runtime.events or signed webhooks",
+});
+refuse("Sprites", "SpritesClient", { prototype: SpritesClient }, {
+    createToken: "Fly macaroons are not Runtime credentials; create a Runtime API key in the console",
+});
 export class Sprite {
     name;
     client;
     id;
+    /** Runtime does not send the organization's name with a sandbox. */
+    organizationName;
     status;
     config;
+    /** Set by createSprite; Runtime keeps it in the sandbox, not in its listing. */
+    environment;
     createdAt;
     updatedAt;
     url;
+    urlSettings;
+    /** Vendor storage and version fields; Runtime has no equivalent to report. */
+    bucketName;
+    primaryRegion;
+    version;
+    environmentVersion;
     labels = [];
+    lastRunningAt;
+    lastWarmingAt;
     constructor(name, client) {
         this.name = name;
         this.client = client;
@@ -199,6 +516,7 @@ export class Sprite {
             region: s.info.region,
             storageGB: (s.info.diskMiB * 1048576) / 1e9,
         };
+        this.primaryRegion = s.info.region;
         this.createdAt = new Date(s.info.createdAt);
         this.updatedAt = this.createdAt;
         this.labels = JSON.parse(s.info.labels["compat.labels"] ?? "[]");
@@ -209,36 +527,49 @@ export class Sprite {
         return s;
     }
     spawn(command, args = [], options = {}) {
+        only("Sprites spawn", options, EXEC_KEYS);
         return new SpriteCommand(this, command, args, options);
     }
-    exec(command, options) {
+    exec(command, options = {}) {
+        only("Sprites exec", options, EXEC_KEYS);
         return this.execFile("bash", ["-c", command], options);
     }
-    async execFile(file, args = [], options = {}) {
-        options.signal?.throwIfAborted();
-        if (options.timeout !== undefined && (!Number.isFinite(options.timeout) || options.timeout < 0))
-            throw new TypeError("timeout must be a non-negative finite number");
-        if (options.encoding &&
-            options.encoding !== "buffer" &&
-            !Buffer.isEncoding(options.encoding))
-            throw new TypeError(`Unknown encoding: ${String(options.encoding)}`);
-        only("Sprites exec", options, [
+    execFile(file, args = [], options = {}) {
+        only("Sprites exec", options, EXEC_KEYS);
+        return this.#execute(file, args, options);
+    }
+    /** Runtime's commands are HTTP calls already; `input` is written to stdin
+     * and stdin closed, and without it stdin is closed at once. */
+    execFileHTTP(file, args = [], options = {}) {
+        only("Sprites HTTP exec", options, [
             "cwd",
             "env",
-            "tty",
-            "rows",
-            "cols",
-            "detachable",
-            "sessionId",
-            "controlMode",
             "encoding",
             "maxBuffer",
             "signal",
             "timeout",
+            "input",
         ]);
+        const { input, ...rest } = options;
+        return this.#execute(file, args, rest, input ?? "");
+    }
+    async #execute(file, args, options, input) {
+        options.signal?.throwIfAborted();
+        if (options.timeout !== undefined && (!Number.isFinite(options.timeout) || options.timeout < 0))
+            throw new TypeError("timeout must be a non-negative finite number");
+        if (options.encoding &&
+            options.encoding !== "buffer" &&
+            !Buffer.isEncoding(options.encoding))
+            throw new TypeError(`Unknown encoding: ${String(options.encoding)}`);
         if (options.controlMode)
             throw new CompatibilityError("Sprites", "control-mode wire protocol");
         const cmd = this.spawn(file, args, options);
+        if (input !== undefined) {
+            if (input.length)
+                cmd.stdin.end(input);
+            else
+                cmd.stdin.end();
+        }
         const out = [], err = [];
         const maxBuffer = options.maxBuffer || 10 * 1024 * 1024;
         let stdoutBytes = 0;
@@ -292,7 +623,7 @@ export class Sprite {
                 exitCode,
             };
             if (exitCode !== 0)
-                throw new ExecError(`Command exited with code ${exitCode}`, exitCode, r.stdout, r.stderr);
+                throw new ExecError(`Command exited with code ${exitCode}`, r);
             return r;
         }
         finally {
@@ -301,15 +632,14 @@ export class Sprite {
             options.signal?.removeEventListener("abort", abort);
         }
     }
-    execFileHTTP(file, args, options) {
-        return this.execFile(file, args, options);
-    }
     createSession(command, args = [], options = {}) {
+        only("Sprites session", options, SPAWN_KEYS);
         // The pinned SDK's session wrapper forces a terminal, even when a caller
         // supplies tty:false. Attaching an existing session detects its own PTY.
         return this.spawn(command, args, { ...options, detachable: true, tty: true });
     }
     attachSession(sessionId, options = {}) {
+        only("Sprites session", options, SPAWN_KEYS);
         return this.spawn("", [], { ...options, sessionId });
     }
     async listSessions() {
@@ -336,19 +666,149 @@ export class Sprite {
     filesystem(workingDir = "/") {
         return new SpriteFilesystem(() => this.native(), workingDir);
     }
-    async createCheckpoint(_comment) {
-        throw new CompatibilityError("Sprites", "filesystem-only checkpoints; Runtime snapshots also include running memory");
+    /** Ends a session: `signal` (SIGTERM by default; "TERM" works too), then
+     * SIGKILL if it has not exited within `timeout` ("10s" by default). */
+    async killSession(sessionId, signal = "SIGTERM", timeout = "10s") {
+        const name = signalName(signal);
+        const ms = duration(timeout, "timeout");
+        const process = await (await this.native()).processes.get(sessionId);
+        const kill = (async function* () {
+            try {
+                await process.kill(name);
+                yield { type: "signal", signal: name };
+                try {
+                    const result = await process.wait({ signal: timeoutSignal(ms) });
+                    yield { type: "exited", exitCode: result.exitCode ?? undefined };
+                }
+                catch (error) {
+                    if (!(error instanceof Error) || !["TimeoutError", "AbortError"].includes(error.name))
+                        throw error;
+                    yield { type: "timeout", message: `Still running after ${timeout}` };
+                    await process.kill("SIGKILL");
+                    yield { type: "killed", signal: "SIGKILL" };
+                }
+            }
+            catch (error) {
+                if (!(error instanceof RuntimeError))
+                    throw error;
+                yield { type: "error", message: error.message };
+                return;
+            }
+            yield { type: "complete" };
+        })();
+        return new SessionKillStream(kill);
+    }
+    /** Ports listening in the Sprite now, then each one opened or closed. */
+    async watchPorts() {
+        const watcher = new PortWatcher(this.client, this.id ?? this.name);
+        await watcher.connect();
+        return watcher;
     }
-    async listCheckpoints() {
-        throw new CompatibilityError("Sprites", "filesystem-only checkpoints");
+    /** Runtime keeps each sandbox's system current itself; this checks it exists. */
+    async upgrade() {
+        await this.client.upgradeSprite(this.id ?? this.name);
     }
-    async getCheckpoint(_id) {
-        throw new CompatibilityError("Sprites", "filesystem-only checkpoints");
+    check() {
+        return this.client.checkSprite(this.id ?? this.name);
     }
+    /** A checkpoint is a Runtime disk snapshot: the files, not the running
+     * processes. The Sprite is paused for the moment it takes, then woken.
+     * Progress arrives as the vendor's stream; a refusal is an `error` message. */
+    async createCheckpoint(comment) {
+        if (comment !== undefined && typeof comment !== "string")
+            throw new TypeError("comment must be a string");
+        const s = await this.native();
+        const taken = s.snapshot({
+            mode: "disk",
+            labels: { "compat.sprite": s.id, ...(comment ? { "compat.comment": comment } : {}) },
+        });
+        taken.catch(() => undefined);
+        return new CheckpointStream((async function* () {
+            yield { type: "info", data: "Creating checkpoint" };
+            try {
+                const snapshot = await taken;
+                yield { type: "info", data: `Checkpoint ${snapshot.id} created` };
+            }
+            catch (error) {
+                if (!(error instanceof RuntimeError))
+                    throw error;
+                yield { type: "error", error: error.message };
+                return;
+            }
+            yield { type: "complete" };
+        })());
+    }
+    /** This Sprite's disk snapshots, newest first. */
+    async listCheckpoints(historyFilter) {
+        if (historyFilter !== undefined)
+            throw new CompatibilityError("Sprites", "checkpoint history filters");
+        const s = await this.native();
+        const found = [];
+        for await (const snapshot of await this.client.runtime.snapshots.list({
+            sandboxId: s.id,
+            state: "ready",
+        }))
+            if (snapshot.mode === "disk" && snapshot.sourceSandboxId === s.id)
+                found.push(checkpoint(snapshot));
+        return found.sort((a, b) => b.createTime.getTime() - a.createTime.getTime());
+    }
+    async getCheckpoint(id) {
+        const s = await this.native();
+        let snapshot;
+        try {
+            snapshot = await this.client.runtime.snapshots.get(id);
+        }
+        catch (error) {
+            if (error instanceof NotFoundError)
+                throw new Error(`Checkpoint not found: ${id}`);
+            throw error;
+        }
+        if (snapshot.mode !== "disk" || snapshot.sourceSandboxId !== s.id)
+            throw new Error(`Checkpoint not found: ${id}`);
+        return checkpoint(snapshot);
+    }
+    /** Forwards localhost:`localPort` here to `remotePort` in the Sprite. */
+    proxyPort(localPort, remotePort, remoteHost) {
+        return proxyPort(this.client, this.id ?? this.name, localPort, remotePort, remoteHost);
+    }
+    proxyPorts(mappings) {
+        return proxyPorts(this.client, this.id ?? this.name, mappings);
+    }
+    /** Runtime's network rules as Sprites rules: `* deny` closes the internet,
+     * allow rules are the only destinations reachable, deny rules are refused. */
+    async getNetworkPolicy() {
+        const policy = await (await this.native()).network.get();
+        if (!policy.internet)
+            return { rules: [{ domain: "*", action: "deny" }] };
+        const rules = [
+            ...policy.allow.map((domain) => ({ domain, action: "allow" })),
+            ...policy.deny.map((domain) => ({ domain, action: "deny" })),
+        ];
+        if (policy.allow.length)
+            rules.push({ domain: "*", action: "deny" });
+        return { rules };
+    }
+    /** Replaces the rules, keeping any host:port openings set through Runtime. */
+    async updateNetworkPolicy(policy) {
+        const rules = networkRules(policy);
+        const s = await this.native();
+        const current = await s.network.get();
+        await s.network.set({ ...rules, connect: current.connect });
+    }
+    /** Control mode is never on: Runtime refuses `controlMode: true`. */
+    useControlMode() {
+        return false;
+    }
+    hasControlConnection() {
+        return false;
+    }
+    /** Nothing to close: no control connection is ever opened. */
+    closeControlConnection() { }
     async updateURLSettings(settings) {
         validateURLSettings(settings);
         const p = await (await this.native()).previews.create(8080, { visibility: settings.auth === "public" ? "public" : "private" });
         this.url = p.urlWithToken ?? p.url;
+        this.urlSettings = { auth: settings.auth };
     }
     async update(options) {
         only("Sprites update", options, ["labels", "urlSettings"]);
@@ -368,6 +828,289 @@ export class Sprite {
         return this;
     }
 }
+const SERVICES = "Runtime has no service manager; run it as a process with spawn, or as an image's start command";
+refuse("Sprites", "Sprite", Sprite, {
+    restoreCheckpoint: "Runtime has no in-place restore; start a new sandbox from the checkpoint with runtime.sandboxes.create({ snapshot: id })",
+    getControlConnection: CONTROL,
+    listServices: SERVICES,
+    getService: SERVICES,
+    createService: SERVICES,
+    deleteService: SERVICES,
+    startService: SERVICES,
+    stopService: SERVICES,
+    restartService: SERVICES,
+    getServiceLogs: SERVICES,
+    signalService: SERVICES,
+    getPrivilegesPolicy: "Runtime sets one privilege profile for every sandbox: root through sudo",
+    updatePrivilegesPolicy: "Runtime sets one privilege profile for every sandbox: root through sudo",
+    deletePrivilegesPolicy: "Runtime sets one privilege profile for every sandbox: root through sudo",
+    getResourcesPolicy: "read the sandbox's memory size from runtime.sandboxes.get",
+    updateResourcesPolicy: "change memory with the native sandbox's resize(), which restarts its programs",
+    deleteResourcesPolicy: "change memory with the native sandbox's resize(), which restarts its programs",
+});
+function checkpoint(snapshot) {
+    const labels = (snapshot.labels ?? {});
+    return {
+        id: snapshot.id,
+        createTime: new Date(snapshot.createdAt),
+        comment: labels["compat.comment"],
+        isAuto: false,
+        health: snapshot.state === "ready" ? "" : snapshot.state,
+    };
+}
+/** Sprites lets the more specific rule win and reads `rules: []` as no
+ * limit; Runtime's allow list is the only destinations reachable and its deny
+ * list always wins. A policy whose meaning would differ is refused. */
+function networkRules(policy) {
+    if (!policy || typeof policy !== "object" || !Array.isArray(policy.rules))
+        throw new TypeError("policy.rules must be an array");
+    only("Sprites network policy", policy, ["rules"]);
+    const allow = [];
+    const deny = [];
+    let everything;
+    for (const rule of policy.rules) {
+        if (!rule || typeof rule !== "object")
+            throw new TypeError("Each rule must be an object");
+        only("Sprites network rule", rule, ["domain", "action", "include"]);
+        if (rule.include !== undefined)
+            throw new CompatibilityError("Sprites", `the network preset ${String(rule.include)}; list its domains as allow rules`);
+        if (typeof rule.domain !== "string" || !rule.domain.trim())
+            throw new TypeError("Each rule needs a domain");
+        if (rule.action !== "allow" && rule.action !== "deny")
+            throw new TypeError("action must be allow or deny");
+        const domain = rule.domain.trim().toLowerCase();
+        if (domain === "*") {
+            if (everything && everything !== rule.action)
+                throw new TypeError("* is both allowed and denied");
+            everything = rule.action;
+        }
+        else
+            (rule.action === "allow" ? allow : deny).push(domain);
+    }
+    const covers = (wide, narrow) => wide === narrow || (wide.startsWith("*.") && narrow.endsWith(wide.slice(1)));
+    for (const allowed of allow)
+        for (const denied of deny)
+            if (covers(denied, allowed))
+                throw new CompatibilityError("Sprites", `allowing ${allowed} inside the denied ${denied}; Runtime's deny rules always win`);
+    if (everything === "deny" && !allow.length)
+        return { internet: false, allow: [], deny };
+    return { internet: true, allow: everything === "allow" ? [] : allow, deny };
+}
+/** A local listener that carries each connection to a port in the Sprite,
+ * over Runtime's tunnel. Node and Bun. */
+export class ProxySession extends EventEmitter {
+    localPort;
+    remotePort;
+    remoteHost;
+    #sprite;
+    #forward;
+    #closed = false;
+    #done;
+    #finish;
+    constructor(client, spriteName, mapping) {
+        super();
+        only("Sprites port mapping", mapping, ["localPort", "remotePort", "remoteHost"]);
+        for (const [name, port] of [
+            ["localPort", mapping.localPort],
+            ["remotePort", mapping.remotePort],
+        ])
+            if (!Number.isInteger(port) ||
+                port < 0 ||
+                port > 65535 ||
+                (name === "remotePort" && port === 0))
+                throw new TypeError(`${name} must be a port number`);
+        const host = mapping.remoteHost ?? "localhost";
+        if (!["localhost", "127.0.0.1", "::1"].includes(host))
+            throw new CompatibilityError("Sprites", `proxying to ${host}; forward a port of the Sprite itself (localhost)`);
+        this.localPort = mapping.localPort;
+        this.remotePort = mapping.remotePort;
+        this.remoteHost = host;
+        const owner = client instanceof SpritesClient
+            ? client
+            : new SpritesClient(client.token, { baseURL: client.baseURL });
+        this.#sprite = owner.sprite(spriteName);
+        this.#done = new Promise((resolve) => (this.#finish = resolve));
+    }
+    async start() {
+        if (this.#closed)
+            throw new Error("Proxy session is closed");
+        try {
+            const s = await ready(await this.#sprite.native());
+            this.#forward = await s.forwardPort(this.remotePort, {
+                localPort: this.localPort,
+                host: "localhost",
+            });
+        }
+        catch (error) {
+            if (this.listenerCount("error"))
+                this.emit("error", error);
+            throw error;
+        }
+        if (this.#closed)
+            await this.#forward.close();
+    }
+    localAddr() {
+        return this.#forward && !this.#closed ? `localhost:${this.#forward.localPort}` : null;
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        void this.#forward?.close().catch(() => undefined);
+        this.#finish();
+        this.emit("close");
+    }
+    wait() {
+        return this.#done;
+    }
+}
+export class ProxyManager {
+    #sessions = [];
+    addSession(session) {
+        this.#sessions.push(session);
+    }
+    closeAll() {
+        for (const session of this.#sessions)
+            session.close();
+    }
+    async waitAll() {
+        await Promise.all(this.#sessions.map((session) => session.wait()));
+    }
+}
+export async function proxyPort(client, spriteName, localPort, remotePort, remoteHost) {
+    const session = new ProxySession(client, spriteName, { localPort, remotePort, remoteHost });
+    await session.start();
+    return session;
+}
+/** All or none: a mapping that cannot start closes the ones before it. */
+export async function proxyPorts(client, spriteName, mappings) {
+    const sessions = [];
+    try {
+        for (const mapping of mappings) {
+            const session = new ProxySession(client, spriteName, mapping);
+            sessions.push(session);
+            await session.start();
+        }
+        return sessions;
+    }
+    catch (error) {
+        for (const session of sessions)
+            session.close();
+        throw error;
+    }
+}
+/** Polls the Sprite's listening TCP sockets once a second with `ss` (as
+ * Sprites' own watcher keeps a connection open, this keeps it awake). */
+export class PortWatcher extends Feed {
+    #timer;
+    #stopped = false;
+    #sprite;
+    constructor(client, spriteName) {
+        super();
+        this.#sprite = client.sprite(spriteName);
+    }
+    async connect() {
+        const s = await ready(await this.#sprite.native());
+        let known = await listening(s);
+        this.push({ type: "port_list", ports: [...known.values()] });
+        const tick = async () => {
+            if (this.#stopped)
+                return;
+            try {
+                const now = await listening(s);
+                for (const [key, port] of known)
+                    if (!now.has(key))
+                        this.push({ ...port, type: "port_closed" });
+                for (const [key, port] of now)
+                    if (!known.has(key))
+                        this.push(port);
+                known = now;
+            }
+            catch (error) {
+                this.end(error);
+                return;
+            }
+            if (!this.#stopped)
+                this.#timer = setTimeout(() => void tick(), 1000);
+        };
+        this.#timer = setTimeout(() => void tick(), 1000);
+    }
+    stop() {
+        this.#stopped = true;
+        if (this.#timer)
+            clearTimeout(this.#timer);
+    }
+}
+async function listening(s) {
+    const result = await s.exec(["ss", "-Hltnp"]);
+    if (result.exitCode !== 0)
+        throw new Error(`Cannot list ports in the Sprite: ${result.stderr.trim() || "ss failed"}`);
+    const ports = new Map();
+    for (const line of result.stdout.split("\n")) {
+        const local = line.trim().split(/\s+/)[3];
+        if (!local)
+            continue;
+        const at = local.lastIndexOf(":");
+        const port = Number(local.slice(at + 1));
+        if (!Number.isInteger(port))
+            continue;
+        const address = local
+            .slice(0, at)
+            .replace(/^\[|\]$/g, "")
+            .replace(/%.*$/, "");
+        const pid = Number(/pid=(\d+)/.exec(line)?.[1] ?? 0);
+        ports.set(`${address}:${port}`, { type: "port_opened", port, address, pid });
+    }
+    return ports;
+}
+/** Runtime's file watch, one per path, as Sprites' watch events. */
+export class FilesystemWatcher extends Feed {
+    sandbox;
+    paths;
+    recursive;
+    #handles = [];
+    #stopped = false;
+    #files;
+    constructor(sandbox, paths, workingDir, recursive) {
+        super();
+        this.sandbox = sandbox;
+        this.paths = paths;
+        this.recursive = recursive;
+        this.#files = new GuestFiles(sandbox, workingDir);
+    }
+    async connect() {
+        const s = await this.sandbox();
+        const paths = this.paths.map((path) => this.#files.path(path));
+        try {
+            for (const path of paths) {
+                const handle = await s.files.watch(path, (event) => {
+                    if (event.type === "access")
+                        return;
+                    this.push({
+                        type: "event",
+                        path: event.path,
+                        event: event.type,
+                        isDir: event.isDir,
+                        timestamp: new Date().toISOString(),
+                    });
+                }, { recursive: this.recursive, timeoutMs: 0 });
+                this.#handles.push(handle);
+                if (this.#stopped)
+                    void handle.stop().catch(() => undefined);
+            }
+        }
+        catch (error) {
+            this.stop();
+            throw error;
+        }
+        this.push({ type: "subscribed", paths });
+    }
+    stop() {
+        this.#stopped = true;
+        for (const handle of this.#handles.splice(0))
+            void handle.stop().catch(() => undefined);
+    }
+}
 export class SpriteCommand extends EventEmitter {
     stdout = new PassThrough();
     stderr = new PassThrough();
@@ -378,20 +1121,7 @@ export class SpriteCommand extends EventEmitter {
     controller = new AbortController();
     constructor(sprite, command, args = [], options = {}) {
         super();
-        only("Sprites spawn", options, [
-            "cwd",
-            "env",
-            "tty",
-            "rows",
-            "cols",
-            "detachable",
-            "sessionId",
-            "controlMode",
-            "encoding",
-            "maxBuffer",
-            "signal",
-            "timeout",
-        ]);
+        only("Sprites spawn", options, EXEC_KEYS);
         if (options.controlMode)
             throw new CompatibilityError("Sprites", "control-mode wire protocol");
         this.process = (async () => {
@@ -479,9 +1209,11 @@ export class SpriteCommand extends EventEmitter {
 }
 export class SpriteFilesystem {
     get;
+    cwd;
     files;
     constructor(get, cwd = "/") {
         this.get = get;
+        this.cwd = cwd;
         this.files = new GuestFiles(get, cwd);
     }
     async readFile(path, encoding) {
@@ -527,6 +1259,8 @@ export class SpriteFilesystem {
     async rm(path, options = {}) {
         if (!options.force && !(await this.files.exists(path)))
             throw new FilesystemError(`Path not found: ${path}`, "ENOENT", path, "rm");
+        if (options.asRoot)
+            return this.#root(path, "rm", ["rm", "-f", ...(options.recursive ? ["-r"] : []), "--", this.files.path(path)], true);
         await fileOperation(path, "rm", () => this.files.remove(path, options.recursive));
     }
     async stat(path) {
@@ -542,15 +1276,85 @@ export class SpriteFilesystem {
             isSymbolicLink: () => e.type === "symlink",
         };
     }
-    rename(from, to) {
+    async rename(from, to, options = {}) {
+        if (options.asRoot)
+            return this.#root(from, "rename", ["mv", "-f", "-T", "--", this.files.path(from), this.files.path(to)], true);
         return fileOperation(from, "rename", () => this.files.rename(from, to, true));
     }
-    copyFile(from, to, options = {}) {
+    async copyFile(from, to, options = {}) {
+        if (options.asRoot || options.preserveAttrs)
+            return this.#root(from, "copyFile", [
+                "cp",
+                ...(options.recursive ? ["-R"] : []),
+                ...(options.preserveAttrs ? ["--preserve=mode,ownership,timestamps"] : []),
+                "--",
+                this.files.path(from),
+                this.files.path(to),
+            ], options.asRoot === true);
         return fileOperation(from, "copyFile", () => this.files.copy(from, to, options.recursive, true));
     }
-    chmod(path, mode, options = {}) {
+    async chmod(path, mode, options = {}) {
+        if (options.asRoot) {
+            if (!Number.isInteger(mode) || mode < 0)
+                throw new TypeError("mode must be a file mode");
+            return this.#root(path, "chmod", [
+                "chmod",
+                ...(options.recursive ? ["-R"] : []),
+                (mode & 0o7777).toString(8),
+                "--",
+                this.files.path(path),
+            ], true);
+        }
         return fileOperation(path, "chmod", () => this.files.chmod(path, mode, options.recursive));
     }
+    /** By number or name, as the Sprite's user unless `asRoot` (sudo). */
+    async chown(path, options) {
+        only("Sprites chown", options ?? {}, ["uid", "gid", "recursive", "asRoot"]);
+        if (options?.uid === undefined && options?.gid === undefined)
+            throw new TypeError("uid or gid is required");
+        for (const id of [options.uid, options.gid])
+            if (id !== undefined &&
+                !(typeof id === "number" ? Number.isInteger(id) && id >= 0 : /^[A-Za-z0-9._-]+$/.test(id)))
+                throw new TypeError("uid and gid must be ids or user and group names");
+        const owner = `${options.uid ?? ""}${options.gid === undefined ? "" : `:${options.gid}`}`;
+        return this.#root(path, "chown", ["chown", ...(options.recursive ? ["-R"] : []), owner, "--", this.files.path(path)], options.asRoot === true);
+    }
+    /** Changes to these paths until the watcher is closed. */
+    async watch(paths, options = {}) {
+        only("Sprites watch", options, ["recursive"]);
+        const list = Array.isArray(paths) ? paths : [paths];
+        if (!list.length || list.some((path) => typeof path !== "string" || !path))
+            throw new TypeError("paths must name at least one path");
+        const watcher = new FilesystemWatcher(this.get, list, this.cwd, options.recursive === true);
+        await watcher.connect();
+        return watcher;
+    }
+    /** A guest command for what the file API does not offer: as root through
+     * sudo when asked, and its failure as the vendor's FilesystemError. */
+    async #root(path, syscall, argv, asRoot) {
+        const result = await (await this.get()).exec(asRoot ? ["sudo", "-n", "--", ...argv] : argv);
+        if (result.exitCode === 0)
+            return;
+        const message = result.stderr.trim() || `${syscall} failed`;
+        const code = /No such file/i.test(message)
+            ? "ENOENT"
+            : /File exists/i.test(message)
+                ? "EEXIST"
+                : /Not a directory/i.test(message)
+                    ? "ENOTDIR"
+                    : /Is a directory/i.test(message)
+                        ? "EISDIR"
+                        : /Directory not empty/i.test(message)
+                            ? "ENOTEMPTY"
+                            : /Operation not permitted|password is required|sudo:/i.test(message)
+                                ? "EPERM"
+                                : /Permission denied/i.test(message)
+                                    ? "EACCES"
+                                    : /invalid/i.test(message)
+                                        ? "EINVAL"
+                                        : "UNKNOWN";
+        throw new FilesystemError(message, code, path, syscall);
+    }
     exists(path) {
         return this.files.exists(path);
     }
@@ -564,25 +1368,3 @@ export class SpriteFilesystem {
         return this.writeFile(path, JSON.stringify(data, null, options.spaces));
     }
 }
-export class CheckpointStream {
-    messages;
-    index = 0;
-    constructor(messages) {
-        this.messages = messages;
-    }
-    async next() {
-        return this.messages[this.index++] ?? null;
-    }
-    async processAll(handler) {
-        for await (const message of this)
-            await handler(message);
-    }
-    close() {
-        this.index = this.messages.length;
-    }
-    async *[Symbol.asyncIterator]() {
-        let message;
-        while ((message = await this.next()))
-            yield message;
-    }
-}