@schemavaults/sandbox-management-sdk 0.0.0-stage → 0.1.0

package/dist/manager.js

@@ -0,0 +1,477 @@
+import { gitCloneCommand, normalizeCommand, resolveSandboxPath, validateSpec } from "./commands.js";
+import { ProviderNotFoundError, ProviderSandboxMissingError, ProviderSandboxStoppedError, SandboxBusyError, SandboxCommandError, SandboxError, SandboxNotFoundError, SandboxStateError, } from "./errors.js";
+import { assertNetworkPolicySupported } from "./network.js";
+import { TRANSITIONAL_STATUSES } from "./types.js";
+const DEFAULT_TRANSITION_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_POLL_INTERVAL_MS = 250;
+export function generateSandboxId() {
+    return `sbx-${crypto.randomUUID().replaceAll("-", "")}`;
+}
+/**
+ * Creates, lists and drives sandboxes across providers, keeping their state in
+ * a `SandboxStore`. Safe to use from many processes at once: every status
+ * change is a compare-and-set on the record's version.
+ */
+export class SandboxManager {
+    providers = new Map();
+    store;
+    defaultProvider;
+    autoResume;
+    transitionTimeoutMs;
+    pollIntervalMs;
+    generateId;
+    now;
+    constructor(options) {
+        for (const provider of options.providers) {
+            if (this.providers.has(provider.name)) {
+                throw new SandboxError(`Duplicate sandbox provider name "${provider.name}"`);
+            }
+            this.providers.set(provider.name, provider);
+        }
+        this.store = options.store;
+        this.defaultProvider =
+            options.defaultProvider ?? (options.providers.length === 1 ? options.providers[0]?.name : undefined);
+        this.autoResume = options.autoResume ?? true;
+        this.transitionTimeoutMs = options.transitionTimeoutMs ?? DEFAULT_TRANSITION_TIMEOUT_MS;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.generateId = options.generateId ?? generateSandboxId;
+        this.now = options.now ?? (() => new Date());
+    }
+    /**
+     * Create a sandbox, clone `spec.git`, run `spec.setup` and launch
+     * `spec.start`. Resolves once the sandbox is running. On failure the record
+     * is marked `failed` and the provider sandbox is kept for inspection; call
+     * `destroy` to remove it.
+     */
+    async create(options) {
+        const providerName = options.provider ?? this.defaultProvider;
+        if (!providerName) {
+            throw new SandboxError("No provider given and no defaultProvider configured");
+        }
+        const provider = this.getProvider(providerName);
+        validateSpec(options.spec);
+        assertNetworkPolicySupported(provider, options.spec.network);
+        const now = this.now();
+        let record = {
+            id: this.generateId(),
+            provider: provider.name,
+            providerRef: null,
+            status: "provisioning",
+            spec: structuredClone(options.spec),
+            ownerId: options.ownerId ?? null,
+            labels: { ...options.labels },
+            metadata: structuredClone(options.metadata ?? {}),
+            error: null,
+            version: 0,
+            createdAt: now,
+            updatedAt: now,
+            expiresAt: null,
+        };
+        await this.store.insert(record);
+        try {
+            const workdir = this.workdirFor(record);
+            const { providerRef } = await provider.create({
+                id: record.id,
+                spec: record.spec,
+                workdir,
+                ownerId: record.ownerId,
+                labels: record.labels,
+            });
+            record = await this.mustUpdate(record, {
+                providerRef,
+                status: "setting_up",
+                expiresAt: this.expiryFor(record.spec),
+            });
+            const sandbox = this.toProviderSandbox(record);
+            if (record.spec.git) {
+                await this.runStep(provider, sandbox, "git clone", gitCloneCommand(record.spec.git, workdir), options);
+            }
+            const setup = record.spec.setup === undefined ? [] : [].concat(record.spec.setup);
+            for (const [index, step] of setup.entries()) {
+                await this.runStep(provider, sandbox, `setup step ${index + 1}`, normalizeCommand(step, workdir), options);
+            }
+            record = await this.mustUpdate(record, { status: "starting" });
+            if (record.spec.start) {
+                await provider.startMainProcess(sandbox, normalizeCommand(record.spec.start, workdir));
+            }
+            return await this.mustUpdate(record, { status: "running" });
+        }
+        catch (error) {
+            await this.markFailed(record, error);
+            throw error;
+        }
+    }
+    /** Resolves the record, or throws `SandboxNotFoundError`. */
+    async get(id) {
+        const record = await this.store.get(id);
+        if (!record)
+            throw new SandboxNotFoundError(id);
+        return record;
+    }
+    /** Resolves the record, or `null` if it does not exist. */
+    async find(id) {
+        return this.store.get(id);
+    }
+    async list(filter) {
+        return this.store.list(filter);
+    }
+    /** Run a one-shot command and wait for it to finish. A non-zero exit does not throw. */
+    async exec(id, command, options) {
+        return this.withRunning(id, "exec in", (provider, sandbox) => provider.exec(sandbox, normalizeCommand(command, sandbox.workdir), options));
+    }
+    /**
+     * Wake a stopped sandbox and relaunch `spec.resume` (or `spec.start`) as its
+     * main process. Also retries a `failed` sandbox that still has a provider
+     * sandbox; `setup` is not re-run. No-op if it is already running.
+     */
+    async resume(id) {
+        for (;;) {
+            const record = await this.settle(id);
+            if (record.status === "running")
+                return record;
+            const resumable = record.status === "stopped" || (record.status === "failed" && record.providerRef !== null);
+            if (!resumable)
+                throw new SandboxStateError(id, record.status, "resume");
+            const resumed = await this.tryResume(record);
+            if (resumed)
+                return resumed;
+        }
+    }
+    /** Stop a running sandbox, keeping its filesystem. No-op if it is already stopped. */
+    async stop(id) {
+        for (;;) {
+            const record = await this.settle(id);
+            if (record.status === "stopped")
+                return record;
+            if (record.status !== "running")
+                throw new SandboxStateError(id, record.status, "stop");
+            const provider = this.getProvider(record.provider);
+            const claimed = await this.store.update(id, record.version, { status: "stopping" });
+            if (!claimed)
+                continue;
+            try {
+                await provider.stop(this.toProviderSandbox(claimed));
+            }
+            catch (error) {
+                if (error instanceof ProviderSandboxMissingError) {
+                    await this.markFailed(claimed, error);
+                }
+                else {
+                    await this.store.update(id, claimed.version, { status: "running", error: errorMessage(error) });
+                }
+                throw error;
+            }
+            return this.mustUpdate(claimed, { status: "stopped", expiresAt: null });
+        }
+    }
+    /** Delete the provider sandbox. The record is kept with status `destroyed`. */
+    async destroy(id) {
+        for (;;) {
+            const record = await this.settle(id);
+            if (record.status === "destroyed")
+                return record;
+            const provider = this.getProvider(record.provider);
+            const claimed = await this.store.update(id, record.version, { status: "destroying" });
+            if (!claimed)
+                continue;
+            try {
+                if (claimed.providerRef)
+                    await provider.destroy(this.toProviderSandbox(claimed));
+            }
+            catch (error) {
+                await this.markFailed(claimed, error);
+                throw error;
+            }
+            return this.mustUpdate(claimed, { status: "destroyed", expiresAt: null });
+        }
+    }
+    /** A URL that reaches `port` (which must be listed in `spec.ports`). */
+    async getUrl(id, port) {
+        return this.withRunning(id, "get a URL for", (provider, sandbox) => {
+            if (!sandbox.spec.ports?.includes(port)) {
+                throw new SandboxError(`Port ${port} is not exposed; add it to spec.ports`);
+            }
+            return provider.getUrl(sandbox, port);
+        });
+    }
+    async writeFiles(id, files) {
+        const encoder = new TextEncoder();
+        await this.withRunning(id, "write files to", (provider, sandbox) => provider.writeFiles(sandbox, files.map((file) => ({
+            path: resolveSandboxPath(sandbox.workdir, file.path),
+            content: typeof file.content === "string" ? encoder.encode(file.content) : file.content,
+            mode: file.mode ?? 0o644,
+        }))));
+    }
+    /** Resolves the file's bytes, or `null` if it does not exist. */
+    async readFile(id, path) {
+        return this.withRunning(id, "read files from", (provider, sandbox) => provider.readFile(sandbox, resolveSandboxPath(sandbox.workdir, path)));
+    }
+    async readTextFile(id, path) {
+        const bytes = await this.readFile(id, path);
+        return bytes === null ? null : new TextDecoder().decode(bytes);
+    }
+    /** State of the detached main process, or `null` if none was launched. */
+    async getMainProcess(id) {
+        return this.withRunning(id, "inspect", (provider, sandbox) => provider.getMainProcess(sandbox));
+    }
+    /** The main process's full log so far. */
+    async readLogs(id) {
+        let output = "";
+        for await (const chunk of this.logs(id))
+            output += chunk;
+        return output;
+    }
+    /**
+     * Stream the main process's log, from the beginning. Only the first read
+     * auto-resumes a stopped sandbox; when following, the stream ends once the
+     * sandbox stops or `signal` aborts.
+     */
+    async *logs(id, options = {}) {
+        const decoder = new TextDecoder();
+        let offset = 0;
+        let first = true;
+        for (;;) {
+            if (options.signal?.aborted)
+                break;
+            const chunk = first
+                ? await this.withRunning(id, "read logs of", (provider, sandbox) => provider.readMainLog(sandbox, offset))
+                : await this.readMainLogIfRunning(id, offset);
+            first = false;
+            if (chunk === null)
+                break;
+            offset = chunk.nextOffset;
+            if (chunk.data.length > 0) {
+                yield decoder.decode(chunk.data, { stream: true });
+                continue;
+            }
+            if (!options.follow)
+                break;
+            await sleep(options.pollIntervalMs ?? 1000, options.signal);
+        }
+        const rest = decoder.decode();
+        if (rest)
+            yield rest;
+    }
+    /** Reads the log without resuming; `null` once the sandbox is no longer running. */
+    async readMainLogIfRunning(id, offset) {
+        const record = await this.get(id);
+        if (record.status !== "running")
+            return null;
+        try {
+            return await this.getProvider(record.provider).readMainLog(this.toProviderSandbox(record), offset);
+        }
+        catch (error) {
+            if (error instanceof ProviderSandboxStoppedError || error instanceof ProviderSandboxMissingError)
+                return null;
+            throw error;
+        }
+    }
+    /** Push back the sandbox's expiry (and the provider's own timeout, if it has one). */
+    async extendTimeout(id, durationMs) {
+        await this.withRunning(id, "extend the timeout of", async (provider, sandbox) => {
+            await provider.extendTimeout?.(sandbox, durationMs);
+        });
+        for (;;) {
+            const record = await this.get(id);
+            const base = Math.max(record.expiresAt?.getTime() ?? 0, this.now().getTime());
+            const updated = await this.store.update(id, record.version, { expiresAt: new Date(base + durationMs) });
+            if (updated)
+                return updated;
+        }
+    }
+    /**
+     * Stop every running sandbox whose `expiresAt` has passed. Run this
+     * periodically (e.g. from a cron job) for providers without native
+     * timeouts, such as Docker.
+     */
+    async stopExpired() {
+        const now = this.now().getTime();
+        const expired = (await this.store.list({ status: "running" })).filter((record) => record.expiresAt !== null && record.expiresAt.getTime() <= now);
+        const stopped = [];
+        for (const record of expired) {
+            try {
+                stopped.push(await this.stop(record.id));
+            }
+            catch {
+                // Leave it for the next run; the error is recorded on the sandbox where possible.
+            }
+        }
+        return stopped;
+    }
+    /**
+     * Bring records in line with what the providers report: running sandboxes
+     * the provider has stopped become `stopped`, vanished ones become `failed`,
+     * and transitions abandoned for longer than the transition timeout (e.g. a
+     * crashed process) are settled. Defaults to every non-destroyed sandbox;
+     * sandboxes on unregistered providers, or whose provider errors, are
+     * skipped. Resolves the records that changed.
+     */
+    async reconcile(ids) {
+        const records = ids
+            ? (await Promise.all(ids.map((id) => this.store.get(id)))).filter((r) => r !== null)
+            : await this.store.list();
+        const changed = [];
+        for (const record of records) {
+            const patch = await this.reconcilePatch(record).catch(() => null);
+            if (!patch)
+                continue;
+            const updated = await this.store.update(record.id, record.version, patch);
+            if (updated)
+                changed.push(updated);
+        }
+        return changed;
+    }
+    async reconcilePatch(record) {
+        if (record.status === "destroyed")
+            return null;
+        const stale = TRANSITIONAL_STATUSES.includes(record.status) &&
+            this.now().getTime() - record.updatedAt.getTime() > this.transitionTimeoutMs;
+        if (!record.providerRef) {
+            return stale ? { status: "failed", error: `Interrupted while ${record.status}` } : null;
+        }
+        const provider = this.providers.get(record.provider);
+        if (!provider)
+            return null;
+        const providerStatus = await provider.status(this.toProviderSandbox(record));
+        if (providerStatus === "missing") {
+            if (record.status === "destroying")
+                return { status: "destroyed", expiresAt: null };
+            if (record.status === "failed")
+                return null;
+            if (TRANSITIONAL_STATUSES.includes(record.status) && !stale)
+                return null;
+            return { status: "failed", error: "Sandbox no longer exists on the provider" };
+        }
+        if (record.status === "running" && providerStatus === "stopped") {
+            return { status: "stopped", expiresAt: null };
+        }
+        if (stale) {
+            if (record.status === "stopping" && providerStatus === "stopped") {
+                return { status: "stopped", expiresAt: null };
+            }
+            return { status: "failed", error: `Interrupted while ${record.status}` };
+        }
+        return null;
+    }
+    /** Runs `fn` against a running sandbox, auto-resuming it if it is (or turns out to be) stopped. */
+    async withRunning(id, operation, fn) {
+        let record = await this.ensureRunning(id, operation);
+        let provider = this.getProvider(record.provider);
+        try {
+            return await fn(provider, this.toProviderSandbox(record));
+        }
+        catch (error) {
+            if (error instanceof ProviderSandboxMissingError) {
+                await this.markFailed(record, error);
+                throw error;
+            }
+            if (!(error instanceof ProviderSandboxStoppedError))
+                throw error;
+            // Stopped behind our back, e.g. by a provider-side timeout.
+            await this.store.update(id, record.version, { status: "stopped", expiresAt: null });
+            record = await this.ensureRunning(id, operation);
+            provider = this.getProvider(record.provider);
+            return await fn(provider, this.toProviderSandbox(record));
+        }
+    }
+    async ensureRunning(id, operation) {
+        for (;;) {
+            const record = await this.settle(id);
+            if (record.status === "running")
+                return record;
+            if (record.status !== "stopped" || !this.autoResume) {
+                throw new SandboxStateError(id, record.status, operation);
+            }
+            const resumed = await this.tryResume(record);
+            if (resumed)
+                return resumed;
+        }
+    }
+    /** Claims the record for resuming. Resolves `null` if another caller claimed it first. */
+    async tryResume(record) {
+        const provider = this.getProvider(record.provider);
+        const claimed = await this.store.update(record.id, record.version, { status: "resuming", error: null });
+        if (!claimed)
+            return null;
+        try {
+            const sandbox = this.toProviderSandbox(claimed);
+            await provider.wake(sandbox);
+            const command = claimed.spec.resume ?? claimed.spec.start;
+            if (command) {
+                await provider.startMainProcess(sandbox, normalizeCommand(command, sandbox.workdir));
+            }
+            return await this.mustUpdate(claimed, { status: "running", expiresAt: this.expiryFor(claimed.spec) });
+        }
+        catch (error) {
+            await this.markFailed(claimed, error);
+            throw error;
+        }
+    }
+    /** Waits until the record is not in a transitional status. */
+    async settle(id) {
+        const deadline = Date.now() + this.transitionTimeoutMs;
+        for (;;) {
+            const record = await this.get(id);
+            if (!TRANSITIONAL_STATUSES.includes(record.status))
+                return record;
+            if (Date.now() >= deadline)
+                throw new SandboxBusyError(id, record.status);
+            await sleep(this.pollIntervalMs);
+        }
+    }
+    async runStep(provider, sandbox, step, command, options) {
+        const result = await provider.exec(sandbox, command, {
+            onStdout: options.onStdout,
+            onStderr: options.onStderr,
+        });
+        if (result.exitCode !== 0)
+            throw new SandboxCommandError(step, result);
+    }
+    /** Update that must succeed because this caller holds the record's transitional status. */
+    async mustUpdate(record, patch) {
+        const updated = await this.store.update(record.id, record.version, patch);
+        if (!updated) {
+            throw new SandboxError(`Sandbox "${record.id}" was modified concurrently while ${record.status}`);
+        }
+        return updated;
+    }
+    async markFailed(record, error) {
+        await this.store
+            .update(record.id, record.version, { status: "failed", error: errorMessage(error) })
+            .catch(() => null);
+    }
+    getProvider(name) {
+        const provider = this.providers.get(name);
+        if (!provider)
+            throw new ProviderNotFoundError(name);
+        return provider;
+    }
+    workdirFor(record) {
+        return record.spec.workdir ?? this.getProvider(record.provider).defaultWorkdir;
+    }
+    toProviderSandbox(record) {
+        if (!record.providerRef) {
+            throw new SandboxError(`Sandbox "${record.id}" has no provider sandbox`);
+        }
+        return { id: record.id, providerRef: record.providerRef, spec: record.spec, workdir: this.workdirFor(record) };
+    }
+    expiryFor(spec) {
+        return spec.timeoutMs === undefined ? null : new Date(this.now().getTime() + spec.timeoutMs);
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", done, { once: true });
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+    });
+}

