# 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//` 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//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 `/.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//public/ complete generated output tree (read-only) /sites//ctl build | watch on | watch off | cancel /sites//status JSON state, PID, exit code, times, generation /sites//log last 256 KiB of current/most recent job /sites//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//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//ctl`, through the same HTTP-to-9P mapping as file editing. The earlier `POST /_cloud9/sites//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/`. 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.