sandboxedjs 0.1.7 → 0.1.8

package/dist/index.d.cts

@@ -613,6 +613,58 @@ interface ContextInit {
 }
 declare function createContext(init: ContextInit): ExecContext;
 
+/**
+ * Executable format handlers — the container's `binfmt_misc`.
+ *
+ * The kernel knows how to dispatch two things by itself: a built-in command,
+ * and a text file with a `#!` line. Everything else is a binary, and the kernel
+ * deliberately knows nothing about what any particular binary is. Instead it
+ * sniffs the first bytes of the file and asks this registry who can run it.
+ *
+ * That indirection is the whole point. A format handler is registered at boot
+ * like a driver, so support for a new kind of executable is a handler, never a
+ * special case in `dispatch` and never a list of blessed program names. When a
+ * user drops a `wasm32-wasi` build of `jq` into `/usr/local/bin` and marks it
+ * executable, it runs — not because anything here has heard of `jq`, but
+ * because something here has heard of WebAssembly.
+ *
+ * A handler with no `run` is still worth registering: recognising an ELF binary
+ * well enough to say "this is an x86-64 Linux executable and nothing in this
+ * container can execute it" is far more use than `Exec format error`.
+ */
+
+interface ExecFormat {
+    /** Short identifier, e.g. `wasi`. Shown by `file` and in diagnostics. */
+    readonly name: string;
+    /**
+     * Handlers are consulted in ascending priority, so a specific format can be
+     * tested before a broader one. Defaults to 50.
+     */
+    readonly priority?: number;
+    /** True when `head` is this format. Must not throw. */
+    matches(head: Uint8Array, path: string): boolean;
+    /** Human-readable description for `file`. */
+    describe?(head: Uint8Array, path: string): string;
+    /**
+     * Execute the file. `ctx.args` holds the arguments, exactly as for a
+     * built-in. Omit to register a format that is recognised but not runnable.
+     */
+    run?(ctx: ExecContext, path: string): Promise<number> | number;
+    /**
+     * Lines explaining why the format cannot run here, printed in place of
+     * `Exec format error`. Only consulted when `run` is absent.
+     */
+    explain?(head: Uint8Array, path: string): string[];
+}
+declare class ExecFormatRegistry {
+    private readonly formats;
+    register(format: ExecFormat): void;
+    registerAll(formats: ExecFormat[]): void;
+    /** The handler claiming `head`, or null when the bytes match nothing. */
+    match(head: Uint8Array, path: string): ExecFormat | null;
+    list(): ExecFormat[];
+}
+
 /**
  * The container's network stack.
  *
@@ -738,7 +790,7 @@ interface RunResult {
     signal: string | null;
     timedOut: boolean;
 }
-type ExecutableKind = "builtin" | "script" | "unknown";
+type ExecutableKind = "builtin" | "script" | "binary" | "unknown";
 interface ResolvedExecutable {
     kind: ExecutableKind;
     /** Absolute path of the file that was found. */
@@ -747,6 +799,10 @@ interface ResolvedExecutable {
     command?: Command;
     /** Interpreter argv from a `#!` line, when `kind === "script"`. */
     interpreter?: string[];
+    /** The registered handler for the file's magic, when `kind === "binary"`. */
+    format?: ExecFormat;
+    /** The bytes the format was identified from, for diagnostics. */
+    head?: Uint8Array;
 }
 interface MountEntry {
     device: string;
@@ -759,6 +815,8 @@ declare class Kernel {
     readonly vfs: Vfs;
     readonly procs: ProcessTable;
     readonly commands: CommandRegistry;
+    /** Handlers for executable files that are neither built-ins nor scripts. */
+    readonly formats: ExecFormatRegistry;
     readonly users: UserDatabase;
     readonly pod: Nodepod;
     readonly bootTime: number;

package/dist/index.d.ts

@@ -613,6 +613,58 @@ interface ContextInit {
 }
 declare function createContext(init: ContextInit): ExecContext;
 
+/**
+ * Executable format handlers — the container's `binfmt_misc`.
+ *
+ * The kernel knows how to dispatch two things by itself: a built-in command,
+ * and a text file with a `#!` line. Everything else is a binary, and the kernel
+ * deliberately knows nothing about what any particular binary is. Instead it
+ * sniffs the first bytes of the file and asks this registry who can run it.
+ *
+ * That indirection is the whole point. A format handler is registered at boot
+ * like a driver, so support for a new kind of executable is a handler, never a
+ * special case in `dispatch` and never a list of blessed program names. When a
+ * user drops a `wasm32-wasi` build of `jq` into `/usr/local/bin` and marks it
+ * executable, it runs — not because anything here has heard of `jq`, but
+ * because something here has heard of WebAssembly.
+ *
+ * A handler with no `run` is still worth registering: recognising an ELF binary
+ * well enough to say "this is an x86-64 Linux executable and nothing in this
+ * container can execute it" is far more use than `Exec format error`.
+ */
+
+interface ExecFormat {
+    /** Short identifier, e.g. `wasi`. Shown by `file` and in diagnostics. */
+    readonly name: string;
+    /**
+     * Handlers are consulted in ascending priority, so a specific format can be
+     * tested before a broader one. Defaults to 50.
+     */
+    readonly priority?: number;
+    /** True when `head` is this format. Must not throw. */
+    matches(head: Uint8Array, path: string): boolean;
+    /** Human-readable description for `file`. */
+    describe?(head: Uint8Array, path: string): string;
+    /**
+     * Execute the file. `ctx.args` holds the arguments, exactly as for a
+     * built-in. Omit to register a format that is recognised but not runnable.
+     */
+    run?(ctx: ExecContext, path: string): Promise<number> | number;
+    /**
+     * Lines explaining why the format cannot run here, printed in place of
+     * `Exec format error`. Only consulted when `run` is absent.
+     */
+    explain?(head: Uint8Array, path: string): string[];
+}
+declare class ExecFormatRegistry {
+    private readonly formats;
+    register(format: ExecFormat): void;
+    registerAll(formats: ExecFormat[]): void;
+    /** The handler claiming `head`, or null when the bytes match nothing. */
+    match(head: Uint8Array, path: string): ExecFormat | null;
+    list(): ExecFormat[];
+}
+
 /**
  * The container's network stack.
  *
@@ -738,7 +790,7 @@ interface RunResult {
     signal: string | null;
     timedOut: boolean;
 }
-type ExecutableKind = "builtin" | "script" | "unknown";
+type ExecutableKind = "builtin" | "script" | "binary" | "unknown";
 interface ResolvedExecutable {
     kind: ExecutableKind;
     /** Absolute path of the file that was found. */
@@ -747,6 +799,10 @@ interface ResolvedExecutable {
     command?: Command;
     /** Interpreter argv from a `#!` line, when `kind === "script"`. */
     interpreter?: string[];
+    /** The registered handler for the file's magic, when `kind === "binary"`. */
+    format?: ExecFormat;
+    /** The bytes the format was identified from, for diagnostics. */
+    head?: Uint8Array;
 }
 interface MountEntry {
     device: string;
@@ -759,6 +815,8 @@ declare class Kernel {
     readonly vfs: Vfs;
     readonly procs: ProcessTable;
     readonly commands: CommandRegistry;
+    /** Handlers for executable files that are neither built-ins nor scripts. */
+    readonly formats: ExecFormatRegistry;
     readonly users: UserDatabase;
     readonly pod: Nodepod;
     readonly bootTime: number;