@ai-ecoverse/slicc-serve 0.0.0 → 1.0.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/LICENSE +201 -0
- package/README.md +207 -5
- package/bin/scserve.js +74 -0
- package/bin/serve.wasm +0 -0
- package/package.json +37 -1
package/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright [yyyy] [name of copyright owner]
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/README.md
CHANGED
|
@@ -1,9 +1,211 @@
|
|
|
1
|
-
#
|
|
1
|
+
# slicc-serve
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`scserve` publishes a directory, or a server that already runs on this machine, at a public capability URL on `sliccy.now`, through the SLICC tray hub. It is slicc 6's `serve` for any host: `scserve ./dist` prints `https://<label>.sliccy.now/` and returns, and anyone with the URL sees the files, pulled from this machine on demand while it is online. `scserve --port 5173` does the same for vite, `python -m http.server` or any other local server, and `scserve --ttl 7d ./dist` uploads an immutable snapshot that stays up without this machine.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
In SLICC the same program is `serve` and `scserve` (`bin/serve.wasm`). There it serves a directory on the kernel's loopback with `--local` today; publishing from SLICC goes through seven's page and comes later (see [In SLICC](#in-slicc)).
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
This README is the spec. The plan is [#1](https://github.com/ai-ecoverse/slicc-serve/issues/1).
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
curl -fsSL https://github.com/ai-ecoverse/slicc-serve/releases/latest/download/install.sh | sh
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
On Windows, in PowerShell:
|
|
16
|
+
|
|
17
|
+
```powershell
|
|
18
|
+
irm https://github.com/ai-ecoverse/slicc-serve/releases/latest/download/install.ps1 | iex
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
With npm (Node 18 or later), which picks the binary for the platform from an optional dependency:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
npm install -g @ai-ecoverse/slicc-serve
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
In SLICC, `pnpm add -g @ai-ecoverse/slicc-serve` puts `serve` and `scserve` in `/usr/bin` (the package declares both in `slicc.commands` with `abi: wasi`).
|
|
28
|
+
|
|
29
|
+
Binaries: macOS (arm64, x86-64, signed and notarized), Linux (arm64, x86-64, static musl) and Windows (arm64, x86-64). [The installers](#the-installers) has the details.
|
|
30
|
+
|
|
31
|
+
## Usage
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
scserve [--entry FILE] [--ttl DURATION] [--local] [--foreground] [--open] [--json] DIRECTORY
|
|
35
|
+
scserve --port PORT [--entry PATH] [--local] [--foreground] [--open] [--json]
|
|
36
|
+
scserve --list [--json]
|
|
37
|
+
scserve --stop TOKEN|URL [--json]
|
|
38
|
+
scserve --version | --upgrade | --help
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
| option | does |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `DIRECTORY` | serves its files with the built-in static server and publishes them |
|
|
44
|
+
| `--port PORT` | publishes the server that already runs on `127.0.0.1:PORT` instead (1 to 65535) |
|
|
45
|
+
| `--entry FILE` | the page the URL opens, relative to the directory (or a path on the server); default: the directory's index |
|
|
46
|
+
| `--ttl DURATION` | publishes an immutable snapshot for `DURATION`: a whole number and `m`, `h`, `d` or `w`, at most `30d` |
|
|
47
|
+
| `--local` | stays on this machine: no tray hub, prints `http://127.0.0.1:PORT/` only |
|
|
48
|
+
| `--foreground` | stays attached instead of returning; Ctrl-C (or the end of the process) stops the preview |
|
|
49
|
+
| `--open` | opens the URL with the platform's opener once it is published (and a sign-in page, see [The tray hub](#the-tray-hub)) |
|
|
50
|
+
| `--json` | prints the result, or the error, as one JSON object (an array for `--list`) |
|
|
51
|
+
| `--list` | lists the previews this machine published |
|
|
52
|
+
| `--stop TOKEN\|URL` | stops a preview, by its token, its public URL or its local URL |
|
|
53
|
+
| `--version` | prints the version alone (`1.2.0`) |
|
|
54
|
+
| `--upgrade` | see [`--upgrade`](#--upgrade) |
|
|
55
|
+
| `-h`, `--help` | prints the usage and the options to stdout and exits 0, wherever it appears among the options |
|
|
56
|
+
|
|
57
|
+
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 `/`.
|
|
58
|
+
|
|
59
|
+
Slicc 6's `--bridge`, `--no-bridge`, `--max-tabs`, `--quiet`, `--logs`, `--lines` and `--truncate` are recognised and refused with `scserve: <option> is not supported yet` (exit 2); they come with the bridge work ([#1](https://github.com/ai-ecoverse/slicc-serve/issues/1), M5). `--project` is refused with `scserve: --project is obsolete: give the directory to serve itself`.
|
|
60
|
+
|
|
61
|
+
### Exit status
|
|
62
|
+
|
|
63
|
+
**0** ok, **1** failure (a missing directory, the hub's error, an unreachable hub), **2** usage error (`scserve: <what is wrong>` and the usage on stderr), **3** the tray hub wants a sign-in or refused the request, **4** a quota of the tray hub is used up. With `--json`, a failure also prints `{"ok":false,"exit":N,"lines":[…],"signIn":URL|null}` to stdout.
|
|
64
|
+
|
|
65
|
+
### Output
|
|
66
|
+
|
|
67
|
+
On success, stdout is the URL alone (so `url=$(scserve dist)` works), and stderr says what it means:
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
$ scserve ./site
|
|
71
|
+
https://0f3c…--a91e….sliccy.now/
|
|
72
|
+
scserve: /home/me/site is public at https://0f3c…--a91e….sliccy.now/ (here: http://127.0.0.1:52811/)
|
|
73
|
+
scserve: stop it with: scserve --stop 0f3c….a91e…
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`--json` prints the record instead: `mode` (`live`, `persistent` or `local`), `previewToken`, `url`, `localUrl`, `root`, `port`, `entry`, `trayId`, `createdAt`, `expiresAt`, `foreground`, and for a snapshot `files` and `bytes`.
|
|
77
|
+
|
|
78
|
+
Without `--entry`, the URL ends in `/` and opens what the server answers there: `index.html`, else a directory listing (the hub's `entryPath` is still `…/index.html`; the relay maps it to `/`). With `--entry`, the URL names the entry.
|
|
79
|
+
|
|
80
|
+
## What runs where
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
scserve DIR ──spawn──► relay (scserve __relay, detached, one per user)
|
|
84
|
+
├─ static server on 127.0.0.1:<random> per directory
|
|
85
|
+
└─ controller WebSocket of this machine's tray ◄── tray hub ◄── visitor
|
|
86
|
+
preview.request ──GET──► 127.0.0.1:<port> ──► preview.response chunks
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- **The relay.** The hub lets one leader socket per tray, so one process holds it for every preview: `scserve` starts `scserve __relay` detached (its own session on Unix, `DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP` on Windows, with the caller's standard handles not inherited), hands it the preview over a loopback control socket, prints the answer and exits. The relay runs the static servers, holds the tray's controller WebSocket, answers the hub's `preview.request` with an HTTP GET to the preview's origin, and exits 5 s after its last preview stops. Its control socket is on `127.0.0.1` with a random port and a 48-hex-digit token in `relay.json` (mode `0600`); a request without the token is dropped. A lock (`relay.lock`) keeps it to one relay per state directory; its stderr goes to `relay.log`.
|
|
90
|
+
- **`--foreground`** keeps the control connection open instead of returning: the relay streams one line per visit (`scserve: GET /app.js 200 1234`) to stderr, and when the connection ends (Ctrl-C, the process killed, the terminal closed) it revokes the preview on the hub and stops its server. A `--stop` from elsewhere ends the foreground `scserve` with `scserve: stopped: <reason>` and exit 0.
|
|
91
|
+
- **`--local`** never talks to the hub. `--local DIR` runs the static server in the relay (listed, stopped with `--stop <local URL>`); `--local --foreground DIR` runs it in the `scserve` process itself and logs each request; `--local --port PORT` only prints `http://127.0.0.1:PORT/[ENTRY]` (with `scserve: nothing answers on 127.0.0.1:PORT yet` when nothing does).
|
|
92
|
+
- **`--port`** publishes an existing server: the relay forwards each visit's path to `127.0.0.1:PORT` (and warns the same way when nothing answers yet). It is published with `allowLive: true`, so the hub doesn't cache it; a directory is published with `allowLive: false` (the hub's 5 s edge cache).
|
|
93
|
+
- **`--ttl`** needs nothing running: `scserve` itself walks the directory, mints the snapshot, uploads the files and finalizes it, then exits.
|
|
94
|
+
|
|
95
|
+
### The static server
|
|
96
|
+
|
|
97
|
+
The built-in server answers `GET` and `HEAD` (others `405` with `Allow: GET, HEAD`) on `127.0.0.1` only, as the user who ran `scserve`, so file permissions hold.
|
|
98
|
+
|
|
99
|
+
- **Paths** are percent-decoded once and split on `/`. A segment that is `.` or `..`, or holds `\`, `:` or NUL, or a path that doesn't decode to UTF-8, is `400`. A segment starting with `.` (`.env`, `.git`) is hidden: `404`, never listed, never snapshotted; `.well-known` is the exception. The resolved file must lie inside the directory after symlinks are resolved, with no hidden segment in its resolved path; a symlink out of it, or to a hidden file or directory (`public.txt -> .env`), is `404`, and `--entry` naming either is `entry file not found`. Names that aren't UTF-8 are skipped.
|
|
100
|
+
- **Directories:** a path without its trailing `/` is `301` to the same path with it (query kept); with it, `index.html` if there is one, else an HTML listing of the visible entries.
|
|
101
|
+
- **Files** get `Content-Type` from the extension (`text/html; charset=utf-8`, `text/css`, `text/javascript`, `application/json`, `image/*`, `font/*`, `video/*`, `audio/*`, `application/wasm`, …; unknown is `application/octet-stream`), `Content-Length`, `Last-Modified`, `Accept-Ranges: bytes`, `Cache-Control: no-cache` and `X-Content-Type-Options: nosniff`.
|
|
102
|
+
- **Ranges:** one `bytes=a-b`, `bytes=a-` or `bytes=-n` range is `206` with `Content-Range`; one outside the file is `416` with `Content-Range: bytes */size`; several ranges, another unit or an `If-Range` get the whole file (`200`), as slicc 6's `parseByteRange` does.
|
|
103
|
+
- HTTP/1.1 keep-alive, a 16 KiB limit on the request head (`431`), and a 30 s idle timeout per connection.
|
|
104
|
+
|
|
105
|
+
### The relay's answers
|
|
106
|
+
|
|
107
|
+
The hub sends `preview.request {reqId, servedRoot, vfsPath, asText, range?}`; the relay answers with `preview.response` messages, exactly as slicc 6's leader does:
|
|
108
|
+
|
|
109
|
+
- `vfsPath` must lie inside `servedRoot` (no `.`/`..` segments, no `%2e`, `servedRoot` never `/`), else `403`; a `servedRoot` the relay doesn't serve (any more) is `404`.
|
|
110
|
+
- The path under `servedRoot` goes to the origin as it came (still percent-encoded); the query string is not part of the hub's request. The entry path of a preview without `--entry` goes to `/`. Same-origin redirects of the origin (`301`, `302`, `303`, `307`, `308` to `127.0.0.1:PORT` or `localhost:PORT`) are followed, at most 5; others are passed on as their status.
|
|
111
|
+
- `200`: the body (at most 25 MiB; more, or a larger `Content-Length`, is `413` `preview file exceeds 25 MiB limit`) in chunks of 64 KiB, as UTF-8 when the hub asked for text and the body is valid UTF-8, else base64, each chunk with `mime` (the origin's `Content-Type`, else from the extension), `chunkIndex`, `totalChunks`, `status: 200` and `size`.
|
|
112
|
+
- `206`: the window, cut to 8 MiB (media players ask for the next one), always base64, with `status: 206`, `size` (the whole entity) and `range: {start, end}`. `416` passes `size` from `Content-Range: bytes */size`.
|
|
113
|
+
- Any other status is `ok: false` with that status and the first 4 KiB of the body as `reason`. An origin that doesn't answer is `502` `nothing answers on 127.0.0.1:PORT: …`.
|
|
114
|
+
- `preview.revoked` stops the preview locally (its server, its record, a foreground holder). Other messages are ignored. The relay sends `{"type":"ping"}` every 30 s, because the hub counts a leader without application messages for 2 minutes as gone.
|
|
115
|
+
- **When the socket drops**, the relay claims the tray again and reconnects after 1, 2, 5, 10, then every 30 s, while it has public previews. If the tray is gone or refused, its live previews are stopped. When it (re)connects, it lists the tray's previews and revokes live ones it doesn't serve, left over from a relay that died.
|
|
116
|
+
|
|
117
|
+
### Snapshots (`--ttl`)
|
|
118
|
+
|
|
119
|
+
`scserve --ttl 7d DIR` collects the visible files (hidden ones, symlinks out of the directory and symlinks to hidden files excluded, each directory walked once so links between directories can't loop, sorted), refuses more than 1,000 files, a file over 25 MiB or more than 50 MiB in total before anything is sent, and needs its entry file (`index.html` by default; `scserve: DIR has no index.html; a --ttl snapshot needs its entry file (give one with --entry)`). It mints with `ttlMs`, uploads the files four at a time (`PUT …/preview/<token>/file?path=<path>` with the upload token and each file's type), finalizes, and prints the URL. If an upload or the finalize fails, it stops the snapshot on the hub before it exits. A snapshot counts toward the tray's 10-snapshot quota (`429 PREVIEW_LIMIT`, exit 4), lasts until its TTL, and is served by the hub without this machine. Subdirectory index pages aren't reachable by their directory URL in a snapshot (the hub serves stored paths only); link to `sub/index.html`.
|
|
120
|
+
|
|
121
|
+
### `--list` and `--stop`
|
|
122
|
+
|
|
123
|
+
`--list` asks the hub for the previews of this machine's tray (and of [retired trays](#state) that still hold snapshots), joins them with the local records, and prints `TOKEN MODE EXPIRES URL ROOT`: `live`, `snapshot`, `uploading` or `local`, `(foreground)` for an attached one. Records whose relay is gone, snapshots past their expiry and previews the hub no longer has are dropped. `no previews` when there are none.
|
|
124
|
+
|
|
125
|
+
`--stop` takes a preview token, a public URL (its host encodes the token, as slicc 6's `previewTokenFromUrl` reads it), a local URL or a record id. A hub preview is stopped with the tray that minted it (`POST /api/tray/<trayId>/preview/stop`); the relay then gets `preview.revoked` and stops its server. A local preview is stopped through the relay. It prints `stopped <token or URL>`; `scserve: no preview matches X`, `scserve: <token> is not a preview of this machine's trays` and `scserve: the tray hub has no preview <token> (already stopped or expired)` exit 1.
|
|
126
|
+
|
|
127
|
+
## The tray hub
|
|
128
|
+
|
|
129
|
+
`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:
|
|
130
|
+
|
|
131
|
+
| call | what for |
|
|
132
|
+
| --- | --- |
|
|
133
|
+
| `POST /tray` `{}` | a tray of this machine's own, created once and kept in `tray.json` |
|
|
134
|
+
| `POST /controller/<token>` `{controllerId, leaderKey?, runtime: "slicc-serve/1"}` | claims the tray's leadership; the answer's `leaderKey` is saved |
|
|
135
|
+
| `GET /controller/<token>?controllerId=…&leaderKey=…` (WebSocket) | the controller socket, on the hub's origin as `ws:`/`wss:` |
|
|
136
|
+
| `POST /api/tray/<id>/preview` `{servedRoot, entryPath, allowLive, ttlMs?}` | mints a preview: `servedRoot` is `/srv/serve/<16 hex>`, opaque to the hub, and never the real path |
|
|
137
|
+
| `PUT /api/tray/<id>/preview/<token>/file?path=` and `POST …/finalize` | a snapshot's files, with the upload token |
|
|
138
|
+
| `POST /api/tray/<id>/preview/stop` `{previewToken}`, `GET /api/tray/<id>/previews` | `--stop`, `--list` and the relay's tidying |
|
|
139
|
+
|
|
140
|
+
The controller token goes in `Authorization: Bearer` to the hub's origin only. Anonymous trays are what the hub offers today; `scserve` is ready for the hub to gate them, and maps every answer of every call above, and of the WebSocket upgrade (any answer but `101`), the same way:
|
|
141
|
+
|
|
142
|
+
- **3xx** is never followed blindly. A `Location` on another origin (an auth page), or on the hub's own origin outside the API (`/tray`, `/api/…`, `/controller/…`), exits 3 with `scserve: the tray hub wants you to sign in: <Location>`; with `--open`, or when you answer `y` on a terminal, the page opens. A same-origin redirect to an API path is followed, at most 5 times (a sixth exits 1, `redirected more than 5 times`), keeping method and body for `307`/`308` and switching to `GET` for `303` (and `301`/`302` after a `POST`); the bearer is only ever sent to the hub's origin.
|
|
143
|
+
- **401 and 403** exit 3 with the hub's `error` and `code`, and `scserve: sign in at <url>` from `Link: <url>; rel="login"` or the first URL in `WWW-Authenticate` (else the header itself). On a **saved** tray, a refusal drops the tray, creates a new one and retries once; a second refusal exits 3.
|
|
144
|
+
- **402 and 429** exit 4 with the hub's error and `scserve: retry after <Retry-After>`. The hub's quota codes name the remedy: `LIVE_PREVIEW_LIMIT` (`… (200 of 200 live previews in use); list them with scserve --list and stop the ones you no longer need with scserve --stop <token>`) and `PREVIEW_LIMIT` for snapshots.
|
|
145
|
+
- **404 and 410** on a saved tray (`TRAY_NOT_INITIALIZED`, `TRAY_EXPIRED`, a leadership the hub won't give back) create a new tray and retry once; elsewhere they exit 1. A tray expires an hour after its last leader left, so a machine that serves now and then gets a new tray, and new URLs, then.
|
|
146
|
+
- **Other 4xx** exit 1 with the hub's JSON `error` (`scserve: publishing: the tray hub answered 400: invalid preview entry path`).
|
|
147
|
+
- **5xx**, and a hub that can't be reached, are retried after 1, 2 and 5 s, then exit 1 (`the tray hub answered 503 4 times: …`).
|
|
148
|
+
|
|
149
|
+
`--list` and `--stop` drop a refused or vanished tray instead of creating one; a refused current tray still exits 3 there.
|
|
150
|
+
|
|
151
|
+
## State
|
|
152
|
+
|
|
153
|
+
| file | what |
|
|
154
|
+
| --- | --- |
|
|
155
|
+
| `<config>/tray.json` (`0600`) | the current tray (`hub`, `trayId`, `controllerToken`, `controllerUrl`, `controllerId`, `leaderKey`) and retired trays that still hold snapshots |
|
|
156
|
+
| `<state>/previews/<id>.json` (`0600`) | one record per preview: what `--json` prints, plus the relay's pid |
|
|
157
|
+
| `<state>/relay.json` (`0600`), `relay.lock`, `relay.log` | the running relay's pid, control port and token |
|
|
158
|
+
|
|
159
|
+
`<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.
|
|
160
|
+
|
|
161
|
+
## Opening
|
|
162
|
+
|
|
163
|
+
`--open` runs `open URL` on macOS, `xdg-open URL` (else `gio open URL`) on Linux and `explorer.exe URL` on Windows, with a fixed argv and no shell. An opener that is missing or fails prints `scserve: …` and leaves the exit status alone.
|
|
164
|
+
|
|
165
|
+
## `--upgrade`
|
|
166
|
+
|
|
167
|
+
A `scserve` from the installers downloads the latest `install.sh` (`install.ps1` on Windows) from `SLICC_INSTALL_BASE_URL` or the latest release, runs it with `--dir` set to the directory `scserve` is in, and prints `scserve: <old> → <new>` or `scserve: already up to date (<version>)`; a download that fails prints `scserve: could not download <url>: HTTP <status>` and exits 1. From npm (the launcher sets `SCSERVE_LAUNCHER=npm`), it prints `npm install -g @ai-ecoverse/slicc-serve@latest`; in SLICC, `pnpm add -g @ai-ecoverse/slicc-serve@latest`. On Windows the running `scserve.exe` is renamed to `scserve.exe.<random>.old` and replaced; the next run removes the old copy.
|
|
168
|
+
|
|
169
|
+
## The installers
|
|
170
|
+
|
|
171
|
+
`install.sh` (macOS, Linux) and `install.ps1` (Windows) download `SHA256SUMS` and the binary for the platform (`scserve-<darwin|linux>-<amd64|arm64>`, `scserve-windows-<amd64|arm64>.exe`) from `SLICC_INSTALL_BASE_URL` (the directory holding the release assets; default `https://github.com/ai-ecoverse/slicc-serve/releases/latest/download`, or `…/download/v<version>` with a version), refuse a checksum mismatch before anything is installed, run the binary's `--version` (which must equal `--version` when one is given), move it into place and print `scserve <version> installed to <path>`.
|
|
172
|
+
|
|
173
|
+
| `install.sh` | `install.ps1` | |
|
|
174
|
+
| --- | --- | --- |
|
|
175
|
+
| `--version VERSION` (or `=`; a leading `v` is dropped) | `-Version VERSION` | the release (default: the latest) |
|
|
176
|
+
| `--dir DIR` (or `=`) | `-Dir DIR` | where `scserve` goes (default `~/.local/bin`; `%LOCALAPPDATA%\slicc-serve\bin`, added to the user's `PATH`) |
|
|
177
|
+
| `--help` | `-Help` | the usage, exit 0 |
|
|
178
|
+
|
|
179
|
+
`install.sh` exits 0 when it installed, 1 on a failure (`install.sh: <what>`), 2 for a usage error; it needs `HOME` only for the default `--dir`. It uses `curl` (else `wget`) and `sha256sum` (else `shasum -a 256`), and never `sudo`. `install.ps1` run as a file exits 1 on failure; through `irm … | iex` it prints the error and returns without closing the shell.
|
|
180
|
+
|
|
181
|
+
## In SLICC
|
|
182
|
+
|
|
183
|
+
`serve.wasm` is built from the same crates for `wasm32-wasip1`, with `serve-core` (arguments, the static server, the snapshot walker, the records) shared with the host build and `wasix-net`'s sockets on the kernel's loopback. The kernel runs it as `serve` or `scserve`, and it names itself after the command it runs as.
|
|
184
|
+
|
|
185
|
+
Today, in SLICC:
|
|
186
|
+
|
|
187
|
+
- `serve --local DIR` runs the static server on the kernel's loopback in the foreground and prints `http://<port>.kernel.localhost/` (from `SLICC_PAGE_LOOPBACK_URL`, else `http://127.0.0.1:<port>/`); `serve --local --port PORT` prints that URL for a server that already runs.
|
|
188
|
+
- `--version`, `--help` and the usage errors behave as on a host; `--upgrade` prints `pnpm add -g @ai-ecoverse/slicc-serve@latest`.
|
|
189
|
+
- Everything that publishes exits 1 with `serve: publishing from SLICC needs seven's serve.publish, which isn't there yet; only --local works in SLICC so far`.
|
|
190
|
+
|
|
191
|
+
Publishing from seven goes through seven's page, which already leads a tray on the same hub: `serve` asks over `/dev/embedder` (`serve.publish`, `serve.snapshot`, `serve.list`, `serve.stop`), and the page relays `preview.request` to `kernel.loopbackFetch`. That is [#1](https://github.com/ai-ecoverse/slicc-serve/issues/1)'s M3 and M4, tracked in this repo's issues together with slicc-bios's side.
|
|
192
|
+
|
|
193
|
+
## Development
|
|
194
|
+
|
|
195
|
+
```sh
|
|
196
|
+
npm install
|
|
197
|
+
npm run lint
|
|
198
|
+
npm test
|
|
199
|
+
npm run build:wasm
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
- `crates/serve` is the binary (`scserve`, and `scserve.wasm` for the kernel); `crates/serve-core` has no host-only dependency and builds for `wasm32-wasip1`; `crates/serve-hub` (native only) is the hub client, the tray, the relay and the CLI.
|
|
203
|
+
- `npm run lint`: Biome, the no-comment check, `slicc-lint`, `shellcheck` and `dash -n` on `install.sh`, `cargo fmt`, and `cargo clippy` for the host and `wasm32-wasip1`.
|
|
204
|
+
- `npm test` builds `scserve` and runs `test/integration/` with Node's test runner. The hub there is `fake-hub.mjs`: trays, leader election, the controller WebSocket (`preview.request` to the relay and the chunks back, `preview.revoked`), mint, upload, finalize, stop and list, a visitor path that resolves `<label>.localhost` hosts like the preview worker, and injected answers per route for every class of error. Tests never reach `www.sliccy.ai`. `wasm.test.mjs` runs `bin/serve.wasm` under `node:wasi` (after `npm run build:wasm`), `install.test.mjs` runs `install.sh` and `--upgrade` against local release directories.
|
|
205
|
+
- `npm run test:unit` runs the unit tests in the gitignored `test/unit/` with `cargo llvm-cov`; the pre-commit hook wants 100% coverage of the changed lines in the crates it measures.
|
|
206
|
+
|
|
207
|
+
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.
|
|
208
|
+
|
|
209
|
+
## License
|
|
210
|
+
|
|
211
|
+
Apache-2.0
|
package/bin/scserve.js
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
const { spawn } = require('node:child_process');
|
|
4
|
+
const fs = require('node:fs');
|
|
5
|
+
const os = require('node:os');
|
|
6
|
+
const tty = require('node:tty');
|
|
7
|
+
|
|
8
|
+
const targets = new Set([
|
|
9
|
+
'darwin-arm64',
|
|
10
|
+
'darwin-x64',
|
|
11
|
+
'linux-arm64',
|
|
12
|
+
'linux-x64',
|
|
13
|
+
'win32-arm64',
|
|
14
|
+
'win32-x64',
|
|
15
|
+
]);
|
|
16
|
+
|
|
17
|
+
function fail(message) {
|
|
18
|
+
process.stderr.write(`scserve: ${message}\n`);
|
|
19
|
+
process.exit(1);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function binaryPath() {
|
|
23
|
+
const target = `${process.platform}-${process.arch}`;
|
|
24
|
+
if (!targets.has(target)) fail(`no scserve binary is published for ${target}`);
|
|
25
|
+
const pkg = `@ai-ecoverse/slicc-serve-${target}`;
|
|
26
|
+
const file = process.platform === 'win32' ? 'scserve.exe' : 'scserve';
|
|
27
|
+
let bin;
|
|
28
|
+
try {
|
|
29
|
+
bin = require.resolve(`${pkg}/bin/${file}`);
|
|
30
|
+
} catch {
|
|
31
|
+
fail(`${pkg} is not installed; reinstall without --omit=optional or --no-optional`);
|
|
32
|
+
}
|
|
33
|
+
if (process.platform !== 'win32') {
|
|
34
|
+
try {
|
|
35
|
+
fs.accessSync(bin, fs.constants.X_OK);
|
|
36
|
+
} catch {
|
|
37
|
+
try {
|
|
38
|
+
fs.chmodSync(bin, 0o755);
|
|
39
|
+
} catch {}
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
return bin;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const forwarded = process.platform === 'win32' ? [] : ['SIGTERM', 'SIGHUP', 'SIGQUIT', 'SIGUSR2'];
|
|
46
|
+
const swallowed = process.platform === 'win32' ? ['SIGINT', 'SIGBREAK'] : [];
|
|
47
|
+
if (process.platform !== 'win32') {
|
|
48
|
+
(tty.isatty(0) ? swallowed : forwarded).push('SIGINT');
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
const child = spawn(binaryPath(), process.argv.slice(2), {
|
|
52
|
+
stdio: 'inherit',
|
|
53
|
+
env: { ...process.env, SCSERVE_LAUNCHER: 'npm' },
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
const handlers = new Map();
|
|
57
|
+
for (const signal of forwarded) {
|
|
58
|
+
handlers.set(signal, () => {
|
|
59
|
+
if (child.exitCode === null && child.signalCode === null) child.kill(signal);
|
|
60
|
+
});
|
|
61
|
+
}
|
|
62
|
+
for (const signal of swallowed) handlers.set(signal, () => {});
|
|
63
|
+
for (const [signal, handler] of handlers) process.on(signal, handler);
|
|
64
|
+
|
|
65
|
+
child.on('error', (err) => fail(err.message));
|
|
66
|
+
child.on('exit', (code, signal) => {
|
|
67
|
+
for (const [name, handler] of handlers) process.removeListener(name, handler);
|
|
68
|
+
if (signal) {
|
|
69
|
+
process.exitCode = 128 + (os.constants.signals[signal] || 0);
|
|
70
|
+
process.kill(process.pid, signal);
|
|
71
|
+
return;
|
|
72
|
+
}
|
|
73
|
+
process.exit(code === null ? 1 : code);
|
|
74
|
+
});
|
package/bin/serve.wasm
ADDED
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,4 +1,40 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ai-ecoverse/slicc-serve",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "1.0.0",
|
|
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
|
+
"license": "Apache-2.0",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/ai-ecoverse/slicc-serve.git"
|
|
9
|
+
},
|
|
10
|
+
"homepage": "https://github.com/ai-ecoverse/slicc-serve#readme",
|
|
11
|
+
"bin": {
|
|
12
|
+
"scserve": "bin/scserve.js"
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"bin/scserve.js",
|
|
16
|
+
"bin/serve.wasm"
|
|
17
|
+
],
|
|
18
|
+
"engines": {
|
|
19
|
+
"node": ">=18"
|
|
20
|
+
},
|
|
21
|
+
"slicc": {
|
|
22
|
+
"abi": "wasi",
|
|
23
|
+
"commands": {
|
|
24
|
+
"serve": {
|
|
25
|
+
"wasm": "bin/serve.wasm"
|
|
26
|
+
},
|
|
27
|
+
"scserve": {
|
|
28
|
+
"wasm": "bin/serve.wasm"
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
"optionalDependencies": {
|
|
33
|
+
"@ai-ecoverse/slicc-serve-darwin-arm64": "1.0.0",
|
|
34
|
+
"@ai-ecoverse/slicc-serve-darwin-x64": "1.0.0",
|
|
35
|
+
"@ai-ecoverse/slicc-serve-linux-arm64": "1.0.0",
|
|
36
|
+
"@ai-ecoverse/slicc-serve-linux-x64": "1.0.0",
|
|
37
|
+
"@ai-ecoverse/slicc-serve-win32-arm64": "1.0.0",
|
|
38
|
+
"@ai-ecoverse/slicc-serve-win32-x64": "1.0.0"
|
|
39
|
+
}
|
|
4
40
|
}
|