@ai-ecoverse/slicc-serve 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +100 -12
  2. package/bin/serve.wasm +0 -0
  3. package/package.json +7 -7
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  `scserve` publishes a directory, or a server that already runs on this machine, at a public capability URL on `sliccy.now`, through the SLICC tray hub. It is slicc 6's `serve` for any host: `scserve ./dist` prints `https://<label>.sliccy.now/` and returns, and anyone with the URL sees the files, pulled from this machine on demand while it is online. `scserve --port 5173` does the same for vite, `python -m http.server` or any other local server, and `scserve --ttl 7d ./dist` uploads an immutable snapshot that stays up without this machine.
4
4
 
5
- In SLICC the same program is `serve` and `scserve` (`bin/serve.wasm`). There it serves a directory on the kernel's loopback with `--local` today; publishing from SLICC goes through seven's page and comes later (see [In SLICC](#in-slicc)).
5
+ In SLICC the same program is `serve` and `scserve` (`bin/serve.wasm`). There it serves the directory on the kernel's loopback, and seven's page, which already leads a tray on the same hub, publishes it: `serve` asks the page over `/dev/embedder` (see [In SLICC](#in-slicc)).
6
6
 
7
7
  This README is the spec. The plan is [#1](https://github.com/ai-ecoverse/slicc-serve/issues/1).
8
8
 
@@ -34,7 +34,7 @@ Binaries: macOS (arm64, x86-64, signed and notarized), Linux (arm64, x86-64, sta
34
34
  scserve [--entry FILE] [--ttl DURATION] [--local] [--foreground] [--open] [--json] DIRECTORY
35
35
  scserve --port PORT [--entry PATH] [--local] [--foreground] [--open] [--json]
36
36
  scserve --list [--json]
37
- scserve --stop TOKEN|URL [--json]
37
+ scserve --stop TOKEN|URL|PORT [--json]
38
38
  scserve --version | --upgrade | --help
39
39
  ```
40
40
 
@@ -49,7 +49,7 @@ scserve --version | --upgrade | --help
49
49
  | `--open` | opens the URL with the platform's opener once it is published (and a sign-in page, see [The tray hub](#the-tray-hub)) |
50
50
  | `--json` | prints the result, or the error, as one JSON object (an array for `--list`) |
51
51
  | `--list` | lists the previews this machine published |
52
- | `--stop TOKEN\|URL` | stops a preview, by its token, its public URL or its local URL |
52
+ | `--stop TOKEN\|URL\|PORT` | stops a preview, by its token, its public URL, its local URL or its local port |
53
53
  | `--version` | prints the version alone (`1.2.0`) |
54
54
  | `--upgrade` | see [`--upgrade`](#--upgrade) |
55
55
  | `-h`, `--help` | prints the usage and the options to stdout and exits 0, wherever it appears among the options |
@@ -122,7 +122,7 @@ The hub sends `preview.request {reqId, servedRoot, vfsPath, asText, range?}`; th
122
122
 
123
123
  `--list` asks the hub for the previews of this machine's tray (and of [retired trays](#state) that still hold snapshots), joins them with the local records, and prints `TOKEN MODE EXPIRES URL ROOT`: `live`, `snapshot`, `uploading` or `local`, `(foreground)` for an attached one. Records whose relay is gone, snapshots past their expiry and previews the hub no longer has are dropped. `no previews` when there are none.
124
124
 
125
- `--stop` takes a preview token, a public URL (its host encodes the token, as slicc 6's `previewTokenFromUrl` reads it), a local URL or a record id. A hub preview is stopped with the tray that minted it (`POST /api/tray/<trayId>/preview/stop`); the relay then gets `preview.revoked` and stops its server. A local preview is stopped through the relay. It prints `stopped <token or URL>`; `scserve: no preview matches X`, `scserve: <token> is not a preview of this machine's trays` and `scserve: the tray hub has no preview <token> (already stopped or expired)` exit 1.
125
+ `--stop` takes a preview token, a public URL (its host encodes the token, as slicc 6's `previewTokenFromUrl` reads it), a local URL, a port or a record id. A local URL matches by its port when its host is a loopback name (`127.0.0.1`, any `127.x.y.z`, `localhost`, `*.localhost`), so `http://localhost:61489/` and `61489` both stop the preview served on `127.0.0.1:61489`; a port matches a preview's static server or the server a `--port` preview publishes. When several previews match, it stops none and exits 1 with `scserve: X matches N previews; stop one by its token`. A hub preview is stopped with the tray that minted it (`POST /api/tray/<trayId>/preview/stop`); the relay then gets `preview.revoked` and stops its server. A local preview is stopped through the relay. It prints `stopped <token or URL>`; `scserve: no preview matches X`, `scserve: <token> is not a preview of this machine's trays` and `scserve: the tray hub has no preview <token> (already stopped or expired)` exit 1.
126
126
 
127
127
  ## The tray hub
128
128
 
@@ -180,15 +180,103 @@ A `scserve` from the installers downloads the latest `install.sh` (`install.ps1`
180
180
 
181
181
  ## In SLICC
182
182
 
183
- `serve.wasm` is built from the same crates for `wasm32-wasip1`, with `serve-core` (arguments, the static server, the snapshot walker, the records) shared with the host build and `wasix-net`'s sockets on the kernel's loopback. The kernel runs it as `serve` or `scserve`, and it names itself after the command it runs as.
183
+ `serve.wasm` is built from the same crates for `wasm32-wasip1-threads`, with `serve-core` (arguments, the static server, the records) shared with the host build and `wasix-net`'s sockets on the kernel's loopback. The kernel runs it as `serve` or `scserve`, and it names itself after the command it runs as. The package's `engines` asks for `slicc-kernel >=1.153.0` (the kernel with `/dev/embedder`), so an older kernel refuses to install its commands; one without the device anyway prints `serve: /dev/embedder not available (needs slicc-kernel >= 1.153.0)` and exits 1 for everything that needs the page, while `--local`, `--version`, `--help`, `--upgrade` and the usage errors work.
184
184
 
185
- Today, in SLICC:
185
+ The options, the output, `--json` and the exit status are the host's, with `serve` for `scserve` in every message. The differences:
186
186
 
187
- - `serve --local DIR` runs the static server on the kernel's loopback in the foreground and prints `http://<port>.kernel.localhost/` (from `SLICC_PAGE_LOOPBACK_URL`, else `http://127.0.0.1:<port>/`); `serve --local --port PORT` prints that URL for a server that already runs.
188
- - `--version`, `--help` and the usage errors behave as on a host; `--upgrade` prints `pnpm add -g @ai-ecoverse/slicc-serve@latest`.
189
- - Everything that publishes exits 1 with `serve: publishing from SLICC needs seven's serve.publish, which isn't there yet; only --local works in SLICC so far`.
187
+ - **Who publishes:** seven's page, which leads a tray on the tray hub already. `serve` never talks to the hub: it asks the page with the [embedder kinds](#the-embedder-contract) below, and the page mints the preview and relays the hub's `preview.request` to `kernel.loopbackFetch`.
188
+ - **Local URLs** are the page's names for the kernel's loopback: `http://<port>.kernel.localhost/` (from `SLICC_PAGE_LOOPBACK_URL`, else `http://127.0.0.1:<port>/`).
189
+ - **`--ttl`** exits 1 with `serve: --ttl from SLICC needs seven's serve.snapshot, which isn't there yet` ([#4](https://github.com/ai-ecoverse/slicc-serve/issues/4)).
190
+ - **`--open`** asks the page for a tab with `open.url` (as [slicc-open](https://github.com/ai-ecoverse/slicc-open) does) once the URL is printed; a refusal prints `serve: <the page's message>` and leaves the exit status alone.
191
+ - **`--upgrade`** prints `pnpm add -g @ai-ecoverse/slicc-serve@latest`.
190
192
 
191
- Publishing from seven goes through seven's page, which already leads a tray on the same hub: `serve` asks over `/dev/embedder` (`serve.publish`, `serve.snapshot`, `serve.list`, `serve.stop`), and the page relays `preview.request` to `kernel.loopbackFetch`. That is [#1](https://github.com/ai-ecoverse/slicc-serve/issues/1)'s M3 and M4, tracked in this repo's issues together with slicc-bios's side.
193
+ ### What runs where in SLICC
194
+
195
+ ```
196
+ serve DIR ──spawn──► serve (background, one per preview)
197
+ ├─ static server on the kernel's 127.0.0.1:<random>
198
+ └─ /dev/embedder: serve.publish, held open ──► seven's page ──► tray hub ◄── visitor
199
+ page: preview.request ──kernel.loopbackFetch──► 127.0.0.1:<port>
200
+ ```
201
+
202
+ - **Detached:** `serve DIR` checks the directory and `--entry`, then starts a background `serve` (the same program, spawned with WASIX `proc_spawn`, standard input on `/dev/null`, standard error appended to `<state>/serve.log`, standard output on a pipe back to it) and waits. The background `serve` binds the static server, sends `serve.publish`, and writes one line back: the record, or what failed. The foreground `serve` prints it the way the host does and exits; the background one keeps the server and the request open. There is one background `serve` per preview and no relay: the page holds the tray.
203
+ - **The request is the preview.** The background `serve` blocks reading the `serve.publish` reply. When that process ends, for whatever reason (`serve --stop`, `kill`, its session torn down, a crash), the kernel aborts the request and the page revokes the preview on the hub. When the page ends the reply (the user stopped it in seven, the hub revoked it, seven lost its tray), the background `serve` stops its server, removes its record and exits.
204
+ - **`--port PORT`** publishes a server that already runs on the kernel's loopback: the background `serve` holds only the request. `serve: nothing answers on 127.0.0.1:PORT yet` warns as on a host.
205
+ - **`--foreground`** does all of it in the `serve` process itself: it prints the URL, logs each request of the static server (`serve: GET /app.js 200 1234`), and Ctrl-C (or the end of the process) ends the request, which revokes the preview. When the page ends the reply, it prints `serve: stopped: <reason>` and exits 0.
206
+ - **`--local DIR`** starts a background `serve` with the static server only, recorded as `local` (listed, stopped with `--stop`); `--local --foreground DIR` serves in the foreground; `--local --port PORT` prints the URL only. None of them asks the page.
207
+ - **`--list`** asks the page with `serve.list` and joins its answer with the records, as the host joins the hub's list: `TOKEN MODE EXPIRES URL ROOT`, `(foreground)` for an attached one. A record whose process is gone is dropped, and so is one whose token the page doesn't list (its process is stopped). `local` records need no page.
208
+ - **`--stop`** matches its argument against the records as on a host (token, public URL, local URL, port or record id). A public preview is stopped with `serve.stop`; a token or a public URL that matches no record is sent to the page all the same. Then the matching record's process gets `SIGTERM` and the record is removed. A local preview is only signalled. It prints `stopped <token or local URL>`.
209
+ - **State** is the host's layout in the kernel's file system: `<state>/previews/<id>.json` (`0600`) per preview, with the background process's pid, and `<state>/serve.log`, where `<state>` is `$SCSERVE_STATE_DIR`, else `$XDG_STATE_HOME/slicc/serve`, else `~/.local/state/slicc/serve`. There is no `tray.json` and no relay.
210
+
211
+ ### Errors from the page
212
+
213
+ A request the page refuses fails with the kernel's errno, and `serve` prints `serve: <the first line of the page's message>` (the errno's text when there is none) and exits 1:
214
+
215
+ | errno | what it means | what `serve` adds |
216
+ | --- | --- | --- |
217
+ | `EACCES` | the user dismissed the prompt or didn't answer it, public previews are switched off, another request is waiting | `serve: if seven asked, answer in seven's tab (a click allows it), then run serve again` |
218
+ | `ENOTSUP` | no page answers for this session (`no page answers requests for this session`: a follower, a headless kernel), or a seven that doesn't answer the kind yet (`this embedder does not answer serve.publish`) | |
219
+ | `ENOENT` | `serve.stop`: the page holds no such preview | |
220
+ | `EBUSY`, `EIO`, any other | the page failed (`EIO` for an unreachable hub too) | |
221
+
222
+ A failure the tray hub answered comes as the reply's first line instead (`{"error", "status", …}`, below) and maps the way the host maps the hub's answers: `401` and `403`, or a `signIn`, exit 3 (`serve: publishing: the tray hub refused it (403: …)`, `serve: sign in at <url>`); `402` and `429` exit 4 (`serve: publishing: the tray hub's limit is reached (429: …)`, `serve: retry after 30 s`); any other status exits 1 (`serve: publishing: the tray hub answered 400: …`). `--json` prints the failure as `{"ok":false,"exit":N,"lines":[…],"signIn":URL|null}`, as on a host.
223
+
224
+ ### The embedder contract
225
+
226
+ This is what seven's page answers ([#6](https://github.com/ai-ecoverse/slicc-serve/issues/6)); `serve`'s tests run against a fake page that answers the same in a node kernel. Each request is one open of `/dev/embedder` (slicc-kernel 1.153.0 and later): a JSON header line `{"kind": …, …options}`, no body, then the reply until end-of-file. Option values are JSON, so no path or URL can break the header.
227
+
228
+ | kind | options | opened | reply | errors |
229
+ | --- | --- | --- | --- | --- |
230
+ | `serve.publish` | `port`, `root`, `entry`, `allowLive` | `O_RDWR` | one JSON line, `{"url","previewToken",…}` or `{"error",…}`; then held open until the preview ends, optionally one `{"stopped"}` line, then end-of-file | `EACCES`, `ENOTSUP`, `EIO` |
231
+ | `serve.list` | none | `O_RDWR` | one JSON line per preview, then end-of-file; nothing when there are none | `ENOTSUP`, `EIO` |
232
+ | `serve.stop` | `previewToken` | `O_WRONLY` | none; the close returns the errno | `ENOENT`, `ENOTSUP`, `EIO` |
233
+
234
+ #### `serve.publish`
235
+
236
+ ```
237
+ {"kind":"serve.publish","port":32768,"root":"/home/me/site","allowLive":false}
238
+ {"kind":"serve.publish","port":5173,"entry":"app/index.html","allowLive":true}
239
+ ```
240
+
241
+ | option | |
242
+ | --- | --- |
243
+ | `port` | number, 1 to 65535: the origin on the kernel's loopback, which the page reaches with `kernel.loopbackFetch(…, {port})` |
244
+ | `root` | string: the directory's absolute path in the kernel, for the prompt and the chip only; absent with `--port`. The page never reads files: every visit goes to `port` |
245
+ | `entry` | string, absent without `--entry`: the `--entry` path as `serve` normalized it (segments joined by `/`; no empty, `.` or `..` segment; no leading `/`; no `\`, `:` or NUL). The page refuses anything else, and a `port` outside 1 to 65535, with an `EIO` error (`invalid entry`, `invalid port`) |
246
+ | `allowLive` | boolean: `true` for `--port` (the hub doesn't edge-cache it), `false` for a directory (the hub's 5 s edge cache); `serve` always sends it, and the page takes `true` when it is missing |
247
+
248
+ What the page does, in order:
249
+
250
+ 1. **Who may publish:** a follower, a page that runs no kernel, or a seven with no tray hub configured throws `NotSupportedError` (`ENOTSUP`). A tray that isn't connected right now throws an `EIO` error with what is wrong. The switch "Public previews" off throws `NotAllowedError` (`EACCES`), `public previews are off in seven's settings`. The messages are bios's to choose; `serve` prints the first line as it is.
251
+ 2. **The prompt:** unless the stamp says `serve` was typed in seven's terminal with a gesture still active (bios's `typed(stamp)`), the page asks: "Publish /home/me/site at a public URL?" (or "the server on port 5173"). Cancel, 60 s without an answer, or a second request of the same session while one is up, throws `NotAllowedError` with what happened (`the request to publish was dismissed`, `nobody answered the request to publish within 60 s`, `another request is waiting for you`); `serve` prints the message as it is.
252
+ 3. **The mint:** `POST /api/tray/<trayId>/preview` `{servedRoot, entryPath, allowLive}`, where `servedRoot` is `/srv/serve/<id>` with a fresh random hex `<id>` of at least 16 digits from `crypto.getRandomValues` for each request (bios uses 32; the host relay 16) (never the real path, never the port: ports are reused), and `entryPath` is `<servedRoot>/<entry>`, or `<servedRoot>/index.html` without `entry` (the hub rejects `<servedRoot>/`).
253
+ 4. **A failure the hub answered** (the mint's HTTP status wasn't 2xx) is the reply, not an errno, so that `serve` can exit 3 or 4: one line `{"error": <the hub's error, or the status text>, "status": <its HTTP status>, "code": <its code, when it has one>, "retryAfter": <its Retry-After, when present>, "signIn": <a sign-in URL, when the hub named one>}`, then end-of-file. A hub the page can't reach at all is an error (`EIO`) with the reason.
254
+ 5. **Registered:** the page keeps `servedRoot → {port, entryPath, entryIsRoot: entry absent, previewToken, url, root, entry, since, uid: stamp.uid}` and answers `{"url": …, "previewToken": …}` and a newline, optionally with `"trayId"`. The `url` is the hub's, with a trailing `index.html` dropped when there is no `entry` (the page may leave that to `serve`, which drops it too).
255
+ 6. **Held open:** the page's reply stream stays open, with nothing more in it, as long as the preview is live. The page shows the live chip ("Serving publicly … Stop").
256
+
257
+ How it ends:
258
+
259
+ - **From the command's side:** the kernel aborts the handler's `signal` (reason `closed` when the description is closed or its process ends, `interrupted` when a signal reaches the blocked read) and cancels the reply stream. On either, the page revokes the preview on the hub (`POST /api/tray/<trayId>/preview/stop {previewToken}`) and drops it from the registry. If the signal is already aborted when the mint answers (the process went away during the prompt or the mint), the page revokes at once and replies nothing.
260
+ - **From the page's side** (the chip's Stop, `serve.stop`, `preview.revoked` from the hub, the switch turned off, the tray lost): the page revokes it on the hub unless the hub revoked it, drops it, writes `{"stopped": <reason>}` and a newline (`stopped in seven`, `stopped with serve --stop`, `revoked by the tray hub`, `public previews were switched off`, `seven lost its tray`), and closes the stream. Every page-side end writes the line, the chip's Stop and `serve.stop` included; `serve` treats end-of-file without it as `stopped in seven`.
261
+ - **A reload** ends the kernel, and every process with it: on boot, and after each leader reconnect, the page revokes the tray's live previews it holds no registration for, as the host relay does.
262
+
263
+ The relay itself (`preview.request` → `kernel.loopbackFetch(GET <path>, {port, headers: {range}})` → `preview.response` chunks) follows [The relay's answers](#the-relays-answers), with `vfsPath` checked against the registered `servedRoot`, the path under it sent as it came, and the `entryPath` of a preview without `entry` sent as `/`.
264
+
265
+ #### `serve.list`
266
+
267
+ ```
268
+ {"kind":"serve.list"}
269
+ ```
270
+
271
+ The reply is one JSON object per line for each preview the page holds from `serve.publish` that the caller may see: those whose publishing process had the caller's uid, all of them for root. `{"previewToken", "url", "root", "port", "entry", "since"}`, with `root` and `entry` absent as in the request and `since` the mint's time in milliseconds since the epoch, which `serve --list` shows as `createdAt` (ISO 8601) when it has no record of its own. An empty reply means none.
272
+
273
+ #### `serve.stop`
274
+
275
+ ```
276
+ {"kind":"serve.stop","previewToken":"0f3c….a91e…"}
277
+ ```
278
+
279
+ The page revokes the preview on the hub, drops it, and ends its `serve.publish` reply with `{"stopped":"stopped with serve --stop"}`, so the background `serve` that holds it exits. A token the page doesn't hold is revoked on the tray all the same; one the hub has no preview for throws `NotFoundError` (`ENOENT`), `the tray hub has no such preview`. A held preview of another uid, for a caller that isn't root, is `ENOENT` too.
192
280
 
193
281
  ## Development
194
282
 
@@ -199,8 +287,8 @@ npm test
199
287
  npm run build:wasm
200
288
  ```
201
289
 
202
- - `crates/serve` is the binary (`scserve`, and `scserve.wasm` for the kernel); `crates/serve-core` has no host-only dependency and builds for `wasm32-wasip1`; `crates/serve-hub` (native only) is the hub client, the tray, the relay and the CLI.
203
- - `npm run lint`: Biome, the no-comment check, `slicc-lint`, `shellcheck` and `dash -n` on `install.sh`, `cargo fmt`, and `cargo clippy` for the host and `wasm32-wasip1`.
290
+ - `crates/serve` is the binary (`scserve`, and `scserve.wasm` for the kernel); `crates/serve-core` has no host-only dependency and builds for `wasm32-wasip1-threads`; `crates/serve-hub` (native only) is the hub client, the tray, the relay and the CLI.
291
+ - `npm run lint`: Biome, the no-comment check, `slicc-lint`, `shellcheck` and `dash -n` on `install.sh`, `cargo fmt`, and `cargo clippy` for the host and `wasm32-wasip1-threads`.
204
292
  - `npm test` builds `scserve` and runs `test/integration/` with Node's test runner. The hub there is `fake-hub.mjs`: trays, leader election, the controller WebSocket (`preview.request` to the relay and the chunks back, `preview.revoked`), mint, upload, finalize, stop and list, a visitor path that resolves `<label>.localhost` hosts like the preview worker, and injected answers per route for every class of error. Tests never reach `www.sliccy.ai`. `wasm.test.mjs` runs `bin/serve.wasm` under `node:wasi` (after `npm run build:wasm`), `install.test.mjs` runs `install.sh` and `--upgrade` against local release directories.
205
293
  - `npm run test:unit` runs the unit tests in the gitignored `test/unit/` with `cargo llvm-cov`; the pre-commit hook wants 100% coverage of the changed lines in the crates it measures.
206
294
 
package/bin/serve.wasm CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ai-ecoverse/slicc-serve",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "serve and scserve: publish a directory or a local server at a public capability URL through the SLICC tray hub, on any host and inside SLICC",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -30,11 +30,11 @@
30
30
  }
31
31
  },
32
32
  "optionalDependencies": {
33
- "@ai-ecoverse/slicc-serve-darwin-arm64": "1.0.0",
34
- "@ai-ecoverse/slicc-serve-darwin-x64": "1.0.0",
35
- "@ai-ecoverse/slicc-serve-linux-arm64": "1.0.0",
36
- "@ai-ecoverse/slicc-serve-linux-x64": "1.0.0",
37
- "@ai-ecoverse/slicc-serve-win32-arm64": "1.0.0",
38
- "@ai-ecoverse/slicc-serve-win32-x64": "1.0.0"
33
+ "@ai-ecoverse/slicc-serve-darwin-arm64": "1.0.1",
34
+ "@ai-ecoverse/slicc-serve-darwin-x64": "1.0.1",
35
+ "@ai-ecoverse/slicc-serve-linux-arm64": "1.0.1",
36
+ "@ai-ecoverse/slicc-serve-linux-x64": "1.0.1",
37
+ "@ai-ecoverse/slicc-serve-win32-arm64": "1.0.1",
38
+ "@ai-ecoverse/slicc-serve-win32-x64": "1.0.1"
39
39
  }
40
40
  }