sandboxedjs 0.1.53 → 0.1.55

package/dist/python-abi.d.ts

@@ -1,6 +1,229 @@
-import { V as Vfs, C as Cred } from './vfs-DzEcPbMY.js';
-export { l as ROOT_CRED, u as makeCred } from './vfs-DzEcPbMY.js';
-export { M as MemoryVolume } from './memory-volume-CTOXNJ6n.js';
+import { V as Vfs, C as Cred, a as VirtualTcpNetwork } from './contracts-CVgctitO.js';
+export { m as ROOT_CRED, v as makeCred } from './contracts-CVgctitO.js';
+export { M as MemoryVolume } from './memory-volume-CWuWScIs.js';
+
+/**
+ * Open-file descriptions: the thing a descriptor points *at*.
+ *
+ * POSIX has three levels and collapsing any two of them produces bugs that look
+ * like something else entirely:
+ *
+ *  - a **pathname** is a directory entry, and may be renamed or removed;
+ *  - an **inode** is the file's identity and content, and outlives its names;
+ *  - an **open-file description** holds the offset and the status flags.
+ *
+ * `dup()` makes two descriptors share one description — so they share an offset.
+ * Two separate `open()` calls on the same path make two descriptions, so their
+ * offsets are independent. A file stays readable through an open description
+ * after its last name is unlinked. None of that is expressible if a descriptor
+ * is just a path and a number, which is why this layer exists rather than the
+ * path-based {@link Vfs} calls being used directly.
+ *
+ * The identity used here is the volume's inode number, so a rename moves a name
+ * without disturbing anything already open.
+ */
+
+/** A failure carrying the errno the guest's libc should see. */
+declare class PosixError extends Error {
+    readonly errno: number;
+    constructor(errno: number, message?: string);
+}
+declare const O_RDONLY = 0;
+declare const O_WRONLY = 1;
+declare const O_RDWR = 2;
+declare const O_CREAT = 64;
+declare const O_EXCL = 128;
+declare const O_TRUNC = 512;
+declare const O_APPEND = 1024;
+declare const O_NONBLOCK = 2048;
+declare const O_DIRECTORY = 65536;
+declare const O_CLOEXEC = 524288;
+/** Access mode alone, with the flag bits masked off. */
+declare function accessMode(flags: number): number;
+interface DescriptionStat {
+    ino: number;
+    mode: number;
+    size: number;
+    uid: number;
+    gid: number;
+    nlink: number;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+}
+/**
+ * What every kind of open thing can do.
+ *
+ * `read` and `write` are permitted to move fewer bytes than asked for: that is
+ * ordinary POSIX behaviour, and a guest that assumes otherwise is already
+ * broken on Linux.
+ */
+interface OpenFileDescription {
+    readonly kind: "file" | "dir" | "pipe" | "stream" | "socket";
+    flags: number;
+    read(length: number): Uint8Array;
+    write(data: Uint8Array): number;
+    pread?(length: number, offset: number): Uint8Array;
+    pwrite?(data: Uint8Array, offset: number): number;
+    seek?(offset: number, whence: number): number;
+    stat(): DescriptionStat;
+    truncate?(length: number): void;
+    /** Ready to read now, or at end of input (which is also "ready"). */
+    readable(): boolean;
+    /** Ready to accept at least one byte. */
+    writable(): boolean;
+    /** Resolves when readiness may have changed; used only to park a poll. */
+    whenReady(): Promise<void>;
+    /** Last reference dropped. */
+    close(): void;
+}
+declare const SEEK_SET = 0;
+declare const SEEK_CUR = 1;
+declare const SEEK_END = 2;
+/**
+ * The bytes behind an open regular file.
+ *
+ * Content lives in the volume while a name still points at it, and moves into
+ * `detached` when the last name goes away with the file still open. That is the
+ * only way to honour "an unlinked file stays readable until the last close" on
+ * top of a path-addressed volume.
+ *
+ * A name removed by something that does not go through this service — the
+ * shell, or the Node side — cannot be intercepted, and the description will
+ * then fail with ENOENT rather than reading stale bytes. Documented in
+ * docs/python/abi.md; correctness holds for everything using the host ABI.
+ */
+declare class Inode {
+    readonly ino: number;
+    path: string;
+    private readonly vfs;
+    private readonly cred;
+    detached: Uint8Array | null;
+    refs: number;
+    constructor(ino: number, path: string, vfs: Vfs, cred: Cred);
+    /** Read the whole file, wherever it currently lives. */
+    contents(): Uint8Array;
+    replace(data: Uint8Array): void;
+    /** Called when the last name is about to be removed. */
+    detach(): void;
+    size(): number;
+    stat(): DescriptionStat;
+}
+/** One `open()`: an offset and status flags over an {@link Inode}. */
+declare class FileDescription implements OpenFileDescription {
+    readonly inode: Inode;
+    flags: number;
+    readonly kind = "file";
+    offset: number;
+    constructor(inode: Inode, flags: number);
+    read(length: number): Uint8Array;
+    pread(length: number, offset: number): Uint8Array;
+    write(data: Uint8Array): number;
+    pwrite(data: Uint8Array, offset: number): number;
+    private writeAt;
+    seek(offset: number, whence: number): number;
+    truncate(length: number): void;
+    stat(): DescriptionStat;
+    readable(): boolean;
+    writable(): boolean;
+    whenReady(): Promise<void>;
+    close(): void;
+}
+/** An open directory: `getdents` reads from a snapshot at the description's offset. */
+declare class DirectoryDescription implements OpenFileDescription {
+    readonly path: string;
+    flags: number;
+    private readonly vfs;
+    private readonly cred;
+    readonly kind = "dir";
+    private entries;
+    private index;
+    constructor(path: string, flags: number, vfs: Vfs, cred: Cred);
+    /** Entry names, NUL-terminated, as many as fit in `length`. */
+    read(length: number): Uint8Array;
+    write(): number;
+    seek(offset: number, whence: number): number;
+    stat(): DescriptionStat;
+    readable(): boolean;
+    writable(): boolean;
+    whenReady(): Promise<void>;
+    close(): void;
+}
+/** The shared buffer between a pipe's two ends. */
+declare class PipeBuffer {
+    private chunks;
+    private queued;
+    readers: number;
+    writers: number;
+    private waiters;
+    get available(): number;
+    get space(): number;
+    push(data: Uint8Array): void;
+    take(length: number): Uint8Array;
+    /** Anything that may have changed readiness for either end. */
+    wake(): void;
+    whenReady(): Promise<void>;
+}
+declare class PipeReadEnd implements OpenFileDescription {
+    private readonly buffer;
+    flags: number;
+    readonly kind = "pipe";
+    constructor(buffer: PipeBuffer, flags: number);
+    read(length: number): Uint8Array;
+    write(): number;
+    stat(): DescriptionStat;
+    readable(): boolean;
+    writable(): boolean;
+    whenReady(): Promise<void>;
+    close(): void;
+}
+declare class PipeWriteEnd implements OpenFileDescription {
+    private readonly buffer;
+    flags: number;
+    readonly kind = "pipe";
+    constructor(buffer: PipeBuffer, flags: number);
+    read(): Uint8Array;
+    write(data: Uint8Array): number;
+    stat(): DescriptionStat;
+    readable(): boolean;
+    writable(): boolean;
+    whenReady(): Promise<void>;
+    close(): void;
+}
+declare function createPipe(flags?: number): [PipeReadEnd, PipeWriteEnd];
+/**
+ * A process's standard streams.
+ *
+ * Bytes, not text: the terminal boundary is where multi-byte characters get cut
+ * in half, so nothing here decodes. Input arrives from the host asynchronously
+ * and is queued; a blocked reader parks on {@link whenReady} rather than
+ * spinning.
+ */
+declare class StreamDescription implements OpenFileDescription {
+    flags: number;
+    private readonly sink;
+    readonly isTty: boolean;
+    readonly kind = "stream";
+    private queue;
+    private queued;
+    private ended;
+    private waiters;
+    constructor(flags: number, sink: ((data: Uint8Array) => void) | null, isTty?: boolean);
+    /** Host side: give the guest more input. */
+    push(data: Uint8Array): void;
+    /** Host side: no more input will arrive. */
+    end(): void;
+    read(length: number): Uint8Array;
+    write(data: Uint8Array): number;
+    stat(): DescriptionStat;
+    readable(): boolean;
+    writable(): boolean;
+    whenReady(): Promise<void>;
+    close(): void;
+    private wake;
+}
+/** Translate a volume error into the errno a guest expects. */
+declare function toPosixError(error: unknown): PosixError;
 
 /** Protocol version carried in every frame. */
 declare const SBX_HOST_ABI_VERSION = 1;
