wtclaude
5d7668d5ea
The first real module. It registers nothing, deliberately: what slice 0 proves
is the delivery path itself, end to end, before a single UO file moves into it.
Server half: module.json, an entry point that takes (ctx, api) and registers
nothing, a test suite built on a fake ctx, and scripts/checkImports.js -- the
MODULE_API.md §5.1 boundary check. Client half: the Vite library build, four
shims re-exporting react / react-dom/client / react-router-dom / jsx-runtime
from window.__rg, an entry that verifies each is identity-equal to core's copy,
and scripts/checkExternals.js. 29 server tests, 9 client tests, both new.
Verified against a real core: the module loads, mounts its zero routes, runs to
`started`, and is published by /api/v1/public/modules. Its chunk serves from
the entry's directory with `Cache-Control: no-cache` while the module's server
source, module.json and package.json all 404. In Chrome, under the enforced
`script-src 'self'`, the chunk evaluates and reports all four shared
dependencies OK, with zero CSP reports and no console errors.
Three findings, each of which had produced a green build that was wrong.
MODULE_API.md §3.6 shows `external` alongside the aliases and they do not
compose. Rollup asks `external` BEFORE Vite's alias resolver runs, so a
specifier in both is marked external and never aliased -- the chunk then ships
bare `import "react"`, which no browser can resolve without an import map, and
CSP forbids one. Built cleanly and emitted exactly that; checkExternals caught
it. So: alias only, `external` empty, and vite.config.js grows a resolution-time
guard that fails the build if a shared dependency resolves into node_modules.
That guard was wrong twice before it worked. Written against Rollup's `load`
hook it never ran -- `load` is first-wins and an earlier plugin had already
claimed the module -- so a deliberately-broken alias produced a 24 kB chunk with
react-router welded in, and a green build. And its forbidden-package list was
derived from the alias list "so the two cannot disagree", which meant deleting
an alias also deleted the guard against what that alias prevented. It states the
contract now, and a test asserts the aliases stay inside it.
checkImports failed on its own documentation the first time it ran: the comment
naming require("../../etc/passwd") as an example of what to catch, and index.js
explaining why the module must never require("express"). A boundary check that
cannot survive being described is one people stop writing comments around. It
strips comments and template literals with a character walk rather than a
regexp, because a URL in a string contains a comment opener and a comment
contains quotes -- and it has its own test suite, since a check never shown to
fail is a check nobody knows the state of.
Co-Authored-By: Claude <noreply@anthropic.com>
52 lines
2.6 KiB
JavaScript
52 lines
2.6 KiB
JavaScript
// ── module-uo's server entry point ─────────────────────────────────────────
|
|
//
|
|
// Core requires this file once, synchronously, while `app.js` is still being
|
|
// required, and calls the exported function with `(ctx, api)`. The normative
|
|
// contract is docs/website/MODULE_API.md §2.2; the three rules that shape every
|
|
// line below are worth restating where they will be read:
|
|
//
|
|
// 1. **No `await`, and no database.** `scripts/routeManifest.js` and
|
|
// `swagger/swagger.js` both require core's `app.js` with the pool pointed
|
|
// at a dead port, so a module that queried at registration time would hang
|
|
// both. Anything needing a live database belongs in `onBoot`.
|
|
// 2. **Never resolve what core owns.** This module lives at
|
|
// `<website>/modules/uo/`, outside `server/`, so Node's resolver never
|
|
// reaches core's `node_modules` and `require('express')` fails outright.
|
|
// express and express-validator arrive on `ctx`; so do the database, the
|
|
// logger, the middleware and the rest of §2.3.
|
|
// 3. **Never reach into core's tree.** No relative path may escape this
|
|
// module's root. `scripts/checkImports.js` enforces that in CI (§5.1)
|
|
// rather than leaving it to review.
|
|
//
|
|
// Slice 0 of the Phase 3 extraction (MODULE_SYSTEM.md §2.7.1) deliberately
|
|
// registers NOTHING. The bundle exists, core discovers it, validates it, mounts
|
|
// its zero routes, serves its client chunk and reports it `started` — which is
|
|
// the whole delivery path proved end to end before a single UO file moves into
|
|
// it. Slice 1 brings the atlas; every slice after that adds registrations here
|
|
// and deletes the matching files from core.
|
|
|
|
/**
|
|
* @param {object} ctx what core hands the module (MODULE_API.md §2.3), frozen
|
|
* @param {object} api what the module registers (§2.4)
|
|
*/
|
|
module.exports = function register(ctx, api) {
|
|
const log = ctx.log()
|
|
|
|
// Registrations land here, slice by slice:
|
|
//
|
|
// api.registerRoutes({ public: {...}, admin: {...}, player: {...} })
|
|
// api.registerExtension('admin.users.detail', usersShardRouter)
|
|
// api.registerNotificationStreams(streams)
|
|
// api.registerAnnounceLeg({ leg: 'towncrier', ... })
|
|
// api.onBoot(async (ctx) => { ... })
|
|
// api.onShutdown(async () => { ... })
|
|
//
|
|
// `api` is referenced by this log line and nothing else yet, on purpose: an
|
|
// entry point that took `api` and never named it would read like an oversight
|
|
// rather than a stage of the extraction.
|
|
log.info('registered', {
|
|
version: require('../module.json').version,
|
|
registers: Object.keys(api).length,
|
|
})
|
|
}
|