wtclaude
9ddb59a326
An event action may declare an optional `progress(envelope)`: how its
step stands while the run is live. Core accepts two shapes and
interprets neither:
- a count: { label, left, of }, rendered "Bandits: 3 of 8 left";
- a percentage: { label, percent }, rendered "The Juggernaut: 62%".
How core asks:
- `events/progress.js` asks each step of a live run whose action has
one. It passes the step's own held ledger rows and the reader's
account id, so the module applies its own visibility.
- Each call has a 2 s deadline. A throw, a late answer or any other
shape is a line not shown, never an error on the page.
- One answer per run and reader is cached for 5 s.
- The public event's live occurrence carries the lines as `progress`.
The route takes an optional session for the reader.
- The page renders them under the phase label and re-reads them every
15 s while the event is live.
Core stays game-agnostic: no game's words are in it. Additive, so a
minor bump. Module-uo declares ^1.10.0, registers no action with
progress(), and its actions and pages are unchanged.
From RunicNPC stage 8 (D304, D305).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
64 lines
5.1 KiB
JavaScript
64 lines
5.1 KiB
JavaScript
// Public · Events — mounted at /api/v1/public/events by public/index.js.
|
|
//
|
|
// No group gate: this is the anonymous surface, and `siteMode` is applied per
|
|
// route as it is everywhere else in this tier — during maintenance only an admin
|
|
// with a valid session sees content.
|
|
//
|
|
// Declaration order: '/' is literal and precedes ':slug', and 'series/:slug' is
|
|
// declared BEFORE ':slug' although it could not be shadowed by it (two segments
|
|
// against one). It stays above so the relationship is visible to whoever adds
|
|
// the next route here — and because the one route bug this feature has already
|
|
// shipped was exactly a static/dynamic ranking surprise, one tier up in React
|
|
// Router (see App.jsx's note above `events/:id`).
|
|
|
|
const express = require('express')
|
|
|
|
const ctrl = require('./events.controller')
|
|
const siteMode = require('../../../middleware/siteMode')
|
|
const { optionalAuth } = require('../../../auth/session.middleware')
|
|
|
|
const eventsRouter = express.Router()
|
|
|
|
eventsRouter.get(
|
|
'/',
|
|
// #swagger.tags = ['Public · Events']
|
|
// #swagger.summary = 'The public event calendar'
|
|
// #swagger.description = 'Upcoming, live and recent events in a window, ascending by instant. An entry is one of two things and says which: a `run` is a materialised occurrence, and a `projected` entry is arithmetic past the materialisation horizon — a forecast, with nothing committed to it, which a client should draw as such. Instants are UTC and each entry carries the EVENT\'s own timezone, because a shard-local 8pm means the shard\'s evening to everyone reading it; the reader\'s own zone places the entry in a month grid. Rehearsals and unlisted events are absent. Defaults to now through 31 days out; the window may span at most 92 days.'
|
|
// #swagger.parameters['from'] = { in: 'query', required: false, schema: { type: 'string', format: 'date-time' }, description: 'Window start (ISO). Defaults to now.' }
|
|
// #swagger.parameters['to'] = { in: 'query', required: false, schema: { type: 'string', format: 'date-time' }, description: 'Window end (ISO). Defaults to 31 days after the start.' }
|
|
// #swagger.parameters['seriesId'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Restrict to one arc.' }
|
|
/* #swagger.responses[200] = { description: 'The calendar', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicEventCalendar" } } } } */
|
|
/* #swagger.responses[400] = { description: 'Bad window', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
|
siteMode,
|
|
ctrl.getCalendar,
|
|
)
|
|
|
|
eventsRouter.get(
|
|
'/series/:slug',
|
|
// #swagger.tags = ['Public · Events']
|
|
// #swagger.summary = 'One arc'
|
|
// #swagger.description = 'A series and the listed events in it, in the order an editor arranged them. A series with no listed events answers 404 rather than an empty page: the arc is a label on its definitions, so a page for an empty one would publish the fact that an operator has named something they have not announced.'
|
|
// #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'The series slug.' }
|
|
/* #swagger.responses[200] = { description: 'The arc', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicEventSeries" } } } } */
|
|
/* #swagger.responses[404] = { description: 'No such arc, or nothing in it is listed', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
|
siteMode,
|
|
ctrl.getSeries,
|
|
)
|
|
|
|
eventsRouter.get(
|
|
'/:slug',
|
|
// #swagger.tags = ['Public · Events']
|
|
// #swagger.summary = 'One event'
|
|
// #swagger.description = 'The storyline, the arc it belongs to, what is live, what is next, what happened recently, and a results table once one has been published. A draft, an archived definition and an unlisted one all answer 404, indistinguishable from a slug that never existed. The plan behind the event — phases, steps, actions and their params — is never published; a live run carries the LABEL of the phase it is in and nothing more, and `progress`: how its steps stand, each line a label with either `left` of `of` or a `percent`, in the words the steps\' modules chose. What a module shows may depend on who is reading, so sending a session is optional and may widen it.'
|
|
// #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'The event slug.' }
|
|
// #swagger.parameters['run'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Which occurrence the results are about — what an announcement\'s link carries, so a mail about last Friday does not open next Friday\'s. A run that does not belong to this event is ignored rather than refused.' }
|
|
// #swagger.security = [{}, { "cookieAuth": [] }, { "bearerAuth": [] }]
|
|
/* #swagger.responses[200] = { description: 'The event', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicEvent" } } } } */
|
|
/* #swagger.responses[404] = { description: 'No such public event', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
|
|
siteMode,
|
|
optionalAuth,
|
|
ctrl.getEvent,
|
|
)
|
|
|
|
module.exports = eventsRouter
|