package/dist/network.d.ts

@@ -0,0 +1,27 @@
+import type { SandboxProvider } from "./provider.js";
+import type { SandboxNetworkPolicy, SandboxNetworkPolicyKind } from "./types.js";
+/** `"allow-all"` for an unset policy, otherwise the policy's kind. */
+export declare function networkPolicyKind(policy: SandboxNetworkPolicy | undefined): SandboxNetworkPolicyKind;
+/** Throws a `SandboxError` unless `provider` declares that it enforces `policy`. */
+export declare function assertNetworkPolicySupported(provider: Pick<SandboxProvider, "name" | "networkPolicies">, policy: SandboxNetworkPolicy | undefined): void;
+/** Throws a `SandboxError` describing the first problem found in `policy`. */
+export declare function validateNetworkPolicy(policy: unknown): void;
+/** Adds the single-host prefix (`/32` or `/128`) to a bare IP address. Expects a valid value. */
+export declare function normalizeCidr(value: string): string;
+/** An IPv4 or IPv6 address as a number (32 or 128 bits). */
+export interface IpAddress {
+    version: 4 | 6;
+    value: bigint;
+}
+/** An IP range; `network` holds the address's first `prefix` bits. */
+export interface CidrRange {
+    version: 4 | 6;
+    prefix: number;
+    network: bigint;
+}
+/** Parses an IPv4 / IPv6 address with an optional `/prefix`, or returns `null`. */
+export declare function parseCidr(value: string): CidrRange | null;
+/** Whether `range` contains `ip`. Addresses of the other IP version are never contained. */
+export declare function cidrContains(range: CidrRange, ip: IpAddress): boolean;
+/** Parses a plain IPv4 or IPv6 address (no zone ID), or returns `null`. */
+export declare function parseIp(address: string): IpAddress | null;

