kern-sandbox 0.2.29 → 0.2.31

package/README.md

@@ -73,6 +73,11 @@ cargo install --git https://github.com/getkern/kern getkern --locked
 kern needs a Linux kernel with unprivileged user namespaces + cgroup v2. On Windows it runs under WSL2.
 Node 18+.
 
+The first call on a machine that has never run it is the slow one: it pulls `python:3.12-slim` before
+it can start a box. Every call after that reads the cached image, and the `startup_failed` row below
+has the measured cost of that first read, which on a slow machine is large enough to trip a short
+`timeoutS`.
+
 **On a Mac this package installs but cannot run**, and it says so rather than sending you after a
 download that does not exist: kern is Linux-only, because macOS has no namespaces and no cgroups. Run
 inside a Linux VM (colima, Lima, OrbStack, UTM), install `kern` and this package there, and it behaves
@@ -259,6 +264,28 @@ or Redis connection under `egressAllow` cannot resolve its host. For a database,
 `SandboxError`, so a caller can tell "this sandbox will not do that" from "the sandbox broke".
 `DEFAULT_TMPFS_MB` and `version` are exported for callers that assert on them.
 
+## The image decides more than the runtime does
+
+`run_code` that imports two standard-library modules measures **46.8 ms** on the default
+`python:3.12-slim`, against 13.8 ms for one that imports nothing. That tag ships 164 `.py` files in
+the standard library and 9 `.pyc`, so every import compiles its source. Precompiling the bytecode is
+one line and is worth **29 ms**, which is more than the box, the interpreter start and every runtime
+flag combined:
+
+```dockerfile
+FROM python:3.12-slim
+RUN python3 -m compileall -q -j 0 /usr/local/lib/python3.12
+```
+
+| `run_code` | `python:3.12-slim` | precompiled |
+|---|---:|---:|
+| `print(1)` | 13.82 ms | 12.27 ms |
+| `import json,re` | **46.82 ms** | **17.66 ms** |
+
+Build it once and pass it: `run_code(..., image="my-python")`. The default stays the stock tag,
+because an SDK that silently required a custom image would be worse than one that costs 29 ms and
+says so. Measured on an Intel i7-14700KF, Linux 7.0.0, idle; [BENCHMARKS.md](https://github.com/getkern/kern/blob/main/BENCHMARKS.md) has the method.
+
 ## Prewarming: a box ready before the call arrives
 
 `prewarm: N` keeps N boxes started in advance, each holding a booted interpreter that has run nothing,

package/index.js

@@ -36,7 +36,7 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.2.29";
+const VERSION = "0.2.31";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -1418,6 +1418,46 @@ class Sandbox {
     if (!(this.timeoutS > 0)) throw new SandboxError("timeoutS must be a positive number of seconds");
     if (!(this.maxOutputBytes > 0)) throw new SandboxError("maxOutputBytes must be positive");
 
+    // SHAPE GUARDS BEFORE ANYTHING CONSUMES THESE, the twin of the Python binding's and added after
+    // the same outside review swept the constructor argument by argument.
+    //
+    // THE JS FAILURE IS WORSE THAN THE PYTHON ONE, which is why this is not just symmetry. Python
+    // raises `AttributeError: 'list' object has no attribute 'items'` - useless, but obviously a
+    // type error. `Object.entries()` does NOT throw on an array or a string: it hands back index
+    // keys. MEASURED, `mounts: ["/tmp:/x"]` reached the mount validator as source `"0"` and reported
+    // `mount source must be an absolute host path, got "0"`, naming a value the caller never wrote,
+    // and `mounts: "/tmp:/x"` walked the string character by character and reported `cannot mount
+    // over the box essential mount "/"`. Both refuse, so nothing unsafe happened; both send the
+    // reader to look at a "0" or a "/" that exists nowhere in their code.
+    //
+    // `tmpfs` is deliberately NOT here: it documents an array form (a list of paths) and already
+    // refuses a bare string by name.
+    for (const [name, value] of [
+      ["mounts", this.mounts],
+      ["env", this.env],
+    ]) {
+      if (value === null || value === undefined) continue;
+      if (typeof value !== "object" || Array.isArray(value)) {
+        const example = name === "env" ? `{ KEY: "value" }` : `{ "/host/path": "/in/box" }`;
+        throw new SandboxError(
+          `${name} must be a plain object, not ${Array.isArray(value) ? "an array" : typeof value}: ` +
+            `write ${name}: ${example}`,
+        );
+      }
+    }
+    // A CALLBACK THAT IS NOT A FUNCTION is never called and says nothing, so the caller sees a
+    // sandbox that produces no output and has nothing to debug.
+    for (const [name, cb] of [
+      ["onStdout", this.onStdout],
+      ["onStderr", this.onStderr],
+    ]) {
+      if (cb !== null && cb !== undefined && typeof cb !== "function") {
+        throw new SandboxError(
+          `${name} must be a function (it is handed one chunk at a time), not ${typeof cb}`,
+        );
+      }
+    }
+
     this._mountArgs = [];
     const boundTargets = new Set();
     if (this.mounts) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kern-sandbox",
-  "version": "0.2.29",
-  "description": "kern is a fast, rootless sandbox and virtual resource runtime for any workload, including untrusted and LLM-generated code; kern-sandbox is its Node/TypeScript binding. Run untrusted or agent-generated code (Python/JS/Bash) in a real, kernel-enforced box, one per call, with no cloud, no account and no VM.",
+  "version": "0.2.31",
+  "description": "kern is a fast, rootless sandbox and virtual resource runtime; kern-sandbox is its Node/TypeScript binding. Run semi-trusted or agent-generated code (Python/JS/Bash) in a real, kernel-enforced box, one per call, with no cloud, no account and no VM. A kernel boundary, not a microVM: for deliberately hostile multi-tenant code, use one.",
   "keywords": [
     "sandbox",
     "kern",