@ai-ecoverse/slicc-kernel 1.56.0 → 1.56.1

package/README.md

@@ -433,7 +433,7 @@ A `hostfs` mount is a folder exported by the local proxy ([slicc-node](https://g
   - 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. Chrome reports no `close` when the peer of a `MessagePort` goes away, so while anything is outstanding (the watch always is), the kernel pings the port every second and `serveHostfsPort` answers at once. No answer within 10 s makes the port gone (a page busy for a few seconds, with a dialog open or paused in devtools, is still alive): pending requests fail with `ENOTCONN`, the mount is `nomedium`, and the kernel asks the hook for a new port. A port whose server never answered a ping (an older `serveHostfsPort`) isn't judged by pings. Pending requests also fail when the port's `close` event fires (Node has it), when its watch ends or goes silent, and, as a last resort, after 60 s without an answer (plus 1 s per MiB of a read or write), with `ETIMEDOUT`. A gone port is closed, and `serveHostfsPort` stops serving when its port closes. A watch started with an already aborted signal also counts the port as gone.
-  - **Hanging folders:** every request to a `hostfs` folder, over a port or over HTTP, gets 20 s: each call, and each read or write of up to `maxIo` bytes. The mount tells the kernel the folder's own `maxIo` (at most 16 MiB), so one file operation never puts more than that on the folder at once. One that takes longer fails with `ENOTCONN`, so the mount goes `nomedium` and reconnects by itself, instead of the driver watchdog (30 s) marking the mount `failed` until a remount. The timeout also retires that connection: its requests in flight are aborted (HTTP) or failed (a port), nothing more is sent on it, its open files are `ESTALE`, and a file whose open answers late is released on the folder. Over a port, the kernel keeps the port for another second for cleanup (a temporary write permission it added to open a read-only file is put back), then tells `serveHostfsPort` it is going (`bye`, which Chrome can't signal by itself). The server then releases every file it opened through that port, including one whose open lands later. A request the host already received may still finish there: an operation that timed out may have happened, so check before retrying it (a retried `mkdir` or create can fail with `EEXIST`, a retried `rename` or `unlink` with `ENOENT`). The kernel itself retries only reads and whole-file rewrites after `ESTALE`, never an exclusive create.
+  - **Hanging folders:** every request to a `hostfs` folder, over a port or over HTTP, gets 20 s: each call, and each read or write of up to `maxIo` bytes. The mount tells the kernel the folder's own `maxIo` (at most 16 MiB), so one file operation never puts more than that on the folder at once. One that takes longer fails with `ENOTCONN`, so the mount goes `nomedium` and reconnects by itself, instead of the driver watchdog (30 s) marking the mount `failed` until a remount. The timeout also retires that connection: its requests in flight are aborted (HTTP) or failed (a port), nothing more is sent on it, its open files are `ESTALE`, and a file whose open answers late is released on the folder. Over a port, the kernel keeps the port for another second for cleanup (a temporary write permission it added to open a read-only file is put back; over HTTP, where a request can still be running on the host after the restore, 30 s later the kernel checks it once more, and if a late chmod still left the same file (same inode, or same size and mtime) with just that bit added, it puts the mode back again), then tells `serveHostfsPort` it is going (`bye`, which Chrome can't signal by itself). The server then releases every file it opened through that port, including one whose open lands later. A request the host already received may still finish there: an operation that timed out may have happened, so check before retrying it (a retried `mkdir` or create can fail with `EEXIST`, a retried `rename` or `unlink` with `ENOENT`). The kernel itself retries only reads and whole-file rewrites after `ESTALE`, never an exclusive create.
   - 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); without one, every port gets its own name. It doesn't decide whether open files survive a reconnect: a file a program holds open is opened again by path on the new connection, with the ETag it had (`ifMatch`). It goes on if the file is unchanged on the host, and fails with `ESTALE` if the host changed it meanwhile. Files opened through a port that is gone are `ESTALE` until they are opened again.
 - **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.