package/dist/network.js

@@ -0,0 +1,128 @@
+import { SandboxError } from "./errors.js";
+const ALLOWLIST_FIELDS = ["allowDomains", "allowCidrs", "denyCidrs"];
+const DOMAIN_LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
+const DOMAIN = new RegExp(`^(?:\\*\\.)?(?:${DOMAIN_LABEL}\\.)*${DOMAIN_LABEL}$`, "i");
+const IPV4_OCTET = /^(?:0|[1-9]\d{0,2})$/;
+const IPV6_GROUP = /^[0-9a-f]{1,4}$/i;
+const PREFIX = /^(?:0|[1-9]\d{0,2})$/;
+/** `"allow-all"` for an unset policy, otherwise the policy's kind. */
+export function networkPolicyKind(policy) {
+    return policy === undefined || policy === "allow-all" ? "allow-all" : policy === "deny-all" ? "deny-all" : "allowlist";
+}
+/** Throws a `SandboxError` unless `provider` declares that it enforces `policy`. */
+export function assertNetworkPolicySupported(provider, policy) {
+    const kind = networkPolicyKind(policy);
+    if (kind === "allow-all" || provider.networkPolicies?.includes(kind))
+        return;
+    const supported = provider.networkPolicies?.length
+        ? `it enforces only ${provider.networkPolicies.map((name) => `"${name}"`).join(", ")}`
+        : "it enforces no network restrictions";
+    throw new SandboxError(`Provider "${provider.name}" cannot enforce ${kind === "allowlist" ? "a network allowlist" : 'a "deny-all" network policy'} (spec.network): ${supported}`);
+}
+/** Throws a `SandboxError` describing the first problem found in `policy`. */
+export function validateNetworkPolicy(policy) {
+    if (policy === undefined || policy === "allow-all" || policy === "deny-all")
+        return;
+    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+        throw new SandboxError(`network must be "allow-all", "deny-all" or { allowDomains?, allowCidrs?, denyCidrs? }`);
+    }
+    const allowlist = policy;
+    for (const key of Object.keys(allowlist)) {
+        if (!ALLOWLIST_FIELDS.includes(key)) {
+            throw new SandboxError(`Unknown field network.${key}; expected allowDomains, allowCidrs or denyCidrs`);
+        }
+    }
+    for (const domain of stringList(allowlist, "allowDomains")) {
+        if (parseCidr(domain)) {
+            throw new SandboxError(`network.allowDomains has the IP address "${domain}"; put it in allowCidrs`);
+        }
+        if (domain !== "*" && !(domain.length <= 253 && DOMAIN.test(domain))) {
+            throw new SandboxError(`Invalid domain "${domain}" in network.allowDomains; expected a host name such as "github.com" or "*.github.com"`);
+        }
+    }
+    for (const field of ["allowCidrs", "denyCidrs"]) {
+        for (const cidr of stringList(allowlist, field)) {
+            if (!parseCidr(cidr)) {
+                throw new SandboxError(`Invalid IP address or CIDR "${cidr}" in network.${field}; expected e.g. "203.0.113.10" or "10.0.0.0/8"`);
+            }
+        }
+    }
+}
+/** Adds the single-host prefix (`/32` or `/128`) to a bare IP address. Expects a valid value. */
+export function normalizeCidr(value) {
+    if (value.includes("/"))
+        return value;
+    return `${value}/${parseIp(value)?.version === 6 ? 128 : 32}`;
+}
+/** Parses an IPv4 / IPv6 address with an optional `/prefix`, or returns `null`. */
+export function parseCidr(value) {
+    const [address = "", prefix, ...extra] = value.split("/");
+    if (extra.length > 0)
+        return null;
+    const ip = parseIp(address);
+    if (ip === null)
+        return null;
+    const bits = ip.version === 4 ? 32 : 128;
+    if (prefix !== undefined && !(PREFIX.test(prefix) && Number(prefix) <= bits))
+        return null;
+    const length = prefix === undefined ? bits : Number(prefix);
+    return { version: ip.version, prefix: length, network: ip.value >> BigInt(bits - length) };
+}
+/** Whether `range` contains `ip`. Addresses of the other IP version are never contained. */
+export function cidrContains(range, ip) {
+    const bits = range.version === 4 ? 32 : 128;
+    return range.version === ip.version && ip.value >> BigInt(bits - range.prefix) === range.network;
+}
+/** Parses a plain IPv4 or IPv6 address (no zone ID), or returns `null`. */
+export function parseIp(address) {
+    const v4 = parseIPv4(address);
+    if (v4 !== null)
+        return { version: 4, value: v4 };
+    const v6 = parseIPv6(address);
+    return v6 === null ? null : { version: 6, value: v6 };
+}
+function stringList(allowlist, field) {
+    const value = allowlist[field];
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+        throw new SandboxError(`network.${field} must be an array of strings`);
+    }
+    return value;
+}
+function parseIPv4(address) {
+    const octets = address.split(".");
+    if (octets.length !== 4 || !octets.every((octet) => IPV4_OCTET.test(octet) && Number(octet) <= 255))
+        return null;
+    return octets.reduce((value, octet) => (value << 8n) | BigInt(octet), 0n);
+}
+function parseIPv6(address) {
+    let rest = address;
+    let embedded = [];
+    const last = rest.slice(rest.lastIndexOf(":") + 1);
+    if (last.includes(".")) {
+        // An embedded IPv4 address, e.g. `::ffff:192.0.2.1`, stands for the last two groups.
+        const v4 = parseIPv4(last);
+        if (v4 === null || last === rest)
+            return null;
+        rest = rest.slice(0, -last.length);
+        if (!rest.endsWith("::"))
+            rest = rest.slice(0, -1);
+        embedded = [v4 >> 16n, v4 & 0xffffn];
+    }
+    const halves = rest.split("::");
+    if (halves.length > 2)
+        return null;
+    const split = (part) => (part ? part.split(":") : []);
+    const head = split(halves[0]);
+    const tail = split(halves[1]);
+    if (![...head, ...tail].every((group) => IPV6_GROUP.test(group)))
+        return null;
+    const groups = 8 - embedded.length;
+    const count = head.length + tail.length;
+    if (halves.length === 2 ? count >= groups : count !== groups)
+        return null;
+    const zeros = Array.from({ length: groups - count }, () => 0n);
+    const values = [...head.map((group) => BigInt(`0x${group}`)), ...zeros, ...tail.map((group) => BigInt(`0x${group}`)), ...embedded];
+    return values.reduce((value, group) => (value << 16n) | group, 0n);
+}