@ai-ecoverse/slicc-kernel 1.53.4 → 1.54.0

package/README.md

@@ -34,7 +34,7 @@ const { status, stdout, stderr } = await kernel.run(['bash', '-c', 'echo hi > he
 | `worker` | `new URL('./kernel-worker.js', import.meta.url)` | the kernel worker script |
 | `network` | none | `{ transport, uplink }`: how programs reach the outside world (see [Network](#network) and [Uplink](#uplink)) |
 | `requestDirectory` | none | `() => Promise<FileSystemDirectoryHandle>`, typically `showDirectoryPicker`: how an `fsa` mount gets its folder (see [Removable media](#removable-media-fsa)) |
-| `hostfs` | none | `(source, { readonly }) => Promise<{ url, token, capabilities? }>`: a grant for a `hostfs` mount from the local proxy (see [Host folders](#host-folders-hostfs)) |
+| `hostfs` | none | `(source, { readonly }) => Promise<{ url, token, capabilities? } \| { port, token?, capabilities? }>`: a grant for a `hostfs` mount from the local proxy, or a `MessagePort` the page serves the folder on (see [Host folders](#host-folders-hostfs)) |
 | `onMountPending` | none | `({ target, source, insert }) => void`: an `fsa` mount needs a folder; call `insert()` from a user gesture |
 | `processMounts` | `true` | whether programs may call `mount(2)` and `umount2(2)`: `false`, or `(req) => boolean \| Promise<boolean>` to decide each call (see [Mounting from a program](#mounting-from-a-program)) |
 | `hostname` | `'slicc'` | the kernel's node name (see [Node name](#node-name)) |
@@ -428,6 +428,12 @@ A `hostfs` mount is a folder exported by the local proxy ([slicc-node](https://g
 - **Changes on the host** arrive as invalidations on a watch stream (`POST /api/hostfs/watch`), so an edit made outside shows up on the next access without a remount.
 - **Proxy loss:** when the watch stream ends, or is silent for 45 s, the kernel reconnects once at once. If that fails, the mount is `nomedium`, as with [removable media](#removable-media-fsa): operations fail with `ENOMEDIUM` (`ENODEV` for WASI), and the kernel keeps reconnecting with backoff (1 s to 30 s), so the folder comes back by itself when the proxy does. A mount made while the proxy is down starts as `nomedium`, and so does one whose grant or first watch takes more than 15 s; it comes up by itself when they arrive.
 - **Consistency:** a file that changes on the host while a program reads it fails with `ESTALE`, and the kernel restarts the whole read (up to 3 times) instead of stitching two versions together. On a ranged mount an open file keeps the version it was opened at (its ETag) until it writes, also when it is handed to a child process: a page fetched after the host changed the file fails the program's read with `ESTALE` ("Stale file handle") instead of mixing versions. A file deleted on the host while a program holds it open fails the next read that goes to the host with `ENOENT`, not with NFS's `ESTALE`.
+- **Over a port:** the hook may answer `{ port, token?, capabilities? }` instead, for a folder that doesn't come from slicc-node over HTTP: for example, a linked `slicc` CLI's export, which the page reaches over its own link. The page implements a `HostfsTransport` for the folder (`capabilities`, `token`, `maxIo`, `call(op, body)`, `read(fh, offset, size, ifMatch?)`, `write(fh, offset, bytes)`, `watch(signal, onEvent, onOpen)`, with slicc-node's ops and answers) and serves it with `serveHostfsPort(port, transport)`, exported from both entries, which returns a function that stops serving and closes the port.
+  - The kernel moves the port into its worker with the grant. Calls, reads and writes are request and reply messages there, and the watch is a stream of messages that the kernel ends by aborting.
+  - Errors keep their `code`. A transport that throws `ENOTCONN` (its link is down) makes the mount `nomedium` and reconnecting, as a lost proxy does: the kernel asks the hook again, and the page answers with a new port.
+  - A port that dies doesn't hang anyone: pending requests fail with `ENOTCONN` when the port closes (its `close` event), when its watch ends or goes silent, and, on engines that don't report a closed peer, when a request gets no answer within 60 s (plus 1 s per MiB of a read or write), which fails it with `ETIMEDOUT`. After any of these the port counts as gone and is closed, files opened through it are `ESTALE`, and the next operation reconnects. `serveHostfsPort` stops serving when its port closes.
+  - A read reply sends a copy of the transport's bytes, so a transport may return a view into storage it keeps (a cache, a pooled or shared buffer).
+  - `token` names the connection (a link id, say). When the next port's token differs, files that were open become `ESTALE`. Without a token, every port is a new connection.
 - **Node:** a page's requests carry its `Origin`, and slicc-node grants a token to that origin only. Node's `fetch` sends none, so a Node embedder passes `createNodeKernel` the origin its `hostfs` hook asked for the grant with, as `hostfsOrigin`, and the kernel adds it to every hostfs request. Without it the mount stays `nomedium`. `hostfsFetch(url, init)` replaces the `fetch` those requests use (for an agent or a test proxy), and gets the `Origin` too when both are given.
 
 ### Mounting from a program

package/dist/index.js

@@ -1632,6 +1632,79 @@ function localProxyTransport(options) {
   };
 }
 
+// src/mount/driver.ts
+function fsError(code, message = code) {
+  return Object.assign(new Error(message), { code });
+}
+
+// src/mount/hostfs.ts
+var HOSTFS_IO = 16 * 1024 * 1024;
+var codeOf = (err) => err?.code;
+var errorOf = (err) => ({
+  code: typeof codeOf(err) === "string" ? codeOf(err) : "EIO",
+  message: err?.message ?? String(err)
+});
+function serveHostfsPort(port, transport) {
+  const watches = /* @__PURE__ */ new Map();
+  const send2 = (reply, transfer = []) => port.postMessage(reply, transfer);
+  const listener = async ({
+    data
+  }) => {
+    const { id, op } = data;
+    if (op === "unwatch") return watches.get(id)?.abort();
+    if (op === "watch") {
+      const stop2 = new AbortController();
+      watches.set(id, stop2);
+      try {
+        await transport.watch(
+          stop2.signal,
+          (event) => send2({ id, event }),
+          () => send2({ id, open: true })
+        );
+        send2({ id, end: true });
+      } catch (err) {
+        send2({ id, error: errorOf(err) });
+      } finally {
+        watches.delete(id);
+      }
+      return;
+    }
+    try {
+      if (op === "read") {
+        const read = await transport.read(
+          data.fh,
+          data.offset,
+          data.size,
+          data.ifMatch
+        );
+        const bytes = read.slice();
+        return send2({ id, bytes }, [bytes.buffer]);
+      }
+      if (op === "write") {
+        await transport.write(data.fh, data.offset, data.bytes);
+        return send2({ id });
+      }
+      if (op !== "call") throw fsError("EINVAL", `unknown hostfs port op ${op}`);
+      send2({
+        id,
+        result: await transport.call(data.name, data.body)
+      });
+    } catch (err) {
+      send2({ id, error: errorOf(err) });
+    }
+  };
+  const stop = () => {
+    port.removeEventListener("message", listener);
+    port.removeEventListener("close", stop);
+    for (const watch of watches.values()) watch.abort();
+    port.close();
+  };
+  port.addEventListener("message", listener);
+  port.addEventListener("close", stop);
+  port.start();
+  return stop;
+}
+
 // src/index.ts
 var ISOLATION = "slicc-kernel needs a cross-origin isolated page (Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp or credentialless)";
 function streamer(callback) {
@@ -1746,7 +1819,7 @@ async function createKernel(options = {}) {
     try {
       if (!options.hostfs) throw new Error("this page gives no host folders");
       const grant = await options.hostfs(source, { readonly });
-      worker.postMessage({ hostfsGrant: { id, grant } });
+      worker.postMessage({ hostfsGrant: { id, grant } }, "port" in grant ? [grant.port] : []);
     } catch (err) {
       worker.postMessage({ hostfsGrant: { id, error: err.message ?? String(err) } });
     }
@@ -1875,6 +1948,7 @@ export {
   createKernel,
   fetchTransport,
   localProxyTransport,
-  probeLocalProxy
+  probeLocalProxy,
+  serveHostfsPort
 };
 //# sourceMappingURL=index.js.map