Merge pull request 'docs(website): settle phase 4's shape — delivery' (#141) from docs/module-phase4-plan into main
Reviewed-on: #141
This commit is contained in:
@@ -400,6 +400,13 @@ is a property of the volume and not of a row here. What the row decides is wheth
|
||||
This is also why
|
||||
`routes.manifest.json` can be generated against a dead database.
|
||||
|
||||
*(Amended in Phase 4, §2.7.2 decision 3: **disable is not only a guard flip.** It dispatches that one
|
||||
module's `onShutdown` first, so a module an admin switches off actually stops — releases its sockets,
|
||||
closes its streams — rather than merely becoming unreachable while it keeps working in the
|
||||
background. Enable is deliberately not the mirror image: there is no `onBoot` re-dispatch, so
|
||||
enabling flips the row and the admin screen offers a restart. The claim this section makes is
|
||||
unaffected — the row still decides only whether a mounted module answers, never what is mounted.)*
|
||||
|
||||
**`disabled` is the only state a boot leaves alone.** Every boot resets each non-disabled row to
|
||||
`enabled`, clearing any recorded failure, and the load that follows writes this boot's outcome —
|
||||
`started` or `startup_failed`. Three consequences, all deliberate:
|
||||
@@ -440,6 +447,12 @@ against its `sha256` → unpacked into `modules/<id>/` on the volume → `instal
|
||||
**restart**. On boot the loader scans the filesystem (§1.12), validates prefixes, mounts, replays the
|
||||
schema fragment, runs `onBoot`, and each module reaches `started` or `startup_failed`.
|
||||
|
||||
*(Made concrete in Phase 4, §2.7.2 decisions 1 and 2: "admin selects the module" is **pasting the URL
|
||||
of a release's install manifest** — there is no catalog, because a catalog would make core's release
|
||||
cadence decide which modules exist. And the **restart is a button on the same screen**, not an
|
||||
instruction to go and restart the container: it runs `moduleLifecycle.shutdown()` and exits, and the
|
||||
supervisor the shipped compose file already declares brings the process back.)*
|
||||
|
||||
Nothing is compiled at any point. The operator restarts; they never build.
|
||||
|
||||
**Uninstall** (default, non-destructive): row set to `disabled`, directory removed, restart. The
|
||||
@@ -1368,12 +1381,121 @@ Six slices, 2026-08-11. Core is 158 routes and knows nothing about any game; mod
|
||||
**Phase 4 — Delivery.** The admin-panel Modules screen (install, enable, disable, retry, purge,
|
||||
`startup_failed` with its recorded reason) and the Docker-environment path from §2.5. Deliberately
|
||||
last, so loader, packaging, schema and chunk-loading problems are not all being debugged at once.
|
||||
Its shape, and the four decisions it turned on, are in §2.7.2 below.
|
||||
|
||||
**Phase 5 — The Integration Kit.** `RunicGateway/Integration-kit`, the instruction book for building
|
||||
a module for a game that is not UO — the website module, the sidecar and why it exists, and the
|
||||
game-side plugin that feeds it. Scaffolded when Phase 2 lands, written against Phase 3's extraction,
|
||||
finished alongside Phase 4. Full shape and its acceptance test in §2.11.
|
||||
|
||||
#### 2.7.2 Phase 4's shape — settled 2026-08-12
|
||||
|
||||
Phase 4 is the first phase that is not about the *boundary*. Phases 1–3 answered "can a module exist
|
||||
and can core live without one"; this one answers "how does a module get onto a box an operator owns,
|
||||
and how do they get it off again", which is the whole point of §1.14's WordPress constraint.
|
||||
|
||||
**Measured starting state.** The producer side is finished and the consumer side is empty.
|
||||
`module-uo`'s `release.yml` already publishes the three assets an installer wants — a
|
||||
`module-uo-<version>.tar.gz`, an install manifest `module-uo-<version>.json` carrying
|
||||
`{id, name, version, coreApi, artifact, url, sha256, size}`, and a `SHA256SUMS` — and `module.json`
|
||||
already declares `purge: server/db/purge.sql`. Core already has the `installed_modules` columns
|
||||
`source` and `sha256` (§2.4 carved them out for exactly this and nothing has ever written them
|
||||
non-null), the live `stateGuard`, and `modules.model.js`'s `enable`/`disable`/`remove`. What core has
|
||||
**none** of: any code that fetches, verifies, unpacks, removes or purges anything; any admin route;
|
||||
any client screen; and any resolution of a declared module set at container start —
|
||||
`docker-compose.yml`'s own comment still tells the operator to untar by hand and restart.
|
||||
|
||||
##### Four decisions, settled by the org lead
|
||||
|
||||
**1. Restart is a button, not an instruction.** Install, uninstall and re-enable only take effect at
|
||||
boot, because §1.12 mounts synchronously from the filesystem and the loader is `load()`-once. Rather
|
||||
than record a pending change and tell the operator to go and restart the container — which
|
||||
contradicts §2.4's "recoverable from the admin panel, with no shell access to the box" — an admin
|
||||
action runs `moduleLifecycle.shutdown()` and then exits the process cleanly, and the supervisor
|
||||
brings it back. The shipped `docker-compose.yml` already declares `restart: unless-stopped` on `app`,
|
||||
so on the supported deployment this is simply true. It is not universally true — a bare
|
||||
`npm start --prefix server` does not come back — so the screen says what it is about to do and the
|
||||
endpoint is not something a stray click reaches.
|
||||
|
||||
**2. The install source is a pasted manifest URL, not a catalog.** The admin pastes the URL of a
|
||||
release's `<module>-<version>.json`; core fetches it, downloads the `artifact` it names, verifies the
|
||||
`sha256` it declares, and unpacks. There is no index to run and no core release needed to make a new
|
||||
module installable — which is the WordPress model exactly, and the only shape that lets a module
|
||||
outside this org be installed at all. The safety is not the catalog, it is the sha256 in the manifest
|
||||
(module-uo's CHANGELOG already names it "the trust anchor") plus a **host allowlist**: `https` only,
|
||||
against a configurable list defaulting to the Gitea host. This endpoint installs code that will run
|
||||
in the server process on the next boot; it is admin-only, rate-limited and audit-logged, and the
|
||||
allowlist is what stops a pasted URL from being an SSRF primitive as well.
|
||||
|
||||
**3. Disable stops the module; enable asks for a restart.** As Phase 2 built it, `disable` flips one
|
||||
field on the in-memory record and the `stateGuard` starts answering 404 — the module becomes
|
||||
*invisible*, not *stopped*. For module-uo, concretely, `boot.js`'s `uoLinkSocket` stays connected to
|
||||
the sidecar and keeps ingesting shard events into `shard_*` tables, and `shardBroadcast`'s SSE
|
||||
streams stay open, because `onShutdown` is dispatched only from the signal handler. That is
|
||||
acceptable for "I do not want this feature on the site today" and wrong for the case the button
|
||||
exists for — "this module is misbehaving and I have no shell". So disable now dispatches **that one
|
||||
module's** `onShutdown` before flipping the guard, and is a real kill switch.
|
||||
|
||||
Enable cannot be its mirror. There is no `onBoot` re-dispatch path, and the contract has never
|
||||
promised the hooks are re-entrant — no module author has written `onBoot` to be safe to run twice in
|
||||
one process. Enable therefore flips the row and the screen offers the restart button from decision 1.
|
||||
Making the hooks re-entrant is the better end state and is recorded as a candidate for a future
|
||||
`MODULE_API_VERSION` major bump, beside the identity-provider gap §2.7's dry run found; it is not
|
||||
worth a rewrite of every module's `boot.js` to save one restart.
|
||||
|
||||
This is a **change to §2.4**, which described both transitions as pure row-and-guard flips. §2.4's
|
||||
underlying claim survives untouched: the row still never decides what is *mounted*, only whether a
|
||||
mounted module answers.
|
||||
|
||||
**4. The Docker path is an environment variable.** §2.5 owes "a declarative module set resolved at
|
||||
container start from the mounted volume, so a compose-managed host is not driven by clicking". That
|
||||
set is declared in the compose file — the file such a host already edits and version-controls —
|
||||
rather than in a second config file on the volume. Resolution runs before the server starts and is
|
||||
**idempotent and offline-safe**: a module already unpacked at the declared version is a no-op, so a
|
||||
restart with the network down brings the site up exactly as it was. Only a missing or
|
||||
wrong-version module reaches out, and it reaches out through the same fetch-verify-unpack path the
|
||||
admin panel uses.
|
||||
|
||||
##### The slices
|
||||
|
||||
Slice 0 is independent of the rest and lands first; 1–4 are ordered. Unlike Phase 3, most of this is
|
||||
core-only, so the two-repo merge dance does not apply — `module-uo` is touched only by slice 0.
|
||||
|
||||
| # | Slice | Repos |
|
||||
| --- | --- | --- |
|
||||
| 0 | **SonarQube for `module-uo`** — `sonar-project.properties` (project key `Module-uo`) plus the scan workflow, mirroring `website`'s. The module is 40 server + 35 client files of extracted code that has never been scanned. | `Module-uo`, `docs` |
|
||||
| 1 | **The install service and the admin API** — fetch, verify, hardened unpack, remove, purge; `/api/v1/admin/modules` with list, install, enable, disable, uninstall, purge and restart; the per-module `onShutdown` dispatch decision 3 requires; the host allowlist. | `website`, `docs` |
|
||||
| 2 | **The Modules screen** — `ModulesAdmin.jsx`, its nav row, its API bindings, and the §7.7 browser smoke against a real install of `module-uo` from a real release URL. | `website`, `docs` |
|
||||
| 3 | **The declarative Docker path** — container-start resolution of decision 4's variable, the compose and image changes it needs, and the operator documentation. | `website`, `docs` |
|
||||
| 4 | **Close the phase** — `BACKEND_DESIGN.md` §3, the `api-route-inventory.json` mirror, `docs/modules/uo/`'s install instructions, and the acceptance table. | `docs`, `website` |
|
||||
|
||||
##### The unpack is the dangerous part, and it is not the download
|
||||
|
||||
The download is a solved problem: an allowlisted `https` host, a declared `sha256`, and a size cap.
|
||||
Unpacking is where the archive gets to choose filenames, and a tar entry may name an absolute path,
|
||||
escape upward with `..`, be a symlink or hardlink pointing anywhere on the filesystem, or expand to
|
||||
far more than it appeared to be. Core writes into a **bind-mounted directory it shares with the
|
||||
host** (Phase 2 PR 9), so an escape is not confined to the container's own filesystem.
|
||||
|
||||
The extractor therefore rejects rather than sanitises — an archive that needs correcting is an
|
||||
archive that should not be trusted — on: any absolute path, any `..` segment, any entry that is not a
|
||||
regular file or a directory (so no symlinks, hardlinks, devices or FIFOs), more than one top-level
|
||||
directory, a top-level directory whose name is not the manifest's `id`, and a total unpacked size or
|
||||
entry count over its cap. Unpacking goes to a temporary directory beside the target and is moved into
|
||||
place only once the whole archive has been accepted, so a rejected or interrupted install never
|
||||
leaves a half-module on the volume for the next boot's scan to find. `tar` is a real dependency
|
||||
rather than a hand-rolled parser: the format has enough shape (long-name extensions, PAX headers,
|
||||
sparse entries) that parsing it is exactly the kind of code this list is trying to defend against.
|
||||
|
||||
##### What Phase 4 must prove
|
||||
|
||||
| # | Criterion | How |
|
||||
| --- | --- | --- |
|
||||
| 1 | A module installs, starts and serves with no shell access and nothing built | Admin panel install from a release URL, restart, module `started`, its pages render |
|
||||
| 2 | Uninstall leaves the data, purge removes it | Uninstall then reinstall recovers the rows; purge then reinstall does not |
|
||||
| 3 | A hostile archive cannot write outside `modules/<id>/` | Unit tests over the rejection list above, each with a real crafted tar |
|
||||
| 4 | A compose-declared module resolves at container start, offline | Container boots with the network down and an already-unpacked module, and comes up unchanged |
|
||||
|
||||
### 2.8 SPA URL namespacing — a deliberate break
|
||||
|
||||
**Decision: module pages are namespaced, and old paths are not redirected.** The site is not public
|
||||
|
||||
Reference in New Issue
Block a user