@ai-ecoverse/slicc-kernel 1.68.0 → 1.70.0

package/README.md

@@ -250,10 +250,11 @@ The module's default export (or its `main` export) is called with a context and
 - `fdStatus(fd)` (`{ type, tty, seekable }`, `type` being `file`, `pipe`, `tty`, `socket`, `device` or `directory`) and `isatty(fd)`, to tell `< file` from a pipe;
 - `open(path, { read, write, append, create, exclusive, truncate })`, which returns a file with `read(position, length)`, `write(position, bytes)`, `size()`, `truncate(size)`, `sync()` and `close()`. Reads and writes go through the kernel's paged files at those positions, so a large file is never read whole;
 - `fs`: `stat`, `lstat`, `exists`, `readdir`, `mkdir` (with parents), `rm` (recursive), `unlink`, `rename`, `symlink`, `readlink`, and `readFile`/`writeFile` for small files;
+- `/dev`, in `open`, `fs` and their `sync` forms, as a WASI or Emscripten program sees it, with the same modes and owners as under `users`: `null`, `zero`, `full`, `random`, `urandom` and `tty` (character devices, `0666`, root's), `stdin`, `stdout` and `stderr` (links to `/proc/self/fd/0`, `1`, `2`), `fd` (a link to `/proc/self/fd`, so `/dev/fd/N` is descriptor N) and the kernel's terminals `/dev/ttyN` and `/dev/pts/N` (with users on, owned by the session's user or the master's opener, `0620`). `/dev/shm` and `/dev/ptmx` aren't there. `stat` through `/dev/stdin`, `/dev/stdout` or `/dev/fd/N` describes the program's own descriptor (the file it is redirected to, a pipe, a terminal), `readlink` of `/dev/fd/N` names it (`pipe:[N]` and `socket:[N]` for a pipe or a socket), and a closed descriptor is `ENOENT`. Opening a device gives a kernel descriptor on it; opening `/dev/std*` or `/dev/fd/N` opens the file again with the flags asked for when the descriptor is on a file (as Linux reopens `/proc/self/fd/N`, so `append` appends and `truncate` truncates), and otherwise duplicates the descriptor; `/dev/tty` is the program's controlling terminal (`ENXIO` without one); and `/dev/ttyN` and `/dev/pts/N` are opened by name through the kernel, so a terminal that isn't the user's is `EACCES` under `enforce`. A file on anything but a regular file reads and writes as a stream (the position is ignored) and only in the directions it was opened for (`EBADF` otherwise), its `size()` is 0 and `truncate` is `EINVAL`. `readFile` reads a device or a descriptor to its end, up to 64 MiB, and fails with `EFBIG` past that (where Node's `readFile` throws `ERR_FS_FILE_TOO_LARGE`), so `readFile('/dev/zero')` fails instead of hanging, while a bounded `read` of it works. Other paths pay only a prefix check: they make the same kernel calls as before. Creating, removing or renaming names in `/dev` goes to the root file system as before;
 - `signals`: `on(signal, handler)` catches a signal (by number or as `'SIGINT'`), `ignore(signal)` ignores it and `reset(signal)` restores its default action. A call blocked in a read or write is restarted after a handler runs; signals without a handler keep their default actions, so an uncaught `SIGINT` ends the program with 130 and `SIGKILL` always does;
 - `sync`: `read`, `write`, `close`, `open` (whose files' methods are synchronous too) and `fs`, made synchronously, for code that cannot `await`, such as a compiled program's file system or a `readFileSync`. A synchronous call holds the worker until the kernel answers, so nothing else of the program runs meanwhile, timers and callbacks included; a signal that arrives during a blocked read or write runs its handler, and the call is then restarted. Descriptors are shared with the rest of the context, so a file opened with `sync.open` can be closed with `close`, and the other way around; `sync.run` and `sync.exit` are described next;
 - `sync.run({ argv, env, cwd, input, stdin, stdout, stderr, maxBuffer, timeout, killSignal })` runs a command to its end and answers `{ pid, status, signal, stdout, stderr, error }`, as Node's `spawnSync` does. It suits `execSync`, `spawnSync` and `execFileSync`. The kernel does the whole run while the program's worker waits; other processes go on.
-  - Each stdio is `'pipe'` (the default), `'ignore'` or `'inherit'` (the program's own, a terminal included). With `'pipe'`, stdin gets `input` (bytes, or a string as UTF-8) and then its end, so `cat` stops; `stdout` and `stderr` come back as bytes and are absent for the other choices. Both are drained while the child runs, so a child that writes more than a pipe holds never stalls.
+  - Each stdio is `'pipe'` (the default), `'ignore'`, `'inherit'` (the program's own, a terminal included), or one of the program's descriptors by number, which the child gets as it is (two slots on one descriptor share it, so their writes keep their order). `stderr: 'stdout'` sends stderr to whatever stdout is, the stdout capture included, in the order the child writes. With `'pipe'`, stdin gets `input` (bytes, or a string as UTF-8) and then its end, so `cat` stops; `stdout` and `stderr` come back as bytes and are absent for the other choices. Both are drained while the child runs, so a child that writes more than a pipe holds never stalls. As in Node, the call returns once the child has exited and every captured stream has reached its end, so output a background grandchild writes later is still collected; `timeout` bounds that wait too. Once the outcome is decided (the end of output, an overflow or a timeout), the captured streams are closed, so a writer still left on them gets `EPIPE` (and `SIGPIPE`) instead of running on.
   - `status` is the exit status, or `null` with `signal` set when a signal ended the child. A non-zero status is not an error. A command that cannot start (it does not exist, or is not executable) answers `error: { code: 'ENOENT' }` (or the errno), `status: null` and `pid: 0` instead of throwing.
   - More than `maxBuffer` bytes on `stdout` or `stderr` (1 MiB by default) sends the child `killSignal` (`SIGTERM` by default), keeps the first `maxBuffer` bytes, and answers `error: { code: 'ENOBUFS' }`. The kernel keeps at most 64 MiB of each stream whatever `maxBuffer` says, `Infinity` included, since the buffers live in the kernel worker that all processes share. `timeout` (ms) sends `killSignal` when it runs out and answers `error: { code: 'ETIMEDOUT' }`. A child that ignores `killSignal` is still waited for, as in Node.
   - The child is in the program's process group, so `^C` reaches it. The kernel reaps it, so it leaves no zombie, and its CPU time counts as the program's children's. A signal the program catches does not cut the run short; its handler runs when the call returns. A signal that kills the program kills it as usual;

package/dist/kernel-worker.js

@@ -1991,6 +1991,16 @@ function written(device, bytes) {
   if (device === "full" && bytes.length > 0) throw new KernelError("ENOSPC");
   return bytes.length;
 }
+var DEVICE_PATHS = /* @__PURE__ */ new Map([
+  ["/dev/null", "null"],
+  ["/dev/zero", "zero"],
+  ["/dev/full", "full"],
+  ["/dev/urandom", "urandom"],
+  ["/dev/random", "urandom"]
+]);
+function deviceAt(path) {
+  return DEVICE_PATHS.get(path);
+}
 function deviceFile(device, access2) {
   const read = async (max) => {
     if (device === "null") return new Uint8Array(0);
@@ -6950,6 +6960,18 @@ function capturing(chunks, max = Number.POSITIVE_INFINITY, overflow) {
     size += bytes.length;
   };
 }
+function captureFile(onData, control) {
+  if (!control) return sinkFile(onData);
+  control.opened = true;
+  return new OpenFile({
+    write: async (bytes) => {
+      if (control.shut) throw new KernelError("EPIPE");
+      onData(bytes.slice());
+      return bytes.length;
+    },
+    close: () => control.ended()
+  });
+}
 function concat3(chunks) {
   const out = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
   let offset = 0;
@@ -6984,7 +7006,12 @@ var ChildTable = class {
     const fds = new FdTable();
     const captured = /* @__PURE__ */ new Map();
     try {
-      for (const [n, slot2] of stdio.entries()) fds.installAt(n, this.openSlot(slot2, n, captured));
+      for (const [n, slot2] of stdio.entries()) {
+        fds.installAt(
+          n,
+          "sameAs" in slot2 ? fds.get(slot2.sameAs).retain() : this.openSlot(slot2, n, captured)
+        );
+      }
       for (const slot2 of inherit2) {
         if (slot2.fd <= 2) continue;
         if ("device" in slot2) {
@@ -7041,7 +7068,7 @@ var ChildTable = class {
     if ("capture" in slot2) {
       const chunks = [];
       captured.set(n, chunks);
-      return sinkFile(capturing(chunks, slot2.max, slot2.overflow));
+      return captureFile(capturing(chunks, slot2.max, slot2.overflow), slot2.control);
     }
     return deviceFile("null");
   }
@@ -10548,9 +10575,11 @@ function capLimit(maxBuffer) {
   return Math.min(asked, RUN_CAPTURE_CAP);
 }
 function slot(how, n, extra) {
+  if (how === "stdout") return { sameAs: 1 };
+  if (typeof how === "number") return { fd: how };
   if (how === "inherit") return { fd: n };
   if (how === "ignore") return { none: true };
-  return extra;
+  return extra();
 }
 function frame2(outcome, out, err) {
   const head = new TextEncoder().encode(JSON.stringify(outcome));
@@ -10580,12 +10609,20 @@ async function runChild(req, deps) {
     if (failure2 !== void 0) return;
     failure2 = code;
     if (pid !== 0) kill();
+    decided.resolve();
+  };
+  const controls = [];
+  const capture = () => {
+    const { promise, resolve } = Promise.withResolvers();
+    const control = { shut: false, ended: resolve, eof: promise };
+    controls.push(control);
+    return { capture: true, max, overflow: () => stop("ENOBUFS"), control };
   };
-  const capture = () => ({ capture: true, max, overflow: () => stop("ENOBUFS") });
+  const decided = Promise.withResolvers();
   const stdio = [
-    slot(req.stdin, 0, { input: req.input ?? new Uint8Array(0) }),
-    slot(req.stdout, 1, capture()),
-    slot(req.stderr, 2, capture())
+    slot(req.stdin, 0, () => ({ input: req.input ?? new Uint8Array(0) })),
+    slot(req.stdout, 1, capture),
+    slot(req.stderr, 2, capture)
   ];
   try {
     pid = await deps.children.spawn(
@@ -10602,8 +10639,11 @@ async function runChild(req, deps) {
   let status;
   try {
     status = await reaped(deps, pid);
+    const open = controls.filter((c) => c.opened);
+    await Promise.race([Promise.all(open.map((c) => c.eof)), decided.promise]);
   } finally {
     clearTimeout(timer);
+    for (const control of controls) control.shut = true;
   }
   const out = deps.children.captured(pid, 1);
   const err = deps.children.captured(pid, 2);
@@ -11701,6 +11741,8 @@ var WasmProcess = class {
   }
   async openVfs(req) {
     if (inProc(req.path)) return this.openProc(req, req.path);
+    const device = req.orphan ? void 0 : deviceAt(req.path);
+    if (device) return this.openDevice(req, device);
     const alias = req.orphan ? void 0 : await procAlias(this.options.fs, req.path, !req.exclusive);
     if (typeof alias === "object")
       throw Object.assign(new Error(alias.refused), { code: alias.refused });
@@ -11738,6 +11780,14 @@ var WasmProcess = class {
     }
     return fd;
   }
+  openDevice(req, device) {
+    if (req.exclusive) throw Object.assign(new Error(req.path), { code: "EEXIST" });
+    const access2 = req.flags & WRITE_ACCESS;
+    return this.fds.install(
+      deviceFile(device, access2 === 0 ? "read" : access2 === 1 ? "write" : void 0),
+      3
+    );
+  }
   async identified(stat, known) {
     const first = await stat();
     if (first.orphan) return first;