refactor(modules)!: move the UO server half out to module-uo (phase 3, slice 1) #137

wtclaude · 2026-08-11T17:09:27Z

wtclaude commented

2026-08-11 17:09:27 +00:00

Core's half of slice 1. Merge after Module-uo#3, per §2.7.1's merge order — that way edge serves these routes from core right up to the moment this lands, and never sits missing them.

40 files and ~9,674 lines leave, along with 27 of 68 tables and 25 of 82 test files. Core no longer contains anything that knows what a shard is.

No URL moved

routes.manifest.json goes 228 → 158 public routes here, and the 70 that left reappear byte-identical once the module is loaded. Verified by generating the manifest against core+module and diffing it against the pre-extraction file: zero missing, zero added, and routes.guards.json identical across all 228 — so no auth gate moved either. That is the one manifest diff the workstream allows (API §5.3).

Three commits, readable in order

feat(modules) — the contract additions (API 1.0.0 → 1.1.0)
refactor(modules)! — the deletion and rewiring
test — re-pointing core's suite at what core still owns

The contract additions, and why none could be avoided

ctx.activity.log — an admin action a module performs has to land in core's one audit log, or the trail has a hole exactly where a module operates the game. A module keeping its own log is a second place to look, which in practice means a place nobody looks.
ctx.users.getById — one function for one caller: the admin.users.detail slot router needs the user its prefix names.
ctx.site.baseUrl — §2.7 forbids a module reading core's APP_BASE_URL. A getter, not a captured string, so it cannot go stale against the env.
ctx.middleware.rateLimit (core's makeLimiter) plus accountChangeLimiter handed over whole. A module states its own window and cap because it knows what its endpoints cost, and takes the plumbing from core so there is one express-rate-limit in the process and one place a breach is logged. accountChangeLimiter is shared policy — /auth/me and /player/account sit behind the same counter — so a module's account-change route must land in it, not beside it. marketLimiter was UO policy living in core's file and leaves with the route it guards.

`registerPostHook` — the last thing binding core to the module

Core's post controller called newsGump.syncPost directly: core's CMS naming a UO file. It now publishes what it already knows ({ post, transition } on save, { post, id } on delete) and a subscriber decides what to do with it. Deliberately not folded into registerAnnounceLeg, which fires on the same transition — a leg is a one-shot delivery with retry and classification, while a post hook maintains idempotent state, runs on delete as well as save, and refreshes silently on an edit.

A real loader defect the extraction exposed

Schema table names were matched against the raw file, so a fragment whose header says "every CREATE TABLE carries IF NOT EXISTS" was rejected for a prefix violation on a table called carries. module-uo's fragment hit exactly that on its first real load. Both scans now read split statements, which strip comments — the same class of bug as a boundary check failing on its own documentation, which is where slice 0 found it.

The one test that stayed, and why

playerRouteAccess.test.js guards a real past bug — an admin 403'd off their own characters — through /player/shard/accounts, now module-owned. The guarantee is core's, though: /player/* is role-agnostic self-service, staff are a superset of players. So it stays and asserts that through /player/appeals, a core route with the same gate. Moving it would have left core with no test of its own tier rule, which is precisely what regressed once before.

Verified

616 server tests, 160 client tests, both green. Against a running server with the module installed: it loads, mounts five prefixes, replays 35 statements, reaches started; public shard/atlas answer 200 with real data, admin and player answer 401 from core's tier gates, the extension slot answers. Core's own SPA renders the shard and atlas pages unchanged, no console errors, no CSP reports. Core also boots and passes with no module installed, which is what the schema split had to preserve — no core table ever referenced a module table.

AI-assisted (Claude Code / Claude Opus 5)

Core's half of slice 1. **Merge after Module-uo#3**, per §2.7.1's merge order — that way `edge` serves these routes from core right up to the moment this lands, and never sits missing them. 40 files and ~9,674 lines leave, along with 27 of 68 tables and 25 of 82 test files. **Core no longer contains anything that knows what a shard is.** ## No URL moved `routes.manifest.json` goes **228 → 158** public routes here, and the 70 that left reappear byte-identical once the module is loaded. Verified by generating the manifest against core+module and diffing it against the pre-extraction file: **zero missing, zero added**, and `routes.guards.json` identical across all 228 — so no auth gate moved either. That is the one manifest diff the workstream allows (API §5.3). ## Three commits, readable in order 1. **`feat(modules)`** — the contract additions (API 1.0.0 → 1.1.0) 2. **`refactor(modules)!`** — the deletion and rewiring 3. **`test`** — re-pointing core's suite at what core still owns ## The contract additions, and why none could be avoided - **`ctx.activity.log`** — an admin action a module performs has to land in core's *one* audit log, or the trail has a hole exactly where a module operates the game. A module keeping its own log is a second place to look, which in practice means a place nobody looks. - **`ctx.users.getById`** — one function for one caller: the `admin.users.detail` slot router needs the user its prefix names. - **`ctx.site.baseUrl`** — §2.7 forbids a module reading core's `APP_BASE_URL`. A getter, not a captured string, so it cannot go stale against the env. - **`ctx.middleware.rateLimit`** (core's `makeLimiter`) **plus `accountChangeLimiter`** handed over whole. A module states its own window and cap because it knows what its endpoints cost, and takes the plumbing from core so there is one `express-rate-limit` in the process and one place a breach is logged. `accountChangeLimiter` is shared policy — `/auth/me` and `/player/account` sit behind the same counter — so a module's account-change route must land *in* it, not beside it. `marketLimiter` was UO policy living in core's file and leaves with the route it guards. ## `registerPostHook` — the last thing binding core to the module Core's post controller called `newsGump.syncPost` directly: core's CMS naming a UO file. It now publishes what it already knows (`{ post, transition }` on save, `{ post, id }` on delete) and a subscriber decides what to do with it. Deliberately **not** folded into `registerAnnounceLeg`, which fires on the same transition — a leg is a one-shot delivery with retry and classification, while a post hook maintains idempotent state, runs on delete as well as save, and refreshes silently on an edit. ## A real loader defect the extraction exposed Schema table names were matched against the **raw file**, so a fragment whose header says *"every CREATE TABLE carries IF NOT EXISTS"* was rejected for a prefix violation on a table called `carries`. module-uo's fragment hit exactly that on its first real load. Both scans now read split statements, which strip comments — the same class of bug as a boundary check failing on its own documentation, which is where slice 0 found it. ## The one test that stayed, and why `playerRouteAccess.test.js` guards a real past bug — an admin 403'd off their own characters — through `/player/shard/accounts`, now module-owned. The *guarantee* is core's, though: `/player/*` is role-agnostic self-service, staff are a superset of players. So it stays and asserts that through `/player/appeals`, a core route with the same gate. Moving it would have left core with no test of its own tier rule, which is precisely what regressed once before. ## Verified 616 server tests, 160 client tests, both green. Against a running server with the module installed: it loads, mounts five prefixes, replays 35 statements, reaches `started`; public shard/atlas answer 200 with real data, admin and player answer 401 from core's tier gates, the extension slot answers. Core's own SPA renders the shard and atlas pages unchanged, no console errors, no CSP reports. Core also boots and passes with **no module installed**, which is what the schema split had to preserve — no core table ever referenced a module table. --- - [x] AI-assisted (Claude Code / Claude Opus 5)

wtclaude added 3 commits 2026-08-11 17:09:29 +00:00

feat(modules): ctx additions and the post-hook registry (API 1.1.0) f50541f374

Everything the extraction needed from core that ctx did not already offer.
Additions only, so minor.

ctx.activity.log, because an admin action a module performs has to land in
core's one audit log or the trail has a hole exactly where a module operates the
game -- a module keeping its own log would be a second place to look, which in
practice means a place nobody looks. Write-only; reading the log is the admin
panel's job and it spans every actor.

ctx.users.getById, one function for one caller: the admin.users.detail slot
router needs the user its prefix names. ctx.site.baseUrl, because a module has
to build absolute links and §2.7 forbids it reading core's APP_BASE_URL -- a
getter, not a captured string, so it cannot go stale against the env.

ctx.middleware.rateLimit is core's makeLimiter, plus accountChangeLimiter handed
over whole. The split is deliberate: a module states its own window and cap
because it knows what its endpoints cost, and takes the plumbing from core so
there is one express-rate-limit in the process and one place a breach is logged.
accountChangeLimiter is shared policy -- core's /auth/me and /player/account sit
behind the same counter -- so a module's account-change route has to land IN it
rather than beside it. marketLimiter was UO policy living in core's file and
leaves with the route it guards.

registerPostHook is the fourth registry, and the last thing binding core to the
module. Core's post controller called newsGump.syncPost directly: core's CMS
naming a UO file. It now publishes what it already knows and a subscriber
decides what to do with it. Not folded into registerAnnounceLeg, which fires on
the same transition, because a leg is a one-shot DELIVERY with retry and
classification while a post hook maintains idempotent STATE, runs on delete as
well as save, and refreshes silently on an edit.

Also fixes a real loader defect the extraction exposed: schema table names were
matched against the RAW file, so a fragment whose header says "every CREATE
TABLE carries IF NOT EXISTS" was rejected for a prefix violation on a table
called `carries`. module-uo's fragment hit exactly that. Both scans now read
split statements, which strip comments -- the same class of bug as a boundary
check failing on its own documentation.

Co-Authored-By: Claude <noreply@anthropic.com>

refactor(modules)!: move the UO server half out to module-uo 39d731d87a

40 files, ~9,674 lines, 27 of 68 tables. Core no longer contains anything that
knows what a shard is.

BREAKING for a deployment only in the sense that the module must be installed
for these URLs to answer -- no URL moved. routes.manifest.json goes 228 -> 158
public routes here, and the 70 that left reappear byte-identical when the module
is loaded: verified by generating the manifest against core+module and diffing
it against the pre-extraction file. Zero missing, zero added, and routes.guards
identical across all 228, so no auth gate moved either.

The five tier mounts are gone from public/admin/player index.js and are still
served: the loader mounts them onto the same routers after every core mount.
That ordering is also what keeps the prefixes unclaimable -- the collision check
asks the live router what core owns, so a second module claiming /shard is
rejected against the mounts actually present rather than against a list.

server.js loses its eight UO call sites to the module's onBoot/onShutdown.
schema.sql loses its 27 shard_*/uo_link_* statements; the two that FK into users
are why the fragment replays AFTER core's schema, and no core table ever
referenced a module table, which is what makes core still able to boot alone.

Verified against a running server with the module installed: it loads, mounts
five prefixes, replays 35 statements, warms up and reaches `started`; public
shard and atlas routes answer 200 with real data (800 creatures, 6,455
spawners), admin and player answer 401 from core's tier gates, and the extension
slot answers at /admin/users/:id/shard/*. Core's own SPA renders the shard and
atlas pages unchanged against the module-served API, with no console errors and
no CSP reports.

Co-Authored-By: Claude <noreply@anthropic.com>

test: re-point core's suite at what core still owns

PR Checks / bot-install (pull_request) Successful in 18s

Details

PR Checks / client-build (pull_request) Successful in 27s

Details

PR Checks / server-tests (pull_request) Successful in 29s

Details

f5e6025dcc

25 of 82 test files left with the module. Three that core keeps needed splitting
rather than moving, and the split is the boundary in each case.

announceJobs.test.js keeps the announce PIPELINE -- the shared backoff schedule,
the parent-status rollup, core's Discord leg -- and loses the town-crier text
building and classification, which are a module's leg. pushDispatch.test.js
keeps the SSRF guard and publish() delivering a content-free tickle, and loses
mapShardEvent and the shard fan-out, which are a module's catalog.

playerRouteAccess.test.js is the one worth explaining. It guards a real past bug
-- an admin 403'd off their own characters -- and it did so through
/player/shard/accounts, which is now module-owned. The guarantee it protects is
CORE's, though: /player/* is role-agnostic self-service, staff are a superset of
players. So it stays here and asserts that through /player/appeals, a core route
with the same gate. Moving it would have left core with no test of its own tier
rule, which is precisely what regressed once before.

The remaining updates are core's own tests catching up: ctx has four more
members, registerCore now registers only what core owns (one stream, one leg, no
filled slot), and the extension-slot test asks for the DECLARED slot's router
rather than the filled one, since core declares it and a module fills it. The
gated-surface floor drops from >100 to >50 -- it is there so a filter matching
nothing fails loudly, not to track core's exact route count.

616 core tests and 160 client tests pass; the module's own suite is 351.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech merged commit 7a236cad8b into edge

2026-08-11 21:06:25 +00:00

whitlocktech referenced this issue from a commit

2026-08-11 21:06:26 +00:00

Merge pull request 'refactor(modules)!: move the UO server half out to module-uo (phase 3, slice 1)' (#137) from feature/module-extract-server into edge

whitlocktech deleted branch feature/module-extract-server

2026-08-11 21:06:27 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/website#137

refactor(modules)!: move the UO server half out to module-uo (phase 3, slice 1) #137

No URL moved

Three commits, readable in order

The contract additions, and why none could be avoided

registerPostHook — the last thing binding core to the module

A real loader defect the extraction exposed

The one test that stayed, and why

Verified

`registerPostHook` — the last thing binding core to the module