@ai-ecoverse/slicc-serve 1.1.0 → 1.2.0
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 +45 -7
- package/bin/serve.wasm +0 -0
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -122,7 +122,7 @@ The hub sends `preview.request {reqId, servedRoot, vfsPath, asText, range?}`; th
|
|
|
122
122
|
|
|
123
123
|
### Snapshots (`--ttl`)
|
|
124
124
|
|
|
125
|
-
`scserve --ttl 7d DIR` collects the visible files (hidden ones, symlinks out of the directory and symlinks to hidden files excluded, each directory
|
|
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`.
|
|
126
126
|
|
|
127
127
|
### `--list` and `--stop`
|
|
128
128
|
|
|
@@ -192,7 +192,7 @@ The options, the output, `--json` and the exit status are the host's, with `serv
|
|
|
192
192
|
|
|
193
193
|
- **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`.
|
|
194
194
|
- **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>/`).
|
|
195
|
-
- **`--ttl`**
|
|
195
|
+
- **`--ttl`** collects the snapshot itself, with the host's walker and limits, and hands the files to the page in the body of one `serve.snapshot` request; the page mints the snapshot, uploads the files and finalizes it ([`serve.snapshot`](#servesnapshot)). Nothing keeps running. The kernel doesn't upload itself: a program's `https://www.sliccy.ai/…` request through the kernel's proxy answers `502` in seven (measured from a seven branch preview with the page's transport, [#4](https://github.com/ai-ecoverse/slicc-serve/issues/4)), while the page reaches the hub, since it already leads a tray there.
|
|
196
196
|
- **`--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.
|
|
197
197
|
- **`--upgrade`** prints `pnpm add -g @ai-ecoverse/slicc-serve@latest`.
|
|
198
198
|
|
|
@@ -210,7 +210,7 @@ serve DIR ──spawn──► serve (background, one per preview)
|
|
|
210
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.
|
|
211
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.
|
|
212
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.
|
|
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.
|
|
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 (a snapshot's has no process and stays until it expires), 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
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.
|
|
215
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.
|
|
216
216
|
|
|
@@ -229,13 +229,14 @@ A failure the tray hub answered comes as the reply's first line instead (`{"erro
|
|
|
229
229
|
|
|
230
230
|
### The embedder contract
|
|
231
231
|
|
|
232
|
-
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}`,
|
|
232
|
+
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}`, a body (`serve.snapshot` only), then the reply until end-of-file. Option values are JSON, so no path or URL can break the header.
|
|
233
233
|
|
|
234
234
|
| kind | options | opened | reply | errors |
|
|
235
235
|
| --- | --- | --- | --- | --- |
|
|
236
236
|
| `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` |
|
|
237
237
|
| `serve.list` | none | `O_RDWR` | one JSON line per preview, then end-of-file; nothing when there are none | `ENOTSUP`, `EIO` |
|
|
238
238
|
| `serve.stop` | `previewToken` | `O_WRONLY` | none; the close returns the errno | `ENOENT`, `ENOTSUP`, `EIO` |
|
|
239
|
+
| `serve.snapshot` | `root`, `entry`, `ttlMs`, `files`, `bytes` | `O_RDWR` | after the body: one JSON line, `{"url","previewToken","expiresAt",…}` or `{"error",…}`, then end-of-file | `EACCES`, `ENOTSUP`, `EIO` |
|
|
239
240
|
|
|
240
241
|
#### `serve.publish`
|
|
241
242
|
|
|
@@ -274,7 +275,7 @@ The relay itself (`preview.request` → `kernel.loopbackFetch(GET <path>, {port,
|
|
|
274
275
|
{"kind":"serve.list"}
|
|
275
276
|
```
|
|
276
277
|
|
|
277
|
-
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"}
|
|
278
|
+
The reply is one JSON object per line for each preview the page holds from `serve.publish` or `serve.snapshot` 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"}` for a live preview, 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. A snapshot's line has `"mode": "persistent"` and `"expiresAt"` (milliseconds since the epoch) and no `port`; a live one may say `"mode": "live"`. An empty reply means none.
|
|
278
279
|
|
|
279
280
|
#### `serve.stop`
|
|
280
281
|
|
|
@@ -282,7 +283,44 @@ The reply is one JSON object per line for each preview the page holds from `serv
|
|
|
282
283
|
{"kind":"serve.stop","previewToken":"0f3c….a91e…"}
|
|
283
284
|
```
|
|
284
285
|
|
|
285
|
-
The page revokes the preview on the hub, drops it, and ends
|
|
286
|
+
The page revokes the preview on the hub (a snapshot too, before its TTL), drops it, and ends a live preview's `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.
|
|
287
|
+
|
|
288
|
+
#### `serve.snapshot`
|
|
289
|
+
|
|
290
|
+
```
|
|
291
|
+
{"kind":"serve.snapshot","root":"/home/me/site","ttlMs":604800000,"files":2,"bytes":1843}
|
|
292
|
+
{"path":"index.html","type":"text/html; charset=utf-8","size":1800}
|
|
293
|
+
<1800 bytes>
|
|
294
|
+
{"path":"app/main.js","type":"text/javascript; charset=utf-8","size":43}
|
|
295
|
+
<43 bytes>
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
`serve --ttl` walks the directory first, as on a host ([Snapshots](#snapshots---ttl)): the limits, the entry file and the names are checked before anything is sent. Then it opens the device `O_RDWR`, writes the header, writes every file as the body, and reads the reply: the kernel ends the body at the first read, so the reply comes once the page has read the whole body.
|
|
299
|
+
|
|
300
|
+
| option | |
|
|
301
|
+
| --- | --- |
|
|
302
|
+
| `root` | string: the directory's absolute path, for the prompt only |
|
|
303
|
+
| `entry` | string, absent without `--entry`: normalized as for `serve.publish` |
|
|
304
|
+
| `ttlMs` | number: the TTL in milliseconds, 60000 to 2592000000 (30 days) |
|
|
305
|
+
| `files`, `bytes` | numbers: how many files and bytes the body holds, for the prompt and to check the body against |
|
|
306
|
+
|
|
307
|
+
**The body** is the files in order, each a JSON line `{"path", "type", "size"}` (at most 4 KiB) followed by exactly `size` bytes. `path` is the file's path in the snapshot, segments joined by `/`, as the host uploads it: no leading `/`, no empty, `.` or `..` segment, no segment starting with `.` (but `.well-known`), no `\`, `:` or NUL. `type` is the file's type from its extension, `size` at most 25 MiB. The body ends after the last file.
|
|
308
|
+
|
|
309
|
+
What the page does, in order:
|
|
310
|
+
|
|
311
|
+
1. **Who may publish, and the prompt:** as for `serve.publish`, before it reads the body: a follower or a seven without a tray hub is `ENOTSUP`, the switch "Public previews" off is `EACCES`, and unless `serve` was typed in seven's terminal with a gesture still active, it asks: "Publish a snapshot of /home/me/site (2 files, 1.8 KiB) at a public URL for 7 days?". Cancel or no answer is `EACCES`, with its message.
|
|
312
|
+
2. **The mint:** `POST /api/tray/<trayId>/preview` `{servedRoot, entryPath, allowLive: false, ttlMs}`, with `servedRoot` and `entryPath` made as for `serve.publish`. The answer's `uploadToken` stays in the page.
|
|
313
|
+
3. **The uploads:** on `*.sliccy.ai` the page reaches the hub through sliccy-ai's same-origin proxy, which forwards `preview/<token>/file` and `preview/<token>/finalize` for this ([sliccy-ai#162](https://github.com/ai-ecoverse/sliccy-ai/pull/162)); elsewhere it calls the hub directly. For each file of the body, `PUT /api/tray/<trayId>/preview/<previewToken>/file?path=<path>` with the upload token as the bearer, `Content-Type: <type>` and the bytes. The page may upload a few at a time, and may report progress with `request.progress` (`uploaded 12 of 40 files`), which `serve` shows on its standard error.
|
|
314
|
+
4. **The finalize:** `POST /api/tray/<trayId>/preview/<previewToken>/finalize` with the upload token, once the body has ended.
|
|
315
|
+
5. **The reply:** one line `{"url": <the hub's url>, "previewToken", "trayId"?, "expiresAt": <milliseconds since the epoch>, "files", "bytes"}` and a newline, then end-of-file. The page keeps the snapshot for `serve.list` and `serve.stop` (with `stamp.uid`, `root`, `entry`, `since`, `expiresAt`) until it expires or is stopped, across reloads, since a snapshot outlives the page.
|
|
316
|
+
|
|
317
|
+
When it fails, the page answers at once, without reading the rest of the body: with an error, or with the failure line as a string (never a stream). The kernel then drops whatever `serve` still writes ([slicc-kernel#1536](https://github.com/ai-ecoverse/slicc-kernel/issues/1536)), so `serve` never waits on a body nobody reads; it gets the errno from its next write or from its read, and the failure line from its read.
|
|
318
|
+
|
|
319
|
+
|
|
320
|
+
- **The body is wrong** (a line that isn't the JSON above, a path or type that breaks the rules, a `size` over 25 MiB, a body that ends inside a file, more than 1,000 files or 50 MiB, the same path twice, or files and bytes that don't add up to exactly `files` and `bytes` when the body ends, so what is finalized is what the prompt showed): the page stops the snapshot on the hub (`POST …/preview/stop`) and throws an `EIO` error `bad snapshot body: <what>`.
|
|
321
|
+
- **The hub answered a failure** to the mint, an upload or the finalize: the page stops a minted snapshot, and the reply is the failure line of `serve.publish` (`{"error", "status", "code"?, "retryAfter"?, "signIn"?, "active"?, "limit"?}`), with `"during": "mint"`, `"upload"` or `"finalize"`, and for an upload `"path"`. `serve` says `publishing the snapshot` for the mint and `uploading the snapshot` otherwise, adds ` (<path>)` to the hub's error for an upload, and maps the status to exits 1, 3 and 4 as for `serve.publish`. `PREVIEW_LIMIT` (`429`, the tray's 10 snapshots) is exit 4.
|
|
322
|
+
- **The hub can't be reached:** the page stops a minted snapshot if it can, and throws an `EIO` error with the reason.
|
|
323
|
+
- **`serve` goes away** before the reply (Ctrl-C, `kill`): the kernel aborts the request, and the page stops the snapshot on the hub unless it had already written its reply, a finalize still in flight included, since `serve` never got the URL. A snapshot whose reply the page had written stays (`serve` may have exited before reading it), and `serve --list` shows it from `serve.list`.
|
|
286
324
|
|
|
287
325
|
## Development
|
|
288
326
|
|
|
@@ -295,7 +333,7 @@ npm run build:wasm
|
|
|
295
333
|
|
|
296
334
|
- `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.
|
|
297
335
|
- `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`.
|
|
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.
|
|
336
|
+
- `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`. `seven-ttl.test.mjs` does the same for `--ttl`, with a fake page that implements `serve.snapshot` against `fake-hub.mjs` (it reads the body, mints, uploads, finalizes, and stops what it minted on a failure): the files that reach the hub, `--json`, `--entry`, `--open`, a file past the request window, the limits checked before the page is asked, each hub failure (mint, upload, finalize, with a 3 MiB body answered early), the page's refusals, and a `serve` killed before the finalize. `install.test.mjs` runs `install.sh` and `--upgrade` against local release directories.
|
|
299
337
|
- `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.
|
|
300
338
|
|
|
301
339
|
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.
|
|
3
|
+
"version": "1.2.0",
|
|
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": {
|
|
@@ -31,11 +31,11 @@
|
|
|
31
31
|
}
|
|
32
32
|
},
|
|
33
33
|
"optionalDependencies": {
|
|
34
|
-
"@ai-ecoverse/slicc-serve-darwin-arm64": "1.
|
|
35
|
-
"@ai-ecoverse/slicc-serve-darwin-x64": "1.
|
|
36
|
-
"@ai-ecoverse/slicc-serve-linux-arm64": "1.
|
|
37
|
-
"@ai-ecoverse/slicc-serve-linux-x64": "1.
|
|
38
|
-
"@ai-ecoverse/slicc-serve-win32-arm64": "1.
|
|
39
|
-
"@ai-ecoverse/slicc-serve-win32-x64": "1.
|
|
34
|
+
"@ai-ecoverse/slicc-serve-darwin-arm64": "1.2.0",
|
|
35
|
+
"@ai-ecoverse/slicc-serve-darwin-x64": "1.2.0",
|
|
36
|
+
"@ai-ecoverse/slicc-serve-linux-arm64": "1.2.0",
|
|
37
|
+
"@ai-ecoverse/slicc-serve-linux-x64": "1.2.0",
|
|
38
|
+
"@ai-ecoverse/slicc-serve-win32-arm64": "1.2.0",
|
|
39
|
+
"@ai-ecoverse/slicc-serve-win32-x64": "1.2.0"
|
|
40
40
|
}
|
|
41
41
|
}
|