@ai-ecoverse/slicc-serve 1.2.0 → 1.3.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 +90 -5
- 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,55 @@ 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, using only the bootstrap's `Runtime.evaluate`. With it, `tab-list`, `eval` (expressions and functions), `snapshot`, `click`, `fill`, `type`, `press`, `screenshot`, `goto` and `curlwright` requests work on `preview:<token>:<connId>` targets (`playwright-cli --cdp <the endpoint's ws URL>`), each action exactly once:
|
|
184
|
+
|
|
185
|
+
- **Results:** every `Runtime.evaluate` goes to the tab wrapped as `(0, eval)(<the expression>)` whose awaited result the page describes as JSON: with `returnByValue`, its value (with `NaN`, `Infinity`, `-0` and BigInts as `unserializableValue`, and inside arrays and objects as `JSON.stringify` writes them); without, its type, subtype (`null`, `array`, `node`, `error`), class and description, and for an object or a function a handle.
|
|
186
|
+
- **Object handles:** the page keeps each object a result hands out in a registry of its own (`globalThis[Symbol.for('scserve.bridge')]`), and its `objectId` names that entry. `Runtime.callFunctionOn` calls the function on the object itself, with handles and values as arguments, so the expression that produced a handle never runs again; the function is compiled by the page's indirect `eval`, at its global scope, so it sees the page's globals and none of the bridge's names. `Runtime.getProperties` lists a handle's own string-keyed properties from their descriptors, reporting an accessor's `get` and `set` without calling them (and only accessors with `accessorPropertiesOnly`); `DOM.describeNode` (by `objectId` or `backendNodeId`) and `DOM.resolveNode` (by `backendNodeId`) work for DOM nodes, with backend node ids the page numbers itself. `Runtime.releaseObject` and `Runtime.releaseObjectGroup` drop entries (a handle joins the `objectGroup` of the `Runtime.evaluate`, `Runtime.callFunctionOn` or `DOM.resolveNode` that made it); a navigation drops them all, and a handle used after that is `-32000` (`the object is gone from the visitor's page`). Other methods that take an `objectId` of the bridge are `-32000`.
|
|
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 trusted input:** a page script can only dispatch events with `isTrusted` false, so `Input.dispatchMouseEvent`, `Input.dispatchKeyEvent` and `Input.insertText` answer `{}` and dispatch nothing (the bootstrap's own, which clicks on a mouse press, would act a second time). `playwright-cli` checks whether its trusted input landed and otherwise dispatches the events in the page itself, which is what happens here, once. A client that relies on `Input.*` alone does nothing through the bridge, and a page that ignores untrusted events (`if (!event.isTrusted) return`) doesn't react.
|
|
189
|
+
- **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.
|
|
190
|
+
- **Not through the bridge:** console, network and dialog events, the `DOM` domain's node ids (`DOM.getDocument` and `DOM.querySelector` are the bootstrap's), PDF, screencasts, downloads, and a page whose own CSP forbids `eval` (the bootstrap's evaluation is the page's indirect `eval`).
|
|
191
|
+
|
|
192
|
+
**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.
|
|
193
|
+
|
|
194
|
+
**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).
|
|
195
|
+
|
|
196
|
+
**Where events go:**
|
|
197
|
+
|
|
198
|
+
- 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.
|
|
199
|
+
- `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 preview the relay bridged is `scserve: no preview matches X` (exit 1); no relay running is no records. A stopped preview's records stay until `--truncate` or until the relay exits.
|
|
200
|
+
- `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}`).
|
|
201
|
+
|
|
133
202
|
## The tray hub
|
|
134
203
|
|
|
135
204
|
`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 +229,7 @@ The controller token goes in `Authorization: Bearer` to the hub's origin only. A
|
|
|
160
229
|
| --- | --- |
|
|
161
230
|
| `<config>/tray.json` (`0600`) | the current tray (`hub`, `trayId`, `controllerToken`, `controllerUrl`, `controllerId`, `leaderKey`) and retired trays that still hold snapshots |
|
|
162
231
|
| `<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 |
|
|
232
|
+
| `<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
233
|
|
|
165
234
|
`<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
235
|
|
|
@@ -237,6 +306,8 @@ This is what seven's page answers ([#6](https://github.com/ai-ecoverse/slicc-ser
|
|
|
237
306
|
| `serve.list` | none | `O_RDWR` | one JSON line per preview, then end-of-file; nothing when there are none | `ENOTSUP`, `EIO` |
|
|
238
307
|
| `serve.stop` | `previewToken` | `O_WRONLY` | none; the close returns the errno | `ENOENT`, `ENOTSUP`, `EIO` |
|
|
239
308
|
| `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` |
|
|
309
|
+
| `serve.logs` | `previewToken` (optional) | `O_RDWR` | one JSON line per lifecycle record, oldest first, then end-of-file | `ENOENT`, `ENOTSUP` |
|
|
310
|
+
| `serve.truncate` | `previewToken` (optional) | `O_RDWR` | one JSON line `{"cleared", "rearmed"}` | `ENOENT`, `ENOTSUP` |
|
|
240
311
|
|
|
241
312
|
#### `serve.publish`
|
|
242
313
|
|
|
@@ -251,6 +322,9 @@ This is what seven's page answers ([#6](https://github.com/ai-ecoverse/slicc-ser
|
|
|
251
322
|
| `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` |
|
|
252
323
|
| `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`) |
|
|
253
324
|
| `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 |
|
|
325
|
+
| `bridge` | `true` with `--bridge`, else absent: see [The bridge in seven](#the-bridge-in-seven) |
|
|
326
|
+
| `maxTabs` | number, 1 to 100, with `bridge` only (default 20) |
|
|
327
|
+
| `quiet` | `true` with `--quiet`, with `bridge` only |
|
|
254
328
|
|
|
255
329
|
What the page does, in order:
|
|
256
330
|
|
|
@@ -322,6 +396,17 @@ When it fails, the page answers at once, without reading the rest of the body: w
|
|
|
322
396
|
- **The hub can't be reached:** the page stops a minted snapshot if it can, and throws an `EIO` error with the reason.
|
|
323
397
|
- **`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`.
|
|
324
398
|
|
|
399
|
+
### The bridge in seven
|
|
400
|
+
|
|
401
|
+
`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:
|
|
402
|
+
|
|
403
|
+
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`.
|
|
404
|
+
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.
|
|
405
|
+
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.
|
|
406
|
+
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.
|
|
407
|
+
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.
|
|
408
|
+
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.
|
|
409
|
+
|
|
325
410
|
## Development
|
|
326
411
|
|
|
327
412
|
```sh
|
|
@@ -333,7 +418,7 @@ npm run build:wasm
|
|
|
333
418
|
|
|
334
419
|
- `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.
|
|
335
420
|
- `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`.
|
|
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.
|
|
421
|
+
- `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. `browser.test.mjs` opens the preview in a real Chrome for Testing (a pinned version, installed with `@ai-ecoverse/slicc-cdp`'s `installBrowser` into `node_modules/.cache/browsers` and launched headless with `launchBrowser`), where the fake hub injects slicc 6's real bridge bootstrap (`@ai-ecoverse/cherry`'s `preview-bridge.js`, the bundle slicc's worker serves); `playwright-cli` then snapshots, clicks, fills, types and presses Enter in it through `scserve --bridge`, and the test reads the page's own state to check each happened exactly once, and that `Runtime.callFunctionOn` on a handle doesn't run the handle's expression again. `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.
|
|
337
422
|
- `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.
|
|
338
423
|
|
|
339
424
|
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.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": {
|
|
@@ -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.1",
|
|
35
|
+
"@ai-ecoverse/slicc-serve-darwin-x64": "1.3.1",
|
|
36
|
+
"@ai-ecoverse/slicc-serve-linux-arm64": "1.3.1",
|
|
37
|
+
"@ai-ecoverse/slicc-serve-linux-x64": "1.3.1",
|
|
38
|
+
"@ai-ecoverse/slicc-serve-win32-arm64": "1.3.1",
|
|
39
|
+
"@ai-ecoverse/slicc-serve-win32-x64": "1.3.1"
|
|
40
40
|
}
|
|
41
41
|
}
|