summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/9web.service4
-rw-r--r--docs/catalog.md99
2 files changed, 94 insertions, 9 deletions
diff --git a/docs/9web.service b/docs/9web.service
index a20bd89..7109935 100644
--- a/docs/9web.service
+++ b/docs/9web.service
@@ -1,9 +1,9 @@
[Unit]
-Description=9web local sites, build controls and listener catalogue
+Description=9web filesystem, sites and services
After=network.target
[Service]
-ExecStart=%h/.local/libexec/9web --listen [::]:8090 --catalog %h/.config/9web/sites.json --catalog-socket %t/9web/catalog.sock --state-dir %h/.local/state/9web
+ExecStart=%h/.local/bin/9ns --mntgen -- %h/.local/libexec/9web --listen [::]:8090 --catalog %h/.config/9web/sites.json --catalog-socket %t/9web/catalog.sock --state-dir %h/.local/state/9web
Restart=on-failure
RestartSec=2
RuntimeDirectory=9web
diff --git a/docs/catalog.md b/docs/catalog.md
index ae6cd46..74062bb 100644
--- a/docs/catalog.md
+++ b/docs/catalog.md
@@ -6,6 +6,27 @@ 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
+mounted at `/_9web`. 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`,
@@ -45,6 +66,12 @@ 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
@@ -85,6 +112,11 @@ symlinks below that root are refused.
The catalogue is itself a 9P backend, consumed by the ordinary gateway mux.
`--serve` and WebSocket clients see the same tree as direct socket clients:
+With `"filesystem": "/"`, prefix every catalogue path below with `/_9web`.
+For example, the control URL becomes `/fs/_9web/sites/entomology/ctl` and its
+mounted path is `/mnt/9p/web/_9web/sites/entomology/ctl`. UI links and controls
+select the prefix automatically from the catalogue snapshot's `namespace`.
+
```
/index.html
/sites/<name>/public/ complete generated output tree (read-only)
@@ -155,18 +187,35 @@ 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.
+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; numeric Host validation and
separate site origins prevent served pages from using the dashboard as a same-origin
control API. 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 through HTTP or 9P; commands come from the local
-registry, which should remain writable only by its owner.
+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
@@ -183,6 +232,41 @@ 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.
+
+## 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 private catalogue socket itself
+ currently uses `listen`, not `listenPosted`.
+* 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 coherent next design step, **not implemented here**, is to expose a pure
+site/build-control 9P view and compose it into the consumer's namespace, with
+HTTP serving those same paths. Shared supervision can remain in one process;
+no extra daemon is required per static site. Do not post the current mixed
+host/catalogue root back under its own `/mnt/9p`: that creates recursion and
+possible self-dependent waits. Arbitrary-upstream composition and unifying
+the separate disk-based static-site HTTP handler remain outstanding.
## Installed workstation configuration
@@ -190,11 +274,12 @@ 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.
-Current limitation: catalogue mode replaces the upstream with its synthetic
-tree. The Files tab therefore does not expose the workstation filesystem or
-compose an existing upstream with the catalogue. Ordinary `--upstream` mode
-still works, but the installed catalogue service is not a filesystem-browser
-replacement for miniserve.
+The workstation registry enables `"filesystem": "/"`. Files opens the host
+root, including the service's live `/mnt/9p` registry mount; the virtual catalogue
+is under `/_9web`. 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 initial workstation setup uses dashboard port 8090 and site ports 8091–8095:
Entomology lab, 0x4200.cafe, Standards, Pardes website, and the older café hub archive.