wtclaude
8e03497eb3
EVENTS_PLAN.md Phase 1. Six of the nine core tables — the ones that do not
depend on the module contract — plus definitions CRUD, publish, archive, and
the action registry with core as its first registrant.
**Nothing dispatches.** There is no runner until Phase 2, so a run row is
created and stays `scheduled`. That is this phase's correct answer and the
surface renders it verbatim rather than hiding it.
Schema (`db/schema.sql`, append-only):
event_series, event_definitions, event_versions, event_runs,
event_run_steps, event_run_log. The four that need a writer —
event_action_settings, event_run_budget, event_run_resources,
event_run_participants — arrive with the phases that give them one.
Registry (`modules/registries.js` + `config/coreEventActions.js`):
registerEventActions staging and commit, with its own id namespace, the
closed risk and reversibility sets, revert() required iff and only iff
reversible: 'ledger', a bounded budgetMs and a param shape whose every
entry needs a type and an example. perform/revert/cost are stripped from
everything the catalog serves. Core declares core.announce, core.wait and
core.cue through the same staging area a module will use.
It is reachable ONLY by registerCore(): loader.js builds its own api facade
and has no method that delegates here, so no module can call it and
MODULE_API_VERSION is untouched. Phase 7 adds the facade and the bump.
Surface (13 routes under /api/v1/admin/events):
Reads staff-wide; publish, archive and run creation admin-only from this
phase per EVENTS.md §N2, even though the switchboard they will consult does
not exist yet — a button that is admin-only later and open now is a gate
nobody notices was missing. The live run controls and `verify` are absent
rather than stubbed, because nothing is in flight yet.
Four things the build settled, all recorded in docs:
- event_definitions gained a `spec` column. A draft's working copy cannot
be an event_versions row: that table is immutable and a run pins one.
- The spec validator must accept its own output. It added `actionVersion`
and `dormant` and then refused them as unknown keys, which would have made
the second save of any definition — and publish's re-validation —
impossible. A test caught it; both are now accepted and recomputed.
- A param's `example` is required, optional params included, matching
registerEventTriggers. It is the authoring form's placeholder.
- Two routes the §API-surface table did not name: GET /admin/events/:id and
GET /admin/events/series.
Core's three perform() bodies answer { ok: false, retry: false } rather than
{ ok: true }: `ok: true` on an action that did nothing is a recorded world
change that did not occur, which is the exact mistake §F's failure default
exists to prevent.
`conditions.checkLiteral` is exported and reused for step-param type checking
— one switch over the six types, so "is this a datetime" has one answer.
Verified: 44 new tests, whole server suite, `npm run check:modules`, routes
manifest and swagger regenerated (the manifest diff is +13 routes, zero moved).
Docs: RunicGateway/docs#209
Co-Authored-By: Claude <noreply@anthropic.com>
122 lines
6.6 KiB
JavaScript
122 lines
6.6 KiB
JavaScript
// /api/v1/admin — the admin surface, assembled from per-capability routers.
|
|
//
|
|
// This file owns exactly two things: the gate every admin route shares, and the
|
|
// mount table. No route is declared here. Each capability router mounts at the
|
|
// prefix it already owned inside the old monolithic admin.routes.js, so the
|
|
// emitted URL set is byte-identical — proved per PR by a zero-line diff in
|
|
// server/routes.manifest.json (`npm run routes:manifest`).
|
|
//
|
|
// The admin group is fully split as of PR 4: admin.routes.js is gone and every
|
|
// one of the 110 admin routes is declared in a capability router below.
|
|
//
|
|
// See docs/website/API_V2_PLAN.md § Phase 2 for the split.
|
|
|
|
const express = require('express')
|
|
|
|
const { isLoggedIn, requireRole } = require('../../../utils/auth')
|
|
const noindex = require('../../../middleware/noindex')
|
|
|
|
const usersRouter = require('./users.router')
|
|
const invitesRouter = require('./invites.router')
|
|
const authProvidersRouter = require('./authProviders.router')
|
|
const moderationRouter = require('./moderation.router')
|
|
const botActivityRouter = require('./botActivity.router')
|
|
const activityRouter = require('./activity.router')
|
|
const postsRouter = require('./posts.router')
|
|
const uploadsRouter = require('./uploads.router')
|
|
const wikiRouter = require('./wiki.router')
|
|
const pagesRouter = require('./pages.router')
|
|
const emailRouter = require('./email.router')
|
|
const discordBotRouter = require('./discordBot.router')
|
|
const settingsRouter = require('./settings.router')
|
|
const modulesRouter = require('./modules.router')
|
|
const engagementRouter = require('./engagement.router')
|
|
const eventsRouter = require('./events.router')
|
|
const teamsRouter = require('./teams.router')
|
|
const teamsVoiceRouter = require('./teamsVoice.router')
|
|
const dashboardRouter = require('./dashboard.router')
|
|
|
|
const adminRouter = express.Router()
|
|
|
|
// Every admin route requires auth, a STAFF role, and is kept out of search
|
|
// indexes. The staff gate matters now that `player` is a logged-in-but-untrusted
|
|
// role: without it, the editor-tier routes below (dashboard, posts, wiki,
|
|
// uploads) that are only guarded by isLoggedIn would be reachable by players.
|
|
// Players get 403 here and use the self-scoped /player group instead.
|
|
//
|
|
// It lives here, ahead of every mount, so a capability router extracted in a
|
|
// later PR cannot silently ship without it.
|
|
const staffOnly = requireRole('admin', 'editor', 'moderator')
|
|
adminRouter.use(noindex, isLoggedIn, staffOnly)
|
|
|
|
adminRouter.use('/users', usersRouter)
|
|
adminRouter.use('/invites', invitesRouter)
|
|
// Mounted at /auth, not /auth/providers: /admin/auth is the capability, and the
|
|
// routes inside read as /providers[/:id].
|
|
adminRouter.use('/auth', authProvidersRouter)
|
|
// /moderation carries its own moderator gate; /bot-activity is admin-only per
|
|
// route. /activity is staff-wide — the audit log, not the bot-scoring state.
|
|
adminRouter.use('/moderation', moderationRouter)
|
|
adminRouter.use('/bot-activity', botActivityRouter)
|
|
adminRouter.use('/activity', activityRouter)
|
|
// Content, all editor-tier (no gate beyond staffOnly above). /uploads is the
|
|
// rich-text editors' generalized upload; /posts owns its own /posts/upload.
|
|
adminRouter.use('/posts', postsRouter)
|
|
adminRouter.use('/uploads', uploadsRouter)
|
|
adminRouter.use('/wiki', wikiRouter)
|
|
adminRouter.use('/pages', pagesRouter)
|
|
// Ops and configuration.
|
|
//
|
|
// `/shard` and `/uo-link` are absent here and are still served: they are
|
|
// module-uo's, mounted onto this same router by the loader after every core
|
|
// mount above (MODULE_API.md §2.4). The URLs did not move — the code did. That
|
|
// ordering is also what makes the prefixes unclaimable by anyone else: the
|
|
// loader asks this live router what core owns, so a second module claiming
|
|
// `/shard` is rejected against the mounts actually present, not against a list.
|
|
adminRouter.use('/email', emailRouter)
|
|
adminRouter.use('/discord-bot', discordBotRouter)
|
|
adminRouter.use('/settings', settingsRouter)
|
|
// The Modules screen (Phase 4). Core's, not a module's — and it has to be
|
|
// core's: it is how a module gets onto the volume in the first place. Mounted
|
|
// here alongside the other configuration capabilities, and admin-only per route
|
|
// rather than at this line, so the gate sits next to what it is guarding.
|
|
adminRouter.use('/modules', modulesRouter)
|
|
// The engagement catalog (ENGAGEMENT.md Phase 2). Read-only for now — the two
|
|
// routes serve what core and the installed modules DECLARED, so there is no
|
|
// table behind it and nothing to configure yet. Rules, templates and the send log
|
|
// land under this same prefix in Phases 4 and 5. Admin-only per route, like
|
|
// /modules above and for a related reason: this is the surface that decides who
|
|
// the site sends mail to.
|
|
adminRouter.use('/engagement', engagementRouter)
|
|
// The Event System (EVENTS.md § API surface, Phase 1). Staff-wide for the reads
|
|
// and gated per route for the writes, which is where §N2's asymmetry lives:
|
|
// publish and start are `admin` ONLY, while the live run controls Phase 3 adds
|
|
// are `admin` + `moderator`. Starting commits the deployment to an unattended
|
|
// world change; cancelling is incident response, and they are deliberately not
|
|
// the same gate.
|
|
adminRouter.use('/events', eventsRouter)
|
|
// Teams. Staff-wide, like /activity: a moderator runs the reserved-name review
|
|
// queue. The three actions that PUBLISH untrusted game-sourced strings are gated
|
|
// per request inside the controller, not per route — a moderator may call them,
|
|
// and calling them files a request rather than applying one (TEAMS.md §2.9).
|
|
// Voice channels (TEAMS.md §7.3, phase 9) are mounted at the more specific prefix
|
|
// FIRST, so /teams/voice/* never reaches the teams router's `/:id`.
|
|
//
|
|
// The voice routes live in their own file, and the mount is out here rather than
|
|
// in that file, because phase 9 believed swagger-autogen enforced a per-file route
|
|
// limit that `teams.router.js` was sitting on. It does not: the generator's
|
|
// runaway is triggered by an expression reaching `.test(` inside a route
|
|
// statement, which that file had and has since had hoisted. The arrangement is
|
|
// kept on its own merits — voice is its own capability — but neither the split nor
|
|
// the placement of this mount is load-bearing any more.
|
|
adminRouter.use('/teams/voice', teamsVoiceRouter)
|
|
adminRouter.use('/teams', teamsRouter)
|
|
|
|
// The two singletons that own no path segment of their own: GET /dashboard and
|
|
// PUT /site-mode. Mounted at the group root, last, exactly where the residual
|
|
// admin.routes.js used to sit — safe because dashboard.router.js declares no
|
|
// router-level middleware, only its two routes.
|
|
adminRouter.use('/', dashboardRouter)
|
|
|
|
module.exports = adminRouter
|