@ai-ecoverse/slicc-serve 1.0.1 → 1.1.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.
package/README.md CHANGED
@@ -26,6 +26,12 @@ npm install -g @ai-ecoverse/slicc-serve
26
26
 
27
27
  In SLICC, `pnpm add -g @ai-ecoverse/slicc-serve` puts `serve` and `scserve` in `/usr/bin` (the package declares both in `slicc.commands` with `abi: wasi`).
28
28
 
29
+ seven's pnpm enforces `minimumReleaseAge=1440`, so it installs a release only once it is 24 hours old. To install a newer one before that:
30
+
31
+ ```sh
32
+ pnpm add -g @ai-ecoverse/slicc-serve --config.minimumReleaseAgeExclude='@ai-ecoverse/slicc-serve*'
33
+ ```
34
+
29
35
  Binaries: macOS (arm64, x86-64, signed and notarized), Linux (arm64, x86-64, static musl) and Windows (arm64, x86-64). [The installers](#the-installers) has the details.
30
36
 
31
37
  ## Usage
@@ -116,7 +122,7 @@ The hub sends `preview.request {reqId, servedRoot, vfsPath, asText, range?}`; th
116
122
 
117
123
  ### Snapshots (`--ttl`)
118
124
 
119
- `scserve --ttl 7d DIR` collects the visible files (hidden ones, symlinks out of the directory and symlinks to hidden files excluded, each directory walked once so links between directories can't loop, sorted), refuses more than 1,000 files, a file over 25 MiB or more than 50 MiB in total before anything is sent, and needs its entry file (`index.html` by default; `scserve: DIR has no index.html; a --ttl snapshot needs its entry file (give one with --entry)`). It mints with `ttlMs`, uploads the files four at a time (`PUT …/preview/<token>/file?path=<path>` with the upload token and each file's type), finalizes, and prints the URL. If an upload or the finalize fails, it stops the snapshot on the hub before it exits. A snapshot counts toward the tray's 10-snapshot quota (`429 PREVIEW_LIMIT`, exit 4), lasts until its TTL, and is served by the hub without this machine. Subdirectory index pages aren't reachable by their directory URL in a snapshot (the hub serves stored paths only); link to `sub/index.html`.
125
+ `scserve --ttl 7d DIR` collects the visible files (hidden ones, symlinks out of the directory and symlinks to hidden files excluded, sorted). A directory reachable by several paths, its own and a symlink's (`latest -> v2`), is collected under each of them, as the live preview serves it; only a symlink back to a directory the walk is inside (`v2/up -> ..`) is skipped, so links can't loop, and the limits below, plus 10,000 directories walked, bound what repeats. It refuses more than 1,000 files, a file over 25 MiB or more than 50 MiB in total before anything is sent, and needs its entry file (`index.html` by default; `scserve: DIR has no index.html; a --ttl snapshot needs its entry file (give one with --entry)`). It mints with `ttlMs`, uploads the files four at a time (`PUT …/preview/<token>/file?path=<path>` with the upload token and each file's type), finalizes, and prints the URL. If an upload or the finalize fails, it stops the snapshot on the hub before it exits. A snapshot counts toward the tray's 10-snapshot quota (`429 PREVIEW_LIMIT`, exit 4), lasts until its TTL, and is served by the hub without this machine. Subdirectory index pages aren't reachable by their directory URL in a snapshot (the hub serves stored paths only); link to `sub/index.html`.
120
126
 
121
127
  ### `--list` and `--stop`
122
128
 
@@ -199,13 +205,13 @@ serve DIR ──spawn──► serve (background, one per preview)
199
205
  page: preview.request ──kernel.loopbackFetch──► 127.0.0.1:<port>
200
206
  ```
201
207
 
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.
208
+ - **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. Like `nohup`, the background `serve` ignores `SIGHUP` as it starts, and none of its standard streams is the terminal, so closing the terminal that ran `serve` (a hangup of its foreground group) leaves the preview up; `serve --stop`, `kill` (`SIGTERM`) or `kill -9` end it.
209
+ - **The request is the preview.** The background `serve` blocks reading the `serve.publish` reply. When that process ends, for whatever reason (`serve --stop`, `kill`, the kernel ending, 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
210
  - **`--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
211
  - **`--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
212
  - **`--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>`.
213
+ - **`--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). When no page answers (`ENOTSUP`, or no `/dev/embedder`), the records alone are listed.
214
+ - **`--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`, which ends its background `serve` through the page; a token or a public URL that matches no record is sent to the page all the same. When the page refuses, the matching record's process gets `SIGTERM` anyway, and the page's message exits 1. A local preview's process gets `SIGTERM`. Either way the record is removed, and it prints `stopped <token or local URL>`. Several matching records stop none, as on a host.
209
215
  - **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
216
 
211
217
  ### Errors from the page
@@ -214,7 +220,7 @@ A request the page refuses fails with the kernel's errno, and `serve` prints `se
214
220
 
215
221
  | errno | what it means | what `serve` adds |
216
222
  | --- | --- | --- |
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` |
223
+ | `EACCES` | the user dismissed the prompt or didn't answer it, public previews are switched off, another request is waiting; or the kernel refused the request before the page saw it (`serve.publish is not allowed for this user`): the kinds are open to the session's own user, so a `serve` run under `sudo -u` someone else from another user's terminal is refused, while an agent in its own session works | `serve: if seven asked, answer in seven's tab (a click allows it), then run serve again` |
218
224
  | `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
225
  | `ENOENT` | `serve.stop`: the page holds no such preview | |
220
226
  | `EBUSY`, `EIO`, any other | the page failed (`EIO` for an unreachable hub too) | |
@@ -250,7 +256,7 @@ What the page does, in order:
250
256
  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
257
  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
258
  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.
259
+ 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>, "active", "limit": <the hub's counts, when it sent them (`LIVE_PREVIEW_LIMIT`)>}`, then end-of-file. A hub the page can't reach at all is an error (`EIO`) with the reason.
254
260
  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
261
  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
262
 
@@ -289,7 +295,7 @@ npm run build:wasm
289
295
 
290
296
  - `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
297
  - `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`.
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.
298
+ - `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`. `seven.test.mjs` installs the package (its staged `package.json`, from `scripts/targets.mjs`) with `bin/serve.wasm` (after `npm run build:wasm`), wasm-bash and wasm-coreutils in a node kernel from `@ai-ecoverse/slicc-kernel` (Node 26), behind a fake page that answers `serve.publish`, `serve.list`, `serve.stop` and `open.url` and records each request: the background `serve`, the page ending a preview, a killed holder revoking, `--port`, `--foreground`, `--open`, `--list` and `--stop` by token, URL and port, each errno and each class of hub failure, and a hostile directory name in the header; then a kernel no page answers, and slicc-kernel 1.152.2 (the devDependency `slicc-kernel-without-embedder`), which refuses the package and, with `engines` stripped, has no `/dev/embedder`. `install.test.mjs` runs `install.sh` and `--upgrade` against local release directories.
293
299
  - `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.
294
300
 
295
301
  CI is `.github/workflows/ci.yml` on [slicc-shared-web's pipeline](https://github.com/ai-ecoverse/slicc-shared-web): lint, the integration tests on Linux, `npm run test:windows` on Windows, the same tests on macOS, `cargo check` for every release target, and the reviews. On a push to `main`, semantic-release tags a release; then the binaries are built for every target (the darwin ones signed and notarized), collected with `serve.wasm` into `SHA256SUMS` (attested), attached to the release with both installers, installed once through `install.sh`, and published to npm as `@ai-ecoverse/slicc-serve` and its six platform packages.
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.1",
3
+ "version": "1.1.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": {
@@ -16,7 +16,8 @@
16
16
  "bin/serve.wasm"
17
17
  ],
18
18
  "engines": {
19
- "node": ">=18"
19
+ "node": ">=18",
20
+ "slicc-kernel": ">=1.153.0"
20
21
  },
21
22
  "slicc": {
22
23
  "abi": "wasi",
@@ -30,11 +31,11 @@
30
31
  }
31
32
  },
32
33
  "optionalDependencies": {
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"
34
+ "@ai-ecoverse/slicc-serve-darwin-arm64": "1.1.1",
35
+ "@ai-ecoverse/slicc-serve-darwin-x64": "1.1.1",
36
+ "@ai-ecoverse/slicc-serve-linux-arm64": "1.1.1",
37
+ "@ai-ecoverse/slicc-serve-linux-x64": "1.1.1",
38
+ "@ai-ecoverse/slicc-serve-win32-arm64": "1.1.1",
39
+ "@ai-ecoverse/slicc-serve-win32-x64": "1.1.1"
39
40
  }
40
41
  }