From f50541f3742fcf93209b289f52ea4d257f723c2d Mon Sep 17 00:00:00 2001 From: wtclaude Date: Tue, 11 Aug 2026 12:07:45 -0500 Subject: [PATCH] feat(modules): ctx additions and the post-hook registry (API 1.1.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- client/src/modules/version.js | 7 +- server/db/data/spawnAtlas.art.example.json | 24 - server/scripts/importSpawnAtlas.js | 127 ---- server/src/config/shardStreams.js | 172 ----- server/src/middleware/rateLimit.js | 22 +- server/src/model/shardAtlas/shardAtlas.db.js | 390 ---------- .../src/model/shardAtlas/shardAtlas.model.js | 485 ------------- .../src/model/shardClilocs/shardClilocs.db.js | 108 --- .../model/shardClilocs/shardClilocs.model.js | 368 ---------- .../src/model/shardEvents/shardEvents.db.js | 46 -- .../model/shardEvents/shardEvents.model.js | 61 -- server/src/model/shardLinks/shardLinks.db.js | 42 -- .../src/model/shardLinks/shardLinks.model.js | 37 - .../src/model/shardMarket/shardMarket.db.js | 299 -------- .../model/shardMarket/shardMarket.model.js | 329 --------- server/src/model/shardState/shardState.db.js | 369 ---------- .../src/model/shardState/shardState.model.js | 638 ---------------- .../shardVisibility/shardVisibility.db.js | 37 - .../shardVisibility/shardVisibility.model.js | 44 -- .../src/model/uoLinkConfig/uoLinkConfig.db.js | 7 - .../model/uoLinkConfig/uoLinkConfig.model.js | 88 --- server/src/modules/loader.js | 66 +- server/src/modules/registries.js | 107 ++- server/src/modules/version.js | 7 +- .../src/router/v1/admin/admin.controller.js | 21 +- server/src/router/v1/admin/shard.router.js | 386 ---------- .../router/v1/admin/shardAtlas.controller.js | 117 --- .../v1/admin/shardClilocs.controller.js | 106 --- .../router/v1/admin/shardOps.controller.js | 171 ----- .../v1/admin/shardVisibility.controller.js | 98 --- .../src/router/v1/admin/uoLink.controller.js | 123 ---- server/src/router/v1/admin/uoLink.router.js | 99 --- .../router/v1/admin/usersShard.controller.js | 130 ---- .../src/router/v1/admin/usersShard.router.js | 111 --- .../src/router/v1/player/shard.controller.js | 274 ------- server/src/router/v1/player/shard.router.js | 124 ---- .../src/router/v1/public/atlas.controller.js | 134 ---- server/src/router/v1/public/atlas.router.js | 128 ---- .../src/router/v1/public/shard.controller.js | 422 ----------- server/src/router/v1/public/shard.router.js | 253 ------- server/src/utils/clilocParse.js | 287 -------- server/src/utils/clilocSource.js | 316 -------- server/src/utils/newsGump.js | 124 ---- server/src/utils/shardAnnounce.js | 77 -- server/src/utils/shardBroadcast.js | 166 ----- server/src/utils/shardIngest.js | 314 -------- server/src/utils/shardPush.js | 47 -- server/src/utils/shardSales.js | 26 - server/src/utils/shardVisibility.js | 435 ----------- server/src/utils/spawnAtlasParse.js | 686 ------------------ server/src/utils/spawnAtlasSource.js | 336 --------- server/src/utils/uoLinkClient.js | 224 ------ server/src/utils/uoLinkSocket.js | 313 -------- server/test/adminUserShard.test.js | 150 ---- server/test/atlasController.test.js | 238 ------ server/test/clilocParse.test.js | 227 ------ server/test/clilocSource.test.js | 194 ----- server/test/newsGump.test.js | 69 -- server/test/publicShardOnline.test.js | 105 --- server/test/shardBroadcast.visibility.test.js | 225 ------ server/test/shardControllerPublic.test.js | 412 ----------- server/test/shardIngest.champsPages.test.js | 71 -- server/test/shardIngest.market.test.js | 114 --- server/test/shardIngest.points.test.js | 111 --- server/test/shardIngest.protocol2.test.js | 121 --- server/test/shardIngest.ruleset.test.js | 161 ---- server/test/shardMarket.model.test.js | 260 ------- server/test/shardState.governorTerms.test.js | 77 -- server/test/shardState.model.test.js | 253 ------- server/test/shardVisibility.test.js | 423 ----------- server/test/spawnAtlas.parse.test.js | 601 --------------- server/test/spawnAtlas.source.test.js | 396 ---------- server/test/uoLinkClient.test.js | 71 -- 73 files changed, 187 insertions(+), 14020 deletions(-) delete mode 100644 server/db/data/spawnAtlas.art.example.json delete mode 100644 server/scripts/importSpawnAtlas.js delete mode 100644 server/src/config/shardStreams.js delete mode 100644 server/src/model/shardAtlas/shardAtlas.db.js delete mode 100644 server/src/model/shardAtlas/shardAtlas.model.js delete mode 100644 server/src/model/shardClilocs/shardClilocs.db.js delete mode 100644 server/src/model/shardClilocs/shardClilocs.model.js delete mode 100644 server/src/model/shardEvents/shardEvents.db.js delete mode 100644 server/src/model/shardEvents/shardEvents.model.js delete mode 100644 server/src/model/shardLinks/shardLinks.db.js delete mode 100644 server/src/model/shardLinks/shardLinks.model.js delete mode 100644 server/src/model/shardMarket/shardMarket.db.js delete mode 100644 server/src/model/shardMarket/shardMarket.model.js delete mode 100644 server/src/model/shardState/shardState.db.js delete mode 100644 server/src/model/shardState/shardState.model.js delete mode 100644 server/src/model/shardVisibility/shardVisibility.db.js delete mode 100644 server/src/model/shardVisibility/shardVisibility.model.js delete mode 100644 server/src/model/uoLinkConfig/uoLinkConfig.db.js delete mode 100644 server/src/model/uoLinkConfig/uoLinkConfig.model.js delete mode 100644 server/src/router/v1/admin/shard.router.js delete mode 100644 server/src/router/v1/admin/shardAtlas.controller.js delete mode 100644 server/src/router/v1/admin/shardClilocs.controller.js delete mode 100644 server/src/router/v1/admin/shardOps.controller.js delete mode 100644 server/src/router/v1/admin/shardVisibility.controller.js delete mode 100644 server/src/router/v1/admin/uoLink.controller.js delete mode 100644 server/src/router/v1/admin/uoLink.router.js delete mode 100644 server/src/router/v1/admin/usersShard.controller.js delete mode 100644 server/src/router/v1/admin/usersShard.router.js delete mode 100644 server/src/router/v1/player/shard.controller.js delete mode 100644 server/src/router/v1/player/shard.router.js delete mode 100644 server/src/router/v1/public/atlas.controller.js delete mode 100644 server/src/router/v1/public/atlas.router.js delete mode 100644 server/src/router/v1/public/shard.controller.js delete mode 100644 server/src/router/v1/public/shard.router.js delete mode 100644 server/src/utils/clilocParse.js delete mode 100644 server/src/utils/clilocSource.js delete mode 100644 server/src/utils/newsGump.js delete mode 100644 server/src/utils/shardAnnounce.js delete mode 100644 server/src/utils/shardBroadcast.js delete mode 100644 server/src/utils/shardIngest.js delete mode 100644 server/src/utils/shardPush.js delete mode 100644 server/src/utils/shardSales.js delete mode 100644 server/src/utils/shardVisibility.js delete mode 100644 server/src/utils/spawnAtlasParse.js delete mode 100644 server/src/utils/spawnAtlasSource.js delete mode 100644 server/src/utils/uoLinkClient.js delete mode 100644 server/src/utils/uoLinkSocket.js delete mode 100644 server/test/adminUserShard.test.js delete mode 100644 server/test/atlasController.test.js delete mode 100644 server/test/clilocParse.test.js delete mode 100644 server/test/clilocSource.test.js delete mode 100644 server/test/newsGump.test.js delete mode 100644 server/test/publicShardOnline.test.js delete mode 100644 server/test/shardBroadcast.visibility.test.js delete mode 100644 server/test/shardControllerPublic.test.js delete mode 100644 server/test/shardIngest.champsPages.test.js delete mode 100644 server/test/shardIngest.market.test.js delete mode 100644 server/test/shardIngest.points.test.js delete mode 100644 server/test/shardIngest.protocol2.test.js delete mode 100644 server/test/shardIngest.ruleset.test.js delete mode 100644 server/test/shardMarket.model.test.js delete mode 100644 server/test/shardState.governorTerms.test.js delete mode 100644 server/test/shardState.model.test.js delete mode 100644 server/test/shardVisibility.test.js delete mode 100644 server/test/spawnAtlas.parse.test.js delete mode 100644 server/test/spawnAtlas.source.test.js delete mode 100644 server/test/uoLinkClient.test.js diff --git a/client/src/modules/version.js b/client/src/modules/version.js index 1d4ff98..b527fe5 100644 --- a/client/src/modules/version.js +++ b/client/src/modules/version.js @@ -11,4 +11,9 @@ // that the two files can drift, so a test asserts they agree // (client/test/moduleRegistry.test.js) rather than trusting a bump to remember // both. -export const MODULE_API_VERSION = '1.0.0' +// 1.1.0 — the server's ctx gained activity.log, users.getById, site.baseUrl and +// the rate-limit factory (MODULE_API.md §2.3). Nothing on window.__rg changed, +// but the two halves state ONE version: a module declares a single coreApi range +// and is served one chunk, so a client that claimed 1.0.0 while the server +// answered 1.1.0 would be two answers to one question. +export const MODULE_API_VERSION = '1.1.0' diff --git a/server/db/data/spawnAtlas.art.example.json b/server/db/data/spawnAtlas.art.example.json deleted file mode 100644 index 309108a..0000000 --- a/server/db/data/spawnAtlas.art.example.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "_comment": [ - "OPTIONAL operator-supplied creature art for the spawn atlas. Copy this file to", - "spawnAtlas.art.json (same directory) and edit it, then restart the server or run", - "`npm run atlas:import` — the art map is read on every atlas refresh.", - "", - "This project ships NO creature artwork and never will. UO sprites live in your", - "own client's .mul/.uop files and are yours to extract, not ours to redistribute.", - "If you want art on the atlas pages, export it yourself (UOFiddler, ClassicUO's", - "tooling, or any art extractor), drop the images under server/uploads/atlas/, and", - "map each creature slug to its file name here.", - "", - "Both spawnAtlas.art.json and server/uploads/ are gitignored, so neither the map", - "nor the images can be committed by accident.", - "", - "Keys are creature slugs, as reported by the atlas API and derived from the type", - "names in your own shard's Spawns/*.xml. Values are file names relative to", - "server/uploads/atlas/. Any creature with no entry here simply renders without", - "art — that is the default and fully supported state, not a degraded one." - ], - "lizardman": "lizardman.png", - "orc": "orc.png", - "dragon": "dragon.png" -} diff --git a/server/scripts/importSpawnAtlas.js b/server/scripts/importSpawnAtlas.js deleted file mode 100644 index b9ecbb8..0000000 --- a/server/scripts/importSpawnAtlas.js +++ /dev/null @@ -1,127 +0,0 @@ -#!/usr/bin/env node -// -// Refresh the spawn atlas from a ServUO tree, from the command line. -// -// npm run atlas:import # use the configured path -// npm run atlas:import -- --servuo # override it for this run -// npm run atlas:import -- --force # reimport even if unchanged -// npm run atlas:import -- --approve # apply a staged refresh -// npm run atlas:import -- --status # report without changing anything -// -// The server does this itself on every boot (see `shardAtlas.refreshOnBoot`), so -// this is for operators who want to apply a map change without a restart, and -// for approving a refresh that was staged because it would remove a facet. -// -// All the logic lives in `src/model/shardAtlas/shardAtlas.model.js`; this file -// is argument parsing and output formatting. - -const db = () => require('../src/utils/db') - -function parseArgs(argv) { - const args = {} - for (let i = 0; i < argv.length; i += 1) { - const flag = argv[i] - if (flag === '--servuo') args.servuo = argv[++i] - else if (flag === '--force') args.force = true - else if (flag === '--approve') args.approve = true - else if (flag === '--reject') args.reject = true - else if (flag === '--status') args.status = true - else if (flag === '--help' || flag === '-h') args.help = true - } - return args -} - -const USAGE = ` -Refresh the spawn atlas from a ServUO tree. - - node scripts/importSpawnAtlas.js [options] - - --servuo Use this tree for this run instead of the configured path. - --force Reimport even when the source files are unchanged. - --approve Apply a refresh that was staged for removing a facet. - --reject Keep the current atlas and dismiss the staged refresh. - --status Report atlas and source state; change nothing. - -With no options this imports only if the tree differs from what is loaded. -` - -function describe(result) { - switch (result.status) { - case 'skipped': - return ( - 'No ServUO path configured — nothing to import.\n' + - 'Set one with SERVUO_PATH, the admin panel, or --servuo .\n' - ) - case 'unavailable': - return `ServUO tree unavailable: ${result.reason}\n` - case 'unchanged': - return `Atlas is already up to date${result.reason ? ` (${result.reason})` : ''}.\n` - case 'needsReview': { - return ( - 'Refresh NOT applied — it would remove ' + - `${result.removedFacets.length} facet(s): ${result.removedFacets.join(', ')}.\n` + - 'This is what a half-copied or mid-update tree looks like, so it has been\n' + - 'staged for review. The current atlas is unchanged.\n' + - 'Apply it with --approve, or dismiss it with --reject.\n' - ) - } - case 'imported': { - const c = result.counts - const added = result.addedFacets?.length ? ` Added facets: ${result.addedFacets.join(', ')}.` : '' - const removed = result.removedFacets?.length - ? ` Removed facets: ${result.removedFacets.join(', ')}.` - : '' - return ( - `Atlas imported: ${c.points} points, ${c.creatures} creatures, ` + - `${c.pointTypes} point/type rows, ${c.regions} regions, ` + - `${c.landmarks} landmarks, ${c.champions} champion altars.${added}${removed}\n` - ) - } - case 'failed': - return `Atlas refresh failed: ${result.reason}\n` - default: - return `${JSON.stringify(result, null, 2)}\n` - } -} - -async function main() { - const args = parseArgs(process.argv.slice(2)) - if (args.help) { - process.stdout.write(USAGE) - return - } - - const shardAtlas = require('../src/model/shardAtlas/shardAtlas.model') - - // `--servuo` is a per-run override and deliberately does NOT persist to the - // configured path; changing where the atlas permanently reads from is an - // admin action, not a side effect of a one-off import. - const override = { path: args.servuo ?? '' } - - if (args.status) { - process.stdout.write(`${JSON.stringify(await shardAtlas.status(override), null, 2)}\n`) - return - } - if (args.reject) { - process.stdout.write(`${JSON.stringify(await shardAtlas.rejectPending(), null, 2)}\n`) - return - } - - const result = args.approve - ? await shardAtlas.approvePending(override) - : await shardAtlas.refresh({ ...override, force: Boolean(args.force) }) - - process.stdout.write(describe(result)) - if (result.status === 'failed') process.exitCode = 1 -} - -if (require.main === module) { - main() - .catch((err) => { - process.stderr.write(`atlas:import failed: ${err.message}\n`) - process.exitCode = 1 - }) - .finally(() => db().close()) -} - -module.exports = { describe, parseArgs } diff --git a/server/src/config/shardStreams.js b/server/src/config/shardStreams.js deleted file mode 100644 index 35add2d..0000000 --- a/server/src/config/shardStreams.js +++ /dev/null @@ -1,172 +0,0 @@ -// ── Shard-derived push streams + event → stream mapping ──────────────────── -// -// MODULE-UO CONTENT, still living in core. MODULE_SYSTEM.md §1.8 named -// config/notificationStreams.js as one of the three genuinely entangled files: -// most of its catalog and all of `mapShardEvent` are shard-derived, and it reads -// `PUBLIC_KINDS` out of utils/shardBroadcast. PR 4 split it — core's one stream -// is config/coreStreams.js, and everything shard-shaped is here, in a file that -// moves to module-uo whole in Phase 3. Nothing in core imports it except -// modules/registries.js's registerCore(), which is the one line Phase 3 deletes. -// -// Two families: -// • public / opt-in — no linked game account required; delivered to every -// subscriber. Drawn ONLY from the SSE public allowlist -// (utils/shardBroadcast PUBLIC_KINDS) — a sensitive kind -// can never produce a public push. -// • personal / owner-keyed — require a linked game account; delivered ONLY to -// the owning user's devices (resolved from the event's -// game account via shardLinks), never fanned out publicly. -// -// The payload the relay ever carries is a CONTENT-FREE tickle ({ stream, ref }); -// `ref` is an opaque hint (serial / city / timestamp) the app uses to pull the -// real, ownership-checked content over the authenticated API. So even a leaked -// ntfy topic reveals nothing (docs/android/PLAN.md §11). - -const { PUBLIC_KINDS } = require('../utils/shardBroadcast') - -const STREAMS = [ - { - id: 'server.status', - label: 'Server up / down', - description: 'The shard comes online or goes offline.', - personal: false, - requiresLinkedAccount: false, - }, - { - id: 'idoc.warning', - label: 'IDOC warnings', - description: 'A house falls into its final (IDOC) decay stage.', - personal: false, - requiresLinkedAccount: false, - }, - { - id: 'champ.start', - label: 'Champion spawn starts', - description: 'A champion spawn becomes active.', - personal: false, - requiresLinkedAccount: false, - }, - { - id: 'governor.election', - label: 'Governor elections', - description: 'A town elects a new governor.', - personal: false, - requiresLinkedAccount: false, - }, - { - id: 'vendor.sale', - label: 'Your vendor sold an item', - description: 'One of your player vendors made a sale.', - personal: true, - requiresLinkedAccount: true, - }, - { - id: 'house.idoc', - label: 'Your house entered IDOC', - description: 'One of your houses fell into its final decay stage.', - personal: true, - requiresLinkedAccount: true, - }, - { - id: 'account.login', - label: 'A login to your account', - description: 'An authentication attempt against your game account.', - personal: true, - requiresLinkedAccount: true, - }, -] - -// The owner-keyed subset, needed by mapShardEvent's public-safety filter below. -// Derived from this file's own catalog rather than read back out of the registry: -// the filter is about THESE streams, and a module must not be able to weaken it -// by registering something that happens to share an id. -const PERSONAL_STREAMS = new Set(STREAMS.filter((s) => s.personal).map((s) => s.id)) - -// Per-process transition state so full-state upserts (champ.update / city.update -// are upserts, not discrete "started"/"elected" events — see docs/link -// PROTOCOL_2 §383) only fire once, on an actual transition. Injectable so tests -// pass a fresh tracker; a module-level default backs the live dispatcher. -function createTracker() { - return { champActive: new Map(), cityGovernor: new Map() } -} -const defaultTracker = createTracker() - -// Per-kind mappers, each pushing 0+ targets onto `out` (and updating `tracker` -// for the upsert-transition kinds). Split out of mapShardEvent so that function -// stays a trivial dispatch + the public-safety filter. -const serverStatusUp = (event, tracker, out) => - out.push({ streamId: 'server.status', ref: `up:${event.bootId || ''}` }) -const serverStatusDown = (event, tracker, out) => out.push({ streamId: 'server.status', ref: 'down' }) - -const EVENT_MAPPERS = { - 'server.hello': serverStatusUp, - 'server.shutdown': serverStatusDown, - 'server.crashed': serverStatusDown, - 'house.decay': (event, tracker, out) => { - if (String(event.to).toUpperCase() !== 'IDOC') return - const ref = String(event.serial ?? '') - out.push({ streamId: 'idoc.warning', ref }) // public — location only - if (event.ownerAcct) { - out.push({ streamId: 'house.idoc', ref, ownerAccount: event.ownerAcct }) // personal - } - }, - 'champ.update': (event, tracker, out) => { - const { serial } = event - if (serial == null) return - const wasActive = tracker.champActive.get(serial) === true - const isActive = event.active === true - tracker.champActive.set(serial, isActive) - if (isActive && !wasActive) out.push({ streamId: 'champ.start', ref: String(serial) }) - }, - 'champ.remove': (event, tracker) => { - if (event.serial != null) tracker.champActive.delete(event.serial) - }, - 'city.update': (event, tracker, out) => { - const { city } = event - if (!city) return - const gov = event.governor && event.governor.serial != null ? String(event.governor.serial) : null - const prev = tracker.cityGovernor.get(city) - tracker.cityGovernor.set(city, gov) - // Only a real transition to a new governor, and never on first sight - // (prev === undefined) so a reconnect snapshot isn't read as an election. - if (prev !== undefined && gov && gov !== prev) { - out.push({ streamId: 'governor.election', ref: String(city) }) - } - }, - 'vendor.sale': (event, tracker, out) => { - if (event.ownerAcct) { - out.push({ streamId: 'vendor.sale', ref: String(event.t ?? ''), ownerAccount: event.ownerAcct }) - } - }, - 'account.login.attempt': (event, tracker, out) => { - if (event.acct) { - out.push({ streamId: 'account.login', ref: String(event.t ?? ''), ownerAccount: event.acct }) - } - }, -} - -// Map one shard event → an array of targets ({ streamId, ref, ownerAccount? }). -// May yield 0, 1, or 2 targets (an owner house.decay produces both the public -// idoc.warning and the personal house.idoc). Pure given `tracker`. -function mapShardEvent(event, tracker = defaultTracker) { - if (!event || typeof event.kind !== 'string') return [] - const kind = event.kind - const out = [] - - const mapper = EVENT_MAPPERS[kind] - if (mapper) mapper(event, tracker, out) - - // Defense in depth: a PUBLIC (non-personal) target may only ride a public-safe - // kind. Personal targets are owner-keyed and delivered solely to the owner, so - // they are exempt from the public allowlist (that is the whole point of the - // owner-keyed split). This guarantees a sensitive kind can never leak publicly - // even if a future mapping case is added carelessly. - // - // This filter, the kinds it reads and the streams it protects now all live in - // one file and move together — the reason PR 4 dropped the contract's - // `mapEvent` half rather than leaving the mapping in core and the catalog in a - // module (MODULE_API.md §2.4). - return out.filter((t) => (PERSONAL_STREAMS.has(t.streamId) ? true : PUBLIC_KINDS.has(kind))) -} - -module.exports = { STREAMS, mapShardEvent, createTracker, PERSONAL_STREAMS } diff --git a/server/src/middleware/rateLimit.js b/server/src/middleware/rateLimit.js index 7821694..db1fa2d 100644 --- a/server/src/middleware/rateLimit.js +++ b/server/src/middleware/rateLimit.js @@ -118,19 +118,6 @@ const passwordResetConfirmLimiter = makeLimiter({ message: 'Too many attempts. Please try again later.', }) -// The player-vendor market search. The first genuinely expensive PUBLIC endpoint -// on the site: every call is a LIKE scan plus a COUNT over the listings table, -// which on a large shard is the biggest table there is, and it is anonymous by -// default. Generous for a human browsing shops (a typed search is debounced to -// one request, and paging is a click), tight enough that it cannot be used as a -// cheap way to load the database. -const marketLimiter = makeLimiter({ - windowMs: 60 * 1000, - max: 60, - label: 'market', - message: 'Too many searches. Please slow down.', -}) - // CSP violation reports. Unauthenticated by necessity (browsers send them with no // session), and every accepted report writes a log line — so an attacker who can get // a victim to load a page could otherwise use it as a log-flood amplifier. Generous @@ -144,6 +131,14 @@ const cspReportLimiter = makeLimiter({ }) module.exports = { + // Exported for modules (MODULE_API.md 2.3, added in API 1.1.0). A module + // writes its own policy -- the window and the cap are its business, since it + // knows what its endpoints cost -- but it takes the PLUMBING from here: one + // express-rate-limit in the process, one store, and one place limit breaches + // are logged. A module resolving the package itself would get a second store, + // and a limit enforced by two independent counters is not the limit either of + // them states. + makeLimiter, loginLimiter, registerLimiter, accountChangeLimiter, @@ -154,6 +149,5 @@ module.exports = { mobileSsoExchangeLimiter, passwordResetRequestLimiter, passwordResetConfirmLimiter, - marketLimiter, cspReportLimiter, } diff --git a/server/src/model/shardAtlas/shardAtlas.db.js b/server/src/model/shardAtlas/shardAtlas.db.js deleted file mode 100644 index ae05106..0000000 --- a/server/src/model/shardAtlas/shardAtlas.db.js +++ /dev/null @@ -1,390 +0,0 @@ -const { pool, query } = require('../../utils/db') - -// Raw SQL for the spawn atlas. Every table here is IMPORT-OWNED: `replaceAtlas` -// empties and refills all six inside one transaction, and nothing else in the -// codebase writes to them. There are no foreign keys, consistent with every -// other shard_* table. - -const BATCH = 500 - -const ATLAS_TABLES = [ - 'shard_spawn_point_types', - 'shard_spawn_points', - 'shard_spawn_creatures', - 'shard_regions', - 'shard_landmarks', - 'shard_champion_spawns', -] - -async function insertBatched(conn, sql, rows) { - for (let i = 0; i < rows.length; i += BATCH) { - await conn.batch(sql, rows.slice(i, i + BATCH)) - } - return rows.length -} - -/** - * Replace the entire atlas in one transaction. - * - * All-or-nothing on purpose: a failed reload must leave the previous atlas - * intact rather than a half-loaded world, since a partially-imported atlas is - * indistinguishable from a real one to anyone reading it. - * - * `DELETE`, not `TRUNCATE` — `TRUNCATE` is DDL in MariaDB and implicitly - * commits, which would defeat exactly that guarantee. At ~7k rows the cost of - * `DELETE` is irrelevant. - */ -async function replaceAtlas(atlas, art = {}) { - const conn = await pool.getConnection() - const counts = {} - try { - await conn.beginTransaction() - - for (const table of ATLAS_TABLES) await conn.query(`DELETE FROM ${table}`) - - counts.creatures = await insertBatched( - conn, - 'INSERT INTO shard_spawn_creatures (slug, name, total, points, facets, art) VALUES (?,?,?,?,?,?)', - atlas.creatures.map((c) => [ - c.slug, - c.name, - c.total ?? 0, - c.points ?? 0, - JSON.stringify(c.facets ?? {}), - art[c.slug] ?? null, - ]), - ) - - counts.regions = await insertBatched( - conn, - 'INSERT INTO shard_regions (facet, name, type, priority, parent, rects) VALUES (?,?,?,?,?,?)', - atlas.regions.map((r) => [ - r.facet, - r.name, - r.type || null, - r.priority ?? 0, - r.parent || null, - JSON.stringify(r.rects ?? []), - ]), - ) - - counts.landmarks = await insertBatched( - conn, - 'INSERT INTO shard_landmarks (facet, name, grp, x, y, z) VALUES (?,?,?,?,?,?)', - atlas.landmarks.map((l) => [ - l.facet, - l.name, - l.group || null, - l.x ?? 0, - l.y ?? 0, - l.z ?? 0, - ]), - ) - - counts.champions = await insertBatched( - conn, - 'INSERT INTO shard_champion_spawns ' + - '(slug, name, grp, type, random_type, facet, x, y, z, radius, label) ' + - 'VALUES (?,?,?,?,?,?,?,?,?,?,?)', - atlas.champions.map((c) => [ - c.slug, - c.name, - c.group || null, - c.type || null, - c.randomType ? 1 : 0, - c.facet, - c.x ?? 0, - c.y ?? 0, - c.z ?? 0, - c.radius ?? 0, - c.label || null, - ]), - ) - - // Point ids are assigned explicitly rather than left to AUTO_INCREMENT: the - // join rows need to know them and `conn.batch()` reports no usable insertId - // for a multi-row insert. Safe because this transaction just emptied the - // table and nothing else writes to it. - counts.points = await insertBatched( - conn, - 'INSERT INTO shard_spawn_points ' + - '(id, facet, name, x, y, width, height, spawn_range, max_count, min_delay, max_delay, ' + - 'tod_start, tod_end, tod_mode, region, landmark, label) ' + - 'VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)', - atlas.points.map((p, i) => [ - i + 1, - p.facet, - p.name, - p.x, - p.y, - p.width ?? 0, - p.height ?? 0, - p.range ?? 0, - p.maxCount ?? 0, - p.minDelay ?? 0, - p.maxDelay ?? 0, - p.todStart ?? 0, - p.todEnd ?? 0, - p.todMode ?? 0, - p.region, - p.landmark, - p.label || 'Wilderness', - ]), - ) - - counts.pointTypes = await insertBatched( - conn, - 'INSERT INTO shard_spawn_point_types (point_id, slug, max_count) VALUES (?,?,?)', - atlas.pointTypes, - ) - - await conn.query( - 'INSERT INTO shard_atlas_meta (id, payload) VALUES (1, ?) ' + - 'ON DUPLICATE KEY UPDATE payload = VALUES(payload), imported_at = CURRENT_TIMESTAMP', - [JSON.stringify({ ...atlas.meta, importedCounts: counts })], - ) - - // A completed import answers whatever was pending. - await conn.query('DELETE FROM shard_atlas_pending') - - await conn.commit() - return counts - } catch (err) { - await conn.rollback().catch(() => {}) - throw err - } finally { - conn.release() - } -} - -async function getMeta() { - const rows = await query('SELECT payload, imported_at FROM shard_atlas_meta WHERE id = 1') - if (rows.length === 0) return null - const payload = typeof rows[0].payload === 'string' ? JSON.parse(rows[0].payload) : rows[0].payload - return { ...payload, importedAt: rows[0].imported_at } -} - -/** Facet names currently loaded, used to detect a facet disappearing. */ -async function getFacets() { - const rows = await query('SELECT DISTINCT facet FROM shard_spawn_points ORDER BY facet') - return rows.map((row) => row.facet) -} - -// ── Pending review ───────────────────────────────────────────────────────── - -async function getPending() { - const rows = await query('SELECT payload, status, detected_at FROM shard_atlas_pending WHERE id = 1') - if (rows.length === 0) return null - const payload = typeof rows[0].payload === 'string' ? JSON.parse(rows[0].payload) : rows[0].payload - return { ...payload, status: rows[0].status, detectedAt: rows[0].detected_at } -} - -async function setPending(payload, status = 'pending') { - return query( - 'INSERT INTO shard_atlas_pending (id, status, payload) VALUES (1, ?, ?) ' + - 'ON DUPLICATE KEY UPDATE status = VALUES(status), payload = VALUES(payload), ' + - 'detected_at = CURRENT_TIMESTAMP', - [status, JSON.stringify(payload)], - ) -} - -async function clearPending() { - return query('DELETE FROM shard_atlas_pending') -} - -// ── Reads (the public /atlas surface) ────────────────────────────────────── -// -// Every read here is a plain indexed query over ~7k rows and is served entirely -// from MariaDB: the atlas is static shard content, so nothing on this path -// touches the sidecar and nothing degrades when the shard is down. -// -// A facet filter is expressed as EXISTS over the points, never as a JSON path -// built from caller input. `shard_spawn_creatures.facets` is a JSON object keyed -// by facet name, and matching a key means either concatenating the name into a -// path or handing it to JSON_SEARCH — whose search string treats `%` and `_` as -// wildcards, so `?facet=%` would quietly match everything. The join is exact and -// uses the indexes that already exist. -const CREATURE_FACET_EXISTS = `EXISTS ( - SELECT 1 FROM shard_spawn_point_types t - JOIN shard_spawn_points p ON p.id = t.point_id - WHERE t.slug = c.slug AND p.facet = ? -)` - -// Build the WHERE for a creature search. `q` is a substring match on the display -// name — a LIKE scan, which is free at ~800 rows and, unlike FULLTEXT, has no -// minimum token length to break a search for "orc". -function creatureWhere({ q, facet }) { - const where = [] - const params = [] - if (q) { - where.push('c.name LIKE ?') - params.push(`%${q}%`) - } - if (facet) { - where.push(CREATURE_FACET_EXISTS) - params.push(facet) - } - return { sql: where.length ? `WHERE ${where.join(' AND ')}` : '', params } -} - -async function countCreatures({ q = '', facet = '' } = {}) { - const { sql, params } = creatureWhere({ q, facet }) - const rows = await query(`SELECT COUNT(*) AS n FROM shard_spawn_creatures c ${sql}`, params) - return rows[0] ? Number(rows[0].n) : 0 -} - -function listCreatures({ q = '', facet = '', limit = 50, offset = 0 } = {}) { - const { sql, params } = creatureWhere({ q, facet }) - return query( - `SELECT c.slug, c.name, c.total, c.points, c.facets, c.art - FROM shard_spawn_creatures c - ${sql} - ORDER BY c.total DESC, c.name ASC - LIMIT ? OFFSET ?`, - [...params, limit, offset], - ) -} - -async function getCreature(slug) { - const rows = await query( - 'SELECT slug, name, total, points, facets, art FROM shard_spawn_creatures WHERE slug = ?', - [slug], - ) - return rows[0] || null -} - -/** - * Where a creature spawns, grouped by resolved place. - * - * This is the answer the atlas exists to give — "lizardman → Shrines, - * Isamu-Jima, Yew" — so it is aggregated in SQL rather than by summing 6,455 - * point rows in Node. - */ -function listCreaturePlaces(slug, { facet = '' } = {}) { - const params = [slug] - let facetSql = '' - if (facet) { - facetSql = 'AND p.facet = ?' - params.push(facet) - } - return query( - `SELECT p.facet, p.label, COUNT(*) AS spawners, SUM(t.max_count) AS max_alive - FROM shard_spawn_point_types t - JOIN shard_spawn_points p ON p.id = t.point_id - WHERE t.slug = ? ${facetSql} - GROUP BY p.facet, p.label - ORDER BY spawners DESC, p.facet ASC, p.label ASC`, - params, - ) -} - -/** The individual spawners for a creature, newest-largest first. Bounded. */ -function listCreaturePoints(slug, { facet = '', limit = 200 } = {}) { - const params = [slug] - let facetSql = '' - if (facet) { - facetSql = 'AND p.facet = ?' - params.push(facet) - } - params.push(limit) - return query( - `SELECT p.id, p.facet, p.name, p.x, p.y, p.width, p.height, p.spawn_range, - p.min_delay, p.max_delay, p.tod_start, p.tod_end, p.tod_mode, - p.region, p.landmark, p.label, t.max_count - FROM shard_spawn_point_types t - JOIN shard_spawn_points p ON p.id = t.point_id - WHERE t.slug = ? ${facetSql} - ORDER BY t.max_count DESC, p.facet ASC, p.label ASC, p.id ASC - LIMIT ?`, - params, - ) -} - -/** Every other creature sharing a spawner with this one. */ -function listCreatureCompanions(slug, { limit = 24 } = {}) { - return query( - `SELECT o.slug, c.name, COUNT(*) AS shared - FROM shard_spawn_point_types t - JOIN shard_spawn_point_types o ON o.point_id = t.point_id AND o.slug <> t.slug - JOIN shard_spawn_creatures c ON c.slug = o.slug - WHERE t.slug = ? - GROUP BY o.slug, c.name - ORDER BY shared DESC, c.name ASC - LIMIT ?`, - [slug, limit], - ) -} - -function listRegions({ facet = '', q = '' } = {}) { - const where = [] - const params = [] - if (facet) { - where.push('facet = ?') - params.push(facet) - } - if (q) { - where.push('name LIKE ?') - params.push(`%${q}%`) - } - return query( - `SELECT facet, name, type, priority, parent, rects - FROM shard_regions - ${where.length ? `WHERE ${where.join(' AND ')}` : ''} - ORDER BY facet ASC, name ASC`, - params, - ) -} - -function listLandmarks({ facet = '', q = '' } = {}) { - const where = [] - const params = [] - if (facet) { - where.push('facet = ?') - params.push(facet) - } - if (q) { - where.push('(name LIKE ? OR grp LIKE ?)') - params.push(`%${q}%`, `%${q}%`) - } - return query( - `SELECT facet, name, grp, x, y, z - FROM shard_landmarks - ${where.length ? `WHERE ${where.join(' AND ')}` : ''} - ORDER BY facet ASC, grp ASC, name ASC`, - params, - ) -} - -function listChampions({ facet = '' } = {}) { - const params = [] - let where = '' - if (facet) { - where = 'WHERE facet = ?' - params.push(facet) - } - return query( - `SELECT slug, name, grp, type, random_type, facet, x, y, z, radius, label - FROM shard_champion_spawns - ${where} - ORDER BY facet ASC, name ASC`, - params, - ) -} - -module.exports = { - replaceAtlas, - getMeta, - getFacets, - getPending, - setPending, - clearPending, - countCreatures, - listCreatures, - getCreature, - listCreaturePlaces, - listCreaturePoints, - listCreatureCompanions, - listRegions, - listLandmarks, - listChampions, -} diff --git a/server/src/model/shardAtlas/shardAtlas.model.js b/server/src/model/shardAtlas/shardAtlas.model.js deleted file mode 100644 index 73e5a26..0000000 --- a/server/src/model/shardAtlas/shardAtlas.model.js +++ /dev/null @@ -1,485 +0,0 @@ -const fs = require('fs') -const path = require('path') - -const db = require('./shardAtlas.db') -const settings = require('../settings/settings.model') -const { slugify } = require('../../utils/spawnAtlasParse') -const { - AtlasSourceError, - PARSER_VERSION, - buildAtlas, - hashSources, - sameSources, -} = require('../../utils/spawnAtlasSource') -const log = require('../../utils/logger')('shardAtlas') - -// The spawn atlas, refreshed from the shard's own ServUO tree. -// -// The tree is the single source of truth. Nothing is precomputed and committed, -// because a shard's maps change over its lifetime — facets get added, replaced -// or renamed — and a snapshot in the repo would go stale against the world -// players actually see. So the atlas is re-derived on every boot. -// -// Two rules govern the boot path: -// -// 1. **It never blocks startup.** No configured path, an unreadable path, a -// malformed file, a database error — all of it is caught and logged. The -// site comes up either way, serving whatever atlas it already had. -// 2. **A facet disappearing is not applied automatically.** Losing a facet is -// the signature of a half-copied or mid-update tree as much as of a real -// map change, and the two are indistinguishable from here. The refresh is -// staged for a human instead, and an admin approves or rejects it. -// -// Everything else — new facets, renamed regions, changed spawns — applies -// straight away, because none of it can silently destroy data an operator would -// miss. - -const SETTING_KEY = 'spawn_atlas_servuo_path' - -/** - * Where the ServUO tree lives. - * - * The admin setting wins over the environment so an operator can point the - * atlas at a different tree without a redeploy, matching how the rest of the - * shard integration is admin-managed rather than env-configured. `SERVUO_PATH` - * remains as the deploy-time default, since the path usually describes a mount - * that the deployment sets up. - */ -async function getServuoPath() { - try { - const configured = await settings.get(SETTING_KEY) - if (configured && String(configured).trim() !== '') return String(configured).trim() - } catch { - // Settings unavailable is not fatal — fall through to the env default. - } - const fromEnv = process.env.SERVUO_PATH - return fromEnv && fromEnv.trim() !== '' ? fromEnv.trim() : '' -} - -async function setServuoPath(value, updatedBy = null) { - return settings.set(SETTING_KEY, String(value ?? '').trim(), updatedBy) -} - -/** - * Optional operator-supplied art map, `{ "": "" }`. - * - * Never committed and never shipped — creature sprites come out of the - * operator's own client `.mul`/`.uop` files, which are theirs, not ours to - * redistribute. Absent (the normal case) every `art` stays NULL and the UI - * renders text-only. - */ -function loadArtMap(dir = path.join(__dirname, '..', '..', '..', 'db', 'data')) { - try { - const file = path.join(dir, 'spawnAtlas.art.json') - if (!fs.existsSync(file)) return {} - const map = JSON.parse(fs.readFileSync(file, 'utf8')) - return map && typeof map === 'object' ? map : {} - } catch (err) { - log.warn('spawn atlas art map could not be read', { error: err.message }) - return {} - } -} - -/** - * Flatten each point's types into `shard_spawn_point_types` rows. - * - * A spawner may legitimately list the same type twice, and the primary key is - * (point_id, slug), so duplicates collapse to the larger max rather than - * failing the insert. - */ -function pointTypeRows(points) { - const rows = [] - points.forEach((point, i) => { - const bySlug = new Map() - for (const entry of point.types ?? []) { - const slug = slugify(entry.type) - if (slug === '') continue - bySlug.set(slug, Math.max(bySlug.get(slug) ?? 0, entry.max ?? 1)) - } - for (const [slug, max] of bySlug) rows.push([i + 1, slug, max]) - }) - return rows -} - -async function applyAtlas(atlas) { - return db.replaceAtlas({ ...atlas, pointTypes: pointTypeRows(atlas.points) }, loadArtMap()) -} - -/** - * Refresh the atlas from the configured ServUO tree. - * - * Returns a result describing what happened rather than throwing, so the caller - * — including the boot path — can log it and move on: - * - * `skipped` no path configured - * `unavailable` path configured but unreadable / missing required files - * `unchanged` source hashes match the loaded atlas; nothing parsed - * `imported` parsed and applied - * `needsReview` parsed, but a facet would be lost; staged for an admin - * `failed` parsed or applied and something went wrong - * - * `force` skips the hash check (an admin asking for a reimport) and `approve` - * additionally accepts facet loss (an admin approving a staged refresh). - */ -/** - * Was the loaded atlas built by THIS parser? - * - * An atlas imported before `parserVersion` existed reports undefined, which is - * correctly "no" — those are exactly the ones carrying the old readings. - */ -const currentParser = (meta) => meta?.parserVersion === PARSER_VERSION - -async function refresh({ force = false, approve = false, path: pathOverride = '' } = {}) { - // An explicit override wins outright — it is a one-off "use this tree", and it - // must not be silently overruled by the configured path the way an env default - // would be. - const root = pathOverride.trim() !== '' ? pathOverride.trim() : await getServuoPath() - if (root === '') return { status: 'skipped', reason: 'no ServUO path configured' } - - let hashes - try { - hashes = hashSources(root) - } catch (err) { - if (err instanceof AtlasSourceError) { - return { status: 'unavailable', reason: err.message, code: err.code, path: root } - } - return { status: 'failed', reason: err.message, path: root } - } - - const meta = await db.getMeta().catch(() => null) - const loaded = meta?.source - ? Object.fromEntries(Object.entries(meta.source).map(([label, v]) => [label, v.sha256])) - : null - - // Two things make a loaded atlas stale: the tree changed, or the PARSER did. - // Only checking the tree would strand an install whose maps never change on - // whatever an older build derived — a corrected parse would ship and never - // reach the data. - if (!force && sameSources(hashes, loaded) && currentParser(meta)) { - return { status: 'unchanged', path: root } - } - - // A rejected refresh must not re-prompt on every boot. It stays rejected until - // the tree changes again, at which point the hashes differ and it is a new - // decision. - const pending = await db.getPending().catch(() => null) - if (!approve && !force && pending?.status === 'rejected' && sameSources(hashes, pending.hashes)) { - return { status: 'unchanged', path: root, reason: 'refresh previously rejected' } - } - - let atlas - try { - atlas = buildAtlas(root) - } catch (err) { - return { status: 'failed', reason: err.message, path: root } - } - - const currentFacets = await db.getFacets().catch(() => []) - const incomingFacets = atlas.facets - const removedFacets = currentFacets.filter((facet) => !incomingFacets.includes(facet)) - const addedFacets = incomingFacets.filter((facet) => !currentFacets.includes(facet)) - - // Losing a facet is indistinguishable here from a half-copied tree, so it is - // staged rather than applied — but startup is never blocked by it. - if (removedFacets.length > 0 && !approve) { - const summary = { - hashes, - path: root, - currentFacets, - incomingFacets, - removedFacets, - addedFacets, - counts: atlas.meta.counts, - } - await db.setPending(summary, 'pending').catch((err) => { - log.warn('could not stage spawn atlas refresh', { error: err.message }) - }) - return { status: 'needsReview', ...summary } - } - - try { - const counts = await applyAtlas(atlas) - return { status: 'imported', path: root, counts, addedFacets, removedFacets } - } catch (err) { - return { status: 'failed', reason: err.message, path: root } - } -} - -/** Admin approved a staged refresh: apply it, facet loss and all. */ -async function approvePending(options = {}) { - return refresh({ ...options, approve: true, force: true }) -} - -/** - * Admin rejected a staged refresh: keep the current atlas and remember the - * decision against those exact source hashes, so it does not re-prompt every - * boot. A further change to the tree produces different hashes and asks again. - */ -async function rejectPending() { - const pending = await db.getPending() - if (!pending) return { status: 'none' } - await db.setPending({ ...pending, rejectedAt: new Date().toISOString() }, 'rejected') - return { status: 'rejected' } -} - -/** Everything the admin panel needs to describe atlas state. */ -async function status({ path: pathOverride = '' } = {}) { - const root = pathOverride.trim() !== '' ? pathOverride.trim() : await getServuoPath() - const [meta, pending, facets] = await Promise.all([ - db.getMeta().catch(() => null), - db.getPending().catch(() => null), - db.getFacets().catch(() => []), - ]) - - let treeReadable = false - let drift = null - if (root !== '') { - try { - const hashes = hashSources(root) - treeReadable = true - const loaded = meta?.source - ? Object.fromEntries(Object.entries(meta.source).map(([l, v]) => [l, v.sha256])) - : null - // Same question `refresh` asks: an import picks something up when either - // the tree or the parser has moved on. - drift = !sameSources(hashes, loaded) || !currentParser(meta) - } catch { - treeReadable = false - } - } - - return { - configured: root !== '', - path: root, - treeReadable, - drift, - facets, - importedAt: meta?.importedAt ?? null, - counts: meta?.counts ?? null, - pending, - } -} - -/** - * Boot hook. Best-effort by contract: it logs and returns, never throws, so a - * missing tree or a bad file can never stop the site coming up. - */ -async function refreshOnBoot() { - try { - const result = await refresh() - switch (result.status) { - case 'imported': - log.info('spawn atlas refreshed from ServUO tree', { - ...result.counts, - added: result.addedFacets, - }) - break - case 'needsReview': - log.warn( - 'spawn atlas refresh staged for admin review — a facet would be removed; ' + - 'the existing atlas is unchanged', - { removed: result.removedFacets, added: result.addedFacets }, - ) - break - case 'unavailable': - log.warn('spawn atlas source unavailable', { reason: result.reason, path: result.path }) - break - case 'failed': - log.warn('spawn atlas refresh failed', { reason: result.reason }) - break - default: - break - } - return result - } catch (err) { - log.warn('spawn atlas refresh errored', { error: err.message }) - return { status: 'failed', reason: err.message } - } -} - -// ── Reads ────────────────────────────────────────────────────────────────── -// -// The shapes the /public/atlas endpoints serve. Rows are camelCased here rather -// than in the controller, for the same reason shardState does it: the column -// names are an implementation detail of the import, and the browser contract -// should not move when a column is renamed. - -const jsonOr = (value, fallback) => { - if (value == null) return fallback - if (typeof value !== 'string') return value - try { - return JSON.parse(value) - } catch { - return fallback - } -} - -const shapeCreature = (row) => ({ - slug: row.slug, - name: row.name, - // `total` is the summed MaxCount across every spawner (how many can be alive - // at once); `points` is how many spawners mention it. They answer different - // questions and the UI shows both. - total: row.total, - points: row.points, - facets: jsonOr(row.facets, {}), - art: row.art || null, -}) - -const shapePlace = (row) => ({ - facet: row.facet, - label: row.label, - spawners: Number(row.spawners) || 0, - maxAlive: Number(row.max_alive) || 0, -}) - -const shapePoint = (row) => ({ - id: row.id, - facet: row.facet, - name: row.name || null, - x: row.x, - y: row.y, - width: row.width, - height: row.height, - range: row.spawn_range, - maxCount: row.max_count, - minDelay: row.min_delay, - maxDelay: row.max_delay, - todStart: row.tod_start, - todEnd: row.tod_end, - todMode: row.tod_mode, - region: row.region || null, - landmark: row.landmark || null, - label: row.label, -}) - -/** - * Paginated creature search. Returns the page plus the unpaginated total, so - * the UI can say "showing 50 of 800" without a second round trip. - */ -async function searchCreatures({ q = '', facet = '', limit = 50, offset = 0 } = {}) { - const [rows, total] = await Promise.all([ - db.listCreatures({ q, facet, limit, offset }), - db.countCreatures({ q, facet }), - ]) - return { total, limit, offset, creatures: rows.map(shapeCreature) } -} - -/** - * One creature: its totals, the places it spawns (the aggregate the atlas - * exists for), the individual spawners, and what else shares those spawners. - * - * `null` when the slug is unknown — the controller turns that into a 404. - */ -async function getCreature(slug, { facet = '', points = 200 } = {}) { - const row = await db.getCreature(slug) - if (!row) return null - const [places, pointRows, alsoHere] = await Promise.all([ - db.listCreaturePlaces(slug, { facet }), - db.listCreaturePoints(slug, { facet, limit: points }), - db.listCreatureCompanions(slug), - ]) - return { - ...shapeCreature(row), - places: places.map(shapePlace), - // `spawners`, not `points`: shapeCreature already uses `points` for the - // COUNT of spawners, and reusing the key for the list of them would make the - // same field a number on the search route and an array here. - spawners: pointRows.map(shapePoint), - // Bounded by the query, so a creature on hundreds of spawners returns a page - // rather than the world. - spawnersTruncated: pointRows.length >= points, - alsoHere: alsoHere.map((r) => ({ - slug: r.slug, - name: r.name, - shared: Number(r.shared) || 0, - })), - } -} - -async function listRegions(opts = {}) { - const rows = await db.listRegions(opts) - return rows.map((r) => ({ - facet: r.facet, - name: r.name, - type: r.type || null, - priority: r.priority, - parent: r.parent || null, - rects: jsonOr(r.rects, []), - })) -} - -async function listLandmarks(opts = {}) { - const rows = await db.listLandmarks(opts) - return rows.map((r) => ({ - facet: r.facet, - name: r.name, - group: r.grp || null, - x: r.x, - y: r.y, - z: r.z, - })) -} - -async function listChampions(opts = {}) { - const rows = await db.listChampions(opts) - return rows.map((r) => ({ - slug: r.slug, - name: r.name, - group: r.grp || null, - // '' on the wire means "randomised at activation"; `randomType` says so - // explicitly rather than making the client infer it from an empty string. - type: r.type || null, - randomType: !!r.random_type, - facet: r.facet, - x: r.x, - y: r.y, - z: r.z, - radius: r.radius, - label: r.label || null, - })) -} - -/** - * What is loaded: the facet list, the counts, and when it was imported. - * - * Deliberately does NOT report the source path, the per-file hashes or whether - * a refresh is pending. Those describe the operator's filesystem, and this is a - * public endpoint; the admin status route carries them instead. - */ -async function publicMeta() { - const [meta, facets] = await Promise.all([ - db.getMeta().catch(() => null), - db.getFacets().catch(() => []), - ]) - return { - importedAt: meta?.importedAt ?? null, - generatedAt: meta?.generatedAt ?? null, - // The parse counts, not the row counts: `unresolvedPoints` is what lets the - // page state its own placement accuracy instead of implying it is complete. - counts: meta?.counts ?? null, - facets, - } -} - -const listFacets = () => db.getFacets() - -module.exports = { - refresh, - refreshOnBoot, - approvePending, - rejectPending, - status, - getServuoPath, - setServuoPath, - pointTypeRows, - loadArtMap, - SETTING_KEY, - searchCreatures, - getCreature, - listRegions, - listLandmarks, - listChampions, - listFacets, - publicMeta, -} diff --git a/server/src/model/shardClilocs/shardClilocs.db.js b/server/src/model/shardClilocs/shardClilocs.db.js deleted file mode 100644 index d944524..0000000 --- a/server/src/model/shardClilocs/shardClilocs.db.js +++ /dev/null @@ -1,108 +0,0 @@ -const { pool, query } = require('../../utils/db') - -// Raw SQL for the cliloc table. `shard_clilocs` is IMPORT-OWNED: `replaceAll` -// empties and refills it inside one transaction, and nothing else in the -// codebase writes to it. No foreign keys, consistent with every other shard_* -// table. - -const BATCH = 1000 - -/** - * Replace the entire cliloc table in one transaction. - * - * All-or-nothing on purpose: a failed reload must leave the previous table - * intact rather than a half-loaded one, because a partially-imported cliloc - * table is indistinguishable from a complete one to anyone reading it — you - * would just see some items named and some not, which is also what "no table at - * all" looks like. - * - * `DELETE`, not `TRUNCATE` — `TRUNCATE` is DDL in MariaDB and implicitly - * commits, which would defeat exactly that guarantee. (The same trap the spawn - * atlas import documents; at ~123k rows `DELETE` is still well under a second.) - */ -async function replaceAll(entries, meta) { - const conn = await pool.getConnection() - try { - await conn.beginTransaction() - await conn.query('DELETE FROM shard_clilocs') - - // Blank entries are dropped rather than stored. Roughly HALF of a real - // cliloc table is empty strings — ids the client reserves and never uses — - // and a row that resolves to no name is indistinguishable from no row at - // all to every caller. Dropping them halves the table (123,490 → ~67,500) - // and, more importantly, makes the binary and text imports converge on - // identical content: the binary format carries the blanks explicitly and a - // text export may or may not, depending on the tool. - // - // Later duplicates win. Merging across sources already happened upstream in - // `readCliloc`, so in practice this collapses nothing — it is kept because - // the plain format permits a repeated id WITHIN one file and the client's - // own loader resolves it the same way (its dictionary assignment - // overwrites). Without it, a file the game itself would load happily would - // fail the batch insert on a primary-key collision. - const byNumber = new Map() - let blank = 0 - for (const entry of entries) { - if (!Number.isInteger(entry.number)) continue - if (String(entry.text ?? '').trim() === '') { - blank++ - continue - } - byNumber.set(entry.number, entry) - } - - const rows = [...byNumber.values()].map((e) => [e.number, e.flag ?? 0, e.text]) - for (let i = 0; i < rows.length; i += BATCH) { - await conn.batch('INSERT INTO shard_clilocs (number, flag, text) VALUES (?,?,?)', rows.slice(i, i + BATCH)) - } - - await conn.query( - 'INSERT INTO shard_cliloc_meta (id, payload) VALUES (1, ?) ' + - 'ON DUPLICATE KEY UPDATE payload = VALUES(payload), imported_at = CURRENT_TIMESTAMP', - [JSON.stringify({ ...meta, count: rows.length })], - ) - - await conn.commit() - return { count: rows.length, blank, duplicates: entries.length - blank - rows.length } - } catch (err) { - await conn.rollback().catch(() => {}) - throw err - } finally { - conn.release() - } -} - -async function getMeta() { - const rows = await query('SELECT payload, imported_at FROM shard_cliloc_meta WHERE id = 1') - if (rows.length === 0) return null - const payload = typeof rows[0].payload === 'string' ? JSON.parse(rows[0].payload) : rows[0].payload - return { ...payload, importedAt: rows[0].imported_at } -} - -/** - * Look up a batch of ids. - * - * Batched rather than one-at-a-time because every caller has a LIST: a character - * sheet resolves a dozen equipment ids at once, and a page of marketplace - * listings resolves fifty. `IN (...)` with generated placeholders keeps it one - * round trip and one parameterized statement. - */ -async function lookup(numbers) { - if (!Array.isArray(numbers) || numbers.length === 0) return [] - const ids = [...new Set(numbers.filter((n) => Number.isInteger(n)))] - if (ids.length === 0) return [] - const placeholders = ids.map(() => '?').join(',') - return query(`SELECT number, text FROM shard_clilocs WHERE number IN (${placeholders})`, ids) -} - -async function count() { - const rows = await query('SELECT COUNT(*) AS n FROM shard_clilocs') - return Number(rows[0]?.n) || 0 -} - -module.exports = { - replaceAll, - getMeta, - lookup, - count, -} diff --git a/server/src/model/shardClilocs/shardClilocs.model.js b/server/src/model/shardClilocs/shardClilocs.model.js deleted file mode 100644 index 6f193bd..0000000 --- a/server/src/model/shardClilocs/shardClilocs.model.js +++ /dev/null @@ -1,368 +0,0 @@ -const db = require('./shardClilocs.db') -const settings = require('../settings/settings.model') -const { displayText } = require('../../utils/clilocParse') -const { - ClilocFormatError, - ClilocSourceError, - PARSER_VERSION, - hashSources, - sameSources, - missingSources, - readCliloc, -} = require('../../utils/clilocSource') -const log = require('../../utils/logger')('shardClilocs') - -// The cliloc table — UO's id → display-string map, refreshed from a file the -// operator converts once from their own client. -// -// Why the site holds this at all: items on the wire carry a `LabelNumber`, not a -// name. `char.profile.equipment` has always sent `cliloc`, and every marketplace -// listing sends one too. Without the table the UI can only print `id 1023721` -// where the game prints "quarter staff". -// -// Two rules govern the boot path, both inherited from the spawn atlas: -// -// 1. **It never blocks startup.** No configured path, an unreadable file, a -// wrong-format file, a database error — all caught and logged. The site -// comes up either way, serving whatever table it already had (or none, in -// which case the UI falls back to item ids exactly as it did before). -// 2. **Nothing client-derived is committed.** The table is built from the -// operator's own file at a configured path. The repo ships no strings. -// -// The table is built from a SET of sources — the converted client table plus -// every operator-maintained overlay beside it — because shards edit items and -// add new ones, and those carry cliloc ids no stock client table has. All of -// them are re-read on every boot and hash-gated together, so adding one custom -// item never means re-exporting a 5 MB client file. Later sources win. -// -// That set is also why this has the atlas's escalation, in a lighter form. A -// single corrupt file fails the parse loudly, but a source that has simply -// VANISHED parses perfectly and imports a table quietly missing everything it -// contributed — the same ambiguity (real change vs half-copied mount) the atlas -// stages a facet removal for. So a disappearing source is refused and reported -// rather than applied. -// -// It is lighter than the atlas's because it needs to be: the atlas stores a -// pending decision in its own table and adds approve/reject endpoints, whereas -// here the decision is a single boolean an admin passes to the import they were -// already going to run. Re-parsing at approval time — the property that makes -// the atlas store only the decision — is automatic when there is nothing stored. - -const SETTING_KEY = 'cliloc_client_path' - -/** - * Where the converted cliloc file lives. - * - * The admin setting wins over the environment so an operator can repoint it - * without a redeploy, matching how the rest of the shard integration is - * admin-managed rather than env-configured. `UO_CLIENT_PATH` remains as the - * deploy-time default, since the path usually describes a mount the deployment - * sets up. - */ -async function getClientPath() { - try { - const configured = await settings.get(SETTING_KEY) - if (configured && String(configured).trim() !== '') return String(configured).trim() - } catch { - // Settings unavailable is not fatal — fall through to the env default. - } - const fromEnv = process.env.UO_CLIENT_PATH - return fromEnv && fromEnv.trim() !== '' ? fromEnv.trim() : '' -} - -async function setClientPath(value, updatedBy = null) { - const result = await settings.set(SETTING_KEY, String(value ?? '').trim(), updatedBy) - invalidate() - return result -} - -// ── Refresh ──────────────────────────────────────────────────────────────── - -/** Was the loaded table built by THIS parser? */ -const currentParser = (meta) => meta?.parserVersion === PARSER_VERSION - -/** - * Refresh the cliloc table from the configured file. - * - * Returns a result describing what happened rather than throwing, so the caller - * — including the boot path — can log it and move on: - * - * `skipped` no path configured - * `unavailable` path configured but missing / unreadable / not a cliloc file - * `unchanged` source hashes match the loaded table; nothing parsed - * `imported` parsed and applied - * `needsReview` a previously-present source has vanished; NOT applied - * `failed` parsed or applied and something went wrong - * - * `force` skips the hash check (an admin asking for a reimport). `approve` - * additionally accepts a vanished source. - */ -async function refresh({ force = false, approve = false, path: pathOverride = '' } = {}) { - // An explicit override wins outright — a one-off "use this file", which must - // not be silently overruled by the configured path the way an env default is. - const configured = pathOverride.trim() !== '' ? pathOverride.trim() : await getClientPath() - if (configured === '') return { status: 'skipped', reason: 'no cliloc path configured' } - - let fingerprint - try { - fingerprint = hashSources(configured) - } catch (err) { - if (err instanceof ClilocSourceError) { - return { status: 'unavailable', reason: err.message, code: err.code, path: configured } - } - return { status: 'failed', reason: err.message, path: configured } - } - - const meta = await db.getMeta().catch(() => null) - - // Two things make a loaded table stale: any source changed, or the PARSER did. - // Only checking the sources would strand an install whose client never patches - // on whatever an older build derived. - if (!force && sameSources(fingerprint.hashes, meta?.hashes) && currentParser(meta)) { - return { - status: 'unchanged', - path: configured, - file: fingerprint.file, - count: meta.count ?? null, - customCount: fingerprint.customCount, - } - } - - // A source that was there last import and is not there now is refused, not - // applied — an unmounted volume and a deliberate deletion look identical from - // here, and the wrong guess silently drops every name that file contributed. - const gone = missingSources(fingerprint.hashes, meta?.hashes) - if (gone.length > 0 && !approve) { - return { - status: 'needsReview', - reason: `${gone.length} previously-loaded cliloc source(s) are missing; the existing table is unchanged`, - missingSources: gone, - path: configured, - file: fingerprint.file, - } - } - - let parsed - try { - parsed = readCliloc(configured) - } catch (err) { - if (err instanceof ClilocFormatError || err instanceof ClilocSourceError) { - return { status: 'unavailable', reason: err.message, code: err.code, path: configured } - } - return { status: 'failed', reason: err.message, path: configured } - } - - try { - const applied = await db.replaceAll(parsed.entries, parsed.source) - invalidate() - return { - status: 'imported', - path: configured, - file: parsed.source.file, - count: applied.count, - parsed: parsed.entries.length, - blank: applied.blank, - // Per-source breakdown: how many entries each file contributed and how - // many of them overrode something already merged. An operator who adds an - // overlay wants to see it took effect, and "overrode: 0" on a file meant - // to re-label stock items says it did not. - sources: parsed.source.sources, - acceptedMissing: gone.length > 0 ? gone : undefined, - } - } catch (err) { - return { status: 'failed', reason: err.message, path: configured } - } -} - -/** - * Boot hook. Best-effort by contract: it logs and returns, never throws, so a - * missing or malformed cliloc file can never stop the site coming up. - */ -async function refreshOnBoot() { - try { - const result = await refresh() - switch (result.status) { - case 'imported': - log.info('cliloc table refreshed', { - file: result.file, - count: result.count, - overlays: (result.sources || []).filter((s) => s.kind === 'custom').length, - }) - break - case 'needsReview': - log.warn( - 'cliloc refresh staged for admin review — a previously-loaded source is missing; ' + - 'the existing table is unchanged', - { missing: result.missingSources }, - ) - break - case 'unavailable': - // Deliberately a warning, not an error: an operator who has not supplied - // a cliloc file is in a supported state (the UI shows item ids), and the - // most common cause — pointing at the client's own compressed file — - // needs the reason spelled out rather than a stack trace. - log.warn('cliloc source unavailable (item names will show as ids)', { - reason: result.reason, - code: result.code, - path: result.path, - }) - break - case 'failed': - log.warn('cliloc refresh failed', { reason: result.reason }) - break - default: - break - } - return result - } catch (err) { - log.warn('cliloc refresh errored', { error: err.message }) - return { status: 'failed', reason: err.message } - } -} - -/** Everything the admin panel needs to describe cliloc state. */ -async function status({ path: pathOverride = '' } = {}) { - const configured = pathOverride.trim() !== '' ? pathOverride.trim() : await getClientPath() - const meta = await db.getMeta().catch(() => null) - const loaded = await db.count().catch(() => 0) - - let fileReadable = false - let file = null - let drift = null - let problem = null - let code = null - let sources = [] - let missing = [] - if (configured !== '') { - try { - const fingerprint = hashSources(configured) - fileReadable = true - file = fingerprint.file - sources = Object.keys(fingerprint.hashes) - missing = missingSources(fingerprint.hashes, meta?.hashes) - // A compressed file is readable but not importable, and the panel has to - // say so HERE — otherwise pointing at an unconverted client directory - // reports a healthy file with pending drift ("ready to import") and the - // operator only finds out when the import fails. `drift` stays null - // because comparing hashes with an unusable file answers nothing. - if (fingerprint.compressed) { - problem = - 'This is a compressed (Mythic-format) cliloc file, which the site cannot read. ' + - 'Convert it to the plain format first — see docs/website/CLILOCS.md.' - code = 'COMPRESSED' - } else { - drift = !sameSources(fingerprint.hashes, meta?.hashes) || !currentParser(meta) - } - } catch (err) { - fileReadable = false - problem = err.message - code = err.code ?? null - } - } - - return { - configured: configured !== '', - path: configured, - file, - fileReadable, - problem, - code, - drift, - count: loaded, - // Every source found now (base first, then overlays), what each contributed - // at the last import, and any that have since vanished — which is the state - // an import will refuse without `approve`. - sources, - loadedSources: meta?.sources ?? null, - missingSources: missing, - importedAt: meta?.importedAt ?? null, - sourceBytes: meta?.bytes ?? null, - } -} - -// ── Lookup ───────────────────────────────────────────────────────────────── -// -// Resolution happens SERVER-SIDE, not in the browser. Two reasons: the table is -// ~123k rows and shipping it to a client would dwarf every page that uses it, -// and the Android app consumes the same JSON and would otherwise need its own -// copy. Callers get names, not ids-plus-a-table. - -// A small write-through cache in front of the table. Item ids repeat heavily — -// one page of listings is mostly the same few hundred clilocs, and a character -// sheet re-resolves the same gear on every view — so this turns the steady state -// into zero queries. Capped so a pathological caller cannot grow it without -// bound; on overflow it is dropped wholesale rather than evicted entry-by-entry, -// which is cheap and correct for a table that only changes on reimport. -const CACHE_MAX = 20000 -let cache = new Map() - -function invalidate() { - cache = new Map() -} - -/** - * Resolve a batch of cliloc ids to display strings. - * - * Returns a `Map` holding only the ids that resolved to - * something displayable — an id with no row, or one whose text is nothing but - * interpolated arguments we do not have, is simply absent. Callers fall back to - * whatever they had (the item id), so "missing" and "unnamed" collapse into one - * branch at the call site. - * - * Never throws: a cliloc lookup is decoration on someone's character sheet, and - * a database blip must not fail the sheet. - */ -async function resolveMany(numbers) { - const out = new Map() - if (!Array.isArray(numbers)) return out - - const wanted = [...new Set(numbers.filter((n) => Number.isInteger(n) && n > 0))] - if (wanted.length === 0) return out - - const missing = [] - for (const number of wanted) { - if (cache.has(number)) { - const hit = cache.get(number) - if (hit !== '') out.set(number, hit) - } else { - missing.push(number) - } - } - - if (missing.length > 0) { - try { - const rows = await db.lookup(missing) - const found = new Map(rows.map((r) => [Number(r.number), displayText(r.text)])) - if (cache.size + missing.length > CACHE_MAX) invalidate() - for (const number of missing) { - // Cache the miss too ('' meaning "no usable name"), so an id absent from - // the table does not re-query on every page view. - const text = found.get(number) ?? '' - cache.set(number, text) - if (text !== '') out.set(number, text) - } - } catch (err) { - log.warn('cliloc lookup failed', { message: err.message }) - } - } - - return out -} - -/** Single-id convenience. Returns `null` when there is no usable name. */ -async function resolve(number) { - const found = await resolveMany([number]) - return found.get(number) ?? null -} - -module.exports = { - SETTING_KEY, - getClientPath, - setClientPath, - refresh, - refreshOnBoot, - status, - resolveMany, - resolve, - invalidate, -} diff --git a/server/src/model/shardEvents/shardEvents.db.js b/server/src/model/shardEvents/shardEvents.db.js deleted file mode 100644 index 5e424f4..0000000 --- a/server/src/model/shardEvents/shardEvents.db.js +++ /dev/null @@ -1,46 +0,0 @@ -const { query } = require('../../utils/db') - -// INSERT IGNORE on the UNIQUE dedupe_key — a re-ingested event (WS-reconnect -// backfill overlap) is silently skipped rather than duplicated. Returns true if -// a new row was actually inserted. -async function insertIgnore({ kind, t, bootId, payload, dedupeKey }) { - const res = await query( - `INSERT IGNORE INTO shard_events (kind, t, boot_id, payload, dedupe_key) - VALUES (?, ?, ?, ?, ?)`, - [kind, t, bootId || null, JSON.stringify(payload), dedupeKey], - ) - return res.affectedRows > 0 -} - -// Recent events, newest first. Filter by a single `kind`, or an allowlist of -// `kinds` (IN clause) — the public feed uses the allowlist so it can never leak -// staff/sensitive kinds. limit is clamped by the model. -async function list({ kind, kinds, limit }) { - // An allowlist that resolved to NOTHING means "serve nothing" — never "serve - // everything". Falling through to the unfiltered query below would have turned - // a fully-gated visibility config into a full dump of the event log, staff - // audit and cheat detections included. - if (kinds && kinds.length === 0) return [] - if (kinds && kinds.length) { - const placeholders = kinds.map(() => '?').join(', ') - return query( - `SELECT id, kind, t, boot_id, payload, created_at - FROM shard_events WHERE kind IN (${placeholders}) ORDER BY t DESC LIMIT ?`, - [...kinds, limit], - ) - } - if (kind) { - return query( - `SELECT id, kind, t, boot_id, payload, created_at - FROM shard_events WHERE kind = ? ORDER BY t DESC LIMIT ?`, - [kind, limit], - ) - } - return query( - `SELECT id, kind, t, boot_id, payload, created_at - FROM shard_events ORDER BY t DESC LIMIT ?`, - [limit], - ) -} - -module.exports = { insertIgnore, list } diff --git a/server/src/model/shardEvents/shardEvents.model.js b/server/src/model/shardEvents/shardEvents.model.js deleted file mode 100644 index 0674d75..0000000 --- a/server/src/model/shardEvents/shardEvents.model.js +++ /dev/null @@ -1,61 +0,0 @@ -// Append-only shard event log. The WS ingest dispatcher calls append() for the -// notable kinds; the public/admin read endpoints call list(). The DB layer only -// sees an already-computed dedupe_key so INSERT IGNORE is idempotent across -// WS-reconnect backfill. - -const crypto = require('crypto') -const db = require('./shardEvents.db') - -const MAX_LIMIT = 1000 -const DEFAULT_LIMIT = 100 - -// Stable stringify — keys sorted — so the dedupe hash is independent of the -// property order the sidecar happened to serialize with. -function stableStringify(value) { - if (value === null || typeof value !== 'object') return JSON.stringify(value) - if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]` - const keys = Object.keys(value).sort() - const entries = keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`) - return `{${entries.join(',')}}` -} - -// dedupe_key = sha256(kind + t + stable-json(payload)), truncated to 40 hex chars. -// This is a content fingerprint for idempotent INSERT IGNORE, not a security value, -// but we use SHA-256 rather than SHA-1 anyway; the truncation keeps it inside the -// CHAR(40) column (160 bits is ample collision resistance for dedupe). Two identical -// events (same kind, same timestamp, same body) collapse to one row. -function dedupeKey(kind, t, payload) { - return crypto - .createHash('sha256') - .update(`${kind}|${t}|${stableStringify(payload)}`) - .digest('hex') - .slice(0, 40) -} - -// Append one event. Returns true if a new row was inserted (false = deduped). -async function append({ kind, t, bootId, payload }) { - return db.insertIgnore({ kind, t, bootId, payload, dedupeKey: dedupeKey(kind, t, payload) }) -} - -function normalizeLimit(limit) { - const n = Number(limit) - if (!Number.isFinite(n) || n <= 0) return DEFAULT_LIMIT - return Math.min(Math.floor(n), MAX_LIMIT) -} - -// Recent events, newest first. Each row's JSON payload is parsed back to an -// object. `kinds` (array) restricts to an allowlist; `kind` filters a single kind. -async function list({ kind, kinds, limit } = {}) { - const rows = await db.list({ kind, kinds, limit: normalizeLimit(limit) }) - return rows.map((row) => ({ - id: row.id, - kind: row.kind, - t: row.t, - bootId: row.boot_id || null, - // mariadb returns JSON columns as strings on some versions; parse defensively. - payload: typeof row.payload === 'string' ? JSON.parse(row.payload) : row.payload, - createdAt: row.created_at, - })) -} - -module.exports = { append, list, dedupeKey } diff --git a/server/src/model/shardLinks/shardLinks.db.js b/server/src/model/shardLinks/shardLinks.db.js deleted file mode 100644 index 76b0418..0000000 --- a/server/src/model/shardLinks/shardLinks.db.js +++ /dev/null @@ -1,42 +0,0 @@ -const { query } = require('../../utils/db') - -const COLS = 'account, user_id, char_name, linked_at' - -// Upsert a link. account is the PK, so a re-link moves the account to the new -// user (the sidecar already treats /link/confirm as authoritative). -async function upsert({ account, userId, charName }) { - await query( - `INSERT INTO shard_account_links (account, user_id, char_name) - VALUES (?, ?, ?) - ON DUPLICATE KEY UPDATE user_id = VALUES(user_id), char_name = VALUES(char_name)`, - [account, userId, charName || null], - ) - return getByAccount(account) -} - -async function getByAccount(account) { - const rows = await query(`SELECT ${COLS} FROM shard_account_links WHERE account = ? LIMIT 1`, [account]) - return rows[0] || null -} - -const listByUser = (userId) => - query(`SELECT ${COLS} FROM shard_account_links WHERE user_id = ? ORDER BY linked_at DESC`, [userId]) - -async function isOwnedBy(account, userId) { - const rows = await query( - 'SELECT 1 FROM shard_account_links WHERE account = ? AND user_id = ? LIMIT 1', - [account, userId], - ) - return rows.length > 0 -} - -const remove = (account, userId) => - query('DELETE FROM shard_account_links WHERE account = ? AND user_id = ?', [account, userId]) - -// Drop the mirror for an account regardless of which user held it — used to -// reconcile when the tie is severed at the source (an in-game [unlink → -// account.unlinked event, or a site-side DELETE /link/{account}). -const removeByAccount = (account) => - query('DELETE FROM shard_account_links WHERE account = ?', [account]) - -module.exports = { upsert, getByAccount, listByUser, isOwnedBy, remove, removeByAccount } diff --git a/server/src/model/shardLinks/shardLinks.model.js b/server/src/model/shardLinks/shardLinks.model.js deleted file mode 100644 index 3d0f907..0000000 --- a/server/src/model/shardLinks/shardLinks.model.js +++ /dev/null @@ -1,37 +0,0 @@ -// Site-side mirror of in-game-account → website-user links. The sidecar owns the -// authoritative link (it tags the game account on /link/confirm); this model -// records it locally so the player portal can list links and enforce ownership. - -const db = require('./shardLinks.db') - -function toSafe(row) { - if (!row) return null - return { - account: row.account, - userId: row.user_id, - charName: row.char_name || null, - linkedAt: row.linked_at, - } -} - -async function link({ account, userId, charName }) { - return toSafe(await db.upsert({ account, userId, charName })) -} - -async function listForUser(userId) { - const rows = await db.listByUser(userId) - return rows.map(toSafe) -} - -const ownsAccount = (account, userId) => db.isOwnedBy(account, userId) - -async function getByAccount(account) { - return toSafe(await db.getByAccount(account)) -} - -const unlink = (account, userId) => db.remove(account, userId) - -// Drop the local mirror for an account (source-of-truth severed elsewhere). -const removeByAccount = (account) => db.removeByAccount(account) - -module.exports = { link, listForUser, ownsAccount, getByAccount, unlink, removeByAccount } diff --git a/server/src/model/shardMarket/shardMarket.db.js b/server/src/model/shardMarket/shardMarket.db.js deleted file mode 100644 index 44db273..0000000 --- a/server/src/model/shardMarket/shardMarket.db.js +++ /dev/null @@ -1,299 +0,0 @@ -const { pool, query } = require('../../utils/db') - -// Raw SQL for the player-vendor market index (Protocol 3.0 vendor.listing). -// -// Two tables, both INGEST-OWNED: `shard_vendors` (one row per shop) and -// `shard_vendor_items` (one row per priced listing). Nothing else in the codebase -// writes to either. No foreign keys, consistent with every other shard_* table. - -// Insert batch size for one vendor's listings. A shop is capped at -// MarketMaxListings (250 by default) on the shard side, so in practice this is -// one batch — it exists for the operator who raised that cap. -const BATCH = 500 - -// LIKE wildcards in user input. `%` and `_` are not special to the parameterized -// query — they are special to LIKE itself — so a search for "50% off" would -// otherwise match everything containing "50" and a search for "_" would match -// every single-character name. Escaped with a backslash, which is MariaDB's -// default LIKE escape (no ESCAPE clause needed). -const likeTerm = (q) => `%${String(q).replace(/[\\%_]/g, (c) => `\\${c}`)}%` - -/** - * Replace one vendor's whole row and listing set, in one transaction. - * - * Delete-then-insert rather than a diff, because the frame is AUTHORITATIVE for - * that vendor: the shard's sweep only emits a shop whose contents, prices or - * location moved, and when it does it sends the whole shop. Reconciling it item - * by item would be more code for the same result and would leave sold items - * behind on any path the reconciliation missed. - * - * All-or-nothing matters here for a specific reason: the two writes are "the - * shop" and "what is in it", and a failure between them leaves a shop advertising - * an inventory it no longer has (or none at all) — visibly wrong on the page, and - * indistinguishable from a genuinely empty shop. - */ -async function replaceVendor(vendor, items) { - const conn = await pool.getConnection() - try { - await conn.beginTransaction() - - await conn.query( - `INSERT INTO shard_vendors - (serial, shop_name, owner_serial, owner_name, map, x, y, z, region, house, - item_count, item_total, truncated, t) - VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?) - ON DUPLICATE KEY UPDATE shop_name = VALUES(shop_name), owner_serial = VALUES(owner_serial), - owner_name = VALUES(owner_name), map = VALUES(map), x = VALUES(x), y = VALUES(y), - z = VALUES(z), region = VALUES(region), house = VALUES(house), - item_count = VALUES(item_count), item_total = VALUES(item_total), - truncated = VALUES(truncated), t = VALUES(t), - -- Touched explicitly rather than left to ON UPDATE CURRENT_TIMESTAMP: - -- MariaDB does not fire that when every column is written back - -- unchanged, and a shop that is re-published identically is still - -- FRESHLY CONFIRMED. Without this the staleness banner would age a - -- perfectly current shop forever. - updated_at = CURRENT_TIMESTAMP`, - [ - vendor.serial, - vendor.shopName ?? null, - vendor.ownerSerial ?? null, - vendor.ownerName ?? null, - vendor.map ?? null, - Number.isFinite(vendor.x) ? vendor.x : null, - Number.isFinite(vendor.y) ? vendor.y : null, - Number.isFinite(vendor.z) ? vendor.z : null, - vendor.region ?? null, - vendor.house ?? null, - items.length, - Number.isFinite(vendor.itemTotal) ? vendor.itemTotal : items.length, - vendor.truncated ? 1 : 0, - Number.isFinite(vendor.t) ? vendor.t : null, - ], - ) - - await conn.query('DELETE FROM shard_vendor_items WHERE vendor_serial = ?', [vendor.serial]) - - const rows = items.map((i) => [ - vendor.serial, - i.serial, - i.itemId, - i.hue, - i.amount, - i.price, - i.name, - i.cliloc, - i.displayName, - i.child ? 1 : 0, - ]) - - for (let i = 0; i < rows.length; i += BATCH) { - await conn.batch( - `INSERT INTO shard_vendor_items - (vendor_serial, serial, item_id, hue, amount, price, name, cliloc, display_name, child) - VALUES (?,?,?,?,?,?,?,?,?,?)`, - rows.slice(i, i + BATCH), - ) - } - - await conn.commit() - return { items: rows.length } - } catch (err) { - await conn.rollback().catch(() => {}) - throw err - } finally { - conn.release() - } -} - -/** Drop one vendor and its listings (vendor.listing.remove). */ -async function removeVendor(serial) { - const conn = await pool.getConnection() - try { - await conn.beginTransaction() - await conn.query('DELETE FROM shard_vendor_items WHERE vendor_serial = ?', [serial]) - await conn.query('DELETE FROM shard_vendors WHERE serial = ?', [serial]) - await conn.commit() - } catch (err) { - await conn.rollback().catch(() => {}) - throw err - } finally { - conn.release() - } -} - -// ── Search ───────────────────────────────────────────────────────────────── -// -// The unit of a search RESULT is a listing, not a vendor: "who sells a vanquishing -// kryss and for how much" is the question, and answering it per vendor would make -// the caller flatten the shops back out. The vendor's columns ride along on the -// join so a result row is self-contained. - -function searchWhere({ q, minPrice, maxPrice, itemId, map, region }) { - const where = ['i.price > 0'] - const params = [] - - if (q) { - // Both the resolved display name and the item's own literal, because an item - // with a player-set name (most of what is actually worth searching for on a - // player-run shard) may have a generic cliloc. - where.push('(i.display_name LIKE ? OR i.name LIKE ?)') - params.push(likeTerm(q), likeTerm(q)) - } - if (Number.isFinite(minPrice)) { - where.push('i.price >= ?') - params.push(minPrice) - } - if (Number.isFinite(maxPrice)) { - where.push('i.price <= ?') - params.push(maxPrice) - } - if (Number.isFinite(itemId)) { - where.push('i.item_id = ?') - params.push(itemId) - } - if (map) { - where.push('v.map = ?') - params.push(map) - } - if (region) { - where.push('v.region = ?') - params.push(region) - } - - return { sql: `WHERE ${where.join(' AND ')}`, params } -} - -// Whitelisted, because this interpolates into the statement. `recent` sorts by -// the vendor's freshness, which is the only way to see what has just been listed -// on a shard whose sweep is minutes wide. -const SORTS = { - price_asc: 'i.price ASC, i.id ASC', - price_desc: 'i.price DESC, i.id ASC', - recent: 'v.updated_at DESC, i.id ASC', -} - -async function searchListings({ q, minPrice, maxPrice, itemId, map, region, sort, limit, offset }) { - const { sql, params } = searchWhere({ q, minPrice, maxPrice, itemId, map, region }) - const order = SORTS[sort] || SORTS.price_asc - - const rows = await query( - `SELECT i.serial, i.item_id, i.hue, i.amount, i.price, i.name, i.cliloc, i.display_name, i.child, - v.serial AS vendor_serial, v.shop_name, v.owner_serial, v.owner_name, - v.map, v.x, v.y, v.z, v.region, v.house, v.updated_at - FROM shard_vendor_items i - JOIN shard_vendors v ON v.serial = i.vendor_serial - ${sql} - ORDER BY ${order} - LIMIT ? OFFSET ?`, - [...params, limit, offset], - ) - - const counted = await query( - `SELECT COUNT(*) AS n - FROM shard_vendor_items i - JOIN shard_vendors v ON v.serial = i.vendor_serial - ${sql}`, - params, - ) - - return { rows, total: Number(counted[0]?.n) || 0 } -} - -async function getVendor(serial) { - const rows = await query( - `SELECT serial, shop_name, owner_serial, owner_name, map, x, y, z, region, house, - item_count, item_total, truncated, t, updated_at - FROM shard_vendors WHERE serial = ?`, - [serial], - ) - return rows[0] || null -} - -async function listVendorItems(serial, { limit, offset }) { - return query( - `SELECT serial, item_id, hue, amount, price, name, cliloc, display_name, child - FROM shard_vendor_items - WHERE vendor_serial = ? - ORDER BY price ASC, id ASC - LIMIT ? OFFSET ?`, - [serial, limit, offset], - ) -} - -/** - * What the market page's header needs: how big the index is, and how stale it may - * be. `staleAt` is the OLDEST vendor row — the round-robin sweep means a shop can - * be a full cycle behind, and the page says so rather than implying live prices. - */ -async function meta() { - const rows = await query( - `SELECT COUNT(*) AS vendors, MIN(updated_at) AS stale_at, MAX(updated_at) AS fresh_at - FROM shard_vendors`, - ) - const items = await query('SELECT COUNT(*) AS n FROM shard_vendor_items') - return { - vendors: Number(rows[0]?.vendors) || 0, - items: Number(items[0]?.n) || 0, - staleAt: rows[0]?.stale_at || null, - freshAt: rows[0]?.fresh_at || null, - } -} - -/** The distinct facets and regions holding vendors — drives the page's filters. */ -async function listPlaces() { - const maps = await query( - 'SELECT DISTINCT map FROM shard_vendors WHERE map IS NOT NULL ORDER BY map', - ) - const regions = await query( - 'SELECT DISTINCT region FROM shard_vendors WHERE region IS NOT NULL ORDER BY region', - ) - return { maps: maps.map((r) => r.map), regions: regions.map((r) => r.region) } -} - -// ── Cliloc re-resolution ─────────────────────────────────────────────────── - -/** - * One page of listings whose name still needs resolving, for the bulk pass that - * runs after a cliloc import. - * - * Keyed on `id > after` rather than OFFSET: the pass updates the very rows it is - * scanning, and an OFFSET walk over a table being rewritten skips rows. Every - * row with a cliloc is re-read, not just the unresolved ones, because an import - * can also CHANGE a name — a shard overlay relabelling a stock item is the whole - * reason overlays exist. - */ -async function listResolvableItems(after, limit) { - return query( - `SELECT id, cliloc, name, display_name - FROM shard_vendor_items - WHERE cliloc IS NOT NULL AND cliloc > 0 AND id > ? - ORDER BY id - LIMIT ?`, - [after, limit], - ) -} - -/** Write back a batch of re-resolved display names. */ -async function updateDisplayNames(pairs) { - if (pairs.length === 0) return 0 - const conn = await pool.getConnection() - try { - await conn.batch('UPDATE shard_vendor_items SET display_name = ? WHERE id = ?', pairs) - return pairs.length - } finally { - conn.release() - } -} - -module.exports = { - replaceVendor, - removeVendor, - searchListings, - getVendor, - listVendorItems, - meta, - listPlaces, - listResolvableItems, - updateDisplayNames, - likeTerm, -} diff --git a/server/src/model/shardMarket/shardMarket.model.js b/server/src/model/shardMarket/shardMarket.model.js deleted file mode 100644 index a0c781d..0000000 --- a/server/src/model/shardMarket/shardMarket.model.js +++ /dev/null @@ -1,329 +0,0 @@ -// ── Player-vendor market index (Protocol 3.0 vendor.listing) ─────────────── -// -// The shard-wide shop index: what every player vendor is selling, for how much, -// and where it is standing. This is the website's half of the search the in-game -// Vendor Search gump offers — the same data, the same opt-out, reachable without -// logging in to the game. -// -// Ingest is per-vendor and authoritative: the shard's round-robin sweep emits one -// `vendor.listing` frame per shop whose contents, prices or location moved, and -// the frame is the whole shop (see docs/link/v3.md §8 and BridgeMarket.cs). This -// module normalizes it into shard_vendors + shard_vendor_items and, crucially, -// resolves each listing's cliloc to a DISPLAY NAME on the way in — a search for -// "kryss" is a search over names, and the shard only ever sends numbers. - -const db = require('./shardMarket.db') -const clilocs = require('../shardClilocs/shardClilocs.model') -const log = require('../../utils/logger')('shard-market') - -// Defense in depth on top of the shard's own MarketMaxListings cap. The shard is -// trusted, but it is a separately-versioned component: a frame from a plugin -// whose cap was raised (or a shard running modified scripts) must not be able to -// turn one ingest into an unbounded transaction. -const MAX_ITEMS_PER_VENDOR = 5000 - -// Column widths in schema.sql. Truncating here rather than letting MariaDB do it -// keeps the behavior the same in strict mode, where an over-length value is an -// ERROR and would fail the whole vendor rather than shortening one name. -const MAX_NAME = 160 -const MAX_SHOP = 160 -const MAX_OWNER = 64 -const MAX_MAP = 40 -const MAX_REGION = 80 -const MAX_SERIAL = 20 - -const clip = (value, max) => { - if (value == null) return null - const s = String(value) - return s.length > max ? s.slice(0, max) : s -} - -const int = (value, fallback = 0) => { - const n = Number(value) - return Number.isFinite(n) ? Math.trunc(n) : fallback -} - -// ── Ingest ───────────────────────────────────────────────────────────────── - -/** - * Flatten one `vendor.listing` frame into the row shapes the DB layer wants. - * - * `location` arrives as a nested object rather than flat map/x/y/region, and that - * shape is load-bearing rather than cosmetic: the visibility projection matches - * literal JSON keys, so ONE `market.location` rule can hide a vendor's - * whereabouts only if `location` is a single key on both the live frame and the - * stored read model. Flattening it here for storage and re-nesting it on read is - * what keeps that true on both paths. - * - * Exported for tests — it is the part with rules in it, and it is pure. - */ -function flattenFrame(ev) { - const loc = (ev && ev.location) || {} - return { - serial: clip(ev.serial, MAX_SERIAL), - shopName: clip(ev.shopName, MAX_SHOP), - ownerSerial: clip(ev.ownerSerial, MAX_SERIAL), - ownerName: clip(ev.ownerName, MAX_OWNER), - map: clip(loc.map, MAX_MAP), - x: Number.isFinite(loc.x) ? Math.trunc(loc.x) : null, - y: Number.isFinite(loc.y) ? Math.trunc(loc.y) : null, - z: Number.isFinite(loc.z) ? Math.trunc(loc.z) : null, - region: clip(loc.region, MAX_REGION), - house: clip(loc.house, MAX_SHOP), - // What the SHOP holds, which is not what the frame carries when it was - // truncated. Kept apart so the page can say "showing 250 of 3,104" rather - // than presenting a partial shop as a complete one. - itemTotal: int(ev.total, int(ev.count, 0)), - truncated: ev.truncated === true, - t: Number.isFinite(ev.t) ? ev.t : null, - } -} - -/** - * Resolve each listing's display name. - * - * Order of preference is the item's own literal `name` first, then the cliloc. - * That is the opposite of what "resolve the id" suggests and it is right: a - * literal name only exists because a player set one ("Bob's vanquishing kryss"), - * and it is strictly more specific than the generic cliloc the item still - * carries. - * - * One batched lookup per frame rather than per item; `resolveMany` is cached and - * never throws, so a cliloc table that is missing entirely just leaves - * `displayName` null and the page renders item ids, exactly as it did before the - * table existed. - */ -async function shapeItems(ev) { - const raw = Array.isArray(ev.items) ? ev.items.slice(0, MAX_ITEMS_PER_VENDOR) : [] - - const wanted = raw - .map((i) => int(i && i.cliloc, 0)) - .filter((n) => n > 0) - - const names = await clilocs.resolveMany(wanted) - - return raw - .filter((i) => i && i.serial) - .map((i) => { - const literal = clip(i.name, MAX_NAME) - const cliloc = int(i.cliloc, 0) || null - return { - serial: clip(i.serial, MAX_SERIAL), - itemId: int(i.itemId, 0), - hue: int(i.hue, 0), - amount: int(i.amount, 1), - price: int(i.price, 0), - name: literal, - cliloc, - displayName: literal || (cliloc ? clip(names.get(cliloc) ?? null, MAX_NAME) : null), - child: i.child === true, - } - }) - // Unpriced rows are inventory, not listings. The shard already drops them; - // this is the same rule enforced where the table is written, so a plugin that - // stops enforcing it cannot put un-buyable rows on the market page. - .filter((i) => i.price > 0) -} - -/** Ingest one `vendor.listing` frame. */ -async function upsertVendor(ev) { - if (!ev || !ev.serial) return - const vendor = flattenFrame(ev) - const items = await shapeItems(ev) - await db.replaceVendor(vendor, items) -} - -/** Ingest one `vendor.listing.remove` frame. */ -async function removeVendor(serial) { - if (!serial) return - await db.removeVendor(String(serial).slice(0, MAX_SERIAL)) -} - -// ── Read models ──────────────────────────────────────────────────────────── -// -// `location` is re-nested (see flattenFrame) so the stored read model and the -// live wire frame present the same keys to the visibility projection. - -const place = (r) => ({ - map: r.map, - x: r.x, - y: r.y, - z: r.z, - region: r.region, - house: r.house, -}) - -// A listing as the search returns it: the item, plus enough of its shop to be -// actionable without a second request. `displayName` falls back to nothing rather -// than to a fabricated "Item 3922" — the client decides how to render an -// unresolved id, and inventing a name here would make it indistinguishable from -// a real one. -const shapeListing = (r) => ({ - serial: r.serial, - itemId: r.item_id, - hue: r.hue, - amount: r.amount, - price: Number(r.price), - name: r.name, - cliloc: r.cliloc, - displayName: r.display_name, - child: !!r.child, - vendor: { - serial: r.vendor_serial, - shopName: r.shop_name, - ownerSerial: r.owner_serial, - ownerName: r.owner_name, - location: place(r), - updatedAt: r.updated_at, - }, -}) - -const shapeVendor = (r) => ({ - serial: r.serial, - shopName: r.shop_name, - ownerSerial: r.owner_serial, - ownerName: r.owner_name, - location: place(r), - count: r.item_count, - total: r.item_total, - truncated: !!r.truncated, - updatedAt: r.updated_at, -}) - -const shapeItem = (r) => ({ - serial: r.serial, - itemId: r.item_id, - hue: r.hue, - amount: r.amount, - price: Number(r.price), - name: r.name, - cliloc: r.cliloc, - displayName: r.display_name, - child: !!r.child, -}) - -/** - * Search the index. Returns a page of LISTINGS (not vendors) plus the - * unpaginated total and the staleness stamp the page's banner needs. - */ -async function search({ - q = '', - minPrice, - maxPrice, - itemId, - map = '', - region = '', - sort = 'price_asc', - limit = 50, - offset = 0, -} = {}) { - const { rows, total } = await db.searchListings({ - q: q.trim(), - minPrice: Number.isFinite(minPrice) ? minPrice : undefined, - maxPrice: Number.isFinite(maxPrice) ? maxPrice : undefined, - itemId: Number.isFinite(itemId) ? itemId : undefined, - map: map.trim(), - region: region.trim(), - sort, - limit, - offset, - }) - - const info = await db.meta() - - return { - listings: rows.map(shapeListing), - total, - limit, - offset, - // Repeated on every search response rather than left to a separate /meta - // call: the banner that says how old these prices are must age with the - // results it labels, and a client that fetched it once would keep showing a - // stamp from before the page it is looking at. - staleAt: info.staleAt, - vendors: info.vendors, - } -} - -/** One shop and its listings. `null` when the index has never seen that serial. */ -async function getVendor(serial, { limit = 250, offset = 0 } = {}) { - const row = await db.getVendor(serial) - if (!row) return null - const items = await db.listVendorItems(serial, { limit, offset }) - return { ...shapeVendor(row), items: items.map(shapeItem) } -} - -/** Index size, staleness, and the facet/region filter options. */ -async function meta() { - const [info, places] = await Promise.all([db.meta(), db.listPlaces()]) - return { ...info, ...places } -} - -// ── Cliloc re-resolution ─────────────────────────────────────────────────── - -// Batch size for the post-import pass. Big enough that a 40k-row table is ~40 -// round trips, small enough that a single batch is not a long-held connection. -const RESOLVE_BATCH = 1000 - -/** - * Re-resolve every listing's display name against the current cliloc table. - * - * Called after a cliloc import, and it has to be: the market's diff sweep will - * NOT re-send an unchanged shop just because the site learned what its items are - * called, so without this an operator who configures clilocs after the first - * market sweep sees item ids until every shop happens to change. That is the same - * class of staleness the spawn atlas avoids by re-parsing on boot — here the - * source of truth for names moved, not the data. - * - * Never throws. It is a cosmetic backfill on a table that is already serving; a - * failure means names stay as they were, which is exactly the pre-import state. - */ -async function refreshDisplayNames() { - let after = 0 - let scanned = 0 - let changed = 0 - - try { - for (;;) { - const rows = await db.listResolvableItems(after, RESOLVE_BATCH) - if (rows.length === 0) break - - after = rows[rows.length - 1].id - scanned += rows.length - - const names = await clilocs.resolveMany(rows.map((r) => Number(r.cliloc))) - - const pairs = [] - for (const row of rows) { - // The literal name still wins, so a re-resolution never overwrites a - // player-set name with the generic cliloc behind it. - const next = row.name - ? clip(row.name, MAX_NAME) - : clip(names.get(Number(row.cliloc)) ?? null, MAX_NAME) - if (next !== row.display_name) pairs.push([next, row.id]) - } - - changed += await db.updateDisplayNames(pairs) - } - - if (changed > 0) log.info('market display names refreshed', { scanned, changed }) - return { scanned, changed } - } catch (err) { - log.warn('market display-name refresh failed', { message: err.message, scanned, changed }) - return { scanned, changed, error: err.message } - } -} - -module.exports = { - upsertVendor, - removeVendor, - search, - getVendor, - meta, - refreshDisplayNames, - flattenFrame, - shapeItems, - shapeListing, - shapeVendor, - MAX_ITEMS_PER_VENDOR, -} diff --git a/server/src/model/shardState/shardState.db.js b/server/src/model/shardState/shardState.db.js deleted file mode 100644 index 38378dd..0000000 --- a/server/src/model/shardState/shardState.db.js +++ /dev/null @@ -1,369 +0,0 @@ -const { query } = require('../../utils/db') - -// Shared upsert builder for the shard-state tables. Each is keyed on a single -// primary column (`pkCol` = pk); `fields` carries only the columns the model -// wants to write, so a partial refresh touches nothing else. `coalesce` keeps -// the prior column value when the incoming one is NULL (used by shard_online so a -// vitals frame that omits acct/name doesn't blank what mob.login set); otherwise -// the incoming value wins (VALUES()). -function upsertRow(table, pkCol, pk, fields, { coalesce = false } = {}) { - const cols = Object.keys(fields) - const allCols = [pkCol, ...cols] - const insertCols = allCols.map((c) => `\`${c}\``).join(', ') - const placeholders = allCols.map(() => '?').join(', ') - const rhs = coalesce - ? (c) => `\`${c}\` = COALESCE(VALUES(\`${c}\`), \`${c}\`)` - : (c) => `\`${c}\` = VALUES(\`${c}\`)` - const updates = cols.map(rhs).join(', ') - return query( - `INSERT INTO ${table} (${insertCols}) VALUES (${placeholders}) - ON DUPLICATE KEY UPDATE ${updates}`, - [pk, ...cols.map((c) => fields[c])], - ) -} - -// ── Online players ───────────────────────────────────────────────────────── -const ONLINE_COLS = - 'serial, name, acct, web_id, map, x, y, z, hits, hits_max, mana, mana_max, stam, stam_max, str, dex, `int`, updated_at' - -// Upsert one online player. `fields` already prepared by the model (only the -// columns it wants to write); serial is required and is the primary key. -// COALESCE variant: a char.vitals frame that omits acct/name must not blank what -// mob.login set, so an incoming NULL keeps the prior column value. -const upsertOnline = (serial, fields) => - upsertRow('shard_online', 'serial', serial, fields, { coalesce: true }) - -const removeOnline = (serial) => query('DELETE FROM shard_online WHERE serial = ?', [serial]) -const clearOnline = () => query('DELETE FROM shard_online') - -async function countOnline() { - const rows = await query('SELECT COUNT(*) AS n FROM shard_online') - return rows[0] ? Number(rows[0].n) : 0 -} - -const listOnline = () => - query(`SELECT ${ONLINE_COLS} FROM shard_online ORDER BY name ASC`) - -// Online players on any of the given game accounts (admin: a user's linked -// accounts). Empty list short-circuits so we never emit `IN ()`. -const listOnlineByAccounts = (accounts) => - accounts.length === 0 - ? Promise.resolve([]) - : query( - `SELECT ${ONLINE_COLS} FROM shard_online - WHERE acct IN (${accounts.map(() => '?').join(', ')}) - ORDER BY name ASC`, - accounts, - ) - -// Staff roles whose online presence is shown on the public Shard page. Players -// who link an account are NOT surfaced publicly — only staff opt into visibility -// by virtue of being staff. -const PUBLIC_ONLINE_ROLES = ['admin', 'editor', 'moderator'] - -// Online players whose game account is linked to a STAFF website user. Joined -// against shard_account_links (not the sidecar-supplied web_id) so a link takes -// effect immediately, regardless of whether the player has re-logged since -// linking, then through to users so only staff roles are surfaced publicly. -const listOnlineLinked = () => { - const cols = ONLINE_COLS.split(', ') - .map((c) => `o.${c}`) - .join(', ') - return query( - `SELECT ${cols} - FROM shard_online o - JOIN shard_account_links l ON l.account = o.acct - JOIN users u ON u.id = l.user_id - WHERE u.role IN (${PUBLIC_ONLINE_ROLES.map(() => '?').join(', ')}) - ORDER BY o.name ASC`, - PUBLIC_ONLINE_ROLES, - ) -} - -// ── Economy supply series ──────────────────────────────────────────────── -const insertEconomy = ({ accounts, gold, t }) => - query('INSERT INTO shard_economy (accounts, gold, t) VALUES (?, ?, ?)', [ - accounts ?? null, - gold ?? null, - t, - ]) - -const listEconomy = (limit) => - query('SELECT accounts, gold, t FROM shard_economy ORDER BY t DESC LIMIT ?', [limit]) - -async function latestEconomy() { - const rows = await query('SELECT accounts, gold, t FROM shard_economy ORDER BY t DESC LIMIT 1') - return rows[0] || null -} - -// ── Houses / IDOC ──────────────────────────────────────────────────────── -const HOUSE_COLS = - 'serial, stage, map, x, y, z, region, name, owner_serial, owner_acct, built_on, last_refreshed, is_idoc, updated_at' - -const upsertHouse = (serial, fields) => upsertRow('shard_houses', 'serial', serial, fields) - -const listIdocHouses = () => - query(`SELECT ${HOUSE_COLS} FROM shard_houses WHERE is_idoc = 1 ORDER BY updated_at DESC`) - -// Houses owned by any of the given game accounts (admin: a user's linked -// accounts). IDOC houses first, then newest-refreshed. Empty list short-circuits. -const listHousesByAccounts = (accounts) => - accounts.length === 0 - ? Promise.resolve([]) - : query( - `SELECT ${HOUSE_REG_COLS} FROM shard_houses - WHERE owner_acct IN (${accounts.map(() => '?').join(', ')}) - ORDER BY is_idoc DESC, updated_at DESC`, - accounts, - ) - -// ── House registry (Protocol 2.0 house.update / house.remove) ────────────── -// The registry columns extend HOUSE_COLS; a registry row is one we've seen via -// house.update (in_registry = 1), as opposed to a decay-only transition row. -const HOUSE_REG_COLS = `${HOUSE_COLS}, owner_name, co_owners, friends, price, decay, in_registry` - -const removeHouse = (serial) => query('DELETE FROM shard_houses WHERE serial = ?', [serial]) - -// The full registered-house browser: every row we've seen via house.update. -const listRegistryHouses = () => - query(`SELECT ${HOUSE_REG_COLS} FROM shard_houses WHERE in_registry = 1 ORDER BY name ASC`) - -// ── Champion spawns ──────────────────────────────────────────────────────── -const CHAMP_COLS = - 'serial, category, type, name, status, active, map, x, y, z, boss_up, payload, t, updated_at' - -const upsertChamp = (serial, fields) => upsertRow('shard_champs', 'serial', serial, fields) - -const removeChamp = (serial) => query('DELETE FROM shard_champs WHERE serial = ?', [serial]) -const clearChamps = () => query('DELETE FROM shard_champs') -// Ordered by name (matches the sidecar's /champs ordering). -const listChamps = () => query(`SELECT ${CHAMP_COLS} FROM shard_champs ORDER BY name ASC`) - -// ── Help-page (support) queue ────────────────────────────────────────────── -const PAGE_COLS = - 'page_id, type, sender_name, sender_acct, web_id, message, map, x, y, z, sent_ms, handled, handler, payload, updated_at' - -async function upsertPage(pageId, fields) { - const cols = Object.keys(fields) - const allCols = ['page_id', ...cols] - const insertCols = allCols.map((c) => `\`${c}\``).join(', ') - const placeholders = allCols.map(() => '?').join(', ') - const updates = cols.map((c) => `\`${c}\` = VALUES(\`${c}\`)`).join(', ') - await query( - `INSERT INTO shard_pages (${insertCols}) VALUES (${placeholders}) - ON DUPLICATE KEY UPDATE ${updates}`, - [pageId, ...cols.map((c) => fields[c])], - ) -} - -const removePage = (pageId) => query('DELETE FROM shard_pages WHERE page_id = ?', [pageId]) -const clearPages = () => query('DELETE FROM shard_pages') -// Oldest-open first so the queue reads like a work list. -const listPages = () => query(`SELECT ${PAGE_COLS} FROM shard_pages ORDER BY sent_ms ASC`) - -// ── Guild board (Protocol 2.0) ───────────────────────────────────────────── -const GUILD_COLS = - 'id, name, abbr, members, online, alliance, leader_serial, leader_name, leader_acct, leader_web_id, payload, t, updated_at' - -const upsertGuild = (id, fields) => upsertRow('shard_guilds', 'id', id, fields) - -const removeGuild = (id) => query('DELETE FROM shard_guilds WHERE id = ?', [id]) -const clearGuilds = () => query('DELETE FROM shard_guilds') -const listGuilds = () => query(`SELECT ${GUILD_COLS} FROM shard_guilds ORDER BY name ASC`) - -// The guild an actor LEADS — matched on the current board (leader_serial or the -// linked leader_acct), so it reflects live state. Guild MEMBERSHIP for non-leaders -// is not modelled (the board carries only counts + leader), so we don't guess it. -const findGuildLedByActor = (serial, acct) => - query( - `SELECT id, name, abbr, alliance, leader_name FROM shard_guilds - WHERE leader_serial = ? OR (leader_acct IS NOT NULL AND leader_acct = ?) - LIMIT 1`, - [serial ?? null, acct ?? null], - ) - -// Guilds led by any of the given game accounts (admin: a user's linked accounts). -const listGuildsLedByAccounts = (accounts) => - accounts.length === 0 - ? Promise.resolve([]) - : query( - `SELECT id, name, abbr, alliance, leader_name FROM shard_guilds - WHERE leader_acct IN (${accounts.map(() => '?').join(', ')}) - ORDER BY name ASC`, - accounts, - ) - -// ── Governor board + term history (Protocol 2.0) ─────────────────────────── -const GOV_COLS = - 'city, governor_serial, governor_name, governor_acct, governor_web_id, elect_serial, elect_name, elect_acct, election_phase, candidates, auto_pick_at, payload, t, updated_at' - -const upsertGovernor = (city, fields) => upsertRow('shard_governors', 'city', city, fields) - -const listGovernors = () => query(`SELECT ${GOV_COLS} FROM shard_governors ORDER BY city ASC`) - -// Cities whose current governor is one of the given game accounts (cross-link: -// does this user hold a governorship?). Empty list short-circuits. -const listGovernorshipsByAccounts = (accounts) => - accounts.length === 0 - ? Promise.resolve([]) - : query( - `SELECT ${GOV_COLS} FROM shard_governors - WHERE governor_acct IN (${accounts.map(() => '?').join(', ')}) - ORDER BY city ASC`, - accounts, - ) - -// The single open term (ended_at IS NULL) for a city, if any. -async function currentGovernorTerm(city) { - const rows = await query( - 'SELECT id, city, governor_serial, governor_name, governor_acct, governor_web_id, started_at, ended_at, votes FROM shard_governor_terms WHERE city = ? AND ended_at IS NULL ORDER BY started_at DESC LIMIT 1', - [city], - ) - return rows[0] || null -} - -const closeGovernorTerm = (id, endedAt) => - query('UPDATE shard_governor_terms SET ended_at = ? WHERE id = ?', [endedAt, id]) - -const openGovernorTerm = ({ city, serial, name, acct, webId, startedAt }) => - query( - `INSERT INTO shard_governor_terms - (city, governor_serial, governor_name, governor_acct, governor_web_id, started_at) - VALUES (?, ?, ?, ?, ?, ?)`, - [city, serial ?? null, name ?? null, acct ?? null, webId ?? null, startedAt], - ) - -const listGovernorTerms = (city, limit) => - query( - 'SELECT id, city, governor_serial, governor_name, governor_acct, governor_web_id, started_at, ended_at, votes FROM shard_governor_terms WHERE city = ? ORDER BY started_at DESC LIMIT ?', - [city, limit], - ) - -// ── Online-population snapshot (Protocol 2.0 presence.online) ─────────────── -async function setPresence({ count, byFacet, byRegion, t }) { - await query( - `INSERT INTO shard_presence (id, count, by_facet, by_region, t) VALUES (1, ?, ?, ?, ?) - ON DUPLICATE KEY UPDATE count = VALUES(count), by_facet = VALUES(by_facet), - by_region = VALUES(by_region), t = VALUES(t)`, - [ - Number.isFinite(count) ? count : 0, - byFacet ? JSON.stringify(byFacet) : null, - byRegion ? JSON.stringify(byRegion) : null, - Number.isFinite(t) ? t : null, - ], - ) -} - -async function latestPresence() { - const rows = await query('SELECT count, by_facet, by_region, t FROM shard_presence WHERE id = 1') - return rows[0] || null -} - -// ── Shard ruleset (Protocol 3.0 world.ruleset) ───────────────────────────── -// Singleton, same shape as shard_presence: the shard re-emits the whole frame on -// every connect, so there is nothing to merge — the latest one wins outright. -async function setRuleset({ rev, expansion, payload, t }) { - await query( - `INSERT INTO shard_ruleset (id, rev, expansion, payload, t) VALUES (1, ?, ?, ?, ?) - ON DUPLICATE KEY UPDATE rev = VALUES(rev), expansion = VALUES(expansion), - payload = VALUES(payload), t = VALUES(t)`, - [rev ?? null, expansion ?? null, payload, Number.isFinite(t) ? t : null], - ) -} - -async function getRuleset() { - const rows = await query( - 'SELECT rev, expansion, payload, t, updated_at FROM shard_ruleset WHERE id = 1', - ) - return rows[0] || null -} - -// ── Points/loyalty boards (Protocol 3.0 points.board) ────────────────────── -// One row per point system. The shard only emits a system whose top N actually -// moved, so this is a sparse stream of overwrites; there is no delete, because -// the shard's set of systems is fixed at startup. -async function upsertPointsBoard({ system, name, nameCliloc, maxPoints, players, showOnGump, payload, t }) { - await query( - `INSERT INTO shard_points_boards - (system, name, name_cliloc, max_points, players, show_on_gump, payload, t) - VALUES (?, ?, ?, ?, ?, ?, ?, ?) - ON DUPLICATE KEY UPDATE name = VALUES(name), name_cliloc = VALUES(name_cliloc), - max_points = VALUES(max_points), players = VALUES(players), - show_on_gump = VALUES(show_on_gump), payload = VALUES(payload), t = VALUES(t)`, - [ - system, - name ?? null, - Number.isFinite(nameCliloc) ? nameCliloc : null, - Number.isFinite(maxPoints) ? maxPoints : null, - Number.isFinite(players) ? players : null, - showOnGump ? 1 : 0, - payload, - Number.isFinite(t) ? t : null, - ], - ) -} - -// Ordered by display name, falling back to the system key for a board whose name -// arrived as a bare cliloc — otherwise every unresolved board would sort together -// under NULL. -async function listPointsBoards() { - return query( - `SELECT system, name, name_cliloc, max_points, players, show_on_gump, payload, t, updated_at - FROM shard_points_boards ORDER BY COALESCE(name, system), system`, - ) -} - -async function getPointsBoard(system) { - const rows = await query( - `SELECT system, name, name_cliloc, max_points, players, show_on_gump, payload, t, updated_at - FROM shard_points_boards WHERE system = ?`, - [system], - ) - return rows[0] || null -} - -module.exports = { - upsertOnline, - removeOnline, - clearOnline, - countOnline, - listOnline, - listOnlineLinked, - listOnlineByAccounts, - insertEconomy, - listEconomy, - latestEconomy, - upsertHouse, - listIdocHouses, - listHousesByAccounts, - removeHouse, - listRegistryHouses, - upsertGuild, - removeGuild, - clearGuilds, - listGuilds, - findGuildLedByActor, - listGuildsLedByAccounts, - upsertGovernor, - listGovernors, - listGovernorshipsByAccounts, - currentGovernorTerm, - closeGovernorTerm, - openGovernorTerm, - listGovernorTerms, - setPresence, - latestPresence, - setRuleset, - getRuleset, - upsertPointsBoard, - listPointsBoards, - getPointsBoard, - upsertChamp, - removeChamp, - clearChamps, - listChamps, - upsertPage, - removePage, - clearPages, - listPages, -} diff --git a/server/src/model/shardState/shardState.model.js b/server/src/model/shardState/shardState.model.js deleted file mode 100644 index 10a3ba2..0000000 --- a/server/src/model/shardState/shardState.model.js +++ /dev/null @@ -1,638 +0,0 @@ -// Live shard state derived from the WS feed: who is online, the gold-supply -// series, and per-house decay stage. The ingest dispatcher calls the write -// methods; the public read endpoints call the list/count methods. Writes take -// camelCase semantic objects and map to the snake_case columns; only the keys -// present are written (so a char.vitals refresh doesn't clobber login fields). - -const db = require('./shardState.db') - -const MAX_ECONOMY = 1000 - -// Small coercion helpers, kept out of the upsert builders below so those stay -// flat (each inline `?? null` / ternary otherwise adds to cognitive complexity). -const orNull = (v) => v ?? null -const toDate = (v) => (v ? new Date(v) : null) -// Owner is an actor object (or null for an abandoned house); flatten to columns. -const ownerFields = (owner) => ({ - owner_serial: orNull(owner?.serial), - owner_acct: orNull(owner?.acct), - owner_name: orNull(owner?.name), -}) - -// Map a camelCase online descriptor to DB columns, dropping undefined keys so a -// partial refresh only touches the fields it carries. -function onlineFields(data) { - const map = { - name: data.name, - acct: data.acct, - web_id: data.webId, - map: data.map, - x: data.x, - y: data.y, - z: data.z, - hits: data.hits, - hits_max: data.hitsMax, - mana: data.mana, - mana_max: data.manaMax, - stam: data.stam, - stam_max: data.stamMax, - str: data.str, - dex: data.dex, - int: data.int, - } - const fields = {} - for (const [k, v] of Object.entries(map)) if (v !== undefined) fields[k] = v - return fields -} - -// Upsert an online player (mob.login) or refresh their vitals (char.vitals). -async function upsertOnline(data) { - if (!data || !data.serial) return - await db.upsertOnline(data.serial, onlineFields(data)) -} - -const setOffline = (serial) => db.removeOnline(serial) -const clearOnline = () => db.clearOnline() -const onlineCount = () => db.countOnline() - -function shapeOnline(r) { - return { - serial: r.serial, - name: r.name, - acct: r.acct, - webId: r.web_id, - map: r.map, - x: r.x, - y: r.y, - z: r.z, - hits: r.hits, - hitsMax: r.hits_max, - mana: r.mana, - manaMax: r.mana_max, - stam: r.stam, - stamMax: r.stam_max, - str: r.str, - dex: r.dex, - int: r.int, - updatedAt: r.updated_at, - } -} - -// Only players whose account is linked to a website user (opt-in visibility). -async function listOnlineLinked() { - const rows = await db.listOnlineLinked() - return rows.map(shapeOnline) -} - -async function listOnline() { - const rows = await db.listOnline() - return rows.map(shapeOnline) -} - -// Append a gold-supply sample (economy.supply). -async function addEconomySample({ accounts, gold, t }) { - await db.insertEconomy({ accounts, gold, t }) -} - -async function listEconomy(limit = 100) { - const n = Math.min(Math.max(Number(limit) || 100, 1), MAX_ECONOMY) - const rows = await db.listEconomy(n) - // Return oldest → newest for charting. - return rows - .map((r) => ({ accounts: r.accounts, gold: r.gold == null ? null : Number(r.gold), t: r.t })) - .reverse() -} - -async function latestEconomy() { - const r = await db.latestEconomy() - return r ? { accounts: r.accounts, gold: r.gold == null ? null : Number(r.gold), t: r.t } : null -} - -// Upsert a house's decay stage (house.decay). is_idoc is derived from the stage. -async function upsertHouse(data) { - if (!data || !data.serial) return - const fields = { - stage: data.stage ?? null, - map: data.map ?? null, - x: data.x ?? null, - y: data.y ?? null, - z: data.z ?? null, - region: data.region ?? null, - name: data.name ?? null, - owner_serial: data.ownerSerial ?? null, - owner_acct: data.ownerAcct ?? null, - built_on: data.builtOn ? new Date(data.builtOn) : null, - last_refreshed: data.lastRefreshed ? new Date(data.lastRefreshed) : null, - is_idoc: String(data.stage).toUpperCase() === 'IDOC' ? 1 : 0, - } - await db.upsertHouse(data.serial, fields) -} - -function shapeHouse(r) { - return { - serial: r.serial, - stage: r.stage, - map: r.map, - x: r.x, - y: r.y, - z: r.z, - region: r.region, - name: r.name, - ownerSerial: r.owner_serial, - ownerAcct: r.owner_acct, - // Registry fields (Protocol 2.0 house.update); undefined on decay-only rows. - ownerName: r.owner_name, - coOwners: r.co_owners, - friends: r.friends, - price: r.price == null ? null : Number(r.price), - decay: r.decay, - inRegistry: r.in_registry == null ? undefined : Boolean(r.in_registry), - builtOn: r.built_on, - lastRefreshed: r.last_refreshed, - isIdoc: Boolean(r.is_idoc), - updatedAt: r.updated_at, - } -} - -async function listIdoc() { - const rows = await db.listIdocHouses() - return rows.map(shapeHouse) -} - -// Houses owned by the given game accounts (admin: a user's linked accounts). -async function listHousesForAccounts(accounts) { - const rows = await db.listHousesByAccounts(accounts) - return rows.map(shapeHouse) -} - -// ── House registry (Protocol 2.0 house.update / house.remove) ────────────── -// Richer per-house snapshot than the decay-transition feed. Writes only the -// registry columns (+ shared location/owner fields); is_idoc/stage stay owned by -// the house.decay path, so the two feeds never clobber each other. owner is an -// actor object (or null for an abandoned house). -async function upsertHouseRegistry(data) { - if (!data || !data.serial) return - const fields = { - name: orNull(data.name), - ...ownerFields(data.owner || null), - co_owners: orNull(data.coOwners), - friends: orNull(data.friends), - price: orNull(data.price), - decay: orNull(data.decay), - region: orNull(data.region), - map: orNull(data.map), - x: orNull(data.x), - y: orNull(data.y), - z: orNull(data.z), - built_on: toDate(data.builtOn), - last_refreshed: toDate(data.lastRefreshed), - in_registry: 1, - } - await db.upsertHouse(data.serial, fields) -} - -const removeHouse = (serial) => (serial ? db.removeHouse(serial) : Promise.resolve()) - -async function listHouses() { - const rows = await db.listRegistryHouses() - return rows.map(shapeHouse) -} - -// Online players on the given game accounts (admin: a user's linked accounts). -async function listOnlineForAccounts(accounts) { - const rows = await db.listOnlineByAccounts(accounts) - return rows.map(shapeOnline) -} - -// ── Champion spawns ──────────────────────────────────────────────────────── -// Upsert a champ spawn's state (champ.update). The full event is stored in -// `payload` for the category-specific fields; a few columns are hoisted out for -// querying/ordering. is-boss-up is derived from bossUp (sea bosses are always up). -async function upsertChamp(ev) { - if (!ev || !ev.serial) return - await db.upsertChamp(ev.serial, { - category: orNull(ev.category), - type: orNull(ev.type), - name: orNull(ev.name), - status: orNull(ev.status), - active: ev.active ? 1 : 0, - map: orNull(ev.map), - x: orNull(ev.x), - y: orNull(ev.y), - z: orNull(ev.z), - boss_up: ev.bossUp ? 1 : 0, - payload: JSON.stringify(ev), - t: Number.isFinite(ev.t) ? ev.t : null, - }) -} - -const removeChamp = (serial) => (serial ? db.removeChamp(serial) : Promise.resolve()) -const clearChamps = () => db.clearChamps() - -// Return the stored champ.update payload (the shape the sidecar/UI expect), -// falling back to the hoisted columns if an older row lacks a payload. -function shapeChamp(r) { - const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload - return payload || { - kind: 'champ.update', - serial: r.serial, - category: r.category, - type: r.type, - name: r.name, - status: r.status, - active: Boolean(r.active), - map: r.map, - x: r.x, - y: r.y, - z: r.z, - bossUp: Boolean(r.boss_up), - t: r.t, - } -} - -async function listChamps() { - const rows = await db.listChamps() - return rows.map(shapeChamp) -} - -// Replace the whole board with a fresh snapshot (sidecar GET /champs on connect). -async function replaceChamps(spawns) { - await db.clearChamps() - for (const ev of spawns || []) await upsertChamp(ev) -} - -// ── Help-page (support) queue ────────────────────────────────────────────── -// Upsert a page (page.new / page.updated). The `sender` actor object carries the -// name/acct/webId; the rest are top-level fields. -async function upsertPage(ev) { - const pageId = ev && (ev.pageId || (ev.sender && ev.sender.serial)) - if (!pageId) return - const sender = ev.sender || {} - await db.upsertPage(pageId, { - type: orNull(ev.type), - sender_name: orNull(sender.name), - sender_acct: orNull(sender.acct), - web_id: orNull(sender.webId), - message: orNull(ev.message), - map: orNull(ev.map), - x: orNull(ev.x), - y: orNull(ev.y), - z: orNull(ev.z), - sent_ms: Number.isFinite(ev.sentMs) ? ev.sentMs : null, - handled: ev.handled ? 1 : 0, - handler: orNull(ev.handler), - payload: JSON.stringify(ev), - }) -} - -const removePage = (pageId) => (pageId ? db.removePage(pageId) : Promise.resolve()) -const clearPages = () => db.clearPages() - -function shapePage(r) { - const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload - return { - pageId: r.page_id, - type: r.type, - sender: { serial: r.page_id, name: r.sender_name, acct: r.sender_acct, webId: r.web_id }, - message: r.message, - map: r.map, - x: r.x, - y: r.y, - z: r.z, - sentMs: r.sent_ms == null ? null : Number(r.sent_ms), - handled: Boolean(r.handled), - handler: r.handler, - updatedAt: r.updated_at, - // Keep the raw payload available for any field not hoisted above. - payload: payload || undefined, - } -} - -async function listPages() { - const rows = await db.listPages() - return rows.map(shapePage) -} - -// Replace the whole queue with a fresh snapshot (sidecar GET /pages on connect). -async function replacePages(pages) { - await db.clearPages() - for (const ev of pages || []) await upsertPage(ev) -} - -// ── Guild board (Protocol 2.0) ───────────────────────────────────────────── -// Upsert a guild's roster snapshot (guild.update). The leader is an actor object -// flattened into leader_* columns; the full event lives in `payload`. -async function upsertGuild(ev) { - if (!ev || ev.id == null) return - const leader = ev.leader || {} - await db.upsertGuild(ev.id, { - name: ev.name ?? null, - abbr: ev.abbr ?? null, - members: ev.members ?? null, - online: ev.online ?? null, - alliance: ev.alliance ?? null, - leader_serial: leader.serial ?? null, - leader_name: leader.name ?? null, - leader_acct: leader.acct ?? null, - leader_web_id: leader.webId ?? null, - payload: JSON.stringify(ev), - t: Number.isFinite(ev.t) ? ev.t : null, - }) -} - -const removeGuild = (id) => (id == null ? Promise.resolve() : db.removeGuild(id)) -const clearGuilds = () => db.clearGuilds() - -function shapeGuild(r) { - const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload - return payload || { - kind: 'guild.update', - id: r.id, - name: r.name, - abbr: r.abbr, - members: r.members, - online: r.online, - alliance: r.alliance, - leader: r.leader_serial - ? { serial: r.leader_serial, name: r.leader_name, acct: r.leader_acct, webId: r.leader_web_id } - : null, - t: r.t, - } -} - -async function listGuilds() { - const rows = await db.listGuilds() - return rows.map(shapeGuild) -} - -// Replace the board with a fresh snapshot (sidecar GET /guilds on connect). -async function replaceGuilds(guilds) { - await db.clearGuilds() - for (const ev of guilds || []) await upsertGuild(ev) -} - -// The guild an actor leads (cross-link on the character sheet). Leadership only — -// see the db note; membership for rank-and-file isn't in the feed, so we return -// null rather than show a possibly-stale guess. -async function findGuildForActor({ serial, acct }) { - const rows = await db.findGuildLedByActor(serial ?? null, acct ?? null) - const g = rows[0] - if (!g) return null - return { id: g.id, name: g.name, abbr: g.abbr, alliance: g.alliance, role: 'leader' } -} - -// Guilds led by any of a user's linked accounts (admin user-detail cross-link). -async function listGuildsLedForAccounts(accounts) { - const rows = await db.listGuildsLedByAccounts(accounts) - return rows.map((g) => ({ id: g.id, name: g.name, abbr: g.abbr, alliance: g.alliance, leaderName: g.leader_name })) -} - -// ── Town governors (Protocol 2.0) ────────────────────────────────────────── -// Upsert a city's governance snapshot (city.update) AND capture term history. -// Term capture runs first (it reads the CURRENT open term to decide whether the -// governor changed) and is idempotent: a repeat/backfill of the same governor is a -// no-op, so it's safe to call on the live feed and on reconnect snapshots alike. -async function upsertGovernor(ev) { - if (!ev || !ev.city) return - await recordGovernorTransition(ev) - const gov = ev.governor - const elect = ev.governorElect - await db.upsertGovernor(ev.city, { - governor_serial: orNull(gov?.serial), - governor_name: orNull(gov?.name), - governor_acct: orNull(gov?.acct), - governor_web_id: orNull(gov?.webId), - elect_serial: orNull(elect?.serial), - elect_name: orNull(elect?.name), - elect_acct: orNull(elect?.acct), - election_phase: orNull(ev.electionPhase), - candidates: orNull(ev.candidates), - auto_pick_at: toDate(ev.autoPickAt), - payload: JSON.stringify(ev), - t: Number.isFinite(ev.t) ? ev.t : null, - }) -} - -// Close the open term and open a new one when the governor CHANGES. Idempotent: -// same governor as the open term ⇒ nothing happens (so backfill/duplicate -// city.update events never spawn spurious terms). -async function recordGovernorTransition(ev) { - const gov = ev.governor || null - const newSerial = gov ? gov.serial ?? null : null - const t = Number.isFinite(ev.t) ? ev.t : Date.now() - const open = await db.currentGovernorTerm(ev.city) - const openSerial = open ? open.governor_serial : null - if (open && openSerial === newSerial) return // unchanged — nothing to record - if (open) await db.closeGovernorTerm(open.id, t) // governor changed or seat vacated - if (newSerial) { - await db.openGovernorTerm({ - city: ev.city, - serial: newSerial, - name: gov.name ?? null, - acct: gov.acct ?? null, - webId: gov.webId ?? null, - startedAt: t, - }) - } -} - -function shapeGovernor(r) { - const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload - return payload || { - kind: 'city.update', - city: r.city, - governor: r.governor_serial - ? { serial: r.governor_serial, name: r.governor_name, acct: r.governor_acct, webId: r.governor_web_id } - : null, - governorElect: r.elect_serial - ? { serial: r.elect_serial, name: r.elect_name, acct: r.elect_acct } - : null, - electionPhase: r.election_phase, - candidates: r.candidates, - t: r.t, - } -} - -async function listGovernors() { - const rows = await db.listGovernors() - return rows.map(shapeGovernor) -} - -// Cities the given game accounts currently govern (cross-link badge). -async function listGovernorshipsForAccounts(accounts) { - const rows = await db.listGovernorshipsByAccounts(accounts) - return rows.map(shapeGovernor) -} - -// Term history for a city (look-back), newest first. -async function listGovernorHistory(city, limit = 100) { - const n = Math.min(Math.max(Number(limit) || 100, 1), 500) - const rows = await db.listGovernorTerms(city, n) - return rows.map((r) => ({ - city: r.city, - governor: r.governor_serial - ? { serial: r.governor_serial, name: r.governor_name, acct: r.governor_acct, webId: r.governor_web_id } - : null, - startedAt: r.started_at == null ? null : Number(r.started_at), - endedAt: r.ended_at == null ? null : Number(r.ended_at), - votes: r.votes, - })) -} - -// Upsert governors without clearing (cities are fixed, no remove event); term -// capture inside upsertGovernor stays idempotent across reconnect snapshots. -async function replaceGovernors(cities) { - for (const ev of cities || []) await upsertGovernor(ev) -} - -// ── Online-population snapshot (Protocol 2.0 presence.online) ─────────────── -async function setPresence(ev) { - if (!ev) return - await db.setPresence({ - count: ev.count, - byFacet: ev.byFacet || null, - byRegion: ev.byRegion || null, - t: ev.t, - }) -} - -async function latestPresence() { - const r = await db.latestPresence() - if (!r) return { count: 0, byFacet: {}, byRegion: {}, t: null } - const parse = (v) => (typeof v === 'string' ? safeJson(v) || {} : v || {}) - return { - count: Number(r.count) || 0, - byFacet: parse(r.by_facet), - byRegion: parse(r.by_region), - t: r.t == null ? null : Number(r.t), - } -} - -// ── Shard ruleset (Protocol 3.0 world.ruleset) ───────────────────────────── -// -// The whole frame is stored in `payload` and served back whole. Nothing is -// normalized out of it: it is a flat description of config read as one page, and -// splitting it into columns would mean a schema change every time the shard grows -// a new block. `rev` and `expansion` are hoisted only because they are cheap to -// index/display, following shard_champs' payload-plus-hoisted-columns pattern. -async function setRuleset(ev) { - if (!ev) return - await db.setRuleset({ - rev: ev.rev ?? null, - expansion: ev.expansion ?? null, - payload: JSON.stringify(ev), - t: ev.t, - }) -} - -// The stored ruleset, or null when the shard has never published one (an old -// plugin, or Bridge.RulesetEnabled=false). Null is a real answer here — the page -// says "not published yet" rather than rendering an empty ruleset as if the shard -// had no rules — so it is deliberately not smoothed into {}. -async function getRuleset() { - const r = await db.getRuleset() - if (!r) return null - const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload - if (!payload) return null - return { ...payload, updatedAt: r.updated_at } -} - -// ── Points/loyalty boards (Protocol 3.0 points.board) ────────────────────── -// -// The whole frame is stored in `payload`; the columns beside it are hoisted for -// listing and ordering only. The top-N list deliberately stays inside the payload -// (see schema.sql) — it is a fixed-size list read whole, like the governor board's -// candidates. -async function upsertPointsBoard(ev) { - if (!ev || !ev.system) return - await db.upsertPointsBoard({ - system: String(ev.system).slice(0, 48), - name: ev.nameString ?? null, - nameCliloc: ev.nameNumber, - maxPoints: ev.maxPoints, - players: ev.players, - showOnGump: ev.showOnGump !== false, - payload: JSON.stringify(ev), - t: ev.t, - }) -} - -// A stored frame plus the freshness stamp. `top` is normalized to an array so a -// caller never has to guard it — a board with nobody on it is a real state (a -// system nobody has scored in yet), distinct from a system that was never -// published at all, which is absent from the table entirely. -function shapePointsBoard(r) { - const payload = (typeof r.payload === 'string' ? safeJson(r.payload) : r.payload) || {} - return { - ...payload, - system: r.system, - top: Array.isArray(payload.top) ? payload.top : [], - updatedAt: r.updated_at, - } -} - -async function listPointsBoards() { - const rows = await db.listPointsBoards() - return rows.map(shapePointsBoard) -} - -async function getPointsBoard(system) { - const r = await db.getPointsBoard(system) - return r ? shapePointsBoard(r) : null -} - -function safeJson(s) { - try { - return JSON.parse(s) - } catch { - return null - } -} - -module.exports = { - upsertOnline, - setOffline, - clearOnline, - onlineCount, - listOnline, - listOnlineLinked, - listOnlineForAccounts, - addEconomySample, - listEconomy, - latestEconomy, - upsertHouse, - listIdoc, - listHousesForAccounts, - upsertHouseRegistry, - removeHouse, - listHouses, - upsertChamp, - removeChamp, - clearChamps, - listChamps, - replaceChamps, - upsertPage, - removePage, - clearPages, - listPages, - replacePages, - upsertGuild, - removeGuild, - clearGuilds, - listGuilds, - replaceGuilds, - findGuildForActor, - listGuildsLedForAccounts, - upsertGovernor, - listGovernors, - listGovernorshipsForAccounts, - listGovernorHistory, - replaceGovernors, - setPresence, - latestPresence, - setRuleset, - getRuleset, - upsertPointsBoard, - listPointsBoards, - getPointsBoard, -} diff --git a/server/src/model/shardVisibility/shardVisibility.db.js b/server/src/model/shardVisibility/shardVisibility.db.js deleted file mode 100644 index 2294482..0000000 --- a/server/src/model/shardVisibility/shardVisibility.db.js +++ /dev/null @@ -1,37 +0,0 @@ -const { query } = require('../../utils/db') - -// One row per shard feature. Absent rows are fine — utils/shardVisibility.js -// compiles a default for every known feature and merges stored rows over it, so -// a fresh install with an empty table behaves exactly as the site did pre-v3. - -const COLS = 'feature, enabled, audience, stream, field_rules, updated_by, updated_at' - -const listAll = () => query(`SELECT ${COLS} FROM shard_feature_visibility`) - -const getOne = (feature) => - query(`SELECT ${COLS} FROM shard_feature_visibility WHERE feature = ?`, [feature]) - -// Upsert one feature's settings. `fieldRules` is stored as a JSON object of -// {field: rung}; the caller has already stripped locked fields and validated -// every rung against the ladder. -const upsert = ({ feature, enabled, audience, stream, fieldRules, updatedBy }) => - query( - `INSERT INTO shard_feature_visibility (feature, enabled, audience, stream, field_rules, updated_by) - VALUES (?, ?, ?, ?, ?, ?) - ON DUPLICATE KEY UPDATE - enabled = VALUES(enabled), - audience = VALUES(audience), - stream = VALUES(stream), - field_rules = VALUES(field_rules), - updated_by = VALUES(updated_by)`, - [ - feature, - enabled ? 1 : 0, - audience, - stream ? 1 : 0, - fieldRules == null ? null : JSON.stringify(fieldRules), - updatedBy ?? null, - ], - ) - -module.exports = { listAll, getOne, upsert } diff --git a/server/src/model/shardVisibility/shardVisibility.model.js b/server/src/model/shardVisibility/shardVisibility.model.js deleted file mode 100644 index 094989a..0000000 --- a/server/src/model/shardVisibility/shardVisibility.model.js +++ /dev/null @@ -1,44 +0,0 @@ -// ── Shard feature visibility (model) ─────────────────────────────────────── -// -// Thin row-shaping layer over shardVisibility.db. The policy — the ladder, the -// feature catalog, the locked fields, the kind→feature map — lives in -// utils/shardVisibility.js; this file only reads and writes rows. - -const db = require('./shardVisibility.db') - -// The `field_rules` JSON column comes back as a string on the mariadb driver. -function parseRules(raw) { - if (raw == null) return {} - if (typeof raw === 'object') return raw - try { - const parsed = JSON.parse(raw) - return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {} - } catch { - return {} - } -} - -const toSafe = (row) => - row && { - feature: row.feature, - enabled: !!row.enabled, - audience: row.audience, - stream: row.stream == null ? null : !!row.stream, - fieldRules: parseRules(row.field_rules), - updatedBy: row.updated_by, - updatedAt: row.updated_at, - } - -async function listAll() { - const rows = await db.listAll() - return rows.map(toSafe) -} - -async function getOne(feature) { - const rows = await db.getOne(feature) - return toSafe(rows[0]) -} - -const upsert = (entry) => db.upsert(entry) - -module.exports = { listAll, getOne, upsert } diff --git a/server/src/model/uoLinkConfig/uoLinkConfig.db.js b/server/src/model/uoLinkConfig/uoLinkConfig.db.js deleted file mode 100644 index a27d54d..0000000 --- a/server/src/model/uoLinkConfig/uoLinkConfig.db.js +++ /dev/null @@ -1,7 +0,0 @@ -const singletonConfigDb = require('../singletonConfigDb') - -const COLS = - 'id, base_url, ws_url, auth_token_enc, protocol, enabled, status, status_detail, plugin_connected, last_event_at, boot_id, updated_by, created_at, updated_at' - -// Singleton row (id = 1). See ../singletonConfigDb for the get/upsert contract. -module.exports = singletonConfigDb('uo_link_config', COLS) diff --git a/server/src/model/uoLinkConfig/uoLinkConfig.model.js b/server/src/model/uoLinkConfig/uoLinkConfig.model.js deleted file mode 100644 index b783367..0000000 --- a/server/src/model/uoLinkConfig/uoLinkConfig.model.js +++ /dev/null @@ -1,88 +0,0 @@ -// uo-link sidecar connection config store. Mirrors botConfig/emailConfig: the DB -// layer only ever sees ciphertext, and only getWithToken() (used server-side to -// call the sidecar over REST/WS) decrypts it. The admin-facing getSafe() never -// includes the token — it exposes only `hasToken`. A blank `token` on save means -// "leave the existing token unchanged" (same convention as the other configs). - -const db = require('./uoLinkConfig.db') -const secretBox = require('../../utils/secretBox') - -// The wire protocol this build speaks (link/sidecar/src/main.rs PROTOCOL_VERSION). -// Only used before an admin has saved anything — the stored row wins once it exists, -// and UOLINK_PROTOCOL still overrides for an operator running an older sidecar. -const DEFAULT_PROTOCOL = Number(process.env.UOLINK_PROTOCOL) || 3 - -function toSafe(row) { - if (!row) { - return { - baseUrl: process.env.UOLINK_BASE_URL || null, - wsUrl: process.env.UOLINK_WS_URL || null, - protocol: DEFAULT_PROTOCOL, - enabled: false, - hasToken: false, - status: 'disconnected', - statusDetail: null, - pluginConnected: false, - lastEventAt: null, - bootId: null, - } - } - return { - baseUrl: row.base_url || null, - wsUrl: row.ws_url || null, - protocol: row.protocol || DEFAULT_PROTOCOL, - enabled: Boolean(row.enabled), - hasToken: Boolean(row.auth_token_enc), - status: row.status || 'disconnected', - statusDetail: row.status_detail || null, - pluginConnected: Boolean(row.plugin_connected), - lastEventAt: row.last_event_at || null, - bootId: row.boot_id || null, - } -} - -async function getSafe() { - return toSafe(await db.get()) -} - -// Decrypted token included — server-side only (calling the sidecar's REST/WS -// API). Returns null when nothing has been saved yet. -async function getWithToken() { - const row = await db.get() - if (!row) return null - return { ...toSafe(row), token: row.auth_token_enc ? secretBox.decrypt(row.auth_token_enc) : null } -} - -// Save admin-supplied config. `token` undefined or '' means "leave the existing -// token unchanged" (same convention as botConfig.save). -async function save({ baseUrl, wsUrl, token, protocol, enabled, updatedBy }) { - const fields = {} - if (baseUrl !== undefined) fields.base_url = baseUrl - if (wsUrl !== undefined) fields.ws_url = wsUrl - if (token) fields.auth_token_enc = secretBox.encrypt(token) - if (protocol !== undefined) fields.protocol = protocol - if (enabled !== undefined) fields.enabled = enabled ? 1 : 0 - if (updatedBy !== undefined) fields.updated_by = updatedBy - const row = await db.upsert(fields) - return toSafe(row) -} - -// Mirror the sidecar's last-reported connection state into the DB so the admin -// panel has something to show between polls and the public status endpoint can -// read it without a live round-trip. -async function recordStatus({ status, statusDetail, pluginConnected, lastEventAt, bootId }) { - const fields = {} - if (status !== undefined) fields.status = status - if (statusDetail !== undefined) fields.status_detail = statusDetail - if (pluginConnected !== undefined) fields.plugin_connected = pluginConnected ? 1 : 0 - // lastEventAt may arrive as an ISO string (e.g. "2026-07-10T22:08:27Z"); the - // mariadb DATETIME parser rejects the "T"/"Z", so hand it a real Date (same - // fix as botConfig.recordStatus's last_connected_at). - if (lastEventAt !== undefined) fields.last_event_at = lastEventAt ? new Date(lastEventAt) : null - if (bootId !== undefined) fields.boot_id = bootId - if (Object.keys(fields).length === 0) return getSafe() - const row = await db.upsert(fields) - return toSafe(row) -} - -module.exports = { getSafe, getWithToken, save, recordStatus } diff --git a/server/src/modules/loader.js b/server/src/modules/loader.js index 9ab8139..f44a547 100644 --- a/server/src/modules/loader.js +++ b/server/src/modules/loader.js @@ -103,6 +103,9 @@ function buildCtx(id, moduleRoot) { const validate = require('../middleware/validate') const noindex = require('../middleware/noindex') const uploads = require('../router/v1/admin/imageUpload') + const activity = require('../model/activity/activity.model') + const users = require('../model/users/users.model') + const { makeLimiter, accountChangeLimiter } = require('../middleware/rateLimit') /* eslint-enable global-require */ // Narrowed on purpose (§2.3): utils/auth also re-exports signToken, @@ -123,7 +126,26 @@ function buildCtx(id, moduleRoot) { auth: { getUserFromRequest: auth.getUserFromRequest }, push: { publish: pushDispatch.publish }, secretBox: { encrypt: secretBox.encrypt, decrypt: secretBox.decrypt }, - middleware: { requireAuth, requireRole, siteMode, validate, noindex }, + middleware: { + requireAuth, + requireRole, + siteMode, + validate, + noindex, + // Rate limiting, added in API 1.1.0 as a factory plus one shared limiter. + // + // `rateLimit(options)` is core's `makeLimiter`: a module states its own + // window and cap — it knows what its endpoints cost — and takes the + // plumbing from core, so there is one express-rate-limit in the process, + // one store, and one place a breach is logged. + // + // `accountChangeLimiter` is handed over whole because it is genuinely + // shared policy: core's `/auth/me`, `/player/account` and + // `/player/appeals` are behind the same counter, and a module's + // account-change route has to land in it rather than beside it. + rateLimit: makeLimiter, + accountChangeLimiter, + }, uploads, posts: { listAll: posts.listAll, @@ -131,6 +153,25 @@ function buildCtx(id, moduleRoot) { linkAnnounceJob: posts.linkAnnounceJob, markAnnounced: posts.markAnnounced, }, + // The admin audit log — WRITE only (§2.3, added in API 1.1.0). Core's one + // audit trail has to include the admin actions a module performs, or the + // trail has a hole exactly where a module operates the game. A module that + // kept its own log would be a second place to look, which in practice means + // a place nobody looks. `list` stays core's: reading the log is the admin + // panel's job, and it spans every actor. + activity: { log: activity.log }, + // One function, for one caller: the `admin.users.detail` slot router needs + // the user its prefix names. Narrowed like `ctx.posts` — the users model + // exports creation, role changes and password handling, none of which is a + // module's business. + users: { getById: users.getById }, + // Where this deployment is reachable, for a module that has to build an + // absolute link (an announcement carries one into a game window or a chat + // message, where a relative path means nothing). §2.7 forbids a module + // reading `process.env` for core configuration and this is core + // configuration, so core answers it. A getter, not a captured string: the + // value is read per call, so it cannot go stale against the env. + site: { get baseUrl() { return (process.env.APP_BASE_URL || 'http://localhost:5173').replace(/\/+$/, '') } }, } // A guard against accident, not against a hostile module — the boundary is // organisational, not a security boundary (MODULE_SYSTEM.md §2.2). @@ -232,7 +273,12 @@ function coreTableNames() { coreTables = new Set() try { const sql = fs.readFileSync(path.join(__dirname, '..', '..', 'db', 'schema.sql'), 'utf8') - for (const m of sql.matchAll(CREATE_TABLE)) coreTables.add(m[1].toLowerCase()) + // Split first, for the same reason tablesOf() does: matching the raw file + // reads CREATE TABLE out of comments, and a phantom core table makes a + // module fail with a collision against something that does not exist. + for (const statement of splitStatements(sql)) { + for (const m of statement.matchAll(CREATE_TABLE)) coreTables.add(m[1].toLowerCase()) + } } catch (err) { log.warn('could not read core schema for the table-collision check', { message: err.message }) } @@ -272,8 +318,9 @@ function tablesOf(dir, manifest) { if (!manifest.schema) return new Set() const file = path.join(dir, manifest.schema) const sql = fs.readFileSync(file, 'utf8') + const statements = splitStatements(sql) - for (const statement of splitStatements(sql)) { + for (const statement of statements) { const verb = (statement.match(/^\w+/) || [''])[0].toUpperCase() if (!ALLOWED_VERBS.has(verb)) { throw new Error(`schema fragment statement starts with "${verb}" (allowed: ${[...ALLOWED_VERBS].join(', ')})`) @@ -285,7 +332,18 @@ function tablesOf(dir, manifest) { } } - return new Set([...sql.matchAll(CREATE_TABLE)].map((m) => m[1].toLowerCase())) + // Scanned over the SPLIT STATEMENTS, never the raw file. `splitStatements` + // strips `--` comments; the file does not, and a fragment that documents + // itself will say "every CREATE TABLE carries IF NOT EXISTS" in its header. + // Read raw, that yields a table called `carries`, and the module is rejected + // for a prefix violation on a table that does not exist — a message with no + // way back to the comment that caused it. module-uo's fragment hit exactly + // this on its first real load. + const tables = new Set() + for (const statement of statements) { + for (const m of statement.matchAll(CREATE_TABLE)) tables.add(m[1].toLowerCase()) + } + return tables } function checkTableNames(id, tables) { diff --git a/server/src/modules/registries.js b/server/src/modules/registries.js index 828cd9d..938765f 100644 --- a/server/src/modules/registries.js +++ b/server/src/modules/registries.js @@ -52,6 +52,12 @@ const streamOwners = new Map() // stream id → owner id, for the collision mess // leg id → { owner, leg, label, dispatch, classify } const legs = new Map() +// owner -> { onSaved?, onDeleted? }. Post hooks (§1.8, API 1.1.0). A Map keyed by +// owner rather than a flat list, so a registrant is a single subscription that +// can be reported and reasoned about as one thing — and so registering twice is +// a collision with a name attached rather than a silently doubled side effect. +const postHooks = new Map() + let coreRegistered = false // Stream ids that predate the module system and may not carry their owner's @@ -119,6 +125,18 @@ const filledSlots = () => .filter(([, e]) => e.filledBy) .map(([slot, e]) => ({ slot, filledBy: e.filledBy, router: e.router, specFile: e.specFile || null })) +/** + * A DECLARED slot's stable router, filled or not. + * + * `filledSlots()` answers what the build needs — a filled slot has a spec file + * to generate a fragment from. This answers what a test needs: the slot exists + * from the moment core declares it at require time, and its position in the + * express stack has to stay findable whether or not a module has filled it. + * Before Phase 3 the two questions had the same answer, because core filled the + * only slot itself. + */ +const declaredSlotRouter = (slot) => (slots.get(slot) || {}).router || null + // ── Notification streams (§1.8) ──────────────────────────────────────────── /** The whole catalog, core's entries first, in registration order. */ @@ -130,6 +148,43 @@ const isValidStream = (id) => streamOwners.has(id) /** Ids of the owner-keyed streams — those needing a linked game account. */ const personalStreams = () => new Set(streams.filter((s) => s.personal).map((s) => s.id)) +// ── Post hooks (§1.8) ────────────────────────────────────────────────────── + +// Core's CMS is the only writer of posts, and a module may need to mirror one +// somewhere core knows nothing about — module-uo keeps UO's in-game Town Cryer +// News gump in step with it. Before this existed, core's post controller +// required `utils/newsGump` directly, which is precisely the coupling the +// extraction had to remove: core's publish path naming a UO file. +// +// It is deliberately NOT folded into `registerAnnounceLeg`, which fires on the +// same transition. A leg is a one-shot DELIVERY with retry and classification; +// a post hook maintains idempotent STATE, has to run on delete as well as save, +// and refreshes silently on an edit. Overloading the leg would have meant a +// dispatch that must not be retried and a classify that means nothing. + +/** Every registered hook, in registration order. */ +const postHookEntries = () => [...postHooks.entries()].map(([owner, h]) => ({ owner, ...h })) + +/** + * Fire `event` at every registered hook, one at a time, never throwing. + * + * Best-effort by contract, and awaited rather than fired-and-forgotten: core's + * own call site awaited `newsGump.syncPost` before this existed, so a save that + * returns 200 still means the mirror was attempted. One subscriber's failure + * must not cost another's, and none of them may cost the save — a sidecar + * hiccup breaking a post edit would be a worse bug than a stale gump. + */ +async function dispatchPostHook(event, payload) { + for (const { owner, [event]: fn } of postHookEntries()) { + if (typeof fn !== 'function') continue + try { + await fn(payload) + } catch (err) { + log.warn('post hook failed', { owner, event, message: err.message }) + } + } +} + // ── Announce legs (§1.8) ─────────────────────────────────────────────────── /** Every registered leg, in registration order. */ @@ -170,6 +225,22 @@ function checkLegShape(entry) { return { leg, label: label || leg, dispatch, classify } } +/** + * `registerPostHook({ onSaved, onDeleted })` — both optional, at least one + * required. A registration with neither is a subscription that can never fire, + * which is a typo rather than an intention. + */ +function checkPostHookShape(entry) { + const { onSaved, onDeleted } = entry || {} + for (const [name, fn] of [['onSaved', onSaved], ['onDeleted', onDeleted]]) { + if (fn !== undefined && typeof fn !== 'function') { + throw new Error(`registerPostHook: ${name} must be a function`) + } + } + if (!onSaved && !onDeleted) throw new Error('registerPostHook: needs onSaved or onDeleted') + return { onSaved, onDeleted } +} + // `specFile` is CORE-ONLY and is not on the module-facing signature. A slot's // router reaches the app through declareSlot(), which no static parse of app.js // can follow, so swagger-autogen would silently drop every route in it — the @@ -194,7 +265,7 @@ function checkExtensionShape(slot, router, specFile) { * `allStreams()` / `announceLeg()` / the slot routers until `apply()`. */ function stage(owner) { - const staged = { owner, streams: [], legs: [], extensions: [] } + const staged = { owner, streams: [], legs: [], extensions: [], postHooks: [] } return { staged, registerNotificationStreams(entries) { @@ -207,6 +278,9 @@ function stage(owner) { registerExtension(slot, router, specFile) { staged.extensions.push(checkExtensionShape(slot, router, specFile)) }, + registerPostHook(entry) { + staged.postHooks.push(checkPostHookShape(entry)) + }, } } @@ -219,7 +293,7 @@ function stage(owner) { * PR 2 learned to protect (mounting inside the scan loop made every collision * look like it was with core). */ -function apply({ owner, streams: newStreams, legs: newLegs, extensions: newExtensions }) { +function apply({ owner, streams: newStreams, legs: newLegs, extensions: newExtensions, postHooks: newPostHooks = [] }) { // ── validate ── const seenStreams = new Set() for (const s of newStreams) { @@ -253,6 +327,11 @@ function apply({ owner, streams: newStreams, legs: newLegs, extensions: newExten seenSlots.add(x.slot) } + if (newPostHooks.length > 1) throw new Error(`"${owner}" registered more than one post hook`) + if (newPostHooks.length && postHooks.has(owner)) { + throw new Error(`"${owner}" already registered a post hook`) + } + // ── commit — nothing below can fail ── for (const s of newStreams) { streamOwners.set(s.id, owner) @@ -265,6 +344,7 @@ function apply({ owner, streams: newStreams, legs: newLegs, extensions: newExten entry.specFile = x.specFile entry.router.use(x.router) } + for (const h of newPostHooks) postHooks.set(owner, h) } // ── Core's own registrations ─────────────────────────────────────────────── @@ -286,25 +366,18 @@ function registerCore() { /* eslint-disable global-require */ const coreStreams = require('../config/coreStreams') const discordLeg = require('../utils/discordAnnounce') - const shardStreams = require('../config/shardStreams') - const townCrierLeg = require('../utils/shardAnnounce') - const shardExtension = require('../router/v1/admin/usersShard.router') /* eslint-enable global-require */ const api = stage('core') api.registerNotificationStreams(coreStreams.STREAMS) api.registerAnnounceLeg(discordLeg.leg) - // ── Phase 3 boundary ──────────────────────────────────────────────────── - // These three lines become module-uo's register() body, with 'core' becoming - // 'uo'. Nothing else in core has to change for that to happen — which is the - // whole claim PR 4 is making. - api.registerNotificationStreams(shardStreams.STREAMS) - api.registerAnnounceLeg(townCrierLeg.leg) - // The third argument is core-only and has no module counterpart — see - // checkExtensionShape. A module ships a prebuilt swagger-fragment.json instead. - api.registerExtension('admin.users.detail', shardExtension, require.resolve('../router/v1/admin/usersShard.router')) - + // The three lines that used to follow — the shard stream catalog, the town + // crier leg and the `admin.users.detail` filling — were shard CONTENT held + // here so the seam would be exercised on every boot before a module first used + // it. Phase 3 moved them into module-uo's `register()` verbatim, with 'core' + // becoming 'uo', and nothing else in core changed. That was the claim PR 4 + // made, and this deletion is it being collected. apply(api.staged) coreRegistered = true @@ -336,6 +409,7 @@ function _reset() { streams.length = 0 streamOwners.clear() legs.clear() + postHooks.clear() coreRegistered = false } @@ -344,12 +418,15 @@ module.exports = { hasSlot, slotFilledBy, filledSlots, + declaredSlotRouter, allStreams, isValidStream, personalStreams, announceLegs, announceLegIds, announceLeg, + postHookEntries, + dispatchPostHook, stage, apply, registerCore, diff --git a/server/src/modules/version.js b/server/src/modules/version.js index 8df4d79..f58c441 100644 --- a/server/src/modules/version.js +++ b/server/src/modules/version.js @@ -9,6 +9,11 @@ // Deliberately separate from PROTOCOL_VERSION (which versions the shard wire and // has nothing to say about a website module) and from any module's own version. -const MODULE_API_VERSION = '1.0.0' +// 1.1.0 — `ctx` gained `activity.log`, `users.getById` and `site.baseUrl`, each +// because module-uo's extraction needed it and none of them could be vendored: +// an admin action a module performs belongs in core's one audit log, the +// extension slot needs the user its prefix names, and §2.7 forbids a module +// reading core's `APP_BASE_URL` for itself. Additions only, so minor. +const MODULE_API_VERSION = '1.1.0' module.exports = { MODULE_API_VERSION } diff --git a/server/src/router/v1/admin/admin.controller.js b/server/src/router/v1/admin/admin.controller.js index 18f618e..047394a 100644 --- a/server/src/router/v1/admin/admin.controller.js +++ b/server/src/router/v1/admin/admin.controller.js @@ -7,8 +7,8 @@ const users = require('../../../model/users/users.model') const activity = require('../../../model/activity/activity.model') const trustedDevices = require('../../../model/trustedDevices/trustedDevices.model') const recoveryCodes = require('../../../model/recoveryCodes/recoveryCodes.model') +const registries = require('../../../modules/registries') const announceJobs = require('../../../model/announceJobs/announceJobs.model') -const newsGump = require('../../../utils/newsGump') const pushDispatch = require('../../../utils/pushDispatch') const { cleanBody } = require('../../../utils/sanitizeHtml') const { parseJsonSetting } = require('../../../utils/settingsJson') @@ -37,11 +37,13 @@ async function announceIfNewlyPublished(post, transition) { // the single "newly published news" signal for the push too, so we never // double-fire on edits or replicate the transition logic. const jobId = await announceJobs.enqueueIfNeeded(post, transition) - // Keep the in-game Town Cryer News gump in sync with the same transition: push - // the article when it becomes published news, refresh it silently on an edit, - // and pull it when it leaves published-news. Best-effort (never throws), so a - // sidecar hiccup never breaks saving a post — same guarantee as the enqueue. - await newsGump.syncPost(post, transition) + // Tell whoever is listening that a post was saved, and what the transition + // was. Core's CMS is the only writer of posts, and a module may mirror one + // somewhere core knows nothing about — module-uo keeps UO's in-game Town Cryer + // News gump in step this way. Awaited but never throwing, so a subscriber's + // sidecar hiccup cannot break saving a post: the same guarantee the enqueue + // above gives. + await registries.dispatchPostHook('onSaved', { post, transition }) // Opt-in push tickle to news.post subscribers, on the same transition. // Fire-and-forget + self-guarding, so a dead ntfy relay never breaks saving. if (jobId) { @@ -203,8 +205,11 @@ async function deletePost(req, res) { const current = await posts.getById(id) await posts.remove(id) await activity.log({ req, action: 'post.delete', detail: { id } }) - // If it was live in the News gump, pull it (best-effort). - if (newsGump.inGump(current)) await newsGump.removePost(id) + // And that it is gone. A subscriber decides for itself whether it was + // mirroring this one — core does not know, and asking would mean core + // holding a predicate that belongs to the subscriber (`inGump` used to live + // right here, and it was UO's question, not the CMS's). + await registries.dispatchPostHook('onDeleted', { post: current, id }) return res.json({ id }) } catch (err) { return res.status(500).json({ message: 'Internal Server Error' }) diff --git a/server/src/router/v1/admin/shard.router.js b/server/src/router/v1/admin/shard.router.js deleted file mode 100644 index e886647..0000000 --- a/server/src/router/v1/admin/shard.router.js +++ /dev/null @@ -1,386 +0,0 @@ -// Admin · Shard — everything under /api/v1/admin/shard, in two tiers. -// -// Mounted at /api/v1/admin/shard by admin/index.js, which already applied -// `noindex, isLoggedIn, staffOnly`. Two capabilities share this prefix, and -// prefix ownership is the invariant the split preserves — so they share a file: -// -// 1. Self-service game-account linking (no extra gate). A staff member links -// and inspects their OWN in-game account exactly as a player does under -// /player/shard; the handlers are the very same `player/shard.controller` -// ones, keyed off req.user.id. These keep their `Admin · Account` swagger -// tag, which is why the tag disagrees with this filename. -// 2. Privileged live-shard operations and the help-page queue (`modAccess` — -// admin or moderator). `actor` is stamped server-side from the session in -// shardOps.controller.js; the request body never carries it. -// -// `modAccess` stays a per-route gate rather than a router-level `use`: it was -// per-route in admin.routes.js, and half the routes here must NOT have it. -// -// NOTE: /admin/shard/pages is the in-game help-page (support) queue. It is -// unrelated to /admin/pages, the CMS page builder. - -const express = require('express') -const { body, param } = require('express-validator') - -const shardOps = require('./shardOps.controller') -const shardVisibility = require('./shardVisibility.controller') -const shardAtlas = require('./shardAtlas.controller') -const shardClilocs = require('./shardClilocs.controller') -const selfShard = require('../player/shard.controller') -const { requireRole } = require('../../../utils/auth') -const validate = require('../../../middleware/validate') - -const shardRouter = express.Router() - -// Moderator gate. Admins can do everything a moderator can. -const modAccess = requireRole('admin', 'moderator') -// Admin-only gate, for settings that decide what the PUBLIC sees. -const adminOnly = requireRole('admin') - -// ── Game account linking (self-service, any staff role) ─────────────── -// Staff link their OWN in-game account here, exactly like players do under -// /player/shard. The controller keys off req.user.id, so the same handlers work. -const SHARD_ACCOUNT_RE = /^[A-Za-z0-9_.-]{1,120}$/ -shardRouter.post( - '/link', - // #swagger.tags = ['Admin · Account'] - // #swagger.summary = 'Link an in-game account with a one-time code (self)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkRequest" } } } } */ - /* #swagger.responses[200] = { description: 'Linked', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkResult" } } } } */ - /* #swagger.responses[400] = { description: 'Unknown or expired code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - body('code').isString().trim().isLength({ min: 4, max: 32 }), - validate, - selfShard.link, -) -shardRouter.get( - '/accounts', - // #swagger.tags = ['Admin · Account'] - // #swagger.summary = 'List the caller’s linked game accounts (self)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'Linked accounts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardLink" } } } } } */ - selfShard.listAccounts, -) -shardRouter.get( - '/roster/:account', - // #swagger.tags = ['Admin · Account'] - // #swagger.summary = 'Character roster for an account (self; admins: any account)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' } - /* #swagger.responses[200] = { description: 'Account roster', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('account').matches(SHARD_ACCOUNT_RE), - validate, - selfShard.roster, -) -shardRouter.get( - '/vendors/:account', - // #swagger.tags = ['Admin · Account'] - // #swagger.summary = 'Player vendors for an account (self; admins: any account)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' } - /* #swagger.responses[200] = { description: 'Vendor snapshot', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('account').matches(SHARD_ACCOUNT_RE), - validate, - selfShard.vendors, -) -shardRouter.get( - '/char/:serial', - // #swagger.tags = ['Admin · Account'] - // #swagger.summary = 'Character sheet (self-linked characters; admins: any character)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['serial'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Mobile serial, e.g. 0x24C.' } - /* #swagger.responses[200] = { description: 'Character profile', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[403] = { description: 'Character not on an account linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('serial').matches(/^0x[0-9a-fA-F]+$/), - validate, - selfShard.getChar, -) -shardRouter.get( - '/sales', - // #swagger.tags = ['Admin · Account'] - // #swagger.summary = 'Recent player-vendor sales for the caller’s linked accounts (self)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'Vendor sales', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardVendorSale" } } } } } */ - selfShard.getSales, -) -shardRouter.post( - '/account', - // #swagger.tags = ['Admin · Account'] - // #swagger.summary = 'Create a game account and link it to the caller (staff self-service)' - // #swagger.description = 'Same as POST /player/shard/account but for a signed-in staff user — provisions a game account (own username + password) and links it. Gated by game_account_signup + the shard’s mode; the password is never stored or logged.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["account","password"], properties: { account: { type: "string" }, password: { type: "string" } } } } } */ - /* #swagger.responses[201] = { description: 'Account created and linked', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[403] = { description: 'Game-account signup unavailable (site or shard)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[409] = { description: 'Account name already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - body('account').matches(/^[A-Za-z0-9][A-Za-z0-9_.-]{2,29}$/), - body('password').isString().isLength({ min: 8, max: 64 }), - validate, - selfShard.createGameAccount, -) - -// ── In-game staff operations (uo-link write plane + support queue) ───── -// Privileged live-shard actions and the help-page queue, open to moderators as -// well as admins (modAccess). `actor` is stamped server-side from the session in -// the controller — the body never carries it. See shardOps.controller.js. -shardRouter.post( - '/kick', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Kick every live session of an account (admin/moderator)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" }, serial: { type: "string" } } } } } } */ - /* #swagger.responses[200] = { description: 'Kicked', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[403] = { description: 'Protected target or write plane disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - modAccess, - body('account').optional({ values: 'falsy' }).matches(SHARD_ACCOUNT_RE), - body('serial').optional({ values: 'falsy' }).matches(/^0x[0-9a-fA-F]+$/), - validate, - shardOps.kick, -) -shardRouter.post( - '/ban', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Ban an account, timed or indefinite (admin/moderator)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" }, serial: { type: "string" }, durationSec: { type: "integer" }, reason: { type: "string" } } } } } } */ - /* #swagger.responses[200] = { description: 'Banned', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[403] = { description: 'Protected target or write plane disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - modAccess, - body('account').optional({ values: 'falsy' }).matches(SHARD_ACCOUNT_RE), - body('serial').optional({ values: 'falsy' }).matches(/^0x[0-9a-fA-F]+$/), - body('durationSec').optional().isInt({ min: 0, max: 315360000 }), - body('reason').optional({ values: 'falsy' }).isString().trim().isLength({ max: 500 }), - validate, - shardOps.ban, -) -shardRouter.post( - '/unban', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Clear an account ban (admin/moderator)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" } }, required: ["account"] } } } } */ - /* #swagger.responses[200] = { description: 'Unbanned', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - modAccess, - body('account').matches(SHARD_ACCOUNT_RE), - validate, - shardOps.unban, -) -shardRouter.post( - '/broadcast', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Broadcast a system message to everyone online (admin/moderator)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { text: { type: "string" }, hue: { type: "integer" } }, required: ["text"] } } } } */ - /* #swagger.responses[200] = { description: 'Broadcast', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - modAccess, - body('text').isString().trim().isLength({ min: 1, max: 300 }), - body('hue').optional().isInt({ min: 0, max: 3000 }), - validate, - shardOps.broadcast, -) -shardRouter.get( - '/pages', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Open help-page (support) queue (admin/moderator)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'Open pages', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */ - modAccess, - shardOps.listPages, -) -shardRouter.post( - '/pages/:id/respond', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Reply to a help page, optionally closing it (admin/moderator)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Page id (sender serial).' } - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { message: { type: "string" }, close: { type: "boolean" } }, required: ["message"] } } } } */ - /* #swagger.responses[200] = { description: 'Responded', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[404] = { description: 'Unknown page', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - modAccess, - param('id').matches(/^0x[0-9a-fA-F]+$/), - body('message').isString().trim().isLength({ min: 1, max: 500 }), - body('close').optional().isBoolean(), - validate, - shardOps.respondPage, -) -shardRouter.post( - '/pages/:id/close', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Resolve a help page without a reply (admin/moderator)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Page id (sender serial).' } - /* #swagger.responses[200] = { description: 'Closed', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - modAccess, - param('id').matches(/^0x[0-9a-fA-F]+$/), - validate, - shardOps.closePage, -) -shardRouter.get( - '/audit', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Recent in-game moderation audit events (admin/moderator)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'admin.audit events, newest first', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardEvent" } } } } } */ - modAccess, - shardOps.listAudit, -) -shardRouter.get( - '/houses', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Full house registry — owner, price, decay (admin/moderator)' - // #swagger.description = 'The complete house registry. The public endpoint shows only IDOC houses with location; this staff view carries owner/price/co-owner/decay detail.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'Houses, ordered by name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */ - modAccess, - shardOps.listHouses, -) - -// ── Spawn atlas (admin only) ────────────────────────────────────────── -// Operating the atlas import. Admin-only rather than moderator: it reads a path -// on the server's filesystem and replaces every atlas table, which is closer to -// a deploy action than to moderation. -// -// These routes sit under /admin/shard even though the public ones deliberately -// do NOT sit under /public/shard. That is not an inconsistency: the public split -// says "this data does not come from the sidecar", while the admin panel is -// simply part of shard administration and belongs beside the rest of it. -shardRouter.get( - '/atlas', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Spawn atlas status: path, drift, counts, pending review (admin only)' - // #swagger.description = 'Where the ServUO tree is, whether it can be read, whether its source files have drifted from the loaded atlas, and any refresh staged for approval. The public /atlas/meta route reports the game world only; the filesystem detail is here.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'Atlas status', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasStatus" } } } } */ - /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - adminOnly, - shardAtlas.getStatus, -) -shardRouter.post( - '/atlas/import', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Re-import the spawn atlas from the ServUO tree (admin only)' - // #swagger.description = 'Applies a map change without a restart. `force` reimports even when the source hashes match what is loaded. A refresh that would REMOVE a facet is still staged for approval rather than applied — that decision is never taken implicitly. An unreadable tree answers 200 with status "unavailable" rather than 500: the refresh contract reports outcomes instead of throwing, and the admin needs to be told what is wrong with the path.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: false, content: { "application/json": { schema: { type: "object", properties: { force: { type: "boolean", description: "Reimport even if the tree is unchanged." } } } } } } */ - /* #swagger.responses[200] = { description: 'What happened', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasRefreshResult" } } } } */ - adminOnly, - body('force').optional().isBoolean(), - validate, - shardAtlas.importAtlas, -) -shardRouter.post( - '/atlas/approve', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Approve a staged atlas refresh that removes a facet (admin only)' - // #swagger.description = 'Re-parses the tree and applies it, facet loss included. Only the decision was stored, never the parsed world, so what lands matches the tree at approval time — an operator who has since fixed a half-copied mount gets the corrected import.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'What happened', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasRefreshResult" } } } } */ - adminOnly, - shardAtlas.approve, -) -shardRouter.post( - '/atlas/reject', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Reject a staged atlas refresh (admin only)' - // #swagger.description = 'Keeps the current atlas and remembers the decision against those exact source hashes, so a declined refresh does not re-prompt on every restart. Changing the tree asks again.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'Rejected', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasRefreshResult" } } } } */ - /* #swagger.responses[404] = { description: 'Nothing is awaiting review', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - adminOnly, - shardAtlas.reject, -) -shardRouter.put( - '/atlas/path', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Set the ServUO tree the atlas reads from (admin only)' - // #swagger.description = 'Persisted as a setting, which wins over the SERVUO_PATH deploy default so the mount can move without a redeploy. Blank clears it and the atlas is simply skipped on the next boot. Deliberately does not import as a side effect — the response carries the refreshed status so the panel can offer that as the next step.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["path"], properties: { path: { type: "string", description: "Absolute path to the ServUO server root. Blank disables the atlas." } } } } } } */ - /* #swagger.responses[200] = { description: 'Atlas status after the change', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasStatus" } } } } */ - adminOnly, - body('path').isString().isLength({ max: 512 }), - validate, - shardAtlas.setPath, -) - -// ── Cliloc table (admin only) ───────────────────────────────────────────── -// UO's id → display-string map, converted once by the operator from their own -// client (docs/website/CLILOCS.md). Sits beside the atlas for the same reason: -// it is static content derived from operator-supplied files rather than anything -// the sidecar sends, and operating it is shard administration. -// -// There is deliberately NO public counterpart. The table is never served as a -// table — 123k rows would dwarf any page that used it, and the Android client -// consumes the same already-resolved JSON. Names are applied server-side to the -// responses that need them. -shardRouter.get( - '/clilocs', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Cliloc table status: sources, drift, entry count (admin only)' - // #swagger.description = 'Where the cliloc sources are, whether they can be read, how many entries are loaded, and whether the files on disk have drifted from them. The table is built from a SET of sources — the converted client table plus every operator-maintained overlay under `custom/`, which is how shard-added and shard-edited items get names. `missingSources` lists any source that was loaded before and is now gone; an import refuses that without `approve`. A shard with nothing configured is a supported state — item names simply render as ids.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'Cliloc status', content: { "application/json": { schema: { $ref: "#/components/schemas/ClilocStatus" } } } } */ - /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - adminOnly, - shardClilocs.getStatus, -) -shardRouter.post( - '/clilocs/import', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Re-import the cliloc table from its source files (admin only)' - // #swagger.description = 'Applies a client patch, or a change to the shard\'s own overlay files, without a restart. `force` reimports even when the source hashes match what is loaded. `approve` accepts a refresh in which a previously-loaded source has VANISHED — refused by default, because an unmounted volume and a deliberate deletion are indistinguishable from the server, and the wrong guess silently drops every name that file contributed. A missing path — or the common mistake of pointing at the client\'s own COMPRESSED Cliloc.enu — answers 200 with status "unavailable" and the reason, rather than 500: the refresh contract reports outcomes instead of throwing, and the admin needs to be told which file to convert.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: false, content: { "application/json": { schema: { type: "object", properties: { force: { type: "boolean", description: "Reimport even if the sources are unchanged." }, approve: { type: "boolean", description: "Accept a refresh in which a previously-loaded source has vanished." } } } } } } */ - /* #swagger.responses[200] = { description: 'What happened', content: { "application/json": { schema: { $ref: "#/components/schemas/ClilocRefreshResult" } } } } */ - adminOnly, - body('force').optional().isBoolean(), - body('approve').optional().isBoolean(), - validate, - shardClilocs.importClilocs, -) -shardRouter.put( - '/clilocs/path', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Set the cliloc source the site reads from (admin only)' - // #swagger.description = 'Accepts either the converted base file itself or a directory to search. Overlays are read from a `custom/` directory beside it either way — pointing at a file does not forfeit them. Persisted as a setting, which wins over the UO_CLIENT_PATH deploy default so the mount can move without a redeploy. Blank clears it and resolution is skipped on the next boot. Deliberately does not import as a side effect — the response carries the refreshed status so the panel can offer that as the next step.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["path"], properties: { path: { type: "string", description: "Path to the converted cliloc file, or a directory containing one. Blank disables resolution." } } } } } } */ - /* #swagger.responses[200] = { description: 'Cliloc status after the change', content: { "application/json": { schema: { $ref: "#/components/schemas/ClilocStatus" } } } } */ - adminOnly, - body('path').isString().isLength({ max: 512 }), - validate, - shardClilocs.setPath, -) - -// ── Feature visibility (admin only) ─────────────────────────────────── -// Who can see which shard surface, and which sensitive fields within it. This -// decides what ANONYMOUS visitors get, so it sits above the moderator tier. -shardRouter.get( - '/visibility', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Get per-feature shard visibility config (admin only)' - // #swagger.description = 'The effective config (compiled defaults merged with stored overrides) plus the vocabulary the admin UI renders from: the audience ladder and the always-locked fields. Defaults reproduce pre-v3 behavior.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'Visibility config', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardVisibilityConfig" } } } } */ - /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - adminOnly, - shardVisibility.getVisibility, -) -shardRouter.put( - '/visibility', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Update per-feature shard visibility config (admin only)' - // #swagger.description = 'Patch one or more features. Unknown feature names, unknown rungs, and any attempt to configure a locked field (acct / webId — admin-only always) are rejected with 400 rather than silently dropped.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ShardVisibilityUpdate" } } } } */ - /* #swagger.responses[200] = { description: 'Updated config', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardVisibilityConfig" } } } } */ - /* #swagger.responses[400] = { description: 'Unknown feature, rung, or a locked field', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - adminOnly, - body('features').isObject(), - validate, - shardVisibility.putVisibility, -) - -module.exports = shardRouter diff --git a/server/src/router/v1/admin/shardAtlas.controller.js b/server/src/router/v1/admin/shardAtlas.controller.js deleted file mode 100644 index b674673..0000000 --- a/server/src/router/v1/admin/shardAtlas.controller.js +++ /dev/null @@ -1,117 +0,0 @@ -// ── Admin · Spawn atlas ──────────────────────────────────────────────────── -// -// Operating the atlas import: where the ServUO tree is, whether it has drifted -// from what is loaded, and the approve/reject decision for a refresh that would -// remove a facet (docs/website/SPAWN_ATLAS.md). -// -// The policy lives in the model. This controller does three things and no more: -// it validates input, it maps a refresh RESULT onto an HTTP status, and it -// records the action in the admin activity log. -// -// **A refresh result is not an exception.** `shardAtlas.refresh()` reports -// `unavailable` / `failed` / `needsReview` rather than throwing, because the boot -// path must never be stopped by a bad tree. That contract is preserved here: an -// unreadable mount is a 200 carrying `status: 'unavailable'`, not a 500. The -// admin needs to be told what is wrong with their path, and a 500 says only -// "something broke". - -const atlas = require('../../../model/shardAtlas/shardAtlas.model') -const activity = require('../../../model/activity/activity.model') - -const log = require('../../../utils/logger')('admin-shard-atlas') - -// GET /admin/shard/atlas — what is loaded, what the tree looks like, what is -// staged. Unlike the public /atlas/meta route this DOES carry the filesystem -// path and the drift flag: that is the whole point of the panel. -async function getStatus(req, res) { - try { - return res.json(await atlas.status()) - } catch (err) { - log.error('getStatus', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// POST /admin/shard/atlas/import — apply a map change without a restart. -// -// `force` reimports even when the source hashes match what is loaded (the escape -// hatch for "the database is wrong but the tree is not"). Facet loss is still -// staged rather than applied — approving is a separate, explicit act. -async function importAtlas(req, res) { - try { - const force = !!req.body?.force - const result = await atlas.refresh({ force }) - await activity.log({ - req, - action: 'shard.atlas.import', - detail: { force, status: result.status, counts: result.counts ?? null }, - }) - return res.json(result) - } catch (err) { - log.error('importAtlas', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// POST /admin/shard/atlas/approve — apply a staged refresh, facet loss and all. -// -// Re-parses the tree rather than applying something captured at boot: only the -// DECISION was stored, so what lands matches the tree as it is now. If the -// operator has since fixed a half-copied mount, the approved import is simply -// the corrected one — which is the desired outcome, not a surprise. -async function approve(req, res) { - try { - const result = await atlas.approvePending() - await activity.log({ - req, - action: 'shard.atlas.approve', - detail: { status: result.status, removed: result.removedFacets ?? null }, - }) - return res.json(result) - } catch (err) { - log.error('approveAtlas', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// POST /admin/shard/atlas/reject — keep the current atlas and remember the -// decision against those exact source hashes, so a declined refresh does not -// re-prompt on every restart. Changing the tree asks again. -async function reject(req, res) { - try { - const result = await atlas.rejectPending() - if (result.status === 'none') { - return res.status(404).json({ message: 'No refresh is awaiting review.' }) - } - await activity.log({ req, action: 'shard.atlas.reject', detail: {} }) - return res.json(result) - } catch (err) { - log.error('rejectAtlas', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// PUT /admin/shard/atlas/path — point the atlas at a different ServUO tree. -// -// Persisted as a setting, which wins over the SERVUO_PATH env default so an -// operator can move the mount without a redeploy. Blank clears it, which turns -// the atlas off (boot skips, the loaded atlas keeps serving) — that is a -// legitimate thing to want, so it is allowed rather than validated away. -// -// Deliberately does NOT import as a side effect: changing where the atlas reads -// from and reloading it are separate decisions, and an operator fixing a typo -// should not have a multi-thousand-row replace happen under them. The response -// carries the refreshed status so the panel can offer the import immediately. -async function setPath(req, res) { - try { - const value = String(req.body?.path ?? '').trim() - await atlas.setServuoPath(value, req.user?.id ?? null) - await activity.log({ req, action: 'shard.atlas.path', detail: { path: value } }) - return res.json(await atlas.status()) - } catch (err) { - log.error('setAtlasPath', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -module.exports = { getStatus, importAtlas, approve, reject, setPath } diff --git a/server/src/router/v1/admin/shardClilocs.controller.js b/server/src/router/v1/admin/shardClilocs.controller.js deleted file mode 100644 index 2ecf4a3..0000000 --- a/server/src/router/v1/admin/shardClilocs.controller.js +++ /dev/null @@ -1,106 +0,0 @@ -// ── Admin · Cliloc table ─────────────────────────────────────────────────── -// -// Operating the cliloc import: where the converted cliloc file is, whether it -// has drifted from what is loaded, and a forced reimport after a client patch -// (docs/website/CLILOCS.md). -// -// The policy lives in the model. This controller does three things and no more: -// it validates input, it maps a refresh RESULT onto an HTTP status, and it -// records the action in the admin activity log. -// -// **A refresh result is not an exception.** `shardClilocs.refresh()` reports -// `unavailable` / `failed` rather than throwing, because the boot path must never -// be stopped by a bad file. That contract is preserved here: a missing file, or -// the single most likely operator mistake — pointing at the client's own -// COMPRESSED `Cliloc.enu` — is a 200 carrying `status: 'unavailable'` and the -// reason, not a 500. A 500 would say only "something broke"; the operator needs -// to be told which file to convert. - -const clilocs = require('../../../model/shardClilocs/shardClilocs.model') -const market = require('../../../model/shardMarket/shardMarket.model') -const activity = require('../../../model/activity/activity.model') - -const log = require('../../../utils/logger')('admin-shard-clilocs') - -// GET /admin/shard/clilocs — what is loaded, what the file looks like, whether -// they disagree. There is no public counterpart: the cliloc table is never -// served as a table, only applied to names the site already returns. -async function getStatus(req, res) { - try { - return res.json(await clilocs.status()) - } catch (err) { - log.error('getStatus', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// POST /admin/shard/clilocs/import — reload after a client patch or a change to -// the shard's own overlay files, without a restart. -// -// `force` reimports even when the source hashes match what is loaded (the escape -// hatch for "the database is wrong but the files are not"). -// -// `approve` accepts a refresh in which a previously-loaded source has VANISHED. -// That is refused by default because an unmounted volume and a deliberate -// deletion look identical from the server — the lighter cousin of the atlas's -// approve/reject flow, and the reason it can be a flag here rather than a -// pending table is that nothing is stored to approve: the import re-reads the -// files at approval time by construction. -async function importClilocs(req, res) { - try { - const force = !!req.body?.force - const approve = !!req.body?.approve - const result = await clilocs.refresh({ force, approve }) - - // The marketplace denormalizes resolved item names into - // shard_vendor_items.display_name, and the shard's market sweep will NOT - // re-send an unchanged shop just because the site learned what its items are - // called — so without this pass, an operator who imports clilocs after the - // first sweep keeps seeing item ids until every shop happens to change. - // Awaited (rather than fired and forgotten) so the panel's "imported" is - // honest about the names being live; the pass is a bounded walk of one table - // and never throws. - if (result.status === 'imported') await market.refreshDisplayNames() - - await activity.log({ - req, - action: 'shard.clilocs.import', - detail: { - force, - approve, - status: result.status, - count: result.count ?? null, - missingSources: result.missingSources ?? result.acceptedMissing ?? null, - }, - }) - return res.json(result) - } catch (err) { - log.error('importClilocs', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// PUT /admin/shard/clilocs/path — point the site at a different cliloc file. -// -// Persisted as a setting, which wins over the UO_CLIENT_PATH env default so an -// operator can move the mount without a redeploy. Blank clears it, which turns -// resolution off (boot skips, the loaded table keeps serving) — a legitimate -// thing to want, so it is allowed rather than validated away. -// -// Deliberately does NOT import as a side effect, for the same reason the atlas -// path does not: changing where the table reads from and reloading it are -// separate decisions. The response carries the refreshed status so the panel can -// offer the import immediately. -async function setPath(req, res) { - try { - const value = String(req.body?.path ?? '').trim() - await clilocs.setClientPath(value, req.user?.id ?? null) - await activity.log({ req, action: 'shard.clilocs.path', detail: { path: value } }) - return res.json(await clilocs.status()) - } catch (err) { - log.error('setClilocPath', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -module.exports = { getStatus, importClilocs, setPath } diff --git a/server/src/router/v1/admin/shardOps.controller.js b/server/src/router/v1/admin/shardOps.controller.js deleted file mode 100644 index be7c2a7..0000000 --- a/server/src/router/v1/admin/shardOps.controller.js +++ /dev/null @@ -1,171 +0,0 @@ -// ── Admin: in-game staff operations (uo-link write plane + support queue) ──── -// -// The privileged "write plane" (§6 of the sidecar guide): kick / ban / unban / -// broadcast against the live shard, plus the help-page (support ticket) queue. -// Gated admin+moderator at the route (modAccess) — the sidecar trusts the -// loopback socket, so authorization is entirely the site's responsibility. -// -// SECURITY: `actor` (who is taking the action) is ALWAYS set here from the -// authenticated session (req.user.username), never from the request body, so an -// action can't be attributed to someone else. The shard records it in its console -// log, the ban's BanDealer tag, and the admin.audit event it echoes back. - -const uoLinkClient = require('../../../utils/uoLinkClient') -const shardState = require('../../../model/shardState/shardState.model') -const shardEvents = require('../../../model/shardEvents/shardEvents.model') -const activity = require('../../../model/activity/activity.model') - -const log = require('../../../utils/logger')('admin-shard-ops') - -// Map a never-throw uoLinkClient result onto an HTTP response. `okData` shapes the -// success body. Mirrors the sidecar's documented status codes so the UI can tell a -// transient outage (503/504 — retry) from a real rejection (403/404). -function relay(res, result, okData) { - if (result.ok) return res.json(okData(result.data)) - switch (result.status) { - case 400: - return res.status(400).json({ message: (result.data && result.data.error) || 'The shard rejected that request.' }) - case 403: - return res.status(403).json({ - message: - (result.data && result.data.error) || - 'That action was refused — the target is protected, or the write plane is disabled on the shard.', - }) - case 404: - return res.status(404).json({ message: 'No such account or target on the shard.' }) - case 503: - case 504: - case 0: - return res.status(503).json({ message: 'The shard is unavailable right now — try again shortly.' }) - default: - return res.status(502).json({ message: 'Could not reach the shard.' }) - } -} - -// POST /admin/shard/kick — disconnect every live session of an account (or serial). -async function kick(req, res) { - const { account, serial } = req.body - const actor = req.user.username - try { - const result = await uoLinkClient.adminKick({ actor, account, serial }) - if (result.ok) await activity.log({ req, action: 'shard.kick', detail: { account, serial } }) - return relay(res, result, (d) => d || { ok: true }) - } catch (err) { - log.error('shardOps.kick', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// POST /admin/shard/ban — ban an account (works offline); durationSec 0/absent = indefinite. -async function ban(req, res) { - const { account, serial, durationSec, reason } = req.body - const actor = req.user.username - try { - const result = await uoLinkClient.adminBan({ actor, account, serial, durationSec, reason }) - if (result.ok) await activity.log({ req, action: 'shard.ban', detail: { account, serial, durationSec, reason } }) - return relay(res, result, (d) => d || { ok: true }) - } catch (err) { - log.error('shardOps.ban', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// POST /admin/shard/unban — clear an account's ban. -async function unban(req, res) { - const { account } = req.body - const actor = req.user.username - try { - const result = await uoLinkClient.adminUnban({ actor, account }) - if (result.ok) await activity.log({ req, action: 'shard.unban', detail: { account } }) - return relay(res, result, (d) => d || { ok: true }) - } catch (err) { - log.error('shardOps.unban', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// POST /admin/shard/broadcast — a system message to everyone online. -async function broadcast(req, res) { - const { text, hue } = req.body - const actor = req.user.username - try { - const result = await uoLinkClient.adminBroadcast({ actor, text, hue }) - if (result.ok) await activity.log({ req, action: 'shard.broadcast', detail: { text } }) - return relay(res, result, (d) => d || { ok: true }) - } catch (err) { - log.error('shardOps.broadcast', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /admin/shard/pages — the open help-page (support) queue, from our store. -async function listPages(req, res) { - try { - return res.json(await shardState.listPages()) - } catch (err) { - log.error('shardOps.listPages', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// POST /admin/shard/pages/:id/respond — reply to a player (optionally close). -async function respondPage(req, res) { - const { id } = req.params - const { message, close } = req.body - try { - const result = await uoLinkClient.respondPage(id, { message, close: Boolean(close) }) - if (result.ok) { - await activity.log({ req, action: 'shard.page.respond', detail: { pageId: id, close: Boolean(close) } }) - // Close removes the page from the queue; reflect it locally at once (the - // page.closed event will confirm it, but the UI shouldn't wait a poll cycle). - if (close) await shardState.removePage(id).catch(() => {}) - } - return relay(res, result, (d) => d || { ok: true }) - } catch (err) { - log.error('shardOps.respondPage', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// POST /admin/shard/pages/:id/close — resolve a page without a reply. -async function closePage(req, res) { - const { id } = req.params - try { - const result = await uoLinkClient.closePage(id) - if (result.ok) { - await activity.log({ req, action: 'shard.page.close', detail: { pageId: id } }) - await shardState.removePage(id).catch(() => {}) - } - return relay(res, result, (d) => d || { ok: true }) - } catch (err) { - log.error('shardOps.closePage', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /admin/shard/audit — recent moderation audit events (admin.audit), from the -// ingested event log. Seeds the live audit log the panel keeps current over SSE. -async function listAudit(req, res) { - try { - const limit = req.query.limit - return res.json(await shardEvents.list({ kind: 'admin.audit', limit })) - } catch (err) { - log.error('shardOps.listAudit', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /admin/shard/houses — the FULL house registry (owner, price, co-owners, -// decay), staff-only (modAccess). The public /public/shard/houses shows only IDOC -// houses with location; this is the complete board, kept live for staff on the -// admin SSE channel (house.update / house.remove). -async function listHouses(req, res) { - try { - return res.json(await shardState.listHouses()) - } catch (err) { - log.error('shardOps.listHouses', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -module.exports = { kick, ban, unban, broadcast, listPages, respondPage, closePage, listAudit, listHouses } diff --git a/server/src/router/v1/admin/shardVisibility.controller.js b/server/src/router/v1/admin/shardVisibility.controller.js deleted file mode 100644 index eab2bd6..0000000 --- a/server/src/router/v1/admin/shardVisibility.controller.js +++ /dev/null @@ -1,98 +0,0 @@ -// ── Admin · Shard visibility ─────────────────────────────────────────────── -// -// Read/write the per-feature audience config that gates every shard-derived -// surface. Admin-only: this decides what anonymous visitors can see, so it is -// not part of the moderator tier. -// -// The policy itself (the ladder, the feature catalog, which fields are locked) -// lives in utils/shardVisibility.js. This controller only validates input -// against that policy and persists it. - -const model = require('../../../model/shardVisibility/shardVisibility.model') -const visibility = require('../../../utils/shardVisibility') -const log = require('../../../utils/logger')('admin-shard-visibility') - -// GET /admin/shard/visibility — the effective config (defaults merged with any -// stored overrides), plus the vocabulary the admin UI needs to render itself: -// the ladder, and which fields each feature exposes as configurable. -async function getVisibility(req, res) { - try { - const config = await visibility.getConfig() - return res.json({ - ladder: visibility.LADDER, - lockedFields: Object.keys(visibility.LOCKED_FIELDS), - defaults: visibility.compileDefaults(), - features: config, - }) - } catch (err) { - log.error('getVisibility', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// PUT /admin/shard/visibility — replace the settings for one or more features. -// Body: { features: { : { enabled, audience, stream, fieldRules } } } -// -// Rejects unknown feature names, unknown rungs, and any attempt to configure a -// locked field — a 400 rather than a silent drop, so an admin who tries to make -// `acct` public learns that it is not negotiable. -async function putVisibility(req, res) { - try { - const incoming = req.body?.features - if (!incoming || typeof incoming !== 'object' || Array.isArray(incoming)) { - return res.status(400).json({ message: 'features object required' }) - } - - const entries = [] - for (const [name, patch] of Object.entries(incoming)) { - if (!visibility.isFeature(name)) { - return res.status(400).json({ message: `Unknown feature: ${name}` }) - } - if (!patch || typeof patch !== 'object' || Array.isArray(patch)) { - return res.status(400).json({ message: `Invalid settings for ${name}` }) - } - if (patch.audience != null && !visibility.isLevel(patch.audience)) { - return res.status(400).json({ message: `Unknown audience for ${name}: ${patch.audience}` }) - } - - const fieldRules = {} - for (const [field, level] of Object.entries(patch.fieldRules || {})) { - // Matches flattened spellings too (`ownerAcct`, `leaderWebId`), so the - // rejection covers every way the field can be named rather than the two - // canonical keys. - if (visibility.isLockedField(field)) { - return res.status(400).json({ message: `Field '${field}' is admin-only and cannot be configured` }) - } - if (!visibility.isLevel(level)) { - return res.status(400).json({ message: `Unknown rung for ${name}.${field}: ${level}` }) - } - fieldRules[field] = level - } - - const current = (await visibility.getConfig())[name] - entries.push({ - feature: name, - enabled: patch.enabled == null ? current.enabled : !!patch.enabled, - audience: patch.audience ?? current.audience, - stream: patch.stream == null ? current.stream : !!patch.stream, - fieldRules, - updatedBy: req.user?.id ?? null, - }) - } - - for (const entry of entries) await model.upsert(entry) - visibility.invalidate() - - log.info('shard visibility updated', { - by: req.user?.id, - features: entries.map((e) => e.feature), - }) - - return res.json({ features: await visibility.getConfig() }) - } catch (err) { - log.error('putVisibility', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -module.exports = { getVisibility, putVisibility } diff --git a/server/src/router/v1/admin/uoLink.controller.js b/server/src/router/v1/admin/uoLink.controller.js deleted file mode 100644 index 04d89be..0000000 --- a/server/src/router/v1/admin/uoLink.controller.js +++ /dev/null @@ -1,123 +0,0 @@ -// ── Admin: uo-link sidecar control ───────────────────────────────────────── -// -// Configure the connection to the uo-link sidecar (base/ws URL, shared-secret -// token, protocol pin, enabled) and drive the town crier. SECURITY: the token -// is write-only over this API — stored encrypted, NEVER returned; responses -// expose only `hasToken` (same convention as the Discord bot token). Saving -// (re)starts the WS ingest client so a change takes effect with no redeploy. - -const uoLinkConfig = require('../../../model/uoLinkConfig/uoLinkConfig.model') -const uoLinkClient = require('../../../utils/uoLinkClient') -const uoLinkSocket = require('../../../utils/uoLinkSocket') -const shardBroadcast = require('../../../utils/shardBroadcast') -const activity = require('../../../model/activity/activity.model') - -const log = require('../../../utils/logger')('admin-uolink') - -// Assemble the masked config + live health + ingestion stats for the panel. -async function buildStatus() { - const config = await uoLinkConfig.getSafe() - const health = await uoLinkClient.health() - return { - ...config, - health: health.ok ? health.data : { ok: false, error: health.error || `status ${health.status}` }, - ingest: uoLinkSocket.getState(), - sse: shardBroadcast.stats(), - } -} - -// GET /admin/uo-link/config — masked config + live status + ingestion stats. -async function getConfig(req, res) { - try { - return res.json(await buildStatus()) - } catch (err) { - log.error('uoLink.getConfig', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// PUT /admin/uo-link/config — save connection settings + (re)start the socket. -async function saveConfig(req, res) { - const { baseUrl, wsUrl, token, protocol, enabled } = req.body - try { - const current = await uoLinkConfig.getSafe() - const willHaveToken = Boolean(token) || current.hasToken - if (enabled && !willHaveToken) { - return res.status(400).json({ message: 'An auth token is required before enabling.' }) - } - - await uoLinkConfig.save({ - baseUrl, - wsUrl, - token, - protocol: protocol !== undefined ? Number(protocol) : undefined, - enabled, - updatedBy: req.user.id, - }) - // Drop the client's cached config so the health check below uses the new values. - uoLinkClient.invalidateConfig() - - // (Re)start or stop the ingest socket to match the new enabled/URL/token. - const saved = await uoLinkConfig.getSafe() - if (saved.enabled && saved.hasToken) { - await uoLinkSocket.start() - } else { - uoLinkSocket.stop() - await uoLinkConfig.recordStatus({ status: 'disconnected', pluginConnected: false }) - } - - await activity.log({ req, action: 'uoLink.config.update', detail: { baseUrl: saved.baseUrl, enabled: saved.enabled } }) - log.info('uo-link config updated', { by: req.user.username, enabled: saved.enabled }) - return res.json(await buildStatus()) - } catch (err) { - log.error('uoLink.saveConfig', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// POST /admin/uo-link/towncrier — publish/replace a town-crier message. -async function postTownCrier(req, res) { - const { id, lines, durationSec } = req.body - try { - const result = await uoLinkClient.postTownCrier({ id, lines, durationSec }) - if (result.ok) { - await activity.log({ req, action: 'uoLink.towncrier.post', detail: { id } }) - return res.json(result.data || { ok: true, id }) - } - if (result.status === 400) return res.status(400).json({ message: 'The shard rejected that message (over the line/duration caps?).' }) - if (result.status === 503 || result.status === 0) { - return res.status(503).json({ message: 'The shard is unavailable right now.' }) - } - return res.status(502).json({ message: 'Could not reach the shard.' }) - } catch (err) { - log.error('uoLink.postTownCrier', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// DELETE /admin/uo-link/towncrier/:id — remove a town-crier message. -async function deleteTownCrier(req, res) { - const { id } = req.params - try { - const result = await uoLinkClient.deleteTownCrier(id) - if (result.ok) { - await activity.log({ req, action: 'uoLink.towncrier.delete', detail: { id } }) - return res.json(result.data || { ok: true, id }) - } - if (result.status === 404) return res.status(404).json({ message: 'No town-crier message with that id.' }) - if (result.status === 503 || result.status === 0) { - return res.status(503).json({ message: 'The shard is unavailable right now.' }) - } - return res.status(502).json({ message: 'Could not reach the shard.' }) - } catch (err) { - log.error('uoLink.deleteTownCrier', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /admin/uo-link/stream — the full live feed (incl. audit/cheat), staff only. -function stream(req, res) { - shardBroadcast.subscribe(req, res, 'admin') -} - -module.exports = { getConfig, saveConfig, postTownCrier, deleteTownCrier, stream } diff --git a/server/src/router/v1/admin/uoLink.router.js b/server/src/router/v1/admin/uoLink.router.js deleted file mode 100644 index 8a4fd90..0000000 --- a/server/src/router/v1/admin/uoLink.router.js +++ /dev/null @@ -1,99 +0,0 @@ -// Admin · uo-link — the sidecar connection config, the town crier, and the -// staff SSE stream. -// -// Mounted at /api/v1/admin/uo-link by admin/index.js, which already applied -// `noindex, isLoggedIn, staffOnly`. This is where shard integration is -// configured: base/ws URL, bearer token, protocol version and the enabled -// toggle all live in the DB (uoLinkConfig), never in env. The token is -// write-only over this API (SECURITY note in uoLink.controller.js). -// -// /stream is the ADMIN SSE channel — it carries staff audit, cheat detection -// and login attempts on top of the public event kinds. The public/admin -// allowlist split in utils/shardIngest.js is a security boundary; the adminOnly -// gate below is its other half. -// -// The routes keep their `Admin · Shard` swagger tag: retagging is a real -// OpenAPI diff and does not belong in a route-move PR. -// -// Admin-only, and kept as a per-route gate rather than a router-level `use` so -// the middleware chain each route carries is unchanged by the move. - -const express = require('express') -const { body, param } = require('express-validator') - -const uoLink = require('./uoLink.controller') -const { requireRole } = require('../../../utils/auth') -const validate = require('../../../middleware/validate') - -const uoLinkRouter = express.Router() -const adminOnly = requireRole('admin') - -uoLinkRouter.get( - '/config', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Get uo-link config + live status + ingestion stats (admin only)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'Masked config, health and ingestion stats', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - adminOnly, - uoLink.getConfig, -) -uoLinkRouter.put( - '/config', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Save uo-link connection config (admin only)' - // #swagger.description = 'token is write-only — omit/blank it to keep the existing one. Saving (re)starts the WS ingest client.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { baseUrl: { type: "string" }, wsUrl: { type: "string" }, token: { type: "string" }, protocol: { type: "integer" }, enabled: { type: "boolean" } } } } } } */ - /* #swagger.responses[200] = { description: 'Updated config + live status', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[400] = { description: 'Validation error, or missing token while enabling', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - adminOnly, - body('baseUrl').optional({ values: 'falsy' }).isString().trim().isURL({ require_tld: false, protocols: ['http', 'https'] }), - body('wsUrl').optional({ values: 'falsy' }).isString().trim().isURL({ require_tld: false, protocols: ['ws', 'wss'] }), - body('token').optional({ values: 'falsy' }).isString().trim(), - body('protocol').optional().isInt({ min: 1, max: 99 }), - body('enabled').optional().isBoolean(), - validate, - uoLink.saveConfig, -) -uoLinkRouter.post( - '/towncrier', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Publish / replace a town-crier message (admin only)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TownCrierRequest" } } } } */ - /* #swagger.responses[200] = { description: 'Posted', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[400] = { description: 'Rejected (over caps)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[503] = { description: 'Shard unavailable', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - adminOnly, - body('id').isString().trim().isLength({ min: 1, max: 64 }), - body('lines').isArray({ min: 1, max: 8 }), - body('lines.*').isString().isLength({ max: 200 }), - body('durationSec').optional().isInt({ min: 1, max: 86400 }), - validate, - uoLink.postTownCrier, -) -uoLinkRouter.delete( - '/towncrier/:id', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Remove a town-crier message (admin only)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Town-crier message id.' } - /* #swagger.responses[200] = { description: 'Removed', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[404] = { description: 'Unknown id', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - adminOnly, - param('id').isString().trim().isLength({ min: 1, max: 64 }), - validate, - uoLink.deleteTownCrier, -) -uoLinkRouter.get( - '/stream', - // #swagger.tags = ['Admin · Shard'] - // #swagger.summary = 'Full live shard event stream incl. audit/cheat (SSE, admin only)' - /* #swagger.responses[200] = { description: 'An SSE stream (Content-Type: text/event-stream).' } */ - adminOnly, - uoLink.stream, -) - -module.exports = uoLinkRouter diff --git a/server/src/router/v1/admin/usersShard.controller.js b/server/src/router/v1/admin/usersShard.controller.js deleted file mode 100644 index 291067a..0000000 --- a/server/src/router/v1/admin/usersShard.controller.js +++ /dev/null @@ -1,130 +0,0 @@ -// ── Admin: a single user's shard (uo-link) footprint ────────────────────────── -// -// Backs the /admin/users/:id detail page. Every read is scoped to the target -// user's linked game accounts (from the local shard_account_links mirror): their -// vendor sales, houses, and currently-online characters. The live character -// rosters are fetched separately by the client through the existing admin-bypass -// /admin/shard/* endpoints, so nothing here round-trips the sidecar — these are -// fast, DB-backed reads. Admin-only (registered under adminOnly in the router). - -const users = require('../../../model/users/users.model') -const shardLinks = require('../../../model/shardLinks/shardLinks.model') -const shardState = require('../../../model/shardState/shardState.model') -const uoLinkClient = require('../../../utils/uoLinkClient') -const activity = require('../../../model/activity/activity.model') -const { salesForAccounts } = require('../../../utils/shardSales') - -const log = require('../../../utils/logger')('admin-user-shard') - -// Resolve the target user's linked game accounts, or null if the user id is -// unknown (so the handler can 404 rather than silently returning an empty set). -async function accountsForUser(id) { - const user = await users.getById(id) - if (!user) return null - const links = await shardLinks.listForUser(id) - return { user, links, accounts: links.map((l) => l.account) } -} - -// GET /admin/users/:id/shard/accounts — the user's linked game accounts. -async function listAccounts(req, res) { - try { - const ctx = await accountsForUser(Number(req.params.id)) - if (!ctx) return res.status(404).json({ message: 'Not found' }) - return res.json(ctx.links) - } catch (err) { - log.error('listAccounts', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /admin/users/:id/shard/sales — recent vendor sales on the user's accounts. -async function getSales(req, res) { - try { - const ctx = await accountsForUser(Number(req.params.id)) - if (!ctx) return res.status(404).json({ message: 'Not found' }) - return res.json(await salesForAccounts(ctx.accounts)) - } catch (err) { - log.error('getSales', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /admin/users/:id/shard/houses — houses owned by the user's accounts. -async function getHouses(req, res) { - try { - const ctx = await accountsForUser(Number(req.params.id)) - if (!ctx) return res.status(404).json({ message: 'Not found' }) - return res.json(await shardState.listHousesForAccounts(ctx.accounts)) - } catch (err) { - log.error('getHouses', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /admin/users/:id/shard/online — the user's characters currently online. -async function getOnline(req, res) { - try { - const ctx = await accountsForUser(Number(req.params.id)) - if (!ctx) return res.status(404).json({ message: 'Not found' }) - return res.json(await shardState.listOnlineForAccounts(ctx.accounts)) - } catch (err) { - log.error('getOnline', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /admin/users/:id/shard/standing — the user's shard "standing" cross-links: -// city governorships they currently hold and guilds they lead. Both are reliable -// current-state lookups on the user's linked accounts. -async function getStanding(req, res) { - try { - const ctx = await accountsForUser(Number(req.params.id)) - if (!ctx) return res.status(404).json({ message: 'Not found' }) - const [governorOf, guildsLed] = await Promise.all([ - shardState.listGovernorshipsForAccounts(ctx.accounts), - shardState.listGuildsLedForAccounts(ctx.accounts), - ]) - return res.json({ governorOf, guildsLed }) - } catch (err) { - log.error('getStanding', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// DELETE /admin/users/:id/shard/link/:account — unlink a game account from this -// user, site-side. `actor` is stamped from the session (never the browser). On -// success the sidecar clears the WebsiteUserId tag on the shard and we drop the -// local mirror so attribution stops immediately. -async function unlinkAccount(req, res) { - const { account } = req.params - try { - const ctx = await accountsForUser(Number(req.params.id)) - if (!ctx) return res.status(404).json({ message: 'Not found' }) - // Only unlink an account actually linked to THIS user (avoid cross-user unlink). - if (!ctx.accounts.includes(account)) { - return res.status(404).json({ message: 'That account is not linked to this user.' }) - } - const result = await uoLinkClient.unlinkAccount({ actor: req.user.username, account }) - if (result.ok) { - await shardLinks.removeByAccount(account) - await activity.log({ req, userId: ctx.user.id, action: 'shard.account.unlink', detail: { account } }) - log.info('game account unlinked', { account, userId: ctx.user.id, actor: req.user.username }) - return res.json({ account, unlinked: true }) - } - if (result.status === 403) return res.status(403).json({ message: 'That account is protected and cannot be unlinked.' }) - if (result.status === 404) { - // Not linked on the shard — reconcile our mirror anyway so the two agree. - await shardLinks.removeByAccount(account) - return res.status(404).json({ message: 'That account is not linked.' }) - } - if (result.status === 503 || result.status === 0) { - return res.status(503).json({ message: 'The game server is unavailable — try again shortly.' }) - } - return res.status(502).json({ message: 'Could not reach the shard to unlink the account.' }) - } catch (err) { - log.error('unlinkAccount', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -module.exports = { listAccounts, getSales, getHouses, getOnline, getStanding, unlinkAccount } diff --git a/server/src/router/v1/admin/usersShard.router.js b/server/src/router/v1/admin/usersShard.router.js deleted file mode 100644 index 13ee1ae..0000000 --- a/server/src/router/v1/admin/usersShard.router.js +++ /dev/null @@ -1,111 +0,0 @@ -// ── The `admin.users.detail` extension slot's contents ───────────────────── -// -// MODULE-UO CONTENT, still living in core. MODULE_SYSTEM.md §1.9 named the -// fourth mount shape: module routes hanging off a CORE resource. These six paths -// are shard reads on `/admin/users/:id`, a user-management URL core owns, so -// they cannot move with a prefix and cannot stay where they are either. -// -// The resolution is an extension SLOT. `users.router.js` declares -// `admin.users.detail` and mounts its router at `/:id`; this file is what fills -// it, registered through modules/registries.js like a module would -// (registerCore() → `api.registerExtension('admin.users.detail', …)`). Phase 3 -// moves this file to module-uo and changes nothing else — the six URLs are -// identical either way, and core never learns what "shard" means. -// -// `mergeParams` comes from the slot's router, so `req.params.id` is the parent's -// user id. Core's own routes on the resource are declared BEFORE the slot is -// mounted, so core always wins a path conflict (MODULE_API.md §2.4). - -const express = require('express') -const { param } = require('express-validator') - -const usersShard = require('./usersShard.controller') -const validate = require('../../../middleware/validate') - -// Same shape the shard routes validate account names with. -const SHARD_ACCOUNT_RE = /^[A-Za-z0-9_.-]{1,120}$/ - -const shardRouter = express.Router({ mergeParams: true }) - -// Backs the /admin/users/:id detail page: a user's linked game accounts and, -// scoped to those accounts, their vendor sales / houses / online characters. -// Live character rosters are fetched by the client through /admin/shard/* (which -// already grants admins a bypass to any account), so no routes for them here. -shardRouter.get( - '/shard/accounts', - // #swagger.tags = ['Admin · Users'] - // #swagger.summary = 'A user’s linked game accounts (admin only)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' } - /* #swagger.responses[200] = { description: 'Linked accounts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardLink" } } } } } */ - /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('id').isInt(), - validate, - usersShard.listAccounts, -) -shardRouter.get( - '/shard/sales', - // #swagger.tags = ['Admin · Users'] - // #swagger.summary = 'Recent vendor sales on a user’s accounts (admin only)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' } - /* #swagger.responses[200] = { description: 'Vendor sales', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardVendorSale" } } } } } */ - /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('id').isInt(), - validate, - usersShard.getSales, -) -shardRouter.get( - '/shard/houses', - // #swagger.tags = ['Admin · Users'] - // #swagger.summary = 'Houses owned by a user’s accounts (admin only)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' } - /* #swagger.responses[200] = { description: 'Houses (IDOC first)', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */ - /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('id').isInt(), - validate, - usersShard.getHouses, -) -shardRouter.get( - '/shard/online', - // #swagger.tags = ['Admin · Users'] - // #swagger.summary = 'A user’s characters currently online (admin only)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' } - /* #swagger.responses[200] = { description: 'Online characters', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */ - /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('id').isInt(), - validate, - usersShard.getOnline, -) -shardRouter.get( - '/shard/standing', - // #swagger.tags = ['Admin · Users'] - // #swagger.summary = 'A user’s shard standing — governorships held and guilds led (admin only)' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' } - /* #swagger.responses[200] = { description: 'Standing { governorOf, guildsLed }', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('id').isInt(), - validate, - usersShard.getStanding, -) -shardRouter.delete( - '/shard/link/:account', - // #swagger.tags = ['Admin · Users'] - // #swagger.summary = 'Unlink a game account from this user (admin only)' - // #swagger.description = 'Severs a game account’s tie to the website user from the site side (sidecar DELETE /link/{account}) and drops the local mirror. actor is stamped from the session.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' } - // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Game account to unlink.' } - /* #swagger.responses[200] = { description: 'Unlinked', content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" }, unlinked: { type: "boolean" } } } } } } */ - /* #swagger.responses[403] = { description: 'Protected staff account (refused by shard)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[404] = { description: 'Not linked', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('id').isInt(), - param('account').matches(SHARD_ACCOUNT_RE), - validate, - usersShard.unlinkAccount, -) - -module.exports = shardRouter diff --git a/server/src/router/v1/player/shard.controller.js b/server/src/router/v1/player/shard.controller.js deleted file mode 100644 index 9f7c5d3..0000000 --- a/server/src/router/v1/player/shard.controller.js +++ /dev/null @@ -1,274 +0,0 @@ -// ── Player: game-account linking + reads ─────────────────────────────────── -// -// The player-facing surface for the uo-link integration. A logged-in player -// runs [link in game, gets a one-time code, and enters it here — the server -// confirms it with the sidecar (which permanently tags the game account with the -// website user id) and mirrors the link locally. Roster/vendor reads are -// ownership-checked against that mirror so a player can only see accounts they -// have linked. The sidecar token stays server-side throughout. - -const uoLinkClient = require('../../../utils/uoLinkClient') -const shardLinks = require('../../../model/shardLinks/shardLinks.model') -const shardState = require('../../../model/shardState/shardState.model') -const shardClilocs = require('../../../model/shardClilocs/shardClilocs.model') -const settings = require('../../../model/settings/settings.model') -const { salesForAccounts } = require('../../../utils/shardSales') -const activity = require('../../../model/activity/activity.model') - -const log = require('../../../utils/logger')('player-shard') - -const SERIAL_RE = /^0x[0-9a-fA-F]+$/ - -/** - * Resolve the cliloc ids on a profile into display names. - * - * Items on the wire carry a `LabelNumber`, not a name — `BridgeProfile.WriteItem` - * sends `cliloc` on every equipment entry and `name` only for the minority of - * items a player has renamed. Reward titles are the same shape: the shard sends - * a cliloc number as a string, which the sheet previously had to SKIP because it - * had no way to turn it into words. - * - * Resolution happens here rather than in the browser because the table is ~123k - * rows: shipping it to render a dozen names would dwarf the page, and the - * Android client consumes this same JSON and would otherwise need its own copy. - * - * A shard with no cliloc table configured resolves nothing and the sheet renders - * ids exactly as it did before — this is decoration, and it is applied in the - * same best-effort block as the guild/governor cross-links. - */ -async function resolveProfileClilocs(profile) { - const wanted = [] - - const equipment = Array.isArray(profile.equipment) ? profile.equipment : [] - for (const item of equipment) { - if (Number.isInteger(item?.cliloc)) wanted.push(item.cliloc) - } - - // Reward titles arrive as strings that may be either a literal ("Knight of - // Trinsic") or a cliloc number in string form. Only the numeric ones need us. - const reward = Array.isArray(profile.titles?.reward) ? profile.titles.reward : [] - const rewardNumbers = reward.map((r) => (/^\d+$/.test(String(r)) ? Number(r) : null)) - for (const n of rewardNumbers) if (n !== null) wanted.push(n) - - if (wanted.length === 0) return - - const names = await shardClilocs.resolveMany(wanted) - if (names.size === 0) return - - for (const item of equipment) { - // A player-given name always wins over the type name: an item called "Bob's - // lucky axe" should not be relabelled "hatchet". - if (item?.name) continue - const resolved = names.get(item?.cliloc) - if (resolved) item.clilocName = resolved - } - - if (rewardNumbers.some((n) => n !== null)) { - profile.titles.rewardResolved = reward.map((raw, i) => { - const n = rewardNumbers[i] - return n === null ? String(raw) : names.get(n) ?? null - }) - } -} - -// Decorate a char.profile with cross-links from our own board data: the guild the -// character leads and any city governorship on its account, plus resolved cliloc -// names. Best-effort — a failure here never fails the profile (it's a nicety, -// not the sheet). -async function enrichCharProfile(profile) { - if (!profile) return profile - try { - const guild = await shardState.findGuildForActor({ serial: profile.serial, acct: profile.acct }) - if (guild) profile.guild = guild - if (profile.acct) { - const govs = await shardState.listGovernorshipsForAccounts([profile.acct]) - if (govs.length) profile.governorOf = govs.map((g) => g.city) - } - await resolveProfileClilocs(profile) - } catch (err) { - log.warn('enrichCharProfile failed', { serial: profile.serial, message: err.message }) - } - return profile -} - -// POST /player/shard/link — confirm an in-game link code. -async function link(req, res) { - const { code } = req.body - try { - const result = await uoLinkClient.confirmLink(code, req.user.id) - - if (result.ok && result.data && result.data.kind === 'link.ok') { - const account = result.data.account - await shardLinks.link({ account, userId: req.user.id, charName: result.data.char || null }) - await activity.log({ req, action: 'uoLink.account.link', detail: { account } }) - log.info('player linked game account', { user: req.user.username, account }) - return res.json({ linked: true, account }) - } - - // Sidecar reports bad/expired codes as 400 link.error or 404. - if (result.status === 400 || result.status === 404) { - return res.status(400).json({ message: 'That code is unknown or has expired. Run [link in game for a new one.' }) - } - if (result.status === 503 || result.status === 0) { - return res.status(503).json({ message: 'The shard is unavailable right now — try again shortly.' }) - } - return res.status(502).json({ message: 'Could not confirm the link with the shard.' }) - } catch (err) { - log.error('player.shard.link', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /player/shard/accounts — the caller's linked game accounts. -async function listAccounts(req, res) { - try { - return res.json(await shardLinks.listForUser(req.user.id)) - } catch (err) { - log.error('player.shard.listAccounts', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// Admins may view any character's data; everyone else is limited to accounts -// they have personally linked. The same handlers back /player/shard (role -// `player`, never admin) and /admin/shard (staff), so this bypass only ever -// widens access for genuine admins. -const isAdmin = (req) => req.user && req.user.role === 'admin' - -// Shared ownership gate + live round-trip for roster/vendors. `fetcher` is the -// uoLinkClient method to call with the account. -async function ownedRoundTrip(req, res, fetcher, label) { - const { account } = req.params - try { - const owns = isAdmin(req) || (await shardLinks.ownsAccount(account, req.user.id)) - if (!owns) return res.status(403).json({ message: 'That account is not linked to your profile.' }) - - const result = await fetcher(account) - if (result.ok) return res.json(result.data) - if (result.status === 404) return res.status(404).json({ message: 'Not found.' }) - if (result.status === 503 || result.status === 0) { - return res.status(503).json({ message: 'The shard is unavailable right now — try again shortly.' }) - } - return res.status(502).json({ message: 'Could not reach the shard.' }) - } catch (err) { - log.error(`player.shard.${label}`, err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /player/shard/roster/:account — characters on a linked account. -const roster = (req, res) => ownedRoundTrip(req, res, uoLinkClient.getRoster, 'roster') - -// GET /player/shard/vendors/:account — player vendors on a linked account. -const vendors = (req, res) => ownedRoundTrip(req, res, uoLinkClient.getVendors, 'vendors') - -// GET /player/shard/char/:serial — a character sheet, but ONLY if the character's -// account is linked to the caller. The sidecar returns the owning account in the -// profile, which we check against the caller's links before returning anything. -async function getChar(req, res) { - const { serial } = req.params - if (!SERIAL_RE.test(serial)) return res.status(400).json({ message: 'Invalid serial.' }) - try { - const result = await uoLinkClient.getCharBySerial(serial) - if (result.ok) { - // Admins see any character; others only characters on an account they linked. - if (!isAdmin(req)) { - const acct = result.data && result.data.acct - const owns = acct ? await shardLinks.ownsAccount(acct, req.user.id) : false - if (!owns) return res.status(403).json({ message: 'That character is not on an account linked to you.' }) - } - return res.json(await enrichCharProfile(result.data)) - } - if (result.status === 404) return res.status(404).json({ message: 'Character not found.' }) - if (result.status === 503 || result.status === 0) { - return res.status(503).json({ message: 'The game server is restarting — try again shortly.' }) - } - return res.status(502).json({ message: 'Could not reach the shard.' }) - } catch (err) { - log.error('player.shard.getChar', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /player/shard/sales — recent player-vendor sales for the caller's linked -// accounts only (as seller/owner). Read from the site's own event log. -async function getSales(req, res) { - try { - const links = await shardLinks.listForUser(req.user.id) - const accounts = links.map((l) => l.account) - return res.json(await salesForAccounts(accounts)) - } catch (err) { - log.error('player.shard.getSales', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /player/shard/houses — the caller's OWN houses (home status), scoped to -// their linked accounts. A player sees their own decay/IDOC standing; never -// anyone else's. Full detail is fine here — it's their property. -async function getHouses(req, res) { - try { - const links = await shardLinks.listForUser(req.user.id) - const accounts = links.map((l) => l.account) - return res.json(await shardState.listHousesForAccounts(accounts)) - } catch (err) { - log.error('player.shard.getHouses', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// Map a failed uoLinkClient.createAccount result to a user-facing HTTP response. -// The password is never echoed anywhere; only the mapped reason is returned. -function mapCreateAccountError(res, result) { - const reason = (result.data && result.data.reason) || '' - switch (result.status) { - case 409: - return res.status(409).json({ message: 'That account name is already taken.' }) - case 429: - return res.status(429).json({ message: 'The account limit for your network has been reached.' }) - case 403: - return res.status(403).json({ message: 'Game-account signups are not available on this shard right now.' }) - case 400: - return res.status(400).json({ message: reason || 'The account name or password was not accepted.' }) - case 503: - case 0: - return res.status(503).json({ message: 'The game server is unavailable — try again shortly.' }) - default: - return res.status(502).json({ message: 'Could not reach the shard to create the account.' }) - } -} - -// POST /player/shard/account — provision a GAME account for the signed-in website -// user and auto-link it (Protocol 2.0 hybrid). Used by self-serve signup and the -// invite-accept "create game account" step alike (both act as the signed-in user). -// actor + websiteUserId are stamped from the session; the browser IP (req.ip, -// trust-proxy configured) is forwarded for the shard's per-IP cap; the password is -// never logged. Gated by the game_account_signup setting AND the shard's own mode. -async function createGameAccount(req, res) { - const { account, password } = req.body - try { - if (!(await settings.isGameAccountSignupEnabled())) { - return res.status(403).json({ message: 'Game-account signup is not available right now.' }) - } - const result = await uoLinkClient.createAccount({ - actor: req.user.username, - account, - password, - websiteUserId: req.user.id, - ip: req.ip, - }) - if (result.ok) { - // Mirror the link locally so the portal lists the account immediately. - await shardLinks.link({ account, userId: req.user.id }) - await activity.log({ req, userId: req.user.id, action: 'shard.account.create', detail: { account } }) - log.info('game account created', { account, userId: req.user.id, ip: req.ip }) - return res.status(201).json({ account, linked: true }) - } - return mapCreateAccountError(res, result) - } catch (err) { - log.error('player.shard.createGameAccount', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -module.exports = { link, listAccounts, roster, vendors, getChar, getSales, getHouses, createGameAccount } diff --git a/server/src/router/v1/player/shard.router.js b/server/src/router/v1/player/shard.router.js deleted file mode 100644 index 0f14b0f..0000000 --- a/server/src/router/v1/player/shard.router.js +++ /dev/null @@ -1,124 +0,0 @@ -// Player · Shard — game-account linking and the caller's own roster / vendors / -// characters / sales / houses, ownership-checked against the local link mirror. -// -// Mounted at /api/v1/player/shard by player/index.js, which already applied -// `noindex, requireAuth`. No extra gate: every handler is self-scoped to -// req.user.id. -// -// These are the *same* handlers (player/shard.controller) that admin/shard.router.js -// serves under /admin/shard for the seven self-service routes — staff are a -// superset of players, and the controller keys off req.user.id either way. Two -// URL surfaces, one implementation. - -const express = require('express') -const { body, param } = require('express-validator') - -const shard = require('./shard.controller') -const validate = require('../../../middleware/validate') -const { accountChangeLimiter } = require('../../../middleware/rateLimit') - -const shardRouter = express.Router() - -// Link an in-game account with a one-time code from [link, then read the -// account's roster / vendors (ownership-checked against the local link mirror). -const ACCOUNT_RE = /^[A-Za-z0-9_.-]{1,120}$/ - -shardRouter.post( - '/link', - // #swagger.tags = ['Player · Shard'] - // #swagger.summary = 'Link an in-game account with a one-time code' - // #swagger.description = 'The player runs [link in game to get a code, then submits it here. The server confirms it with the sidecar and mirrors the link.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkRequest" } } } } */ - /* #swagger.responses[200] = { description: 'Linked', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkResult" } } } } */ - /* #swagger.responses[400] = { description: 'Unknown or expired code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - body('code').isString().trim().isLength({ min: 4, max: 32 }), - validate, - shard.link, -) -shardRouter.post( - '/account', - // #swagger.tags = ['Player · Shard'] - // #swagger.summary = 'Create a game account (hybrid signup) and link it to the caller' - // #swagger.description = 'Provisions a new game account with its own username + password and auto-links it to the signed-in website user. Available only when game_account_signup is enabled and the shard accepts website signups. The password is hashed on the shard and never stored or logged by the site.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["account","password"], properties: { account: { type: "string" }, password: { type: "string" } } } } } */ - /* #swagger.responses[201] = { description: 'Account created and linked', content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" }, linked: { type: "boolean" } } } } } } */ - /* #swagger.responses[400] = { description: 'Validation error or rejected name/password', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */ - /* #swagger.responses[403] = { description: 'Game-account signup unavailable (site or shard)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[409] = { description: 'Account name already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[429] = { description: 'Per-IP account cap reached', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - accountChangeLimiter, - body('account').matches(/^[A-Za-z0-9][A-Za-z0-9_.-]{2,29}$/), - body('password').isString().isLength({ min: 8, max: 64 }), - validate, - shard.createGameAccount, -) -shardRouter.get( - '/accounts', - // #swagger.tags = ['Player · Shard'] - // #swagger.summary = 'List the caller’s linked game accounts' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'Linked accounts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardLink" } } } } } */ - shard.listAccounts, -) -shardRouter.get( - '/roster/:account', - // #swagger.tags = ['Player · Shard'] - // #swagger.summary = 'Character roster for a linked account' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' } - /* #swagger.responses[200] = { description: 'Account roster', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('account').matches(ACCOUNT_RE), - validate, - shard.roster, -) -shardRouter.get( - '/vendors/:account', - // #swagger.tags = ['Player · Shard'] - // #swagger.summary = 'Player vendors for a linked account' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' } - /* #swagger.responses[200] = { description: 'Vendor snapshot', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('account').matches(ACCOUNT_RE), - validate, - shard.vendors, -) -shardRouter.get( - '/char/:serial', - // #swagger.tags = ['Player · Shard'] - // #swagger.summary = 'Character sheet — only for a character on the caller’s linked account' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - // #swagger.parameters['serial'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Mobile serial, e.g. 0x24C.' } - /* #swagger.responses[200] = { description: 'Character profile', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - /* #swagger.responses[403] = { description: 'Character not on an account linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('serial').matches(/^0x[0-9a-fA-F]+$/), - validate, - shard.getChar, -) -shardRouter.get( - '/sales', - // #swagger.tags = ['Player · Shard'] - // #swagger.summary = 'Recent player-vendor sales for the caller’s linked accounts' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'Vendor sales', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardVendorSale" } } } } } */ - shard.getSales, -) -shardRouter.get( - '/houses', - // #swagger.tags = ['Player · Shard'] - // #swagger.summary = 'The caller’s own houses (home status)' - // #swagger.description = 'Houses owned by the caller’s linked accounts, with decay/IDOC status. Only the caller’s own houses — never anyone else’s.' - // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }] - /* #swagger.responses[200] = { description: 'The caller’s houses', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */ - shard.getHouses, -) - -module.exports = shardRouter diff --git a/server/src/router/v1/public/atlas.controller.js b/server/src/router/v1/public/atlas.controller.js deleted file mode 100644 index b002519..0000000 --- a/server/src/router/v1/public/atlas.controller.js +++ /dev/null @@ -1,134 +0,0 @@ -// ── Public: the spawn atlas ──────────────────────────────────────────────── -// -// A browsable catalogue of what the shard CONTAINS — which creatures spawn, -// where, how many, and which champion altars are configured. Everything here is -// a plain indexed read of the tables the boot-time import fills from the shard's -// own ServUO tree (docs/website/SPAWN_ATLAS.md). -// -// Two properties separate this from /public/shard/*: -// -// • **Nothing touches the sidecar.** The atlas is static shard content, not -// live shard state, so these pages stay fully populated while the shard is -// down. That is why the routes are mounted at /public/atlas and are -// siteMode-gated like /posts and /wiki, rather than under /shard. -// • **The live champion feed is a different thing.** `/atlas/champions` is the -// configured roster ("there is an Unholy Terror altar in Deceit"); -// `/shard/champs` is the running state ("it is on level 3 right now"). -// -// Every response is still passed through `projectFeature` for the `atlas` -// feature. It declares no sensitive fields today, so the projection is a -// no-op — but v3.md §3.6.1's rule is that a read path returning shard data and -// not projecting is a bug, and the cost of honouring it is one call per handler -// rather than a retrofit the first time a field needs gating. - -const atlas = require('../../../model/shardAtlas/shardAtlas.model') -const visibility = require('../../../utils/shardVisibility') - -const log = require('../../../utils/logger')('public-atlas') - -const FEATURE = 'atlas' - -// Query params arrive as strings; express-validator has already bounded them. -const int = (value, fallback) => { - const n = Number.parseInt(value, 10) - return Number.isFinite(n) ? n : fallback -} - -const str = (value) => (typeof value === 'string' ? value.trim() : '') - -// GET /public/atlas/creatures?q=&facet=&limit=&offset= -async function getCreatures(req, res) { - try { - const page = await atlas.searchCreatures({ - q: str(req.query.q), - facet: str(req.query.facet), - limit: int(req.query.limit, 50), - offset: int(req.query.offset, 0), - }) - return res.json(await visibility.project(FEATURE, page, req)) - } catch (err) { - log.error('atlas.getCreatures', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/atlas/creatures/:slug — one creature, with the places it spawns. -// -// 404 means "no such creature in this atlas", which also covers "the atlas has -// never been imported" — an empty atlas has no slugs, and there is nothing more -// specific to say to an anonymous caller. -async function getCreature(req, res) { - try { - const creature = await atlas.getCreature(req.params.slug, { - facet: str(req.query.facet), - points: int(req.query.points, 200), - }) - if (!creature) return res.status(404).json({ message: 'Not Found' }) - return res.json(await visibility.project(FEATURE, creature, req)) - } catch (err) { - log.error('atlas.getCreature', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/atlas/regions?facet=&q= -async function getRegions(req, res) { - try { - const regions = await atlas.listRegions({ - facet: str(req.query.facet), - q: str(req.query.q), - }) - return res.json(await visibility.project(FEATURE, regions, req)) - } catch (err) { - log.error('atlas.getRegions', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/atlas/landmarks?facet=&q= -async function getLandmarks(req, res) { - try { - const landmarks = await atlas.listLandmarks({ - facet: str(req.query.facet), - q: str(req.query.q), - }) - return res.json(await visibility.project(FEATURE, landmarks, req)) - } catch (err) { - log.error('atlas.getLandmarks', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/atlas/champions?facet= — the CONFIGURED altar roster. -async function getChampions(req, res) { - try { - const champions = await atlas.listChampions({ facet: str(req.query.facet) }) - return res.json(await visibility.project(FEATURE, champions, req)) - } catch (err) { - log.error('atlas.getChampions', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/atlas/meta — what is loaded: facets, counts, when it was imported. -// -// Public-safe by construction: the model omits the ServUO path, the per-file -// hashes and the pending-refresh state, all of which describe the operator's -// filesystem rather than the game world. The admin status route carries those. -async function getMeta(req, res) { - try { - return res.json(await visibility.project(FEATURE, await atlas.publicMeta(), req)) - } catch (err) { - log.error('atlas.getMeta', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -module.exports = { - getCreatures, - getCreature, - getRegions, - getLandmarks, - getChampions, - getMeta, -} diff --git a/server/src/router/v1/public/atlas.router.js b/server/src/router/v1/public/atlas.router.js deleted file mode 100644 index 97498ec..0000000 --- a/server/src/router/v1/public/atlas.router.js +++ /dev/null @@ -1,128 +0,0 @@ -// Public · Atlas — the spawn atlas / bestiary. Static shard CONTENT derived from -// the shard's own ServUO tree, not live shard state. -// -// Mounted at /api/v1/public/atlas by public/index.js. Two deliberate differences -// from the /public/shard routes next door (docs/link/v3.md §6): -// -// • **Not under /shard.** Nothing here round-trips the sidecar, and the pages -// stay fully populated while the shard is down. Mounting it under /shard -// would imply a dependency it does not have. -// • **siteMode-gated, like /posts and /wiki.** The shard routes are exempt -// because shard status is wanted *during* maintenance; a bestiary is site -// content and follows site content's rules. -// -// Every route also carries `requireFeature('atlas')` — 404 when an admin has -// disabled the feature, 403 when the caller sits below its configured audience. -// The default audience is `anonymous`, so these gates are inert until an admin -// changes something. - -const express = require('express') -const { param, query } = require('express-validator') - -const atlas = require('./atlas.controller') -const siteMode = require('../../../middleware/siteMode') -const validate = require('../../../middleware/validate') -const { requireFeature } = require('../../../utils/shardVisibility') - -const atlasRouter = express.Router() - -// Facet names come from the shard's own files and are never validated against a -// list — nothing in the codebase names a facet (§6.1 R2). Only the length is -// bounded, and the query matches exactly, so an unknown name returns an empty -// result rather than an error. -const facetParam = query('facet').optional({ values: 'falsy' }).isString().isLength({ max: 40 }) - -atlasRouter.get( - '/creatures', - requireFeature('atlas'), - // #swagger.tags = ['Public · Atlas'] - // #swagger.summary = 'Search the bestiary (paginated)' - // #swagger.description = 'Every creature the shard spawns, most numerous first. `total` is how many can be alive at once across all spawners; `points` is how many spawners mention it; `facets` maps facet name to that creature\'s share on it. Static content parsed from the shard\'s ServUO tree — unaffected by the shard being offline.' - // #swagger.parameters['q'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Substring match on the creature name (max 60 chars).' } - // #swagger.parameters['facet'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to creatures spawning on this facet. Facet names come from the shard\'s own files; an unknown one returns an empty page.' } - // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Page size, 1..100 (default 50).' } - // #swagger.parameters['offset'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Rows to skip (default 0).' } - /* #swagger.responses[200] = { description: 'A page of creatures plus the unpaginated total', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasCreaturePage" } } } } */ - /* #swagger.responses[403] = { description: 'The atlas feature is gated above this caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[404] = { description: 'The atlas feature is disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - query('q').optional({ values: 'falsy' }).isString().isLength({ max: 60 }), - facetParam, - query('limit').optional().isInt({ min: 1, max: 100 }), - query('offset').optional().isInt({ min: 0, max: 100000 }), - validate, - siteMode, - atlas.getCreatures, -) -atlasRouter.get( - '/creatures/:slug', - requireFeature('atlas'), - // #swagger.tags = ['Public · Atlas'] - // #swagger.summary = 'One creature: where it spawns, and what spawns with it' - // #swagger.description = 'The answer the atlas exists to give. `places` is the aggregate — "lizardman → Shrines, Isamu-Jima, Yew" — resolved by point-in-rect against the shard\'s own region rectangles, falling back to the nearest landmark, else "Wilderness". `spawners` lists the individual spawn points (bounded; `spawnersTruncated` says when the list was cut), and `alsoHere` is what shares those spawners.' - // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Creature slug, e.g. lizardman.' } - // #swagger.parameters['facet'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Restrict places and spawners to one facet.' } - // #swagger.parameters['points'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max spawners to return, 1..1000 (default 200).' } - /* #swagger.responses[200] = { description: 'The creature', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasCreature" } } } } */ - /* #swagger.responses[404] = { description: 'No such creature in this atlas (or the feature is disabled)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - param('slug').isString().isLength({ min: 1, max: 120 }), - facetParam, - query('points').optional().isInt({ min: 1, max: 1000 }), - validate, - siteMode, - atlas.getCreature, -) -atlasRouter.get( - '/regions', - requireFeature('atlas'), - // #swagger.tags = ['Public · Atlas'] - // #swagger.summary = 'Named regions and their rectangles' - // #swagger.description = 'Flattened out of the shard\'s nested Regions.xml. `priority` and the rectangles are what placed each spawn point, kept so the placement can be re-derived rather than taken on trust.' - // #swagger.parameters['facet'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to one facet.' } - // #swagger.parameters['q'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Substring match on the region name.' } - /* #swagger.responses[200] = { description: 'Regions, by facet then name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/AtlasRegion" } } } } } */ - facetParam, - query('q').optional({ values: 'falsy' }).isString().isLength({ max: 60 }), - validate, - siteMode, - atlas.getRegions, -) -atlasRouter.get( - '/landmarks', - requireFeature('atlas'), - // #swagger.tags = ['Public · Atlas'] - // #swagger.summary = 'Points of interest (dungeon levels, town markers)' - // #swagger.description = 'From the shard\'s Data/Locations files. `group` is the innermost enclosing parent ("Covetous"), which is the label worth showing over the individual marker ("Level 1").' - // #swagger.parameters['facet'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to one facet.' } - // #swagger.parameters['q'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Substring match on the landmark name or its group.' } - /* #swagger.responses[200] = { description: 'Landmarks, by facet then group', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/AtlasLandmark" } } } } } */ - facetParam, - query('q').optional({ values: 'falsy' }).isString().isLength({ max: 60 }), - validate, - siteMode, - atlas.getLandmarks, -) -atlasRouter.get( - '/champions', - requireFeature('atlas'), - // #swagger.tags = ['Public · Atlas'] - // #swagger.summary = 'Configured champion altars (the roster, not the live board)' - // #swagger.description = 'Where the altars are and what each one summons — "there is an Unholy Terror altar in Deceit". `randomType` marks altars whose champion is drawn at activation. Do not conflate this with GET /public/shard/champs, which is the live sidecar-fed board ("it is on level 3 right now").' - // #swagger.parameters['facet'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to one facet.' } - /* #swagger.responses[200] = { description: 'Altars, by facet then name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/AtlasChampion" } } } } } */ - facetParam, - validate, - siteMode, - atlas.getChampions, -) -atlasRouter.get( - '/meta', - requireFeature('atlas'), - // #swagger.tags = ['Public · Atlas'] - // #swagger.summary = 'What atlas is loaded: facets, counts, when it was imported' - // #swagger.description = 'Drives the facet filter and the "parsed from the shard\'s own files on " line. Reports the game world only — the ServUO path, the per-file hashes and any pending refresh are operator detail and live on the admin status route.' - /* #swagger.responses[200] = { description: 'Atlas metadata', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasMeta" } } } } */ - siteMode, - atlas.getMeta, -) - -module.exports = atlasRouter diff --git a/server/src/router/v1/public/shard.controller.js b/server/src/router/v1/public/shard.controller.js deleted file mode 100644 index e94fc3f..0000000 --- a/server/src/router/v1/public/shard.controller.js +++ /dev/null @@ -1,422 +0,0 @@ -// ── Public: shard live data ──────────────────────────────────────────────── -// -// Same-origin, token-free read endpoints backed by the data the WS ingest -// pipeline persists (shard_online / shard_events / shard_economy / shard_houses) -// plus a live character round-trip to the sidecar. The browser never sees the -// sidecar URL or token — every sidecar call is server-side (uoLinkClient). -// -// The stored-data endpoints are cheap DB reads. The live /char endpoint hits the -// running shard, so it is briefly cached and degrades gracefully: a 503 (shard -// restarting) surfaces as a retry-able banner rather than an error. - -const shardEvents = require('../../../model/shardEvents/shardEvents.model') -const shardState = require('../../../model/shardState/shardState.model') -const shardMarket = require('../../../model/shardMarket/shardMarket.model') -const uoLinkConfig = require('../../../model/uoLinkConfig/uoLinkConfig.model') -const broadcast = require('../../../utils/shardBroadcast') -const visibility = require('../../../utils/shardVisibility') - -const log = require('../../../utils/logger')('public-shard') - -// GET /public/shard/status — connection state + online count + latest economy. -async function getStatus(req, res) { - try { - const config = await uoLinkConfig.getSafe() - const [online, economy] = await Promise.all([ - shardState.onlineCount(), - shardState.latestEconomy(), - ]) - return res.json({ - enabled: config.enabled, - status: config.status, - pluginConnected: config.pluginConnected, - lastEventAt: config.lastEventAt, - onlineCount: online, - economy, - }) - } catch (err) { - log.error('shard.getStatus', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/feed?kind=&limit= — recent notable events from the log. -// -// This is the stored-history twin of the SSE stream, and it must reach the same -// verdict the stream does about the same event. Two things are therefore resolved -// against the LIVE config rather than the compiled defaults: -// -// • which kinds this viewer may read at all — `visibleKinds`, not the static -// PUBLIC_KINDS set (which is fixed at module load, so an admin moving -// `guilds` to `staff` would gate /guilds while /feed kept serving -// guild.join to anonymous callers), and -// • the payload itself, projected per event against ITS OWN kind's feature — -// the rows are a mix of features, and without this the stored frames were -// returned verbatim, `acct`/`webId` and all, on an anonymous endpoint. -async function getFeed(req, res) { - try { - const config = await visibility.getConfig() - const level = req.viewerLevel || (await visibility.viewerLevel(req)) - const allowed = new Set(visibility.visibleKinds(level, config)) - - const { kind, limit } = req.query - // No readable kinds ⇒ nothing to serve. Returning early also keeps us clear - // of `list({ kinds: [] })`, which means "no filter", not "match nothing". - if (allowed.size === 0) return res.json([]) - - let events - if (kind) { - if (!allowed.has(kind)) return res.json([]) - events = await shardEvents.list({ kind, limit }) - } else { - events = await shardEvents.list({ kinds: [...allowed], limit }) - } - - return res.json( - events.map((ev) => ({ - ...ev, - payload: visibility.projectFeature( - visibility.KIND_FEATURE.get(ev.kind), - ev.payload, - level, - config, - ), - })), - ) - } catch (err) { - log.error('shard.getFeed', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/economy — gold-supply series, oldest → newest. -async function getEconomy(req, res) { - try { - return res.json(await shardState.listEconomy(req.query.limit)) - } catch (err) { - log.error('shard.getEconomy', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/online — players online now whose account is linked to a -// STAFF website user (admin/editor/moderator). Everyone sees that a staff member -// is online (name + serial); their in-game location (map + coordinates) is gated -// on the `presence` feature's `location` field rule, which defaults to `staff` -// — the same admin/moderator set this used to hardcode. Non-staff players are -// never listed. -async function canSeeStaffLocation(req) { - const config = await visibility.getConfig() - const required = config.presence?.fields?.location || 'staff' - const level = req.viewerLevel || (await visibility.viewerLevel(req)) - return visibility.meets(level, required) -} - -async function getOnline(req, res) { - try { - const rows = await shardState.listOnlineLinked() - const showLocation = await canSeeStaffLocation(req) - return res.json( - rows.map((r) => { - const entry = { serial: r.serial, name: r.name } - if (showLocation) { - entry.map = r.map - entry.x = r.x - entry.y = r.y - entry.z = r.z - } - return entry - }), - ) - } catch (err) { - log.error('shard.getOnline', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/idoc — houses currently in danger (stage IDOC). -// -// Projected: shapeHouse flattens the owner actor into `ownerSerial`/`ownerAcct`/ -// `ownerName`, so this endpoint used to hand an anonymous caller the house -// owner's GAME ACCOUNT NAME. The public IDOC board only ever needed name, region -// and location — which is all that survives projection below `staff`. -async function getIdoc(req, res) { - try { - return res.json(await visibility.project('houses', await shardState.listIdoc(), req)) - } catch (err) { - log.error('shard.getIdoc', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/champs — the current champion-spawn board (all categories). -// Served from our own store; live deltas (champ.update / champ.remove) arrive on -// the public SSE stream so the page can update in place. -async function getChamps(req, res) { - try { - return res.json(await visibility.project('champs', await shardState.listChamps(), req)) - } catch (err) { - log.error('shard.getChamps', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/guilds — the current guild board. Served from our store; -// live via guild.update / guild.remove / guild.join on the public SSE stream. -// -// Projected: the stored payload is the raw guild.update frame, whose `leader` -// actor carries `acct` and `webId`. Those are admin-only and were previously -// returned verbatim to anonymous callers. -async function getGuilds(req, res) { - try { - return res.json(await visibility.project('guilds', await shardState.listGuilds(), req)) - } catch (err) { - log.error('shard.getGuilds', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/governors — the current town-governor board (empty on shards -// without City Loyalty). Live via city.update on the public SSE stream. Projected -// for the same reason as getGuilds: `governor` / `governorElect` are actors. -async function getGovernors(req, res) { - try { - return res.json(await visibility.project('governors', await shardState.listGovernors(), req)) - } catch (err) { - log.error('shard.getGovernors', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/governors/:city/history — the term ledger for one city -// (look-back: "who were all the governors of Britain?"), newest first. -async function getGovernorHistory(req, res) { - try { - const terms = await shardState.listGovernorHistory(req.params.city, req.query.limit) - return res.json(await visibility.project('governors', terms, req)) - } catch (err) { - log.error('shard.getGovernorHistory', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/presence — the online-population aggregate (count + per-facet -// + per-region). Live via presence.online on the public SSE stream. -async function getPresence(req, res) { - try { - return res.json(await visibility.project('presence', await shardState.latestPresence(), req)) - } catch (err) { - log.error('shard.getPresence', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/houses — PUBLIC view: only houses in danger (IDOC), and only -// their location (name + region + map/coords). Owner, price, co-owners and decay -// detail are staff-only (see admin GET /admin/shard/houses). Live via house.decay -// on the public SSE stream. This is the "where are the falling houses" board. -async function getHouses(req, res) { - try { - const idoc = await shardState.listIdoc() - const publicHouses = idoc.map((h) => ({ - serial: h.serial, - name: h.name, - region: h.region, - map: h.map, - x: h.x, - y: h.y, - z: h.z, - isIdoc: true, - })) - // Already a hand-picked safe subset; projected anyway so an admin who - // tightens a `houses` field rule sees it honoured on every houses surface - // rather than on some of them. - return res.json(await visibility.project('houses', publicHouses, req)) - } catch (err) { - log.error('shard.getHouses', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/ruleset — the shard's published ruleset (Protocol 3.0): -// expansion, which optional systems are on, skill/stat caps, account and house -// limits, champion scroll rules, the save/restart schedule. Served from our own -// store, so it renders while the shard is down; live via world.ruleset on the -// public SSE stream. -// -// `null` means the shard has never published one (an old plugin, or -// Bridge.RulesetEnabled=false) — a real answer, distinct from a published -// ruleset, and the page says so rather than rendering an empty one. -// -// Projected like every other shard read (§3.6.1's rule: a read path that returns -// shard data and does not call projectFeature is a bug). The `connect` string is -// the one configurable field — an operator who published a connect address may -// still want it behind a login. -async function getRuleset(req, res) { - try { - const ruleset = await shardState.getRuleset() - if (!ruleset) return res.json(null) - return res.json(await visibility.project('ruleset', ruleset, req)) - } catch (err) { - log.error('shard.getRuleset', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// The shard keys boards by its own PointsType enum name (QueensLoyalty, -// CleanUpBritannia, …). Constrain the path param to that shape before it reaches -// the model: the column is VARCHAR(48), and an unbounded string here is a needless -// query on a value that can only ever be an identifier. -const SYSTEM_RE = /^[A-Za-z][A-Za-z0-9_]{0,47}$/ - -// GET /public/shard/points — every points/loyalty leaderboard the shard publishes. -// Served from our own store, so the page renders while the shard is down — which -// matters more here than for live state: these are standings accumulated over -// months, and blanking them during a restart would look like a data loss. -async function getPointsBoards(req, res) { - try { - const boards = await shardState.listPointsBoards() - return res.json(await visibility.project('leaderboards', boards, req)) - } catch (err) { - log.error('shard.getPointsBoards', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/points/:system — one system's board. -// -// 404 for a system the shard has never published, matching the sidecar: "no such -// board" and "a board nobody is on yet" are different answers. -async function getPointsBoard(req, res) { - const { system } = req.params - if (!SYSTEM_RE.test(system)) return res.status(400).json({ message: 'Invalid points system.' }) - try { - const board = await shardState.getPointsBoard(system) - if (!board) return res.status(404).json({ message: 'Unknown points system.' }) - return res.json(await visibility.project('leaderboards', board, req)) - } catch (err) { - log.error('shard.getPointsBoard', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// ── Marketplace (Protocol 3.0 vendor.listing) ────────────────────────────── -// -// The shard-wide player-vendor index. Served entirely from our own tables — the -// sidecar is never touched on this path — so shops stay browsable while the shard -// is down, labelled with how stale they may be. -// -// The staleness label is not decoration. The shard sweeps vendors round-robin, so -// a shop can legitimately be a full cycle behind; a page that implied live prices -// would send people to a vendor whose item sold twenty minutes ago. - -// The serial spelling the bridge uses everywhere: "0x" and hex. Constrained -// before it reaches the model, like SYSTEM_RE above. -const SERIAL_RE = /^0x[0-9A-Fa-f]{1,16}$/ - -const intParam = (value) => { - const n = Number.parseInt(value, 10) - return Number.isFinite(n) ? n : undefined -} - -// GET /public/shard/market — search the index. -// -// Returns LISTINGS, not vendors: "who sells a vanquishing kryss and for how much" -// is the question, and a vendor-shaped result would make every caller flatten the -// shops back out. -async function getMarket(req, res) { - try { - const page = await shardMarket.search({ - q: typeof req.query.q === 'string' ? req.query.q : '', - minPrice: intParam(req.query.minPrice), - maxPrice: intParam(req.query.maxPrice), - itemId: intParam(req.query.itemId), - map: typeof req.query.map === 'string' ? req.query.map : '', - region: typeof req.query.region === 'string' ? req.query.region : '', - sort: typeof req.query.sort === 'string' ? req.query.sort : 'price_asc', - limit: intParam(req.query.limit) ?? 50, - offset: intParam(req.query.offset) ?? 0, - }) - return res.json(await visibility.project('market', page, req)) - } catch (err) { - log.error('shard.getMarket', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/market/meta — index size, staleness, and the filter options -// (which facets and regions actually hold vendors). Separate from the search so -// the page can build its filters without running a query it will throw away. -async function getMarketMeta(req, res) { - try { - return res.json(await visibility.project('market', await shardMarket.meta(), req)) - } catch (err) { - log.error('shard.getMarketMeta', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/market/vendors/:serial — one shop and its listings. -// -// 404 for a serial the index has never seen, which also covers a vendor that has -// since been dismissed or hidden: to an anonymous caller "no such shop" is the -// only honest answer, and distinguishing the two would leak that a vendor exists -// but was hidden. -async function getMarketVendor(req, res) { - const { serial } = req.params - if (!SERIAL_RE.test(serial)) return res.status(400).json({ message: 'Invalid vendor serial.' }) - try { - const vendor = await shardMarket.getVendor(serial, { - limit: intParam(req.query.limit) ?? 250, - offset: intParam(req.query.offset) ?? 0, - }) - if (!vendor) return res.status(404).json({ message: 'Unknown vendor.' }) - return res.json(await visibility.project('market', vendor, req)) - } catch (err) { - log.error('shard.getMarketVendor', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/features — the shard features THIS caller can actually see, -// so the SPA (and the Android client) can hide nav entries instead of rendering -// links that 403. Deliberately reports only what the viewer may reach: the list -// itself must not disclose the existence of a feature they're gated out of. -async function getFeatures(req, res) { - try { - const config = await visibility.getConfig() - const level = await visibility.viewerLevel(req) - return res.json({ level, features: visibility.visibleFeatures(level, config) }) - } catch (err) { - log.error('shard.getFeatures', err) - return res.status(500).json({ message: 'Internal Server Error' }) - } -} - -// GET /public/shard/stream — live-event SSE channel. What arrives depends on the -// caller's audience rung, resolved once at subscribe time; see shardBroadcast.js. -function stream(req, res) { - return broadcast.subscribe(req, res, 'public') -} - -module.exports = { - getStatus, - getFeed, - getEconomy, - getOnline, - getIdoc, - getChamps, - getGuilds, - getGovernors, - getGovernorHistory, - getPresence, - getHouses, - getRuleset, - getPointsBoards, - getPointsBoard, - getMarket, - getMarketMeta, - getMarketVendor, - getFeatures, - stream, -} diff --git a/server/src/router/v1/public/shard.router.js b/server/src/router/v1/public/shard.router.js deleted file mode 100644 index 38fb66b..0000000 --- a/server/src/router/v1/public/shard.router.js +++ /dev/null @@ -1,253 +0,0 @@ -// Public · Shard — token-free, same-origin reads of the live shard. The -// status/feed/economy/idoc/champs/guilds/governors/presence/houses endpoints read -// the site's own ingested data; nothing here round-trips the sidecar per request. -// -// Mounted at /api/v1/public/shard by public/index.js. Deliberately NOT site-mode -// gated — shard status is useful (and wanted) while the site itself is in -// maintenance. -// -// **GET /shard/stream stays anonymous.** It is consumed by logged-out browser -// visitors *and* by the Android ShardStreamClient, neither of which sends an -// Authorization header; adding requireAuth here blacks out the public live boards -// on web and mobile. The sensitive kinds (staff audit, cheat detection, login -// attempts, IPs) are withheld by utils/shardBroadcast.js, not by a route gate — -// that per-frame filtering is the security boundary, not this file. /stream is -// deliberately NOT wrapped in requireFeature either: it spans every feature, and -// each frame is gated individually against the subscriber's rung. -// -// Every other route carries `requireFeature()` (utils/shardVisibility.js), -// which 404s when an admin has disabled the feature and 403s when the caller sits -// below its configured audience. Defaults reproduce pre-v3 behavior exactly, so -// these gates are inert until an admin changes something. - -const express = require('express') -const { param, query } = require('express-validator') - -const shard = require('./shard.controller') -const validate = require('../../../middleware/validate') -const { marketLimiter } = require('../../../middleware/rateLimit') -const { requireFeature } = require('../../../utils/shardVisibility') - -const shardRouter = express.Router() - -shardRouter.get( - '/status', - requireFeature('status'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Shard connection state, online count and latest economy' - /* #swagger.responses[200] = { description: 'Shard status', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardStatus" } } } } */ - shard.getStatus, -) -shardRouter.get( - '/feed', - requireFeature('activity'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Recent notable shard events (from the ingested log)' - // #swagger.description = 'The stored-history twin of /shard/stream, and it reaches the same verdict: which kinds are returned is resolved against the caller\'s audience rung under the live visibility config, and each event\'s payload is field-projected against its own kind\'s feature. Kinds the caller may not read are omitted (an explicit ?kind= for one of them returns []), and acct/webId never appear below admin.' - // #swagger.parameters['kind'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Filter to a single event kind, e.g. vendor.sale. Returns [] if the caller may not read that kind.' } - // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max rows (default 100, max 1000).' } - /* #swagger.responses[200] = { description: 'Events, newest first', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardEvent" } } } } } */ - query('kind').optional({ values: 'falsy' }).isString().isLength({ max: 48 }), - query('limit').optional().isInt({ min: 1, max: 1000 }), - validate, - shard.getFeed, -) -shardRouter.get( - '/economy', - requireFeature('status'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Gold-supply time series (oldest → newest)' - // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max samples (default 100, max 1000).' } - /* #swagger.responses[200] = { description: 'Economy samples', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardEconomyPoint" } } } } } */ - query('limit').optional().isInt({ min: 1, max: 1000 }), - validate, - shard.getEconomy, -) -shardRouter.get( - '/online', - requireFeature('presence'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Staff online now (linked staff accounts; location is admin/moderator-only)' - /* #swagger.responses[200] = { description: 'Online players', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardOnlinePlayer" } } } } } */ - shard.getOnline, -) -shardRouter.get( - '/idoc', - requireFeature('houses'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Houses currently in danger (IDOC)' - // #swagger.description = 'Location-level board of the houses about to collapse. Owner identity and price are gated by the `houses` feature\'s field rules (default `staff`), and the owner\'s game account is admin-only always — so an anonymous caller sees name, region and coordinates only.' - /* #swagger.responses[200] = { description: 'IDOC houses', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */ - shard.getIdoc, -) -shardRouter.get( - '/champs', - requireFeature('champs'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Current champion-spawn board (all categories)' - // #swagger.description = 'The live board of every champion / mini-champ / sea-boss spawn. Update in place via the champ.update / champ.remove frames on /shard/stream.' - /* #swagger.responses[200] = { description: 'Champion spawns, ordered by name', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */ - shard.getChamps, -) -shardRouter.get( - '/guilds', - requireFeature('guilds'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Current guild board (rosters, alliances, leaders)' - // #swagger.description = 'The live board of every guild. Update in place via the guild.update / guild.remove / guild.join frames on /shard/stream.' - /* #swagger.responses[200] = { description: 'Guilds, ordered by name', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */ - shard.getGuilds, -) -shardRouter.get( - '/governors', - requireFeature('governors'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Current town-governor board (City Loyalty)' - // #swagger.description = 'One entry per city with its governor and election phase. Empty if the shard does not run the City Loyalty system. Live via city.update on /shard/stream.' - /* #swagger.responses[200] = { description: 'Cities, ordered by name', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */ - shard.getGovernors, -) -shardRouter.get( - '/governors/:city/history', - requireFeature('governors'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Governor term history for a city' - // #swagger.parameters['city'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'City name, e.g. Britain.' } - // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max terms (default 100, max 500).' } - /* #swagger.responses[200] = { description: 'Terms, newest first', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */ - param('city').isString().isLength({ min: 1, max: 40 }), - query('limit').optional().isInt({ min: 1, max: 500 }), - validate, - shard.getGovernorHistory, -) -shardRouter.get( - '/presence', - requireFeature('presence'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Online population aggregate (count + per-facet + per-region)' - // #swagger.description = 'The latest presence.online snapshot powering the "Players Online" widget. Live via presence.online on /shard/stream.' - /* #swagger.responses[200] = { description: 'Population snapshot', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */ - shard.getPresence, -) -shardRouter.get( - '/houses', - requireFeature('houses'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'House registry (owner, co-owners, price, decay)' - // #swagger.description = 'Every house seen via the house.update registry feed. `price` is the placement value, not a for-sale flag. Live via house.update / house.remove on /shard/stream.' - /* #swagger.responses[200] = { description: 'Houses, ordered by name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */ - shard.getHouses, -) -shardRouter.get( - '/ruleset', - requireFeature('ruleset'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'The shard\'s published ruleset (expansion, systems, caps, limits)' - // #swagger.description = 'How this shard is actually configured, published by the shard itself as one world.ruleset frame: expansion, which optional systems are on, skill/stat caps, account and house limits, champion scroll rules and the save/restart schedule. Served from our own store, so it renders while the shard is down; live via world.ruleset on /shard/stream. Returns `null` if the shard has never published one (an older plugin, or Bridge.RulesetEnabled=false) — distinct from a published ruleset, and the page renders it differently.' - /* #swagger.responses[200] = { description: 'The ruleset, or null if never published', content: { "application/json": { schema: { type: "object", nullable: true, additionalProperties: true } } } } */ - shard.getRuleset, -) -shardRouter.get( - '/points', - requireFeature('leaderboards'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Points / loyalty leaderboards, one board per point system' - // #swagger.description = 'Every points/loyalty leaderboard the shard publishes (Queen\'s Loyalty, Void Pool, the nine city loyalties, Clean Up Britannia, …), each with its display name, max points, participant count and top N. Served from our own store, so it renders while the shard is down; live via points.board on /shard/stream. A board\'s display name may arrive as a literal (`nameString`) or a cliloc id (`nameNumber`) — resolve clilocs client-side.' - /* #swagger.responses[200] = { description: 'Boards, ordered by display name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardPointsBoard" } } } } } */ - shard.getPointsBoards, -) -shardRouter.get( - '/points/:system', - requireFeature('leaderboards'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'One points system\'s leaderboard' - // #swagger.description = 'A single board by the shard\'s own PointsType name (e.g. `QueensLoyalty`, `CleanUpBritannia`). Returns 404 when the shard has never published that system — distinct from a published board that nobody has scored in yet, which returns 200 with an empty `top`.' - /* #swagger.parameters['system'] = { in: 'path', required: true, description: 'PointsType name, e.g. QueensLoyalty', schema: { type: 'string' } } */ - /* #swagger.responses[200] = { description: 'The board', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardPointsBoard" } } } } */ - /* #swagger.responses[400] = { description: 'Malformed system name' } */ - /* #swagger.responses[404] = { description: 'The shard has never published that system' } */ - shard.getPointsBoard, -) -// ── Marketplace ──────────────────────────────────────────────────────────── -// -// Rate-limited, unlike every other route in this file. These are the first -// genuinely expensive PUBLIC reads on the site — a LIKE scan plus a COUNT over -// what is typically the largest shard_* table, reachable with no session. -shardRouter.get( - '/market', - requireFeature('market'), - marketLimiter, - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Search the player-vendor marketplace' - // #swagger.description = 'Every priced listing on every player vendor the shard publishes — the same index the in-game Vendor Search gump reads, and it honours the same per-vendor opt-out, so a player who hid their shop in game is hidden here too. Results are LISTINGS, each carrying enough of its shop to be actionable. Served from the site\'s own tables (the sidecar is not touched), so it renders while the shard is down; `staleAt` is the oldest vendor row and the page must say how far behind the index can be — the shard sweeps vendors round-robin, so prices are inherently up to one full cycle old. Item names are resolved server-side against the cliloc table (docs/website/CLILOCS.md); on a shard that has not configured one, `displayName` is null and clients render the item id.' - // #swagger.parameters['q'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Substring match on the resolved item name or the item\'s own literal name (max 60 chars).' } - // #swagger.parameters['minPrice'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Lowest price to include.' } - // #swagger.parameters['maxPrice'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Highest price to include.' } - // #swagger.parameters['itemId'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Exact ItemID (art id) match, for "more like this".' } - // #swagger.parameters['map'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to one facet. Facet names come from the shard\'s own data; an unknown one returns an empty page.' } - // #swagger.parameters['region'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to one named region.' } - // #swagger.parameters['sort'] = { in: 'query', required: false, schema: { type: 'string', enum: ['price_asc','price_desc','recent'] }, description: 'Default price_asc. `recent` orders by when the shop was last seen.' } - // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Page size, 1..100 (default 50).' } - // #swagger.parameters['offset'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Rows to skip (default 0).' } - /* #swagger.responses[200] = { description: 'A page of listings plus the unpaginated total and the staleness stamp', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardMarketPage" } } } } */ - /* #swagger.responses[403] = { description: 'The market feature is gated above this caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[404] = { description: 'The market feature is disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - /* #swagger.responses[429] = { description: 'Rate limited', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ - query('q').optional({ values: 'falsy' }).isString().isLength({ max: 60 }), - query('minPrice').optional({ values: 'falsy' }).isInt({ min: 0, max: 999999999 }), - query('maxPrice').optional({ values: 'falsy' }).isInt({ min: 0, max: 999999999 }), - query('itemId').optional({ values: 'falsy' }).isInt({ min: 0, max: 65535 }), - query('map').optional({ values: 'falsy' }).isString().isLength({ max: 40 }), - query('region').optional({ values: 'falsy' }).isString().isLength({ max: 80 }), - query('sort').optional({ values: 'falsy' }).isIn(['price_asc', 'price_desc', 'recent']), - query('limit').optional().isInt({ min: 1, max: 100 }), - query('offset').optional().isInt({ min: 0, max: 100000 }), - validate, - shard.getMarket, -) -shardRouter.get( - '/market/meta', - requireFeature('market'), - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Marketplace size, staleness and filter options' - // #swagger.description = 'How many vendors and listings the index holds, how stale it may be (`staleAt` = the oldest vendor row, `freshAt` = the newest), and which facets and regions actually hold vendors — so a client can build its filters without running a search it will discard.' - /* #swagger.responses[200] = { description: 'Marketplace metadata', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardMarketMeta" } } } } */ - shard.getMarketMeta, -) -shardRouter.get( - '/market/vendors/:serial', - requireFeature('market'), - marketLimiter, - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'One player vendor and everything it is selling' - // #swagger.description = 'A single shop by its vendor serial, with its listings. `truncated` (and `total` exceeding `count`) means the shop holds more than the shard publishes per frame — a commodity reseller with thousands of stacks is a real thing, and the page says so rather than presenting a partial shop as complete. Returns 404 for a serial the index has never seen, which also covers a vendor since dismissed or hidden.' - /* #swagger.parameters['serial'] = { in: 'path', required: true, description: 'Vendor serial, e.g. 0x40001234', schema: { type: 'string' } } */ - // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Listings to return, 1..500 (default 250).' } - // #swagger.parameters['offset'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Listings to skip (default 0).' } - /* #swagger.responses[200] = { description: 'The vendor', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardMarketVendor" } } } } */ - /* #swagger.responses[400] = { description: 'Malformed vendor serial' } */ - /* #swagger.responses[404] = { description: 'No such vendor in the index' } */ - param('serial').isString().isLength({ max: 20 }), - query('limit').optional().isInt({ min: 1, max: 500 }), - query('offset').optional().isInt({ min: 0, max: 100000 }), - validate, - shard.getMarketVendor, -) -shardRouter.get( - '/features', - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Shard features visible to the caller (drives client nav)' - // #swagger.description = 'The caller\'s audience rung plus the shard features they may reach, so a client can hide nav entries instead of rendering links that 403. Reports only what the caller can see — the list itself does not disclose gated features.' - /* #swagger.responses[200] = { description: 'Visible features', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardFeatures" } } } } */ - shard.getFeatures, -) -shardRouter.get( - '/stream', - // #swagger.tags = ['Public · Shard'] - // #swagger.summary = 'Live shard event stream (Server-Sent Events, filtered by audience)' - // #swagger.description = 'text/event-stream of live events. The caller\'s audience rung is resolved once at subscribe time and frozen for the connection; each frame is then gated on its feature and field-projected, so sensitive kinds and fields (staff audit, cheat detection, login attempts, IPs, acct/webId) never reach a caller below their configured rung.' - /* #swagger.responses[200] = { description: 'An SSE stream (Content-Type: text/event-stream).' } */ - shard.stream, -) - -module.exports = shardRouter diff --git a/server/src/utils/clilocParse.js b/server/src/utils/clilocParse.js deleted file mode 100644 index cf1a113..0000000 --- a/server/src/utils/clilocParse.js +++ /dev/null @@ -1,287 +0,0 @@ -// Cliloc parsing — the pure half. -// -// A "cliloc" is UO's localization table: an integer id mapped to a display -// string. Items carry a `LabelNumber` rather than a name, so without this table -// the site can only render `id 1023721` where the game shows "quarter staff". -// The shard already sends the id on every equipment entry (`char.profile`'s -// `cliloc` field) and will send one per marketplace listing — the *number* was -// never the missing piece, the *table* was. -// -// This module is fs-free on purpose, exactly like `spawnAtlasParse.js`: the -// suite runs in CI where there is no UO client, so every parser here is driven -// from inline fixtures. `clilocSource.js` is the only thing that touches disk. -// -// ── Two input formats, and why ───────────────────────────────────────────── -// -// The client's own `Cliloc.enu` is COMPRESSED (Mythic format) on any modern -// client, and decompressing it is a bit-level port of an inverse-BWT coder that -// nothing in this stack needs at runtime. ServUO's own bundled `Ultima.StringList` -// cannot read it either — which is why `VendorSearch.GetItemName` is already inert -// on such a shard and the plugin could not supply names even if we asked it to. -// -// So the operator converts once, from their own client, and points the site at -// the result (see docs/website/CLILOCS.md). Two shapes are accepted because -// different tools produce different things: -// -// • PLAIN BINARY — the pre-compression cliloc layout: a 6-byte header, then -// records of {int32 number, byte flag, uint16 length, UTF-8 bytes}. -// • DELIMITED TEXT — `numbertext` per line, which is what the common -// GUI exports emit. Quoted CSV fields and a header row are tolerated. -// -// Nothing derived from the client is ever committed: the converted file lives at -// an operator-supplied path and is gitignored, the same rule the spawn atlas art -// map already follows. - -/** Raised for a file we can identify but deliberately refuse to guess at. */ -class ClilocFormatError extends Error { - constructor(message, code) { - super(message) - this.name = 'ClilocFormatError' - this.code = code - } -} - -/** - * Bumped when this parser produces DIFFERENT data from an IDENTICAL source file. - * - * Stored beside the source hash so the boot path can tell "same file, but the - * parser moved on" from "same file, nothing to do". Without it a corrected parse - * would ship and never reach an install whose cliloc file never changes — the - * trap `spawnAtlasSource.PARSER_VERSION` documents. - */ -const PARSER_VERSION = 1 - -// The plain layout's header is `02 00 00 00 01 00` — a 4-byte version and a -// 2-byte language marker. Only the size matters for parsing; the values are -// checked to sniff the format, not to validate it. -const HEADER_BYTES = 6 -const RECORD_HEADER_BYTES = 7 // int32 number + byte flag + uint16 length - -// Every compressed cliloc file the client ships begins with a DWORD whose high -// byte is 0x8E (the XOR key UOFiddler calls `HeaderXorKey`, 0x8E2C9A3D). That is -// the single cheapest way to tell an operator they exported the wrong file — -// without it, the plain parser happily reads compressed bytes as ~19k records of -// negative ids and 60 KB "strings" before dying somewhere in the middle, and the -// resulting error names the wrong problem. -const MYTHIC_HIGH_BYTE = 0x8e - -/** True when `buffer` is a Mythic-compressed cliloc rather than the plain layout. */ -function isCompressedCliloc(buffer) { - return buffer.length >= 4 && buffer[3] === MYTHIC_HIGH_BYTE -} - -/** - * Parse the plain binary cliloc layout. - * - * Strict about truncation, and that strictness is load-bearing: a half-copied or - * partly-written file is the realistic failure here, and it must fail loudly - * rather than import a silently short table that then renders half the world as - * `id 1023721`. A record that runs past the end of the buffer throws. - */ -function parseClilocBinary(buffer) { - if (!Buffer.isBuffer(buffer)) throw new ClilocFormatError('Not a buffer', 'NOT_BUFFER') - if (isCompressedCliloc(buffer)) { - throw new ClilocFormatError( - 'This is a compressed (Mythic-format) cliloc file, which the site cannot read. ' + - 'Convert it to the plain format first — see docs/website/CLILOCS.md.', - 'COMPRESSED', - ) - } - if (buffer.length < HEADER_BYTES) { - throw new ClilocFormatError('File is shorter than a cliloc header', 'TRUNCATED') - } - - const entries = [] - let offset = HEADER_BYTES - - while (offset < buffer.length) { - if (offset + RECORD_HEADER_BYTES > buffer.length) { - throw new ClilocFormatError( - `Truncated record header at byte ${offset} (${entries.length} entries read)`, - 'TRUNCATED', - ) - } - const number = buffer.readInt32LE(offset) - const flag = buffer.readUInt8(offset + 4) - // The length is written by the client as an unsigned 16-bit value. Reading it - // signed (as ServUO's own SDK does) turns any string over 32 KB into a - // negative length; real tables top out around 12 KB, so this has no effect on - // current data and costs nothing to get right. - const length = buffer.readUInt16LE(offset + 5) - offset += RECORD_HEADER_BYTES - - if (offset + length > buffer.length) { - throw new ClilocFormatError( - `Truncated record body at byte ${offset} (${entries.length} entries read)`, - 'TRUNCATED', - ) - } - entries.push({ number, flag, text: buffer.toString('utf8', offset, offset + length) }) - offset += length - } - - return entries -} - -// A delimited line splits on the FIRST separator only: cliloc text is full of -// commas ("a scroll of magery, unfinished") and splitting on all of them would -// truncate every such entry at its first comma. -const TEXT_SEPARATORS = ['\t', ',', ';'] - -/** Unwrap one CSV field: strip surrounding quotes and unescape doubled quotes. */ -function unquote(value) { - const trimmed = value.trim() - if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) { - return trimmed.slice(1, -1).replace(/""/g, '"') - } - return trimmed -} - -/** - * Parse a delimited text export: `numbertext` per line. - * - * Tolerant by design — this is whatever an operator's GUI tool produced, not a - * format we control. A header row, blank lines, `#` comments and a trailing - * flags column are all ignored. A line whose first field is not an integer is - * skipped rather than fatal, because that is exactly what a header row is. - * - * The one thing it will NOT do is return an empty table quietly: a file that - * yields no entries at all is a wrong file, not an empty one. - */ -function parseClilocText(text) { - const entries = [] - for (const line of String(text).split(/\r?\n/)) { - // The line is deliberately NOT trimmed before the separator search. Roughly - // half of a real cliloc table is empty strings (unused ids), which export as - // `1005008` — and trimming eats that trailing separator, leaving a bare - // number that then looks like a header row and is skipped. That silently - // dropped 55,994 of 123,490 entries. Individual FIELDS are trimmed instead, - // by `unquote`. - if (line.trim() === '' || line.trimStart().startsWith('#')) continue - - // Pick the separator that actually appears first, so a tab-delimited line - // whose text contains a comma still splits on the tab. - let cut = -1 - for (const sep of TEXT_SEPARATORS) { - const at = line.indexOf(sep) - if (at !== -1 && (cut === -1 || at < cut)) cut = at - } - if (cut === -1) continue - - // An EMPTY first field must not become id 0: `Number('')` is 0, not NaN, so - // a line that merely starts with a separator would otherwise import as a - // bogus cliloc 0 instead of being skipped. - const head = unquote(line.slice(0, cut)) - if (head === '') continue - const number = Number(head) - if (!Number.isInteger(number)) continue // header row, or a wrapped line - - let rest = line.slice(cut + 1) - // Some exports carry `number,flag,text`. A bare integer in the second field - // is a flag; anything else is the text itself (and a text field that IS just - // a number is indistinguishable, so it stays as the text — the safer miss). - let flag = 0 - for (const sep of TEXT_SEPARATORS) { - const at = rest.indexOf(sep) - if (at === -1) continue - const head = unquote(rest.slice(0, at)) - if (/^\d{1,3}$/.test(head) && rest.slice(at + 1).trim() !== '') { - flag = Number(head) - rest = rest.slice(at + 1) - } - break - } - - entries.push({ number, flag, text: unquote(rest) }) - } - - if (entries.length === 0) { - throw new ClilocFormatError('No cliloc entries found in the text export', 'EMPTY') - } - return entries -} - -/** - * Parse either supported shape, sniffing which one this is. - * - * The sniff is on the binary header rather than the file extension: operators - * name these things whatever they like, and an `.enu` that is really a TSV (or a - * `.txt` that is really binary) should still import. - */ -function parseCliloc(buffer) { - const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer) - - if (isCompressedCliloc(buf)) { - throw new ClilocFormatError( - 'This is a compressed (Mythic-format) cliloc file, which the site cannot read. ' + - 'Convert it to the plain format first — see docs/website/CLILOCS.md.', - 'COMPRESSED', - ) - } - - // The plain layout always opens with version 2 / language 1. Anything else is - // treated as text, which is the recoverable guess: a mis-sniffed text file - // yields "no entries found", while a mis-sniffed binary yields nonsense. - if (buf.length >= HEADER_BYTES && buf.readInt32LE(0) === 2 && buf.readUInt16LE(4) === 1) { - return parseClilocBinary(buf) - } - return parseClilocText(buf.toString('utf8')) -} - -// ── Display ──────────────────────────────────────────────────────────────── - -// Cliloc strings interpolate arguments the client supplies out of an item's -// property list: `~1_val~`, `~2_NAME~`, `~1_ITEM~`. We never have those — the -// bridge sends the id, not the packet — so a name carrying them must be reduced -// to what is actually knowable rather than shown with the raw tokens in it. -const PLACEHOLDER_RE = /~\d+_[^~]*~/g - -/** - * Reduce a raw cliloc string to something displayable. - * - * Placeholders are dropped and the leftover punctuation tidied, so - * `"[~1_stuff~]"` becomes `""` (correctly nothing — the whole string was the - * argument) and `"cold damage ~1_val~%"` becomes `"cold damage"`. - * - * **Punctuation is only tidied when a placeholder was actually removed.** The - * trailing `%` above is the unit belonging to the number we never had, and the - * brackets in `[~1_stuff~]` only ever wrapped the argument — but a string with - * no placeholder has no such debris, and trimming it anyway corrupts real names. - * A shard's `"Runic Gateway Sigil (v2)"` came back as `"(v2"` while this was - * unconditional. - * - * Returns `''` when nothing survives, which callers treat as "no name" and fall - * back to the item id — better than showing a bracket. - */ -const DEBRIS = /^[\s\-–—,.;:%[\]()]+|[\s\-–—,.;:%[\]()]+$/g - -function displayText(raw) { - if (raw == null) return '' - const source = String(raw) - const hadPlaceholder = PLACEHOLDER_RE.test(source) - PLACEHOLDER_RE.lastIndex = 0 // the regex is global; `test` advances it - - if (!hadPlaceholder) return source.replace(/\s+/g, ' ').trim() - - return source - .replace(PLACEHOLDER_RE, ' ') - .replace(/\s+/g, ' ') - .replace(/\s+([,.;:!?])/g, '$1') - .replace(DEBRIS, '') - .trim() -} - -/** True when a raw cliloc string is nothing but interpolated arguments. */ -const isPlaceholderOnly = (raw) => raw != null && String(raw).trim() !== '' && displayText(raw) === '' - -module.exports = { - ClilocFormatError, - PARSER_VERSION, - HEADER_BYTES, - isCompressedCliloc, - parseCliloc, - parseClilocBinary, - parseClilocText, - displayText, - isPlaceholderOnly, -} diff --git a/server/src/utils/clilocSource.js b/server/src/utils/clilocSource.js deleted file mode 100644 index 93ae061..0000000 --- a/server/src/utils/clilocSource.js +++ /dev/null @@ -1,316 +0,0 @@ -// Cliloc table — the filesystem layer. -// -// `clilocParse.js` holds the pure parsers; this module is the only thing that -// touches cliloc files on disk, and it is shared by both callers: -// -// - the server, which refreshes the table on boot (`shardClilocs.model.js`) -// - the admin panel, which can force a reimport without a restart -// -// The files are the OPERATOR'S (see docs/website/CLILOCS.md). Nothing derived -// from them is committed: the repo holds no string table, exactly as it holds no -// map snapshot and no artwork. That rule is why this module reads a configured -// path instead of a path inside the repo. -// -// ── Why this reads a SET of files, not one ──────────────────────────────── -// -// Shards edit items and add new ones. Those carry cliloc ids that a stock client -// table does not have — and forcing a 5 MB client re-export every time an -// operator adds one item would be miserable enough that the table would simply -// go stale, which is the exact failure the spawn atlas was redesigned to avoid. -// -// So this mirrors `spawnAtlasSource.readSources()`: a BASE table (the converted -// client file) plus every operator-maintained OVERLAY beside it, all re-read on -// every boot and hash-gated as a SET. Adding, editing or removing any overlay -// counts as drift and re-imports. Later sources win, so an overlay both adds new -// ids and overrides stock ones. -// -// Measured on a real shard: the script tree references 16,434 cliloc ids and only -// 37 are absent from the stock client table. Tens of entries against a 67k base -// is what makes the overlay the right shape rather than a second full table. -// -// Reading and hashing ~5 MB costs a few milliseconds and a full parse ~50 ms, so -// the boot path hashes first and only parses when something actually changed. - -const crypto = require('crypto') -const fs = require('fs') -const path = require('path') - -const { ClilocFormatError, PARSER_VERSION, parseCliloc, isCompressedCliloc } = require('./clilocParse') - -/** - * Filenames looked for as the BASE table when the configured path is a directory. - * - * Ordered by how specific they are: an explicitly converted file wins over - * something that merely sits in a client folder, so an operator who dropped a - * `cliloc.plain.enu` next to the original compressed `cliloc.enu` gets the one - * they made rather than the one that will be rejected. - * - * Matching is case-insensitive against the real directory listing, because the - * client ships `Cliloc.enu` on Windows and the site usually runs on Linux, where - * a hardcoded lowercase open would simply miss. - */ -const CANDIDATE_NAMES = [ - 'clilocs.tsv', - 'clilocs.csv', - 'clilocs.plain', - 'cliloc.plain', - 'cliloc.plain.enu', - 'cliloc.enu.plain', - 'clilocs.txt', - 'cliloc.enu', -] - -/** - * Where shard-specific additions and overrides live: a `custom/` directory - * beside the base table. - * - * ServUO has **no server-side convention** for custom clilocs — they live in the - * patched client file a shard distributes to its players, and nothing in the - * tree declares them. There is therefore nothing to discover, and this is the - * one place in the cliloc pipeline that is a convention we chose rather than one - * the shard already has. It is a directory rather than a single file so an - * operator can keep additions grouped however they like (per system, per patch) - * without the site caring. - */ -const CUSTOM_DIR = 'custom' -const CUSTOM_EXTENSIONS = ['.tsv', '.csv', '.txt', '.enu', '.plain'] - -class ClilocSourceError extends Error { - constructor(message, code) { - super(message) - this.name = 'ClilocSourceError' - this.code = code - } -} - -function sha256(buffer) { - return crypto.createHash('sha256').update(buffer).digest('hex') -} - -/** - * Resolve the configured path to `{ root, base }`. - * - * Accepts either a direct file path or a directory to search, because operators - * reasonably supply both — "here is the file" and "here is the folder I put it - * in" are equally natural answers to the admin panel's prompt. When it is a - * file, `root` is the directory CONTAINING it, so overlays work either way: an - * operator who pointed at a file should not have to re-point at its folder just - * to add a `custom/` directory next to it. - */ -function resolveBase(configured) { - if (!configured || String(configured).trim() === '') { - throw new ClilocSourceError('No cliloc path configured', 'NO_PATH') - } - const target = String(configured).trim() - - let stat - try { - stat = fs.statSync(target) - } catch { - throw new ClilocSourceError(`Cliloc path does not exist: ${target}`, 'NOT_FOUND') - } - - if (stat.isFile()) return { root: path.dirname(target), base: target } - - if (!stat.isDirectory()) { - throw new ClilocSourceError(`Cliloc path is neither a file nor a directory: ${target}`, 'NOT_FOUND') - } - - let listing - try { - listing = fs.readdirSync(target) - } catch { - throw new ClilocSourceError(`Cliloc directory is not readable: ${target}`, 'NOT_FOUND') - } - - const byLower = new Map(listing.map((name) => [name.toLowerCase(), name])) - for (const candidate of CANDIDATE_NAMES) { - const actual = byLower.get(candidate) - if (actual) return { root: target, base: path.join(target, actual) } - } - - throw new ClilocSourceError( - `No cliloc file found in ${target} (looked for ${CANDIDATE_NAMES.join(', ')})`, - 'NO_FILE', - ) -} - -/** Overlay files under `/custom/`, sorted so precedence is deterministic. */ -function listCustom(root) { - const dir = path.join(root, CUSTOM_DIR) - let listing - try { - listing = fs.readdirSync(dir, { withFileTypes: true }) - } catch (err) { - // No overlay directory is the normal case, not an error. - if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return [] - throw new ClilocSourceError(`Cliloc overlay directory is not readable: ${dir}`, 'UNREADABLE') - } - return listing - .filter((e) => e.isFile() && CUSTOM_EXTENSIONS.includes(path.extname(e.name).toLowerCase())) - .map((e) => e.name) - .sort() - .map((name) => path.join(dir, name)) -} - -function readFileOrThrow(file) { - try { - return fs.readFileSync(file) - } catch { - throw new ClilocSourceError(`Cliloc file is not readable: ${file}`, 'UNREADABLE') - } -} - -/** - * Read every cliloc source under the configured path. - * - * Returns `{ root, files: [{ label, kind, file, buffer, sha256, bytes, compressed }] }` - * with the base first and overlays after, in the order they must be merged. - * - * Labels are root-relative and forward-slashed so a hash map compares equal - * across platforms — the same directory read on Windows and Linux must produce - * the same fingerprint, or every boot would look like a change. (The same - * reasoning, and the same bug, as `spawnAtlasSource.readSources`.) - */ -function readSources(configured) { - const { root, base } = resolveBase(configured) - - const describe = (file, kind) => { - const buffer = readFileOrThrow(file) - return { - label: path.relative(root, file).split(path.sep).join('/'), - kind, - file, - buffer, - sha256: sha256(buffer), - bytes: buffer.length, - compressed: isCompressedCliloc(buffer), - } - } - - const files = [describe(base, 'base')] - for (const overlay of listCustom(root)) files.push(describe(overlay, 'custom')) - - return { root, files } -} - -/** - * A fingerprint of every source: `{ "