summaryrefslogtreecommitdiff
path: root/docs/namespace-sites-validation.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-12 17:15:03 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:16 -0300
commit7a07e24916cd5bc762996d81aa1faf550177cd6f (patch)
tree4530a8562fb3f068cc4340f1fab1f6c599721735 /docs/namespace-sites-validation.md
parentf9ca3fb5ba767300bec3f1fbb13fc5e6552a90e3 (diff)
downloadcloud9-7a07e24916cd5bc762996d81aa1faf550177cd6f.tar.gz
cloud9-7a07e24916cd5bc762996d81aa1faf550177cd6f.zip
9web: serve prefixed sites through the composed 9P namespace
Post only the pure site/control/discovery tree, with a separate host-only adapter and no duplicate supervision. Serve websites, metadata and legacy controls through the ordinary 9P mux; retain whole-root filesystem browsing and compatibility paths. Pin public file descriptors across publication. Add opt-in build-time HTML/CSS prefix packaging with separate atomic preview generations and unchanged JavaScript/default output. Optional compatibility ports use ?u16. Deploy all five workstation sites on [::]:8090, with /mnt/9p/9web controls. Document Plan 9 references, companion build commits, shared-origin trust and live validation. Validated catalogue, host/FUSE, HTTP FS, mux, prefix and Chromium suites; original E2E 32 scenarios; all five live sites, blog navigation, IPv4/IPv6 and real cafe build through 9P.
Diffstat (limited to 'docs/namespace-sites-validation.md')
-rw-r--r--docs/namespace-sites-validation.md74
1 files changed, 74 insertions, 0 deletions
diff --git a/docs/namespace-sites-validation.md b/docs/namespace-sites-validation.md
new file mode 100644
index 0000000..64858fc
--- /dev/null
+++ b/docs/namespace-sites-validation.md
@@ -0,0 +1,74 @@
+# Namespace-backed sites: implementation and validation
+
+## Design
+
+One 9web process supervises builds and posts a pure service as `9web` in the
+normal per-user 9P registry. A separate host-only export consumes its composed
+namespace through 9ns. Website HTTP, Files, catalogue metadata and controls use
+the same 9P mux. The host export is never posted back into itself.
+
+Plan 9 references reviewed locally in Principia Softwarica: `srv(3)`,
+`namespace(6)`, `mntgen(4)`, `exportfs(4)`, and `httpd(8)` (namespace webroot and
+internal URL mappings). A conversational critique review caught public-file
+reopening across publication and two HTML prefix parsing edge cases; all have
+regression tests. Explicit recipe configuration remains policy, not a
+self-registration protocol. Unix listener posting is a Linux adaptation of
+channel publication, not identical `/srv` semantics.
+
+## Deployment
+
+- Enabled user unit `9web.service`, wrapped with `9ns --mntgen`.
+- Sole HTTP listener `[::]:8090`, reachable using LAN IPv4 and IPv6.
+- Existing 8091–8095 site listeners removed from configuration; miniserve untouched.
+- Whole `/`, including `/mnt/9p`, retained in Files; pure service at `/mnt/9p/9web`.
+- URLs `/sites/{entomology,cafe,standards,pardes,cafe-hub}/`.
+- Preview generations under `~/.local/state/9web/public/`; normal output unchanged
+ by prefix packaging. Initial publication reused existing builds.
+- `--url-prefix` is optional in project build commands and never enabled by
+ default. The service explicitly supplies it for builds and managed watch.
+- Optional compatibility site port is represented as `?u16 = null`, not zero.
+- Configuration backup: `~/.config/9web/sites.before-namespace.json`.
+
+The helper `9web-prefix` is installed by `zig build` and locally at
+`~/.local/bin/9web-prefix`. It relocates generated HTML/CSS only. JavaScript,
+JSON, authored content and source URLs are unchanged. The archive stays
+read-only in the service. Old preview generations are retained, not garbage
+collected. Same-origin site scripts are trusted operator code, not isolated
+from writable files or build controls. Cloudflare APIs are not implemented.
+
+## Companion build commits
+
+| Project | Commit | Scope |
+|---|---|---|
+| Entomology lab | `da9d227` | Optional prefix/output/reuse flags in existing builder |
+| Standards | `4ad43a0` | Same optional build flags |
+| 0x4200.cafe | `2d47b2b` | Optional flags in build/build.sh; default/watch preserved |
+| Pardes website | `a1da335` | Build entry point with optional prefix packaging |
+| Café hub archive | `3e07a67` | Optional static archive build/packaging entry point |
+
+Existing unrelated project edits were not committed. No remote push.
+
+## Checks
+
+`zig build -Doptimize=ReleaseSafe catalog-test host-fs-test http-fs-test
+catalog-ui-test mux-test prefix-test` passes. Coverage includes:
+
+- Index/pretty URLs, redirects with query preservation, MIME, HEAD and byte ranges.
+- Identical website bytes through namespace/9P and HTTP; traversal rejection.
+- Pinned public file reads when a new generation replaces its pathname.
+- Scoped HTML/CSS prefixing, CSS selectors, entities, srcset/data URLs, unchanged
+ scripts/code examples/external URLs and normal-output hashes.
+- Atomic publication, stale-asset exclusion and preservation on failure.
+- Whole-host operations and mounted 9P controls, large directories, blocking
+ events and repeated flush/clunk without reader exhaustion.
+- Existing Files/Sites/Services shell, mobile layout, editing and history.
+
+Live Chromium validation (`NINE_WEB_LIVE=http://127.0.0.1:8090 node
+test/web/catalog_ui.mjs zig-out/bin/9web`) also passes: `/mnt/9p/9web`, agents,
+zmx, `/usr/bin`, all five site landing pages, 22 same-origin images across
+Entomology and the café, and café blog/pretty article navigation. LAN IPv4 and
+IPv6 site requests return 200. An actual café build requested through
+`/fs/mnt/9p/9web/sites/cafe/ctl` completed with exit code 0 and published a new
+prefixed generation; no preview daemon was started.
+
+`zig build -Doptimize=ReleaseSafe e2e` passes all 32 original gateway scenarios.