@ai-ecoverse/slicc-serve 1.1.1 → 1.3.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 +132 -10
- package/bin/serve.wasm +0 -0
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -9,11 +9,21 @@ This README is the spec. The plan is [#1](https://github.com/ai-ecoverse/slicc-s
|
|
|
9
9
|
## Install
|
|
10
10
|
|
|
11
11
|
```sh
|
|
12
|
-
curl -fsSL https://
|
|
12
|
+
curl -fsSL https://get.sliccy.ai/serve | sh
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
On Windows, in PowerShell:
|
|
16
16
|
|
|
17
|
+
```powershell
|
|
18
|
+
irm https://get.sliccy.ai/serve.ps1 | iex
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
`get.sliccy.ai/serve` redirects to the latest release's `install.sh`, and `serve.ps1` runs its `install.ps1` ([sliccy-ai](https://github.com/ai-ecoverse/sliccy-ai)). The release assets work directly too, and options go after `sh -s --` (for example `curl -fsSL https://get.sliccy.ai/serve | sh -s -- --dir ~/bin`):
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
curl -fsSL https://github.com/ai-ecoverse/slicc-serve/releases/latest/download/install.sh | sh
|
|
25
|
+
```
|
|
26
|
+
|
|
17
27
|
```powershell
|
|
18
28
|
irm https://github.com/ai-ecoverse/slicc-serve/releases/latest/download/install.ps1 | iex
|
|
19
29
|
```
|
|
@@ -39,8 +49,11 @@ Binaries: macOS (arm64, x86-64, signed and notarized), Linux (arm64, x86-64, sta
|
|
|
39
49
|
```
|
|
40
50
|
scserve [--entry FILE] [--ttl DURATION] [--local] [--foreground] [--open] [--json] DIRECTORY
|
|
41
51
|
scserve --port PORT [--entry PATH] [--local] [--foreground] [--open] [--json]
|
|
52
|
+
scserve --bridge [--max-tabs N] [--quiet] [other options] DIRECTORY | --port PORT
|
|
42
53
|
scserve --list [--json]
|
|
43
54
|
scserve --stop TOKEN|URL|PORT [--json]
|
|
55
|
+
scserve --logs [TOKEN|URL] [--lines N] [--json]
|
|
56
|
+
scserve --truncate [TOKEN|URL] [--json]
|
|
44
57
|
scserve --version | --upgrade | --help
|
|
45
58
|
```
|
|
46
59
|
|
|
@@ -54,15 +67,22 @@ scserve --version | --upgrade | --help
|
|
|
54
67
|
| `--foreground` | stays attached instead of returning; Ctrl-C (or the end of the process) stops the preview |
|
|
55
68
|
| `--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)) |
|
|
56
69
|
| `--json` | prints the result, or the error, as one JSON object (an array for `--list`) |
|
|
70
|
+
| `--bridge` | makes every visitor's tab a target that a CDP client on this machine can drive, and passes the page's `window.slicc.emit()` calls on (see [The bridge](#the-bridge---bridge)) |
|
|
71
|
+
| `--no-bridge` | the default: no bridge |
|
|
72
|
+
| `--max-tabs N` | with `--bridge`: at most `N` visitor tabs bridged at once, 1 to 100 (default 20); the hub refuses more |
|
|
73
|
+
| `--quiet` | with `--bridge`: no first-visit announcement (the visit is still recorded for `--logs`) |
|
|
74
|
+
| `--logs [TOKEN\|URL]` | prints the bridge's lifecycle records (connects, disconnects, emits), of one preview or of all |
|
|
75
|
+
| `--lines N` | with `--logs`: only the newest `N` records |
|
|
76
|
+
| `--truncate [TOKEN\|URL]` | clears those records and re-arms the first-visit announcement |
|
|
57
77
|
| `--list` | lists the previews this machine published |
|
|
58
78
|
| `--stop TOKEN\|URL\|PORT` | stops a preview, by its token, its public URL, its local URL or its local port |
|
|
59
79
|
| `--version` | prints the version alone (`1.2.0`) |
|
|
60
80
|
| `--upgrade` | see [`--upgrade`](#--upgrade) |
|
|
61
81
|
| `-h`, `--help` | prints the usage and the options to stdout and exits 0, wherever it appears among the options |
|
|
62
82
|
|
|
63
|
-
Options come before or after the directory; `--name=value` works for options with a value, and `--` ends the options. Give a directory or `--port`, not both and not neither. `--ttl` needs a directory and is neither `--local` nor `--foreground`. `--list` and `--stop` take only `--json`; `--version` and `--upgrade` take nothing else. `--entry` must stay inside the directory: no leading `/` or `\`, no `..`, no `:`; `./` and doubled slashes are dropped, and `\` counts as `/`.
|
|
83
|
+
Options come before or after the directory; `--name=value` works for options with a value, and `--` ends the options. Give a directory or `--port`, not both and not neither. `--ttl` needs a directory and is neither `--local` nor `--foreground`. `--list` and `--stop` take only `--json`, `--logs` only a target, `--lines` and `--json`, `--truncate` only a target and `--json`; `--version` and `--upgrade` take nothing else. `--bridge` is neither `--ttl` (a snapshot has no visitor sockets) nor `--local`, and not with `--no-bridge`; `--max-tabs` and `--quiet` need `--bridge`. `--entry` must stay inside the directory: no leading `/` or `\`, no `..`, no `:`; `./` and doubled slashes are dropped, and `\` counts as `/`.
|
|
64
84
|
|
|
65
|
-
|
|
85
|
+
`--project` is refused with `scserve: --project is obsolete: give the directory to serve itself`.
|
|
66
86
|
|
|
67
87
|
### Exit status
|
|
68
88
|
|
|
@@ -130,6 +150,54 @@ The hub sends `preview.request {reqId, servedRoot, vfsPath, asText, range?}`; th
|
|
|
130
150
|
|
|
131
151
|
`--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.
|
|
132
152
|
|
|
153
|
+
## The bridge (`--bridge`)
|
|
154
|
+
|
|
155
|
+
`scserve --bridge ./app` is slicc 6's `serve --bridge` on a host: every tab a visitor opens on the public URL becomes a CDP target on this machine, `preview:<token>:<connId>`, that a CDP client (playwright-cli, a script with `chrome-remote-interface`) can evaluate in, query, click, type into, screenshot and navigate, and the page's `window.slicc.emit(name, detail)` calls arrive here. Nothing on the hub changes: the hub already injects the bridge's bootstrap into a bridged preview's HTML (`<script src="/__slicc/preview-bridge.js">`), holds one `/__slicc/bridge` WebSocket per visitor tab, and relays between those sockets and the tray's leader. `scserve` is that leader.
|
|
156
|
+
|
|
157
|
+
```
|
|
158
|
+
visitor tab ──wss /__slicc/bridge──► tray hub ──controller WS──► relay ◄──ws──── CDP client
|
|
159
|
+
(bootstrap answers cdp.req) bridge.connected / .disconnected http://127.0.0.1:<port>/<secret>/
|
|
160
|
+
bridge.cdp.request / .response / .close
|
|
161
|
+
webhook.event (emits)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
**The mint** of a bridged preview adds `bridge: true`, `maxTabs` (`--max-tabs`, default 20), `quiet` (`--quiet`) and `webhookId: "scserve-<record id>"` to `POST /api/tray/<id>/preview`. The hub routes the preview's emits to the leader as `webhook.event` with that `webhookId`, which is all the id is for: the hub doesn't look it up.
|
|
165
|
+
|
|
166
|
+
**The CDP endpoint.** The relay runs one CDP server for all its bridged previews, on `127.0.0.1` with a random port (never 9222 to 9229), from the first bridged preview until the relay exits. Every path carries a 32-hex-digit secret, made fresh each time the relay starts and kept in `relay.json` (`0600`); a request without it is `404`, one whose `Host` isn't `127.0.0.1:<port>` or `localhost:<port>` is `403` (no DNS rebinding), and a WebSocket upgrade with an `Origin` header of a web page is `403`. So a page in the user's browser can't reach it, and neither can another user of the machine who doesn't hold the secret.
|
|
167
|
+
|
|
168
|
+
| path | answers |
|
|
169
|
+
| --- | --- |
|
|
170
|
+
| `GET /<secret>/json/version` | `{"Browser": "scserve/<version>", "Protocol-Version": "1.3", "webSocketDebuggerUrl": "ws://127.0.0.1:<port>/<secret>/devtools/browser"}` |
|
|
171
|
+
| `GET /<secret>/json/list`, `/<secret>/json` | one entry per bridged tab: `{"id": "preview:<token>:<connId>", "type": "page", "title": <the preview's directory, or 127.0.0.1:PORT>, "url": <the preview's public URL; the hub doesn't say which page the tab is on>, "description": "<origin> <userAgent>"}`; no per-target sockets |
|
|
172
|
+
| `GET /<secret>/devtools/browser` (WebSocket) | a browser-level CDP connection, below |
|
|
173
|
+
|
|
174
|
+
`scserve --bridge` prints the endpoint with the URL (`scserve: its visitor tabs are CDP targets at http://127.0.0.1:<port>/<secret>/`), and `--json` and `--list --json` give it as `cdpUrl`. The secret is a capability: anyone who has the URL can drive the bridged tabs while the relay runs.
|
|
175
|
+
|
|
176
|
+
**The browser connection** emulates the `Target` domain over the bridged tabs, with Chrome's flattened sessions:
|
|
177
|
+
|
|
178
|
+
- `Target.getTargets` lists the tabs (`type: "page"`, `attached` when a session is on it); `Target.setDiscoverTargets {discover: true}` sends `Target.targetCreated` for each tab there is and each that connects, and `Target.targetDestroyed` for each that goes; `Target.attachToTarget {targetId, flatten: true}` answers a `sessionId` and sends `Target.attachedToTarget`; `Target.setAutoAttach` attaches every tab there is and every new one; `Target.detachFromTarget` ends a session (`Target.detachedFromTarget`); `Target.closeTarget` closes the visitor's bridge (`bridge.close`). `Target.createTarget`, `Target.createBrowserContext` and `Browser.close` are `-32000`, `a preview bridge can't open or close the visitor's browser`; `Browser.getVersion` answers as `/json/version`; any other method without a `sessionId` is `-32601`.
|
|
179
|
+
- **In a session**, as slicc 6's `PreviewBridgeCdpTransport` and `SyntheticCdpTransport` do: `Page.enable`, `DOM.enable`, `Page.bringToFront`, `Runtime.disable`, `Runtime.runIfWaitingForDebugger` and `Target.setAutoAttach` answer `{}`; `Runtime.enable` answers `{}` and sends `Runtime.executionContextCreated` for the main world (once per enable); `Page.getFrameTree` and `Page.createIsolatedWorld` answer from the tab's URL and origin. Everything else goes to the tab as `bridge.cdp.request {connId, id, method, params, sessionId}`, and the tab's `bridge.cdp.response` is the answer. The bootstrap answers `Runtime.evaluate`, `DOM.getDocument`, `DOM.querySelector`, `DOM.getBoxModel`, `Input.dispatchMouseEvent`, `Input.dispatchKeyEvent`, `Page.captureScreenshot` (html2canvas), `Page.navigate` and `Target.createTarget` (it opens the URL), and `-32601` for the rest. After a `Page.navigate`, the relay sends `Page.frameNavigated`, a new execution context (when `Runtime` is on) and `Page.loadEventFired`, as slicc 6 does, since the hub relays no CDP events from the tab. A tab that doesn't answer within 30 s is `-32000`, `the visitor's tab didn't answer within 30 s`; a tab that is gone, `-32000`, `the visitor's tab is gone` (the hub's `Preview bridge connection is gone`).
|
|
180
|
+
- When a tab disconnects, its sessions end (`Target.detachedFromTarget`, `Target.targetDestroyed`) and its pending calls fail. When the preview stops, the hub closes its tabs' sockets. A CDP client closing its socket detaches its sessions and changes nothing for the visitor.
|
|
181
|
+
- **When the relay's controller socket drops**, the visitor sockets stay on the hub. The relay keeps its targets, and when it is back the hub replays `bridge.connected {…, replay: true}` for the tabs still there: they keep their target ids and sessions. A tab the hub doesn't replay within 3 s of the reconnect closed meanwhile; the relay drops it (`Target.targetDestroyed`, a `disconnected` record with the reason `the tray hub no longer had it after the relay reconnected`).
|
|
182
|
+
|
|
183
|
+
**What a client can do through the bridge.** The bootstrap the hub injects answers a small set of methods in the page itself, so the relay makes up the rest of what [slicc-cdp](https://github.com/ai-ecoverse/slicc-cdp)'s `playwright-cli` and `curlwright` need from a browser. With them, `tab-list`, `eval` (expressions and functions), `snapshot`, `screenshot`, `goto` and `curlwright` requests work on `preview:<token>:<connId>` targets (`playwright-cli --cdp <the endpoint's ws URL>`):
|
|
184
|
+
|
|
185
|
+
- **Results by value:** a `Runtime.evaluate` with `returnByValue` goes to the tab as `Promise.resolve((0, eval)(<the expression>)).then((v) => JSON.stringify({t: typeof v, v}))`, and the relay answers with the value. Without `returnByValue`, the tab returns a description (type, subtype, class, description, and the value of a primitive), from which the relay builds the remote object.
|
|
186
|
+
- **Object handles:** an object result gets an `objectId` that stands for the expression that produced it. `Runtime.callFunctionOn` on it evaluates that expression again and calls the function on the result (`(<function>).apply((0, eval)(<expression>), [<arguments>])`), so a handle is only as stable as its expression: one with side effects runs them again. `Runtime.getProperties` of a handle is empty, and `DOM.describeNode`, `DOM.resolveNode` and `DOM.requestNode` of one are `-32000`, `the preview bridge can't hold objects of the visitor's page`: there are no DOM node ids, so `playwright-cli`'s refs are found by their selectors.
|
|
187
|
+
- **One world:** the page has one execution context, renewed by each navigation. `Page.createIsolatedWorld` answers that context, so scripts meant for an isolated world run in the page's own (and see its globals).
|
|
188
|
+
- **No network domain:** `Inspector.enable`, `Fetch.enable`, `Fetch.disable`, `Network.enable`, `Network.disable` and `Network.setBypassServiceWorker` answer `{}` and no event ever follows; `Network.getAllCookies`, `Network.getCookies` and `Storage.getCookies` answer no cookies. The visitor's cookie jar, requests and responses don't reach the relay.
|
|
189
|
+
- **Not through the bridge:** console, network and dialog events, DOM node ids, PDF, screencasts, downloads, and a page whose own CSP forbids `eval` (the bootstrap's evaluation is the page's indirect `eval`). Input commands (`click`, `fill`, `type`) go through the bootstrap's `Input.dispatchMouseEvent` and `Input.dispatchKeyEvent`; their checks run in the page, so they depend on the visitor's page as any page script does.
|
|
190
|
+
|
|
191
|
+
**The lifecycle records.** The relay keeps the last 500 records of all its bridged previews, in memory (they are gone when the relay exits): `connected` (with the visitor's `origin`, `userAgent` and `connectedAt`), `disconnected` (with the `reason` when the hub gives one) and `emit` (the `name` and the `detail`, as JSON, cut to 1,000 characters). An emit, like a visitor's `origin`, `userAgent` and `reason`, is untrusted text from a stranger's browser; the hub already limits each emit to 16 KiB and 20 per tab every 10 s. Every line `scserve` prints for a person (`--foreground`'s event lines, `--logs`, the first-visit line) writes those fields with control characters (C0, DEL and C1) escaped as JSON escapes them (`\u001b`), so a visitor can't send escape sequences to the terminal; `--json` output is JSON already.
|
|
192
|
+
|
|
193
|
+
**The first visit.** The first tab that connects to a preview is announced, unless the preview is `--quiet`: its record is `announced` (the others `suppressed`), a `--foreground` `scserve` prints `scserve: first visitor on <url>: <origin> (<userAgent>)`, and the relay sends `preview.state.update {previewToken, announced: true}`, so the hub keeps the latch across relay restarts (it replays `preview.state {previewToken, quiet, announced}` to a leader that connects, with `bridge.connected {…, replay: true}` for tabs already there, which are neither recorded nor announced again).
|
|
194
|
+
|
|
195
|
+
**Where events go:**
|
|
196
|
+
|
|
197
|
+
- A `--foreground` `scserve --bridge` prints one line per event to stderr, `scserve: connected <connId> <origin> <userAgent>`, `scserve: disconnected <connId> <reason>`, `scserve: emit <connId> <name> <detail>`; with `--json`, stdout has one JSON object per event after the record: `{"event": "connected"|"disconnected"|"emit", "previewToken", "connId", "at", …}`, the record's fields.
|
|
198
|
+
- `scserve --logs [TOKEN|URL] [--lines N]` asks the relay for them: `Preview lifecycle records (oldest to newest):`, then `<at> <event> <announced|suppressed|-> preview=<token> conn=<connId> <origin=… userAgent=…|reason=…|name=… detail=…>` per record, or `no lifecycle records (the relay keeps them in memory, so they are gone when it restarts)`; `--json` prints the array. A target that matches no bridged preview is `scserve: no preview matches X` (exit 1); no relay running is no records.
|
|
199
|
+
- `scserve --truncate [TOKEN|URL]` clears them (of that preview, or all), re-arms the first-visit announcement of each matching bridged preview (`preview.state.update {announced: false}`), and prints `cleared <n> records, re-armed <m> previews` (`--json`: `{"cleared": n, "rearmed": m}`).
|
|
200
|
+
|
|
133
201
|
## The tray hub
|
|
134
202
|
|
|
135
203
|
`scserve` talks to the tray hub at `https://www.sliccy.ai` (`SLICC_TRAY_HUB` replaces it, for tests and staging) with the same API as slicc 6 and seven. Nothing on the hub changes for it:
|
|
@@ -160,7 +228,7 @@ The controller token goes in `Authorization: Bearer` to the hub's origin only. A
|
|
|
160
228
|
| --- | --- |
|
|
161
229
|
| `<config>/tray.json` (`0600`) | the current tray (`hub`, `trayId`, `controllerToken`, `controllerUrl`, `controllerId`, `leaderKey`) and retired trays that still hold snapshots |
|
|
162
230
|
| `<state>/previews/<id>.json` (`0600`) | one record per preview: what `--json` prints, plus the relay's pid |
|
|
163
|
-
| `<state>/relay.json` (`0600`), `relay.lock`, `relay.log` | the running relay's pid, control port and token |
|
|
231
|
+
| `<state>/relay.json` (`0600`), `relay.lock`, `relay.log` | the running relay's pid, control port and token, and once a bridged preview is up its CDP port and secret |
|
|
164
232
|
|
|
165
233
|
`<config>` is `$XDG_CONFIG_HOME/slicc/serve` (default `~/.config/slicc/serve`), `%APPDATA%\slicc\serve` on Windows; `<state>` is `$XDG_STATE_HOME/slicc/serve` (default `~/.local/state/slicc/serve`), `%LOCALAPPDATA%\slicc\serve` on Windows. `SCSERVE_CONFIG_DIR` and `SCSERVE_STATE_DIR` replace them. Directories are `0700`; files are written to a temporary name and renamed.
|
|
166
234
|
|
|
@@ -192,7 +260,7 @@ The options, the output, `--json` and the exit status are the host's, with `serv
|
|
|
192
260
|
|
|
193
261
|
- **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
262
|
- **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`**
|
|
263
|
+
- **`--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
264
|
- **`--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
265
|
- **`--upgrade`** prints `pnpm add -g @ai-ecoverse/slicc-serve@latest`.
|
|
198
266
|
|
|
@@ -210,7 +278,7 @@ serve DIR ──spawn──► serve (background, one per preview)
|
|
|
210
278
|
- **`--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
279
|
- **`--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
280
|
- **`--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.
|
|
281
|
+
- **`--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
282
|
- **`--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
283
|
- **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
284
|
|
|
@@ -229,13 +297,16 @@ A failure the tray hub answered comes as the reply's first line instead (`{"erro
|
|
|
229
297
|
|
|
230
298
|
### The embedder contract
|
|
231
299
|
|
|
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}`,
|
|
300
|
+
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
301
|
|
|
234
302
|
| kind | options | opened | reply | errors |
|
|
235
303
|
| --- | --- | --- | --- | --- |
|
|
236
304
|
| `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
305
|
| `serve.list` | none | `O_RDWR` | one JSON line per preview, then end-of-file; nothing when there are none | `ENOTSUP`, `EIO` |
|
|
238
306
|
| `serve.stop` | `previewToken` | `O_WRONLY` | none; the close returns the errno | `ENOENT`, `ENOTSUP`, `EIO` |
|
|
307
|
+
| `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` |
|
|
308
|
+
| `serve.logs` | `previewToken` (optional) | `O_RDWR` | one JSON line per lifecycle record, oldest first, then end-of-file | `ENOENT`, `ENOTSUP` |
|
|
309
|
+
| `serve.truncate` | `previewToken` (optional) | `O_RDWR` | one JSON line `{"cleared", "rearmed"}` | `ENOENT`, `ENOTSUP` |
|
|
239
310
|
|
|
240
311
|
#### `serve.publish`
|
|
241
312
|
|
|
@@ -250,6 +321,9 @@ This is what seven's page answers ([#6](https://github.com/ai-ecoverse/slicc-ser
|
|
|
250
321
|
| `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` |
|
|
251
322
|
| `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`) |
|
|
252
323
|
| `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 |
|
|
324
|
+
| `bridge` | `true` with `--bridge`, else absent: see [The bridge in seven](#the-bridge-in-seven) |
|
|
325
|
+
| `maxTabs` | number, 1 to 100, with `bridge` only (default 20) |
|
|
326
|
+
| `quiet` | `true` with `--quiet`, with `bridge` only |
|
|
253
327
|
|
|
254
328
|
What the page does, in order:
|
|
255
329
|
|
|
@@ -274,7 +348,7 @@ The relay itself (`preview.request` → `kernel.loopbackFetch(GET <path>, {port,
|
|
|
274
348
|
{"kind":"serve.list"}
|
|
275
349
|
```
|
|
276
350
|
|
|
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"}
|
|
351
|
+
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
352
|
|
|
279
353
|
#### `serve.stop`
|
|
280
354
|
|
|
@@ -282,7 +356,55 @@ The reply is one JSON object per line for each preview the page holds from `serv
|
|
|
282
356
|
{"kind":"serve.stop","previewToken":"0f3c….a91e…"}
|
|
283
357
|
```
|
|
284
358
|
|
|
285
|
-
The page revokes the preview on the hub, drops it, and ends
|
|
359
|
+
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.
|
|
360
|
+
|
|
361
|
+
#### `serve.snapshot`
|
|
362
|
+
|
|
363
|
+
```
|
|
364
|
+
{"kind":"serve.snapshot","root":"/home/me/site","ttlMs":604800000,"files":2,"bytes":1843}
|
|
365
|
+
{"path":"index.html","type":"text/html; charset=utf-8","size":1800}
|
|
366
|
+
<1800 bytes>
|
|
367
|
+
{"path":"app/main.js","type":"text/javascript; charset=utf-8","size":43}
|
|
368
|
+
<43 bytes>
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
`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.
|
|
372
|
+
|
|
373
|
+
| option | |
|
|
374
|
+
| --- | --- |
|
|
375
|
+
| `root` | string: the directory's absolute path, for the prompt only |
|
|
376
|
+
| `entry` | string, absent without `--entry`: normalized as for `serve.publish` |
|
|
377
|
+
| `ttlMs` | number: the TTL in milliseconds, 60000 to 2592000000 (30 days) |
|
|
378
|
+
| `files`, `bytes` | numbers: how many files and bytes the body holds, for the prompt and to check the body against |
|
|
379
|
+
|
|
380
|
+
**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.
|
|
381
|
+
|
|
382
|
+
What the page does, in order:
|
|
383
|
+
|
|
384
|
+
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.
|
|
385
|
+
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.
|
|
386
|
+
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.
|
|
387
|
+
4. **The finalize:** `POST /api/tray/<trayId>/preview/<previewToken>/finalize` with the upload token, once the body has ended.
|
|
388
|
+
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.
|
|
389
|
+
|
|
390
|
+
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.
|
|
391
|
+
|
|
392
|
+
|
|
393
|
+
- **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>`.
|
|
394
|
+
- **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.
|
|
395
|
+
- **The hub can't be reached:** the page stops a minted snapshot if it can, and throws an `EIO` error with the reason.
|
|
396
|
+
- **`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`.
|
|
397
|
+
|
|
398
|
+
### The bridge in seven
|
|
399
|
+
|
|
400
|
+
`serve --bridge DIR` in seven is the same preview, with seven's page as the leader that the hub's `bridge.*` messages reach. `serve` sends `bridge`, `maxTabs` and `quiet` with `serve.publish`, and the options and output are the host's, except that the targets show up on seven's own CDP endpoint instead of a local one: `serve: its visitor tabs are CDP targets preview:<token>:* on $SLICC_CDP_URL`. What the page does:
|
|
401
|
+
|
|
402
|
+
1. **The mint** adds `bridge: true`, `maxTabs`, `quiet` and `webhookId: "serve-<16 hex>"` (a fresh name for each preview, matching seven's webhook names) to the mint. The prompt says so: "Publish /home/me/app at a public URL, and let the agent drive the tabs of whoever opens it?" The reply's first line adds `"webhook": "serve-<16 hex>"`. A reply without it comes from a seven that doesn't know the bridge and published without one: `serve` then ends the request, so the page revokes the preview, and exits 1 with `serve: this seven publishes without the bridge, so serve stopped the preview again; --bridge needs a newer slicc-bios`.
|
|
403
|
+
2. **Visitor tabs as targets.** For each `bridge.connected` of a preview the page holds, the page adds a target `preview:<token>:<connId>` (`type: "page"`, the preview's URL and the connection's origin, as on a host) to the `Target` domain its CDP hook emulates for kernel programs (`SLICC_CDP_URL`), and drops it on `bridge.disconnected` or when the preview stops. It answers in a session exactly as the host's relay does ([The bridge](#the-bridge---bridge)): the same synthetic methods and navigation events, everything else as `bridge.cdp.request` over the tray's controller socket, the same errors and the same 30 s timeout; `Target.closeTarget` sends `bridge.close`. The targets pass the same guard as seven's other targets: a connection seven wouldn't let drive a tab doesn't see them, and whatever seven asks before an agent drives a tab, it asks here. `bridge.connected` with `replay: true` restores a target without recording or announcing it. A `bridge.cdp.response` for a `connId` the page doesn't know is dropped.
|
|
404
|
+
3. **Emits** arrive as `webhook.event {webhookId: "serve-…", headers: {"x-slicc-preview-conn", "x-slicc-preview-token"}, body: {name, detail}}`, which seven already delivers to the agent as a webhook of that name. The page delivers them only while it holds the preview, and drops them after it stopped.
|
|
405
|
+
4. **The first visit** of a preview that isn't `quiet` is delivered to the agent on the same webhook, as a delivery with the header `x-slicc-preview-lifecycle: connected`, the headers above and the body `{"origin", "userAgent", "connectedAt"}`; then the page sends `preview.state.update {previewToken, announced: true}`. The page restores `quiet` and `announced` from the hub's `preview.state` when it connects.
|
|
406
|
+
5. **Lifecycle records:** the page keeps the last 500 records of the previews it holds from `serve.publish`, in memory, with the host's fields (`at`, `event`, `previewToken`, `connId`, `announced`, `origin`, `userAgent`, `connectedAt`, `reason`, `name`, `detail` cut to 1,000 characters). `serve.logs` answers them as JSON lines, of one preview or of all, filtered by uid as `serve.list` is (a `previewToken` the caller can't see is `ENOENT`, `seven holds no preview <token>`); `serve.truncate` clears them and re-arms the announcement (`preview.state.update {announced: false}`), and answers `{"cleared", "rearmed"}`. `serve --logs` and `serve --truncate` print them as on a host.
|
|
407
|
+
6. **`--foreground`** gets each event as a line of the held `serve.publish` reply after the first, `{"event": "connected"|"disconnected"|"emit", …}` with the record's fields, and prints it as a host `--foreground` does; a detached `serve`'s reply gets the same lines and ignores them. A `serve` built before the bridge reads only `stopped` from those lines, and ignores the rest.
|
|
286
408
|
|
|
287
409
|
## Development
|
|
288
410
|
|
|
@@ -295,7 +417,7 @@ npm run build:wasm
|
|
|
295
417
|
|
|
296
418
|
- `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
419
|
- `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.
|
|
420
|
+
- `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. `slicc-cdp.test.mjs` downloads `playwright-cli` and `curlwright` for the platform from a pinned [slicc-cdp](https://github.com/ai-ecoverse/slicc-cdp) release (checked against its `SHA256SUMS`, cached in `node_modules/.cache/`) and runs them against a visitor tab (`visitor.mjs`, which answers as the hub's bootstrap does, evaluating in a `node:vm` context with a stand-in `document`): `tab-list`, `eval`, `snapshot`, `screenshot`, `goto`, a `curlwright` request, and a relay reconnect that keeps one tab's target id and drops a tab that closed meanwhile. `bridge.test.mjs` plays the visitor's tab against the fake hub's `/__slicc/bridge` (`hub.tab(url)`, answering `cdp.req` frames and sending emits) and drives the relay's CDP endpoint with Node's `WebSocket`: the guards (secret, `Host`, `Origin`), `/json/*`, discovery, attach and auto-attach, the synthetic and forwarded methods, navigation events, a tab that goes away mid-call, `closeTarget`, `--stop`, `--max-tabs`, `--quiet`, the first-visit latch through `preview.state.update`, `--logs`, `--truncate`, and an emit full of escape sequences. `install.test.mjs` runs `install.sh` and `--upgrade` against local release directories.
|
|
299
421
|
- `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
422
|
|
|
301
423
|
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.3.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.3.0",
|
|
35
|
+
"@ai-ecoverse/slicc-serve-darwin-x64": "1.3.0",
|
|
36
|
+
"@ai-ecoverse/slicc-serve-linux-arm64": "1.3.0",
|
|
37
|
+
"@ai-ecoverse/slicc-serve-linux-x64": "1.3.0",
|
|
38
|
+
"@ai-ecoverse/slicc-serve-win32-arm64": "1.3.0",
|
|
39
|
+
"@ai-ecoverse/slicc-serve-win32-x64": "1.3.0"
|
|
40
40
|
}
|
|
41
41
|
}
|