wtclaude
419dee3e49
module-uo's half of ENGAGEMENT.md Phase 11: every trigger DECLARATION, the
wire-kind mapping that fires them, and the three registered audiences. No rule
and no template is seeded here -- that is 11b -- so nothing this adds sends
anybody anything until an operator writes a rule.
server/config/shardTriggers.js declares the 24, grouped by the audience kind
each family exercises, and every variable carries the `example` the template
editor previews and test-sends with. Ceilings: 10 `owner`, 2 `members`, 7
`authenticated`, 2 `staff`, 3 `admin` (the value core adds in the same window).
`uo.cheat.detected` at `staff` is the declaration the lattice exists for.
server/utils/shardEngagement.js maps the wire to those ids, hung off
shardIngest.ingest beside the SSE broadcast and the push tickle, and reads like
shardPush.js on purpose -- owner resolution is why neither can be a pure mapper.
Three things live here because a rule cannot express them:
* Transitions. champ.update and city.update are full-state upserts, so without
a per-process tracker a sidecar reconnect reads as twenty spawns starting.
A FIRST sighting is never a transition.
* Thresholds. conditions.js compares a declared variable against a LITERAL, so
"within 24 hours of dismissal" is not expressible; and vendor.listing is a
sweep frame re-emitted on any price change, so per-frame would flood. The
crossing is tracked here and `hoursRemaining` is declared so an operator can
still narrow with `is at most`.
* The members audience. "The members of THIS guild" differs every firing, so
it travels on the envelope as recipientUserIds (Phase 6 decision 2).
**The fan-out runs BEFORE the state write, and that ordering is load-bearing.**
account.unlinked drops the shard_account_links row that names the one person who
needs to be told; house.remove drops the house whose stored ownerAcct is the only
place a collapsed house's owner appears; guild.leave/remove need the roster and
board mirrors to name who left. Resolving afterwards finds nobody, every time.
Four rows of 8.6 deliberately do not ship, each with its reason recorded in
docs (docs#194): uo.market.item_listed (a saved search, no per-user query store),
uo.guild.joined (core's team.member.joined already fires for it -- a UO guild IS
a Team and this module is the provider), uo.link.requested (no addressable
recipient by construction, ~5-minute TTL), and uo.points.rank_changed's personal
half (top[] names a serial, links are keyed by account).
coreApi -> ^1.8.0: the module now calls registerEventTriggers and declares
`ceiling: 'admin'`, so a 1.7.0 core would refuse the ceiling and a 1.6.0 one
would not have the method at all.
39 new tests; 509/509 pass. check:imports, check:bundle and check:swagger clean.
Co-Authored-By: Claude <noreply@anthropic.com>
219 lines
13 KiB
Markdown
219 lines
13 KiB
Markdown
# module-uo — the Ultima Online module for Runic Gateway
|
|
|
|
The Runic Gateway website is becoming **game-agnostic**: core keeps accounts, sessions, the wiki,
|
|
posts, branding, theming and the admin panel, and everything that knows what a *shard* is moves out
|
|
into an installable module. This repo is that module — the first one, and the reference for every
|
|
module that follows.
|
|
|
|
```
|
|
RunicGateway/website (core — game-agnostic)
|
|
│ loads modules at boot, synchronously, from the filesystem
|
|
▼
|
|
┌───────────────────────────────────────────┐
|
|
│ module-uo (>>> HERE <<<) │
|
|
│ shard status · spawn atlas · marketplace │
|
|
│ governors · cliloc · town crier · uo-link│
|
|
└───────────────────────────────────────────┘
|
|
│ server half: routers, models, schema fragment
|
|
│ client half: prebuilt ESM chunk, SPA routes + nav
|
|
▼
|
|
the shard bridge (RunicGateway/link → RunicGateway/servuo-plugins)
|
|
```
|
|
|
|
The module's **id** is `uo` — that is what appears in `module.json`, in the `installed_modules`
|
|
table, in the `modules/<id>/` path on disk and in the URL segment (`/uo/*`, `/admin/uo/*`,
|
|
`/player/uo/*`). `Module-uo` is the repository; `module-uo` is the module and its release artifact.
|
|
|
|
## Status: the extraction is complete; this repo is the UO half of the site
|
|
|
|
The design of record is
|
|
[`website/MODULE_SYSTEM.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_SYSTEM.md)
|
|
and the normative contract is
|
|
[`website/MODULE_API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md)
|
|
in the docs repo — **read them before opening a PR here.** Where the two differ, the contract wins.
|
|
|
|
| Phase | Where it happens | State |
|
|
|---|---|---|
|
|
| 0 — CI trigger fix, cut `website` `edge`, bootstrap this repo | `website`, here | ✅ done |
|
|
| 1 — module API contract (`docs/website/MODULE_API.md`) + the atlas spike | `docs`, `website` | ✅ done |
|
|
| 2 — core scaffolding: loader, `installed_modules`, registries, client registry | `website` | ✅ done |
|
|
| 3 — extract the UO half of the site into this repo | `website`, here | ✅ done |
|
|
| 4 — delivery: the admin Modules screen + the Docker path | `website` | ✅ done |
|
|
|
|
Phase 3 moved the UO half of `website/` here in six slices (`MODULE_SYSTEM.md` §2.7.1): the bundle
|
|
skeleton, the whole server half, core's client extension slots, the whole client half, the de-UO of
|
|
core's own copy, and this one — the artifacts that make the result installable and checkable. Each
|
|
slice was one PR here that added and one in `website` that deleted, this one merging first, so
|
|
`website`'s `edge` branch served each feature from core right up to the moment core dropped it.
|
|
|
|
Neither half sliced by feature in the end, and for the same reason on both sides: a mount prefix is
|
|
claimed whole and a shared leaf moves with its **last** consumer, so the closure of either half is
|
|
the whole half.
|
|
|
|
**What core serves and what this repo serves is now a fact you can read**, not a claim: 72 URLs, in
|
|
[`routes.manifest.json`](routes.manifest.json), derived by loading this module into a real core and
|
|
diffing. Not one of core's own URLs moved — that is the promise `MODULE_SYSTEM.md` §1.2 makes to the
|
|
shipped Android app and the Discord bot, and it is checked on every PR.
|
|
|
|
## Working on it
|
|
|
|
```bash
|
|
npm ci --prefix server && npm test --prefix server && npm run check:imports --prefix server
|
|
npm run check:swagger --prefix server # is swagger-fragment.json still current?
|
|
npm ci --prefix client && npm test --prefix client && npm run build --prefix client
|
|
npm run check:externals --prefix client # asks the BUILT chunk, so it runs after the build
|
|
```
|
|
|
|
The `check:*` scripts are the contract's acceptance criteria rather than this module's own tests: no
|
|
import may escape the module root (`MODULE_API.md` §5.1), no bare specifier may survive into the
|
|
built chunk (§3.6), and the OpenAPI fragment core merges must describe the routes registered today
|
|
(§2.8). The matching build failure — a shared dependency being *bundled* — comes from a guard inside
|
|
`vite.config.js`.
|
|
|
|
**Changed a route, or its `#swagger` annotations?** `npm run swagger --prefix server` regenerates
|
|
`swagger-fragment.json`; commit it. Core cannot generate it — core is a prebuilt image and this
|
|
module mounts through a call no static parser can follow — so the file this repo commits is the one
|
|
an operator's `/api/docs` shows.
|
|
|
|
**Changed a mount prefix, or added a route?** `routes.manifest.json` is regenerated by the
|
|
`frozen-manifest` CI job, which clones core at the ref pinned in [`ci/core-ref.json`](ci/core-ref.json),
|
|
loads this module into it and takes the difference. To do it locally, check this repo out into that
|
|
core as `modules/uo` (**copy it — a symlink is silently skipped by the loader**), run core's
|
|
`npm run routes:manifest` with and without it, and hand both files to
|
|
`server/scripts/frozenManifest.js`.
|
|
|
|
Running it against a real core means checking this repo out as `website/modules/uo`, building the
|
|
client half, and booting core. The four-step browser smoke in `MODULE_API.md` §7.7 is the only thing
|
|
that proves the client half works: its real failure modes are timing and module resolution, and
|
|
neither has a shape a DOM-less test runner can see.
|
|
|
|
## What it contains
|
|
|
|
One repo, one bundle: the server half and the client half live side by side and version together, so
|
|
a route and the screen that calls it can never be mismatched.
|
|
|
|
```
|
|
module.json id, version, coreApi range, mounts, extensions
|
|
swagger-fragment.json generated · the OpenAPI core merges into /api/docs.json
|
|
routes.manifest.json generated · the 72 URLs this module serves
|
|
ci/core-ref.json the core commit the two above were proved against
|
|
server/index.js the entry point — register(ctx, api), synchronous, no database
|
|
server/router/ routers + controllers, one directory per tier
|
|
server/model/ one directory per table family; nothing crosses the boundary
|
|
server/utils/ sidecar client, visibility, ingest, town crier, cliloc, atlas
|
|
server/config/ the push stream catalog, the engagement triggers and audiences
|
|
server/db/schema.sql idempotent fragment, replayed by core's ensureSchema()
|
|
server/db/purge.sql destructive; only ever run by an explicit purge
|
|
server/scripts/ the three checks: imports, the fragment, the frozen manifest
|
|
server/test/ node --test, with a fake ctx standing in for core
|
|
client/src/entry.jsx the chunk's entry — registers routes, nav, slots, feature provider
|
|
client/src/shim/ react, react-dom, react-router-dom, jsx-runtime, from window.__rg
|
|
client/vite.config.js the library build, the aliases, the not-bundled guard
|
|
client/dist/ PREBUILT ESM chunk, built by CI — never by an operator
|
|
```
|
|
|
|
**What this module registers with core, beyond its routes.** Seven push streams, one announce leg
|
|
(the in-game town crier), a Team provider (a UO guild is a Team), one slash command, and — since
|
|
ENGAGEMENT.md Phase 11 — **24 engagement triggers and 3 audiences**. A trigger is a payload contract:
|
|
what a rule may fire on, what a template may interpolate, and the widest audience an operator may ever
|
|
give it. Core learns none of the vocabulary; it holds ids, labels and ceilings. Declaring a trigger
|
|
sends nobody anything — every rule ships disabled. The catalogue, the four rows deliberately absent
|
|
and the reasons are in [`docs/modules/uo/API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/uo/API.md) §5.
|
|
|
|
**The three generated files are committed on purpose.** Two of them are what core reads instead of
|
|
looking at this source — it never has it — and the third records which core they were proved against.
|
|
A generated file nobody reviews is a generated file nobody notices going wrong, so each lands in a
|
|
diff.
|
|
|
|
Release artifact: `module-uo-<version>.tar.gz`, plus `module-uo-<version>.json` carrying its
|
|
`sha256`. See below.
|
|
|
|
## How it reaches an operator
|
|
|
|
**An operator never builds anything.** Installing a module is the WordPress-plugin experience: an
|
|
admin-panel action, or a directory mounted into the Docker container — never a build step, because
|
|
production runs a prebuilt, pull-only image. That constraint is why the client half ships as a
|
|
prebuilt ESM chunk that resolves React from a `window.__rg` global rather than an import map (an
|
|
import map must be inline, and the site's CSP is `script-src 'self'`).
|
|
|
|
The [installer](https://gitea.whitlocktech.com/RunicGateway/installer) is **not** the delivery path.
|
|
It deploys the *shard* side — the plugin overlay and the uo-link sidecar — and never contacts the
|
|
website. Module delivery is website-side only.
|
|
|
|
### Releases
|
|
|
|
**Every merge to `main` that carries a releasable commit publishes a bundle.** The next version is
|
|
computed from conventional-commit subjects since the newest `v*` tag, as in `link` and `installer`:
|
|
`feat!:` or `BREAKING CHANGE` is a major, `feat:` a minor, `fix:` or `perf:` a patch, and a `main`
|
|
that gained none of those cuts no release. The number that ships is the **tag**, and CI writes it
|
|
into the `module.json` inside the bundle.
|
|
|
|
`module.json`'s version survives as a **floor**: name a version there above the newest tag and that
|
|
version is what releases, which is how you overrule the subjects — when a `coreApi` bump forces a
|
|
minor, say. What no longer happens is a `main` full of `feat:` producing nothing because a separate
|
|
PR to move one number had not been merged yet.
|
|
|
|
For a change with nothing releasable behind it — a widened `coreApi`, a new mount, a capability —
|
|
run the **Release** workflow by hand (Actions → Release → Run workflow). Leave `version` blank to
|
|
bump the newest tag by `bump` (default `patch`), or type an exact version to publish that.
|
|
|
|
Each release carries:
|
|
|
|
| Asset | What it is |
|
|
|---|---|
|
|
| `module-uo-<version>.tar.gz` | the directory core expects at `modules/uo/` — already assembled, with the chunk built and `ws` installed |
|
|
| `module-uo-<version>.json` | id, version, `coreApi`, the artifact's URL, size and **`sha256`** |
|
|
| `SHA256SUMS` | the same hash, in the shape every other repo here publishes |
|
|
|
|
Releases are **unsigned**; the `sha256` is the trust anchor, and the website verifies it before
|
|
unpacking. That is the model `installer`'s bundles already use, and a second trust model would be a
|
|
second thing to get right.
|
|
|
|
The tarball is assembled from an **include** list, never an exclude list — an exclude list ships
|
|
whatever it forgot. Tests, scripts, `client/src` and the dev dependencies are not in it.
|
|
|
|
## Environment variables
|
|
|
|
Four, all optional, all read by this module rather than by core — which is why they are documented
|
|
here and not in core's `.env.example`. In Docker they go in the Compose `.env`, since that is what
|
|
reaches the container.
|
|
|
|
| Var | Default | What |
|
|
|---|---|---|
|
|
| `UOLINK_BASE_URL` | — | Default sidecar base URL for a site with nothing saved yet. The admin panel's stored value wins. |
|
|
| `UOLINK_WS_URL` | — | Same, for the WebSocket URL. |
|
|
| `UOLINK_PROTOCOL` | `3` | Wire protocol this build speaks. Again only a fallback — set it lower only if you deliberately run an older sidecar. |
|
|
| `TOWNCRIER_DURATION_SEC` | `3600` | How long a published news post's in-game town-crier message stays up (≤ `86400`). |
|
|
|
|
**The sidecar's auth token is deliberately not here.** It is entered in Admin → Shard, encrypted at
|
|
rest with core's `SECRET_ENC_KEY`, and write-only in the API — never returned to any client.
|
|
|
|
## Compatibility
|
|
|
|
`module.json` declares a `coreApi` semver range, checked at boot against core's `MODULE_API_VERSION`.
|
|
A mismatch fails **loudly** — the module is marked `startup_failed` and the site comes up without it,
|
|
rather than mis-loading. This is a separate number from `PROTOCOL_VERSION`, which versions the shard
|
|
wire protocol and says nothing about a website module.
|
|
|
|
A module that fails to load must never take the site down.
|
|
|
|
## Related repos
|
|
|
|
| Repo | What |
|
|
|------|------|
|
|
| **this** — `RunicGateway/Module-uo` | The UO module: the game-specific half of the website. |
|
|
| [RunicGateway/website](https://gitea.whitlocktech.com/RunicGateway/website) | Core — the site, admin panel and API that loads this module. |
|
|
| [RunicGateway/link](https://gitea.whitlocktech.com/RunicGateway/link) | The **uo-link sidecar** — the network-facing half of the game bridge this module talks to. |
|
|
| [RunicGateway/servuo-plugins](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins) | The **C# ServUO plugin** that feeds the sidecar. |
|
|
| [RunicGateway/installer](https://gitea.whitlocktech.com/RunicGateway/installer) | Deploys the shard side. Not the module delivery path. |
|
|
| [RunicGateway/docs](https://gitea.whitlocktech.com/RunicGateway/docs) | All project documentation, including the module system design and this module's docs under `modules/uo/`. |
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md). Contributions are welcome, AI assistance must be disclosed,
|
|
and security problems go to [SECURITY.md](SECURITY.md) rather than a public issue.
|
|
|
|
## License
|
|
|
|
**GNU General Public License v3.0 or later** — see [LICENSE.md](LICENSE.md).
|