1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
|
# 9web local catalogue (Linux)
`9web --catalog FILE` runs a local website catalogue in the gateway process.
It serves existing generated websites immediately, supervises requested builds,
and inventories listening TCP sockets without making requests to them. No
separate site servers are needed. The existing `--upstream` gateway mode is
unchanged; catalogue mode and an explicit upstream are mutually exclusive.
Set the top-level registry field `"filesystem": "/"` to expose the whole
workstation in the Files tab. The real `/` remains the root; the catalogue is
posted separately as `9web`, visible at `/mnt/9p/9web` under `9ns --mntgen`.
`/_9web` is a compatibility path alias to that mount, not another backend.
Startup refuses an existing real `/_9web` rather than hiding it.
Without this opt-in field, the previous catalogue-only tree is unchanged.
Only `/` is accepted: this export is not a restricted directory sandbox.
Host files support reading, editing, uploads, mkdir, rename and removal through
the normal 9P/WebSocket and HTTP `/fs` interfaces. Symlinks and mount points are
followed, including `/mnt/9p`. Access is checked by the kernel as the service's
user, not root; the 9P permission bits are permissive because its engine cannot
represent POSIX group/ACL checks. Device nodes, FIFOs and sockets are listed but
refused as file contents. Open files retain their descriptors across reads.
Blocking reads use bounded background tasks so one FUSE event stream does not
block all requests on the shared 9P connection. Non-seekable FUSE files use
streaming reads/writes rather than positional I/O.
The installed service runs `9ns --mntgen -- 9web ...`: `/mnt/9p` is the posted
registry in that service's namespace, not an assumption about another shell's
mount namespace. No host-global mount is changed. Newly posted services are
discovered by 9ns in the usual way.
## Configuration and serving
See [catalog.example.json](catalog.example.json). Every site has a unique `name`,
`title`, absolute `cwd` and `root`. Sites live at `/sites/<name>/` on the gateway
port. An optional `port` (`?u16`, omitted by default) retains the old separate
listener for explicit compatibility; it must be nonzero and unique. Optional
`build` and `watch` values are argument arrays, not shell command strings.
Use an explicit `sh -c` only when a trusted recipe needs shell syntax.
```
9web --listen '[::]:8090' \
--catalog "$HOME/.config/9web/sites.json" \
--catalog-socket "$XDG_RUNTIME_DIR/9web/catalog.sock" \
--state-dir "$HOME/.local/state/9web"
```
Create the socket's parent directory first. Configuration is read at startup;
restart the service to change it. A failed site-port bind fails startup rather
than advertising a site that is not actually served. All site listeners use
the dashboard's bind address. `[::]` uses a dual-stack listener for all IPv6 and
IPv4 interfaces; `0.0.0.0` restricts this to IPv4.
HTTP roots map into `/mnt/9p/9web/sites/<name>/public` in the service namespace.
Website responses use the same mux, 9P walks, opens and reads as `/fs`, not a
second disk-serving implementation. Root-relative sites need an **opt-in build
prefix**, described below; there is no response rewriting or Referer/cookie
routing. Directory URLs redirect to a trailing slash
and serve `index.html`; extensionless paths try `.html`. Static serving supports
MIME types, HEAD, single byte ranges, and streaming large files. Symlink traversal,
dotfiles, `..`, and encoded path separators are refused. Directory listings are
available through 9P, not through site HTTP roots.
The HTTP site root is static: provider-specific `_redirects`, `_headers`, and
Worker APIs are not executed. For example the café's articles and assets work,
but its Cloudflare poke API is not reproduced locally.
## Builds and watch
The regular 9web interface has **files**, **sites**, and **services** views in
catalogue mode. They share the existing header, stylesheet, tables and file
browser. The root opens files; `/?view=sites` and `/?view=services` are direct
links to the other tabs. Browser history and reload preserve the selected view.
Switching tabs preserves unsaved file edits. Ordinary upstream mode shows only
files and does not poll the catalogue API.
Files uses the main directory table and breadcrumbs; there is no duplicate
sidebar tree.
Each file entry has a `follow` link (`?follow=1`) which opens metadata first and
starts an SSE read without first waiting for a finite snapshot. Use it for event
streams; stop does not reopen the file or discard received text. Ordinary file
navigation still reads finite contents for editing.
The sites table has build, watch and cancel controls, plus files and log links
that open the same file browser. Builds execute in the
configured working directory with the service's environment. One child job runs
per site. Repeated build requests during a build coalesce into one later build.
Build writes enqueue work immediately; serving does not wait for compilation.
For managed watch, configure `inputs` as source paths relative to `cwd` (or absolute
paths for shared libraries outside the project). The
watcher checks source names, modification times and sizes once per second and
invokes the build recipe on changes. It skips hidden entries, symlinks and common
generated directories (`out`, `dist`, `build`, `node_modules`, `__pycache__`).
List a particular build script explicitly if it lives in one of those directories.
This is a metadata watcher, not a content hash or a Typst dependency graph.
Changes during a build are detected by the next scan. Browser refresh is manual.
Alternatively, `watch` can specify an existing persistent watcher. Its stdout and
stderr go to the same log, and watch-off cancels its process group. A native watcher
may itself serve a preview port, but the catalogue never requires that preview to
serve the site's generated files. Manual builds are refused while a native watcher
is active. Cancel disables watching and clears queued work. Server shutdown under
systemd kills the whole service cgroup, including build descendants.
Each new job replaces `<state-dir>/<name>.log`. The UI and 9P expose its last
256 KiB; the on-disk log is not rotated during a long-running native watcher.
Watch state and build status reset at service restart; generated output remains.
No build or watch is started automatically.
Generic builders may still write in place. The optional prefix packaging step
below publishes complete preview generations instead. Public files retain their
disk descriptors for the lifetime of an open 9P fid, including across publication.
The served root can be a symlink; symlinks below that root are refused.
## Opt-in prefix builds
`zig build` installs `zig-out/bin/9web-prefix` (Python 3). Put it on the build
process's PATH; the installed service uses `~/.local/bin/9web-prefix`.
The site's build option is **unset by default**. Authored content, source links,
scripts and default output URLs do not acquire a local prefix.
The workstation build entry points accept:
```
--url-prefix /sites/NAME/ --prefix-output /absolute/preview/output
```
- Entomology/Standards: `python3 site/build.py ...`
- Café: `mise exec -- sh build/build.sh ...`
- Pardes website: `mise exec -- python3 build/build.py ...` (also its build task)
- Café hub archive: `python3 build/static.py ...`
They run the normal build, then package a **separate** output copy. For initial
publication of an existing build, add `--reuse-output` to skip compilation.
9web's configured build recipes pass the prefix explicitly; managed watch calls
the same recipe. The archive remains read-only in the deployed catalogue.
The shared packaging tool only relocates generated HTML URL attributes and CSS
URLs/imports/URL selectors. Relative URLs, external URLs, fragments, text/code
examples, JavaScript and JSON are preserved. It does not pretend to understand
arbitrary JavaScript-generated URLs; future sites using those need their own
build-time base-path support. Worker/API routes are not implemented locally.
Preview output is an atomically replaced symlink to a complete generation in
the same parent directory. A failed compile/package leaves the prior preview
published; deleted assets do not survive in a new generation. Old generation
directories are retained (no automatic garbage collection), so repeated builds
consume disk space. Normal output is never overwritten by prefix packaging.
## 9P and HTTP controls
There is one supervisor in the 9web process, with a pure 9P service for site
files, controls and discovery. In host mode this is posted through the ordinary
per-user registry as `$XDG_RUNTIME_DIR/9p/9web` (`--post NAME` changes the name).
A host-only export has a separate runner, mutex, fid tables and pending reads;
it has no build/discovery loops. It exports the process's composed `/` through
the private `--catalog-socket` to the gateway mux. The host export is **not**
posted back inside its own mount, avoiding recursive exposure.
With `"filesystem": "/"`, prefix every pure-service path below with `/mnt/9p/9web`.
For example, the control URL becomes `/fs/mnt/9p/9web/sites/entomology/ctl` and its
mounted path is `/mnt/9p/9web/sites/entomology/ctl`. UI links and controls
select the prefix automatically from the catalogue snapshot's `namespace`.
```
/index.html
/index.json catalogue snapshot (sites, state, discovery)
/sites/<name>/public/ complete generated output tree (read-only)
/sites/<name>/ctl build | watch on | watch off | cancel
/sites/<name>/status JSON state, PID, exit code, times, generation
/sites/<name>/log last 256 KiB of current/most recent job
/sites/<name>/events blocking stream of JSON state changes
/services/index.json recognized HTTP/HTTPS listeners
/listeners/index.json all observed TCP listeners, including unknown ones
```
```
9ns --mntgen -- sh
echo build > /mnt/9p/9web/sites/entomology/ctl
cat /mnt/9p/9web/sites/entomology/status
cat /mnt/9p/9web/sites/entomology/log
```
Event opens receive the current state, then park until its revision changes.
Each reader has its own cursor; slow readers receive the newest state, not a
durable history of every transition. 9P flush cancels parked reads. State events
also work through `/fs/sites/<name>/events?follow=1` as SSE. `status` is the finite
snapshot to use for ordinary polling.
The sites and services views read `GET /_cloud9/catalog.json` while visible;
this is an HTTP-to-9P mapping to the posted service's `index.json`.
Build controls use `PUT /fs/sites/<name>/ctl`, through the same HTTP-to-9P mapping
as file editing. The earlier `POST /_cloud9/sites/<name>/ctl` endpoint remains
compatible for existing clients and also writes the 9P control file. Logs use the normal file viewer rather than a
separate dialog. Polling preserves site-row focus and pauses in background tabs.
## Passive discovery
Every five seconds, an embedded Python 3 inventory helper reads `/proc/net/tcp*`,
joins socket inodes to process descriptors, and recognizes executable/argument
patterns for miniserve, Python `http.server`, Typst watch, Vite and Wrangler dev.
9web identifies only its own known HTTP listening ports: its 9P listener is
never labelled HTTP just because the owning executable is 9web.
No TCP connections or HTTP probes are performed. Unknown or inaccessible process
ownership stays unknown. Full command lines and environments are not published;
entries contain address, actual bound port, PID, executable, cwd and the evidence
for classification. Process races and permissions can make entries temporarily
unknown. Discovery is in the service's network namespace, not across containers.
The helper is a short-lived child of 9web, not another daemon.
Wildcard addresses in dashboard links use the browser's current server hostname.
Specific addresses remain specific; loopback services are labelled local-only.
There is no automatic proxy to loopback-only services. Recognizers identify likely
HTTP listeners from process evidence; they cannot prove application health.
## Service and access
[9web.service](9web.service) is a user-systemd unit template. Install the binary
at `~/.local/libexec/9web`, the config at `~/.config/9web/sites.json`, and the unit
at `~/.config/systemd/user/9web.service`, then:
```
systemctl --user daemon-reload
systemctl --user enable --now 9web.service
systemctl --user status 9web.service
journalctl --user -u 9web.service
```
The unit supplies a private runtime directory and socket, restarts on failure,
and kills child jobs together with the service. Lingering must be enabled if the
user service should run without an interactive login. It needs `python3`, `setsid`,
and the configured project build tools in PATH. Miniserve remains independent.
This is a trusted-network operator interface: it has **no login or TLS**. Anyone
who can reach the dashboard can read the catalogue and trigger configured jobs.
Sites under URL prefixes share the operator interface's origin: site scripts
can access filesystem writes and build controls. Prefixes are **not security
isolation**; only serve trusted code here.
With `"filesystem": "/"`, they can additionally read or modify any file the
service user can access, including credentials, configuration and source code,
and operate control files under `/mnt/9p`. This can amount to arbitrary code
execution as that user. Only enable this export for clients you fully trust.
Browser control requests reject foreign Origins and unexpected Hosts, but served
sites on this same origin are trusted clients too. This is not authentication.
Bind to loopback or place an authenticated
gateway in front of it when those network permissions are inappropriate. No
arbitrary command can be supplied to the catalogue build-control parser itself;
its commands come from the local registry. A whole-host writable export removes
that as a security boundary, since clients can edit the registry and build inputs.
## Verification
Mounted synthetic files commonly report length zero and are non-seekable. Their
normal EOF must become an empty 9P read, not `Rerror EndOfStream`. The browser
reads until EOF, so that error previously discarded otherwise valid contents.
Directory HTTP reads are now sized to the receiving buffer, and JSON/HTML
listings stream rather than overflowing a fixed-size buffer or hiding a read
failure behind an empty listing.
The browser's WASM adapter also releases its previous borrowed reply frame before
submitting another request. Without that release, a full-msize read could fail
with `InputFull` even though small files worked.
```
zig build catalog-test http-fs-test mux-test -Doptimize=ReleaseSafe
zig build catalog-ui-test -Doptimize=ReleaseSafe
zig build -Doptimize=ReleaseSafe # install 9ns and the 9proc-demo fixture too
zig build host-fs-test -Doptimize=ReleaseSafe
```
The catalogue integration test uses temporary real sites and processes. It checks
immediate static serving, pretty URLs, MIME, HEAD/ranges, traversal and symlink
rejection, Host/Origin checks, HTTP and raw 9P controls, watched rebuilds, failed
build status, process-group cancellation, nonblocking event readers, and actual
socket ownership discovery. Existing gateway HTTP/filesystem and mux suites cover
the original mode.
The Chromium UI test checks the shared shell and styles, view navigation and
history, direct tab links, builds through `/fs`, logs in the file browser,
preservation of unsaved edits and focused controls, and mobile layout. It writes
inspection screenshots to `.zig-cache/catalog-ui/`. It uses the installed
`google-chrome-stable` binary (or `CLOUD9_CHROME`), with no npm dependencies.
It also checks that live HTTP ports stay exclusive and recent connections do not
prevent an immediate restart of the dashboard or site listeners.
`host-fs-test` additionally checks a 1,500-entry directory, mounted 9P reads,
control writes, non-seekable EOF, blocking FUSE reads concurrent with other
requests, and 40 flush/clunk cycles without exhausting background readers.
The Chromium test navigates a real mounted fixture, reads a 180 KB file and
opens/stops a live event stream directly from its directory entry.
It also checks exact multi-frame bytes under parallel load, alongside canceled
downloads and synchronous metadata requests. Asynchronous host-read replies
wait for output space rather than overfilling the shared 9P connection.
## Publication and namespace policy
There are three separate mechanisms, not one registration service:
* 9P servers may use `serve.Runner.listenPosted` to publish a Unix listener at
`$XDG_RUNTIME_DIR/9p/<name>`. 9ns lists the registry and connects on a walk.
No request is made to 9web; publication lifetime belongs to the producer.
* Website roots and build recipes in this catalogue are startup configuration
in `sites.json`, not self-registration. The shared supervisor posts its pure
service using `listenPosted`; the private host adapter uses `listen`.
* HTTP listener discovery observes `/proc` socket ownership and process metadata.
It neither registers services nor probes HTTP endpoints.
The Plan 9 reference was checked against the local Principia Softwarica sources:
`ROOT/docs/man/3/srv`, `kernel/devices/sys/devsrv.c`,
`lib_networking/lib9p/post.c`, `ROOT/docs/man/4/mntgen`, and
`ROOT/docs/man/4/exportfs`. Plan 9's `/srv` stores references to already-open
channels; Unix listeners are a Linux adaptation, not identical semantics.
Original `mntgen` creates mountpoints on demand; 9ns's registry auto-connection
is additional policy. Explicit configuration is not itself contrary to Plan 9:
`ROOT/docs/man/6/namespace` specifies configured mount/bind/import composition.
The pure site/build-control view is now composed into the consumer's namespace,
and HTTP serves those same paths. Shared supervision remains in one process;
no extra daemon is required per static site. Only that pure view is posted,
never the host export. This also follows `ROOT/docs/man/8/httpd`: a namespace
webroot and explicit internal URL mappings, not a separate registration API.
Composition with an arbitrary explicit upstream remains outside this mode.
## Installed workstation configuration
The application is named **9web** in its header, footer and page titles. The
existing `/_cloud9/` asset/protocol URLs and library module names are retained
for compatibility; they are not a different application name.
The workstation registry enables `"filesystem": "/"`. Files opens the host
root, including the service's live `/mnt/9p` registry mount; the pure catalogue
is under `/mnt/9p/9web` (old `/_9web` paths still work). The unit wraps the separately installed 9web binary with 9ns.
Ordinary `--upstream` mode is unchanged. Composition with an arbitrary explicit
upstream is still not implemented; this mode composes the host filesystem with
the catalogue, and existing 9P servers are available through `/mnt/9p`.
The workstation now uses a **single port, 8090**, for the dashboard and sites:
Entomology lab, 0x4200.cafe, Standards, Pardes website, and the older café hub archive.
The prior 8091–8095 listeners are no longer configured. Site URLs are
`/sites/entomology/`, `/sites/cafe/`, `/sites/standards/`, `/sites/pardes/`, and
`/sites/cafe-hub/`. Prefix output lives in `~/.local/state/9web/public/`.
The archive is read-only (no build recipe registered). Other sites have explicit
local build recipes and opt-in managed watches. Port 8081 remains miniserve's.
Runtime config is `~/.config/9web/sites.json`; the service uses a separately
installed binary so subsequent development builds do not change the running
service's executable on disk. Source and deployment changes are described in
the implementing git commit; no remote push is required for the local service.
|