refactor(server): split public, player and residual auth into capability routers (PR 5)
The last split PR of docs/website/API_V2_PLAN.md § Phase 2. public.routes.js,
player.routes.js and auth.routes.js are deleted; each group is now a directory
whose index.js owns the group gate and the mount table and declares no routes.
Every one of the 200 manifest routes is now in a capability router.
public/ posts (2) wiki (4) pages (2) shard (12) site (4, group root)
player/ account (8) shard (8) appeals (4), behind noindex + requireAuth
auth/ login (2) register (1) invite (2) password (3) session (2, root)
No URL moves. All four gates zero-diff: routes.manifest.json (200 public + 2
internal), routes.guards.json, swagger-output.json (198 operations), and
docs/website/api-route-inventory.json was already in sync. 434 tests green.
Notes on the non-mechanical parts:
- public/index.js and auth/index.js carry no group gate, deliberately, and say
so. The public surface is anonymous by contract (logged-out SPA, Discord bot,
Android ShardStreamClient on /public/shard/stream); /auth is where a caller
becomes authenticated. player/index.js gates on requireAuth only, never
requireRole('player') — staff are a superset of players.
- GET /auth/me has a mount-order dependency: use('/me', meRouter) matches the
bare /me, so the request runs meRouter's noindex + requireAuth and falls
through. session.router.js must stay mounted last. Verified by the
counterfactual — mounting it first still 401s but drops X-Robots-Tag, which
no manifest or guards file can see.
- loginGuards moved to auth/loginGuards.js (frozen) rather than being copied
into the three routers that spread it; sso.routes.js drops its duplicate.
- The :param shadowing check was re-run in dispatch order against the built
stack: 86 routes, 64 literal, none shadowed. /public/wiki/{categories,tags}
ahead of /:slug is the only ordering-sensitive pair.
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
43
server/src/router/v1/public/index.js
Normal file
43
server/src/router/v1/public/index.js
Normal file
@@ -0,0 +1,43 @@
|
||||
// /api/v1/public — the anonymous public surface, assembled from per-capability
|
||||
// routers.
|
||||
//
|
||||
// This file owns the mount table and nothing else; no route is declared here.
|
||||
// Each capability router mounts at the prefix it already owned inside the old
|
||||
// monolithic public.routes.js, so the emitted URL set is byte-identical — proved
|
||||
// by a zero-line diff in server/routes.manifest.json (`npm run routes:manifest`).
|
||||
//
|
||||
// **There is deliberately no group gate.** Unlike /admin (staffOnly) and /player
|
||||
// (requireAuth), this group is unauthenticated by design and must stay that way:
|
||||
// the SPA renders logged-out, the Discord bot reads it anonymously, and the
|
||||
// Android app's ShardStreamClient consumes /public/shard/stream with no
|
||||
// Authorization header. Content visibility during maintenance is handled by the
|
||||
// per-route `siteMode` middleware, not by an auth gate.
|
||||
//
|
||||
// See docs/website/API_V2_PLAN.md § Phase 2 for the split.
|
||||
|
||||
const express = require('express')
|
||||
|
||||
const postsRouter = require('./posts.router')
|
||||
const wikiRouter = require('./wiki.router')
|
||||
const pagesRouter = require('./pages.router')
|
||||
const shardRouter = require('./shard.router')
|
||||
const siteRouter = require('./site.router')
|
||||
|
||||
const publicRouter = express.Router()
|
||||
|
||||
// Content. All three are site-mode gated per route (the /pages draft-preview
|
||||
// route is the one deliberate exception — see pages.router.js).
|
||||
publicRouter.use('/posts', postsRouter)
|
||||
publicRouter.use('/wiki', wikiRouter)
|
||||
publicRouter.use('/pages', pagesRouter)
|
||||
// Live shard data, never site-mode gated.
|
||||
publicRouter.use('/shard', shardRouter)
|
||||
|
||||
// The four singletons that own no path segment of their own: /settings, /status,
|
||||
// /version and /contact. Mounted at the group root, last — safe only because
|
||||
// site.router.js declares no router-level middleware (a bare `use(gate)` in a
|
||||
// root-mounted router runs for every request passing through toward another
|
||||
// mount). Same arrangement as admin/dashboard.router.js.
|
||||
publicRouter.use('/', siteRouter)
|
||||
|
||||
module.exports = publicRouter
|
||||
40
server/src/router/v1/public/pages.router.js
Normal file
40
server/src/router/v1/public/pages.router.js
Normal file
@@ -0,0 +1,40 @@
|
||||
// Public · Pages — the block-based CMS pages, read side. Counterpart of
|
||||
// admin/pages.router.js (the page builder). Unrelated to /admin/shard/pages,
|
||||
// which is the in-game help-page queue.
|
||||
//
|
||||
// Mounted at /api/v1/public/pages by public/index.js. No group gate.
|
||||
//
|
||||
// Declaration order is load-bearing: the draft-preview route is registered ahead
|
||||
// of /:slug, and it is deliberately NOT site-mode gated so a preview link keeps
|
||||
// working during maintenance — the single-use token is the access control.
|
||||
|
||||
const express = require('express')
|
||||
|
||||
const ctrl = require('./public.controller')
|
||||
const siteMode = require('../../../middleware/siteMode')
|
||||
|
||||
const pagesRouter = express.Router()
|
||||
|
||||
pagesRouter.get(
|
||||
'/:id/preview/:token',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Render a page from a draft-preview token'
|
||||
// #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Page id.' }
|
||||
// #swagger.parameters['token'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Preview token from POST /admin/pages/:id/preview.' }
|
||||
/* #swagger.responses[200] = { description: 'The page (any status)', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
|
||||
/* #swagger.responses[404] = { description: 'Token invalid/expired or page missing', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
ctrl.getPagePreview,
|
||||
)
|
||||
pagesRouter.get(
|
||||
'/:slug',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Get a published CMS page by slug'
|
||||
// #swagger.description = 'Drafts 404 for the public; staff sessions see drafts. Gated by site mode.'
|
||||
// #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Page slug.' }
|
||||
/* #swagger.responses[200] = { description: 'The page', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
|
||||
/* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
siteMode,
|
||||
ctrl.getPage,
|
||||
)
|
||||
|
||||
module.exports = pagesRouter
|
||||
39
server/src/router/v1/public/posts.router.js
Normal file
39
server/src/router/v1/public/posts.router.js
Normal file
@@ -0,0 +1,39 @@
|
||||
// Public · Posts — the published news / five-on-friday / newsletter / screenshots
|
||||
// feed. The read-only counterpart of admin/posts.router.js, sharing the same
|
||||
// posts model through public.controller.
|
||||
//
|
||||
// Mounted at /api/v1/public/posts by public/index.js. No group gate: this is the
|
||||
// anonymous public surface. `siteMode` is applied per route — during maintenance
|
||||
// only an admin with a valid session sees content.
|
||||
|
||||
const express = require('express')
|
||||
|
||||
const ctrl = require('./public.controller')
|
||||
const siteMode = require('../../../middleware/siteMode')
|
||||
|
||||
const postsRouter = express.Router()
|
||||
|
||||
postsRouter.get(
|
||||
'/:category',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'List published posts in a category'
|
||||
// #swagger.description = 'Gated by site mode: during maintenance only admins with a valid session see content.'
|
||||
// #swagger.parameters['category'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'news | five-on-friday | newsletter | screenshots' }
|
||||
/* #swagger.responses[200] = { description: 'Published posts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Post" } } } } } */
|
||||
/* #swagger.responses[404] = { description: 'Unknown category', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
siteMode,
|
||||
ctrl.getPosts,
|
||||
)
|
||||
postsRouter.get(
|
||||
'/:category/:idOrSlug',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Get a single published post'
|
||||
// #swagger.parameters['category'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Post category.' }
|
||||
// #swagger.parameters['idOrSlug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Numeric id or slug.' }
|
||||
/* #swagger.responses[200] = { description: 'The post', content: { "application/json": { schema: { $ref: "#/components/schemas/Post" } } } } */
|
||||
/* #swagger.responses[404] = { description: 'Unknown category or post not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
siteMode,
|
||||
ctrl.getPost,
|
||||
)
|
||||
|
||||
module.exports = postsRouter
|
||||
@@ -1,248 +0,0 @@
|
||||
const express = require('express')
|
||||
const { body, param, query } = require('express-validator')
|
||||
|
||||
const ctrl = require('./public.controller')
|
||||
const shard = require('./shard.controller')
|
||||
const siteMode = require('../../../middleware/siteMode')
|
||||
const validate = require('../../../middleware/validate')
|
||||
const { contactLimiter } = require('../../../middleware/rateLimit')
|
||||
|
||||
const publicRouter = express.Router()
|
||||
|
||||
// Always available (so the client can render the maintenance page + contact).
|
||||
publicRouter.get(
|
||||
'/settings',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Public site settings + branding'
|
||||
// #swagger.description = 'Whitelisted, non-sensitive settings plus the per-shard brand block (name/colors/logo/hero/favicon) a client themes itself from, and derived registration / game-account-signup availability flags.'
|
||||
/* #swagger.responses[200] = { description: 'Public settings + branding', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicSettings" } } } } */
|
||||
ctrl.getSettings,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/status',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Site mode / status'
|
||||
// #swagger.description = 'Current site mode (live or maintenance) so the client can show the maintenance page, plus a version block (service id + API/server versions) for a client first-run probe and version-mismatch guard.'
|
||||
/* #swagger.responses[200] = { description: 'Site status', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicStatus" } } } } */
|
||||
ctrl.getStatus,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/version',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Backend identity + version'
|
||||
// #swagger.description = 'Lightweight, DB-free descriptor of this backend: a stable service id and the API/server versions. A client uses it to recognize a Runic Gateway backend on first-run and to run a version-mismatch guard. Doubles as a cheap liveness check.'
|
||||
/* #swagger.responses[200] = { description: 'Backend version', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicVersion" } } } } */
|
||||
ctrl.getVersion,
|
||||
)
|
||||
publicRouter.post(
|
||||
'/contact',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Send a contact message'
|
||||
// #swagger.description = 'Emails the site owner (or falls back to a mailto). Rate limited.'
|
||||
/* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ContactRequest" } } } } */
|
||||
/* #swagger.responses[200] = { description: 'Message sent', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
|
||||
/* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
|
||||
/* #swagger.responses[429] = { description: 'Too many messages (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
/* #swagger.responses[502] = { description: 'Mail delivery failed', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
contactLimiter,
|
||||
body('message').isString().trim().notEmpty().isLength({ max: 5000 }),
|
||||
body('email').optional({ values: 'falsy' }).isEmail(),
|
||||
body('name').optional({ values: 'falsy' }).isString().trim().isLength({ max: 100 }),
|
||||
validate,
|
||||
ctrl.contact,
|
||||
)
|
||||
|
||||
// Content — gated by site mode (admins with a valid token bypass for preview).
|
||||
publicRouter.get(
|
||||
'/posts/:category',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'List published posts in a category'
|
||||
// #swagger.description = 'Gated by site mode: during maintenance only admins with a valid session see content.'
|
||||
// #swagger.parameters['category'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'news | five-on-friday | newsletter | screenshots' }
|
||||
/* #swagger.responses[200] = { description: 'Published posts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Post" } } } } } */
|
||||
/* #swagger.responses[404] = { description: 'Unknown category', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
siteMode,
|
||||
ctrl.getPosts,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/posts/:category/:idOrSlug',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Get a single published post'
|
||||
// #swagger.parameters['category'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Post category.' }
|
||||
// #swagger.parameters['idOrSlug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Numeric id or slug.' }
|
||||
/* #swagger.responses[200] = { description: 'The post', content: { "application/json": { schema: { $ref: "#/components/schemas/Post" } } } } */
|
||||
/* #swagger.responses[404] = { description: 'Unknown category or post not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
siteMode,
|
||||
ctrl.getPost,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/wiki',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'List published wiki pages'
|
||||
/* #swagger.responses[200] = { description: 'Published wiki pages', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/WikiPage" } } } } } */
|
||||
siteMode,
|
||||
ctrl.getWikiList,
|
||||
)
|
||||
// Static paths must precede the :slug route so they aren't captured as a slug.
|
||||
publicRouter.get(
|
||||
'/wiki/categories',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'List wiki categories'
|
||||
/* #swagger.responses[200] = { description: 'Wiki categories', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/WikiCategory" } } } } } */
|
||||
siteMode,
|
||||
ctrl.getWikiCategories,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/wiki/tags',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'List wiki tags'
|
||||
/* #swagger.responses[200] = { description: 'Wiki tags', content: { "application/json": { schema: { type: "array", items: { type: "string" } } } } } */
|
||||
siteMode,
|
||||
ctrl.getWikiTags,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/wiki/:slug',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Get a single published wiki page'
|
||||
// #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Wiki page slug.' }
|
||||
/* #swagger.responses[200] = { description: 'The wiki page', content: { "application/json": { schema: { $ref: "#/components/schemas/WikiPage" } } } } */
|
||||
/* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
siteMode,
|
||||
ctrl.getWikiPage,
|
||||
)
|
||||
|
||||
// ── CMS pages (block-based) ────────────────────────────────────────────
|
||||
// Preview is registered before /pages/:slug and is NOT site-mode gated, so a
|
||||
// draft-preview link keeps working during maintenance. The token itself is the
|
||||
// access control.
|
||||
publicRouter.get(
|
||||
'/pages/:id/preview/:token',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Render a page from a draft-preview token'
|
||||
// #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Page id.' }
|
||||
// #swagger.parameters['token'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Preview token from POST /admin/pages/:id/preview.' }
|
||||
/* #swagger.responses[200] = { description: 'The page (any status)', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
|
||||
/* #swagger.responses[404] = { description: 'Token invalid/expired or page missing', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
ctrl.getPagePreview,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/pages/:slug',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Get a published CMS page by slug'
|
||||
// #swagger.description = 'Drafts 404 for the public; staff sessions see drafts. Gated by site mode.'
|
||||
// #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Page slug.' }
|
||||
/* #swagger.responses[200] = { description: 'The page', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
|
||||
/* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
siteMode,
|
||||
ctrl.getPage,
|
||||
)
|
||||
|
||||
// ── Shard live data (uo-link) ──────────────────────────────────────────────
|
||||
// Token-free, same-origin reads. The status/feed/economy/idoc endpoints read
|
||||
// the site's own ingested data; /char round-trips the live shard (cached). Not
|
||||
// site-mode gated — shard status is useful even during site maintenance.
|
||||
publicRouter.get(
|
||||
'/shard/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,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/shard/feed',
|
||||
// #swagger.tags = ['Public · Shard']
|
||||
// #swagger.summary = 'Recent notable shard events (from the ingested log)'
|
||||
// #swagger.parameters['kind'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Filter to a single event kind, e.g. vendor.sale.' }
|
||||
// #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,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/shard/economy',
|
||||
// #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,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/shard/online',
|
||||
// #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,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/shard/idoc',
|
||||
// #swagger.tags = ['Public · Shard']
|
||||
// #swagger.summary = 'Houses currently in danger (IDOC)'
|
||||
/* #swagger.responses[200] = { description: 'IDOC houses', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */
|
||||
shard.getIdoc,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/shard/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,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/shard/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,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/shard/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,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/shard/governors/:city/history',
|
||||
// #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,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/shard/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,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/shard/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,
|
||||
)
|
||||
publicRouter.get(
|
||||
'/shard/stream',
|
||||
// #swagger.tags = ['Public · Shard']
|
||||
// #swagger.summary = 'Live shard event stream (Server-Sent Events, public/safe kinds)'
|
||||
// #swagger.description = 'text/event-stream of curated live events. Sensitive kinds (staff audit, cheat detection, login attempts, IPs) are NOT sent on this channel.'
|
||||
/* #swagger.responses[200] = { description: 'An SSE stream (Content-Type: text/event-stream).' } */
|
||||
shard.stream,
|
||||
)
|
||||
|
||||
module.exports = publicRouter
|
||||
128
server/src/router/v1/public/shard.router.js
Normal file
128
server/src/router/v1/public/shard.router.js
Normal file
@@ -0,0 +1,128 @@
|
||||
// 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 the allowlist in utils/shardBroadcast.js, not by
|
||||
// a route gate — that allowlist split is the security boundary, not this file.
|
||||
|
||||
const express = require('express')
|
||||
const { param, query } = require('express-validator')
|
||||
|
||||
const shard = require('./shard.controller')
|
||||
const validate = require('../../../middleware/validate')
|
||||
|
||||
const shardRouter = express.Router()
|
||||
|
||||
shardRouter.get(
|
||||
'/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',
|
||||
// #swagger.tags = ['Public · Shard']
|
||||
// #swagger.summary = 'Recent notable shard events (from the ingested log)'
|
||||
// #swagger.parameters['kind'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Filter to a single event kind, e.g. vendor.sale.' }
|
||||
// #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',
|
||||
// #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',
|
||||
// #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',
|
||||
// #swagger.tags = ['Public · Shard']
|
||||
// #swagger.summary = 'Houses currently in danger (IDOC)'
|
||||
/* #swagger.responses[200] = { description: 'IDOC houses', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */
|
||||
shard.getIdoc,
|
||||
)
|
||||
shardRouter.get(
|
||||
'/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',
|
||||
// #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',
|
||||
// #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',
|
||||
// #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',
|
||||
// #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',
|
||||
// #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(
|
||||
'/stream',
|
||||
// #swagger.tags = ['Public · Shard']
|
||||
// #swagger.summary = 'Live shard event stream (Server-Sent Events, public/safe kinds)'
|
||||
// #swagger.description = 'text/event-stream of curated live events. Sensitive kinds (staff audit, cheat detection, login attempts, IPs) are NOT sent on this channel.'
|
||||
/* #swagger.responses[200] = { description: 'An SSE stream (Content-Type: text/event-stream).' } */
|
||||
shard.stream,
|
||||
)
|
||||
|
||||
module.exports = shardRouter
|
||||
67
server/src/router/v1/public/site.router.js
Normal file
67
server/src/router/v1/public/site.router.js
Normal file
@@ -0,0 +1,67 @@
|
||||
// Public · Site — the four group-root singletons: settings, status, version and
|
||||
// contact. None of them owns a path segment that could become a prefix, so this
|
||||
// is the public group's counterpart to admin/dashboard.router.js: one file for
|
||||
// the routes that own no prefix, mounted at the group root.
|
||||
//
|
||||
// It is safe at the root **only** because this file declares no router-level
|
||||
// middleware. A bare `use(gate)` in a root-mounted router runs for every request
|
||||
// passing through toward another mount — it would gate /public/wiki and
|
||||
// /public/shard/* too. Keep gates on the individual routes here (siteMode is
|
||||
// deliberately absent: settings/status/version/contact must answer during
|
||||
// maintenance so the client can render the maintenance page and let a visitor
|
||||
// get in touch).
|
||||
//
|
||||
// Mounted at /api/v1/public by public/index.js.
|
||||
|
||||
const express = require('express')
|
||||
const { body } = require('express-validator')
|
||||
|
||||
const ctrl = require('./public.controller')
|
||||
const validate = require('../../../middleware/validate')
|
||||
const { contactLimiter } = require('../../../middleware/rateLimit')
|
||||
|
||||
const siteRouter = express.Router()
|
||||
|
||||
siteRouter.get(
|
||||
'/settings',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Public site settings + branding'
|
||||
// #swagger.description = 'Whitelisted, non-sensitive settings plus the per-shard brand block (name/colors/logo/hero/favicon) a client themes itself from, and derived registration / game-account-signup availability flags.'
|
||||
/* #swagger.responses[200] = { description: 'Public settings + branding', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicSettings" } } } } */
|
||||
ctrl.getSettings,
|
||||
)
|
||||
siteRouter.get(
|
||||
'/status',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Site mode / status'
|
||||
// #swagger.description = 'Current site mode (live or maintenance) so the client can show the maintenance page, plus a version block (service id + API/server versions) for a client first-run probe and version-mismatch guard.'
|
||||
/* #swagger.responses[200] = { description: 'Site status', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicStatus" } } } } */
|
||||
ctrl.getStatus,
|
||||
)
|
||||
siteRouter.get(
|
||||
'/version',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Backend identity + version'
|
||||
// #swagger.description = 'Lightweight, DB-free descriptor of this backend: a stable service id and the API/server versions. A client uses it to recognize a Runic Gateway backend on first-run and to run a version-mismatch guard. Doubles as a cheap liveness check.'
|
||||
/* #swagger.responses[200] = { description: 'Backend version', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicVersion" } } } } */
|
||||
ctrl.getVersion,
|
||||
)
|
||||
siteRouter.post(
|
||||
'/contact',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Send a contact message'
|
||||
// #swagger.description = 'Emails the site owner (or falls back to a mailto). Rate limited.'
|
||||
/* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ContactRequest" } } } } */
|
||||
/* #swagger.responses[200] = { description: 'Message sent', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
|
||||
/* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
|
||||
/* #swagger.responses[429] = { description: 'Too many messages (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
/* #swagger.responses[502] = { description: 'Mail delivery failed', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
contactLimiter,
|
||||
body('message').isString().trim().notEmpty().isLength({ max: 5000 }),
|
||||
body('email').optional({ values: 'falsy' }).isEmail(),
|
||||
body('name').optional({ values: 'falsy' }).isString().trim().isLength({ max: 100 }),
|
||||
validate,
|
||||
ctrl.contact,
|
||||
)
|
||||
|
||||
module.exports = siteRouter
|
||||
56
server/src/router/v1/public/wiki.router.js
Normal file
56
server/src/router/v1/public/wiki.router.js
Normal file
@@ -0,0 +1,56 @@
|
||||
// Public · Wiki — the published wiki: the page list, categories, tags and a
|
||||
// single page by slug. Read-only counterpart of admin/wiki.router.js.
|
||||
//
|
||||
// Mounted at /api/v1/public/wiki by public/index.js. No group gate; `siteMode`
|
||||
// is applied per route.
|
||||
//
|
||||
// Declaration order is load-bearing: `/categories` and `/tags` are literal paths
|
||||
// and MUST stay ahead of `/:slug`, or GET /public/wiki/categories dispatches as a
|
||||
// wiki page whose slug is "categories". routes.manifest.json sorts its entries
|
||||
// and therefore cannot catch a reordering — the same trap admin/wiki.router.js
|
||||
// carries (see docs/website/API_V2_PLAN.md § PR 3).
|
||||
|
||||
const express = require('express')
|
||||
|
||||
const ctrl = require('./public.controller')
|
||||
const siteMode = require('../../../middleware/siteMode')
|
||||
|
||||
const wikiRouter = express.Router()
|
||||
|
||||
wikiRouter.get(
|
||||
'/',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'List published wiki pages'
|
||||
/* #swagger.responses[200] = { description: 'Published wiki pages', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/WikiPage" } } } } } */
|
||||
siteMode,
|
||||
ctrl.getWikiList,
|
||||
)
|
||||
// Static paths must precede the :slug route so they aren't captured as a slug.
|
||||
wikiRouter.get(
|
||||
'/categories',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'List wiki categories'
|
||||
/* #swagger.responses[200] = { description: 'Wiki categories', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/WikiCategory" } } } } } */
|
||||
siteMode,
|
||||
ctrl.getWikiCategories,
|
||||
)
|
||||
wikiRouter.get(
|
||||
'/tags',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'List wiki tags'
|
||||
/* #swagger.responses[200] = { description: 'Wiki tags', content: { "application/json": { schema: { type: "array", items: { type: "string" } } } } } */
|
||||
siteMode,
|
||||
ctrl.getWikiTags,
|
||||
)
|
||||
wikiRouter.get(
|
||||
'/:slug',
|
||||
// #swagger.tags = ['Public']
|
||||
// #swagger.summary = 'Get a single published wiki page'
|
||||
// #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Wiki page slug.' }
|
||||
/* #swagger.responses[200] = { description: 'The wiki page', content: { "application/json": { schema: { $ref: "#/components/schemas/WikiPage" } } } } */
|
||||
/* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
||||
siteMode,
|
||||
ctrl.getWikiPage,
|
||||
)
|
||||
|
||||
module.exports = wikiRouter
|
||||
Reference in New Issue
Block a user