@@ -39,6 +262,19 @@ declare const Op: {
     readonly chdir: 1282;
     readonly environ: 1283;
     readonly getrandom: 1536;
+    readonly socket: 1792;
+    readonly bind: 1793;
+    readonly listen: 1794;
+    readonly accept: 1795;
+    readonly connect: 1796;
+    readonly send: 1797;
+    readonly recv: 1798;
+    readonly shutdown: 1799;
+    readonly getsockname: 1800;
+    readonly getpeername: 1801;
+    readonly setsockopt: 1802;
+    readonly getsockopt: 1803;
+    readonly socket_close: 1804;
 };
 type OpCode = (typeof Op)[keyof typeof Op];
 /** Canonical (Linux/musl) errno values. A negative status is `-Errno.X`. */
@@ -77,6 +313,15 @@ declare const Errno: {
     readonly ENOTEMPTY: 39;
     readonly ELOOP: 40;
     readonly ENODATA: 61;
+    readonly ENOTSOCK: 88;
+    readonly EAFNOSUPPORT: 97;
+    readonly EADDRINUSE: 98;
+    readonly EADDRNOTAVAIL: 99;
+    readonly ENETUNREACH: 101;
+    readonly ECONNRESET: 104;
+    readonly EISCONN: 106;
+    readonly ENOTCONN: 107;
+    readonly ECONNREFUSED: 111;
     readonly EPROTO: 71;
     readonly EOVERFLOW: 75;
     readonly ETIMEDOUT: 110;
@@ -226,229 +471,6 @@ declare class HostCallServer {
     private publish;
 }
 
-/**
- * Open-file descriptions: the thing a descriptor points *at*.
- *
- * POSIX has three levels and collapsing any two of them produces bugs that look
- * like something else entirely:
- *
- *  - a **pathname** is a directory entry, and may be renamed or removed;
- *  - an **inode** is the file's identity and content, and outlives its names;
- *  - an **open-file description** holds the offset and the status flags.
- *
- * `dup()` makes two descriptors share one description — so they share an offset.
- * Two separate `open()` calls on the same path make two descriptions, so their
- * offsets are independent. A file stays readable through an open description
- * after its last name is unlinked. None of that is expressible if a descriptor
- * is just a path and a number, which is why this layer exists rather than the
- * path-based {@link Vfs} calls being used directly.
- *
- * The identity used here is the volume's inode number, so a rename moves a name
- * without disturbing anything already open.
- */
-
-/** A failure carrying the errno the guest's libc should see. */
-declare class PosixError extends Error {
-    readonly errno: number;
-    constructor(errno: number, message?: string);
-}
-declare const O_RDONLY = 0;
-declare const O_WRONLY = 1;
-declare const O_RDWR = 2;
-declare const O_CREAT = 64;
-declare const O_EXCL = 128;
-declare const O_TRUNC = 512;
-declare const O_APPEND = 1024;
-declare const O_NONBLOCK = 2048;
-declare const O_DIRECTORY = 65536;
-declare const O_CLOEXEC = 524288;
-/** Access mode alone, with the flag bits masked off. */
-declare function accessMode(flags: number): number;
-interface DescriptionStat {
-    ino: number;
-    mode: number;
-    size: number;
-    uid: number;
-    gid: number;
-    nlink: number;
-    atimeMs: number;
-    mtimeMs: number;
-    ctimeMs: number;
-}
-/**
- * What every kind of open thing can do.
- *
- * `read` and `write` are permitted to move fewer bytes than asked for: that is
- * ordinary POSIX behaviour, and a guest that assumes otherwise is already
- * broken on Linux.
- */
-interface OpenFileDescription {
-    readonly kind: "file" | "dir" | "pipe" | "stream";
-    flags: number;
-    read(length: number): Uint8Array;
-    write(data: Uint8Array): number;
-    pread?(length: number, offset: number): Uint8Array;
-    pwrite?(data: Uint8Array, offset: number): number;
-    seek?(offset: number, whence: number): number;
-    stat(): DescriptionStat;
-    truncate?(length: number): void;
-    /** Ready to read now, or at end of input (which is also "ready"). */
-    readable(): boolean;
-    /** Ready to accept at least one byte. */
-    writable(): boolean;
-    /** Resolves when readiness may have changed; used only to park a poll. */
-    whenReady(): Promise<void>;
-    /** Last reference dropped. */
-    close(): void;
-}
-declare const SEEK_SET = 0;
-declare const SEEK_CUR = 1;
-declare const SEEK_END = 2;
-/**
- * The bytes behind an open regular file.
- *
- * Content lives in the volume while a name still points at it, and moves into
- * `detached` when the last name goes away with the file still open. That is the
- * only way to honour "an unlinked file stays readable until the last close" on
- * top of a path-addressed volume.
- *
- * A name removed by something that does not go through this service — the
- * shell, or the Node side — cannot be intercepted, and the description will
- * then fail with ENOENT rather than reading stale bytes. Documented in
- * docs/python/abi.md; correctness holds for everything using the host ABI.
- */
-declare class Inode {
-    readonly ino: number;
-    path: string;
-    private readonly vfs;
-    private readonly cred;
-    detached: Uint8Array | null;
-    refs: number;
-    constructor(ino: number, path: string, vfs: Vfs, cred: Cred);
-    /** Read the whole file, wherever it currently lives. */
-    contents(): Uint8Array;
-    replace(data: Uint8Array): void;
-    /** Called when the last name is about to be removed. */
-    detach(): void;
-    size(): number;
-    stat(): DescriptionStat;
-}
-/** One `open()`: an offset and status flags over an {@link Inode}. */
-declare class FileDescription implements OpenFileDescription {
-    readonly inode: Inode;
-    flags: number;
-    readonly kind = "file";
-    offset: number;
-    constructor(inode: Inode, flags: number);
-    read(length: number): Uint8Array;
-    pread(length: number, offset: number): Uint8Array;
-    write(data: Uint8Array): number;
-    pwrite(data: Uint8Array, offset: number): number;
-    private writeAt;
-    seek(offset: number, whence: number): number;
-    truncate(length: number): void;
-    stat(): DescriptionStat;
-    readable(): boolean;
-    writable(): boolean;
-    whenReady(): Promise<void>;
-    close(): void;
-}
-/** An open directory: `getdents` reads from a snapshot at the description's offset. */
-declare class DirectoryDescription implements OpenFileDescription {
-    readonly path: string;
-    flags: number;
-    private readonly vfs;
-    private readonly cred;
-    readonly kind = "dir";
-    private entries;
-    private index;
-    constructor(path: string, flags: number, vfs: Vfs, cred: Cred);
-    /** Entry names, NUL-terminated, as many as fit in `length`. */
-    read(length: number): Uint8Array;
-    write(): number;
-    seek(offset: number, whence: number): number;
-    stat(): DescriptionStat;
-    readable(): boolean;
-    writable(): boolean;
-    whenReady(): Promise<void>;
-    close(): void;
-}
-/** The shared buffer between a pipe's two ends. */
-declare class PipeBuffer {
-    private chunks;
-    private queued;
-    readers: number;
-    writers: number;
-    private waiters;
-    get available(): number;
-    get space(): number;
-    push(data: Uint8Array): void;
-    take(length: number): Uint8Array;
-    /** Anything that may have changed readiness for either end. */
-    wake(): void;
-    whenReady(): Promise<void>;
-}
-declare class PipeReadEnd implements OpenFileDescription {
-    private readonly buffer;
-    flags: number;
-    readonly kind = "pipe";
-    constructor(buffer: PipeBuffer, flags: number);
-    read(length: number): Uint8Array;
-    write(): number;
-    stat(): DescriptionStat;
-    readable(): boolean;
-    writable(): boolean;
-    whenReady(): Promise<void>;
-    close(): void;
-}
-declare class PipeWriteEnd implements OpenFileDescription {
-    private readonly buffer;
-    flags: number;
-    readonly kind = "pipe";
-    constructor(buffer: PipeBuffer, flags: number);
-    read(): Uint8Array;
-    write(data: Uint8Array): number;
-    stat(): DescriptionStat;
-    readable(): boolean;
-    writable(): boolean;
-    whenReady(): Promise<void>;
-    close(): void;
-}
-declare function createPipe(flags?: number): [PipeReadEnd, PipeWriteEnd];
-/**
- * A process's standard streams.
- *
- * Bytes, not text: the terminal boundary is where multi-byte characters get cut
- * in half, so nothing here decodes. Input arrives from the host asynchronously
- * and is queued; a blocked reader parks on {@link whenReady} rather than
- * spinning.
- */
-declare class StreamDescription implements OpenFileDescription {
-    flags: number;
-    private readonly sink;
-    readonly isTty: boolean;
-    readonly kind = "stream";
-    private queue;
-    private queued;
-    private ended;
-    private waiters;
-    constructor(flags: number, sink: ((data: Uint8Array) => void) | null, isTty?: boolean);
-    /** Host side: give the guest more input. */
-    push(data: Uint8Array): void;
-    /** Host side: no more input will arrive. */
-    end(): void;
-    read(length: number): Uint8Array;
-    write(data: Uint8Array): number;
-    stat(): DescriptionStat;
-    readable(): boolean;
-    writable(): boolean;
-    whenReady(): Promise<void>;
-    close(): void;
-    private wake;
-}
-/** Translate a volume error into the errno a guest expects. */
-declare function toPosixError(error: unknown): PosixError;
-
 /**
  * Per-process descriptor tables, and the path operations that have to know
  * about them.
@@ -539,6 +561,7 @@ interface HostAbiProcess {
     cwd: string;
     /** Aborts when the process is killed; wakes anything parked in a call. */
     readonly signal: AbortSignal;
+    readonly sockets?: VirtualTcpNetwork;
 }
 declare function createHostAbiServer(proc: HostAbiProcess): (frame: Uint8Array) => Promise<Uint8Array>;
 
@@ -629,6 +652,22 @@ declare class HostAbiClient {
     chdir(path: string): void;
     environ(): Record<string, string>;
     getrandom(length: number): Uint8Array;
+    socket(family: number, type: number, protocol?: number): number;
+    bind(fd: number, address: string, port: number): void;
+    listen(fd: number, backlog?: number): void;
+    accept(fd: number): {
+        fd: number;
+        address: string;
+        port: number;
+    };
+    connect(fd: number, address: string, port: number): void;
+    send(fd: number, data: Uint8Array): number;
+    recv(fd: number, length: number): Uint8Array;
+    shutdown(fd: number, how: number): void;
+    socketName(fd: number, peer?: boolean): {
+        address: string;
+        port: number;
+    };
 }
 interface HostStat {
     ino: number;