From 7a07e24916cd5bc762996d81aa1faf550177cd6f Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Mon, 12 Oct 2026 17:15:03 -0300 Subject: 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. --- docs/namespace-sites-validation.md | 74 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/namespace-sites-validation.md (limited to 'docs/namespace-sites-validation.md') 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. -- cgit v1.3