// ── Public · World ────────────────────────────────────────────────────────
//
// Mounted at `/api/v1/public/world` by `index.js`. One express Router, built
// from CORE's express (`core.express`) — never from a `require('express')` of
// your own, which would not resolve from here anyway (MODULE_API.md §7.2).
//
// **The tier's gate is already on.** This router sits inside core's public tier,
// which is behind nothing by design — the public API is public. Per-route
// middleware goes on top, and `siteMode` below is the one worth understanding:
// it is what makes a page respect the operator's maintenance switch. Core applies
// it to its own content routes (`/posts`, `/wiki`) and deliberately does not
// apply it to its status endpoints, because status is exactly what an operator
// wants visible *during* maintenance. Which of those two your route is depends on
// what it serves, and it is your decision to make.
//
// ── About the `#swagger` comments ─────────────────────────────────────────
//
// They are not documentation *of* the code, they are the source the OpenAPI
// fragment is generated from — `npm run swagger` parses this file (§2.8). Two
// rules that cost this project real time:
//
//   • swagger-autogen reads these as JavaScript literals it evaluates. It
//     re-quotes `"` and a backtick to `'` first, so either one inside a
//     single-quoted description ends the string early — and when it cannot parse
//     an annotation it drops that annotation, prints an error, and then reports
//     success. Use a typographic apostrophe (’) in prose. `swaggerFragment.js`
//     captures those errors and makes them fatal, which is the only reason you
//     will find out.
//   • A `\'` escape is valid JavaScript and wrong here: the annotation is never
//     evaluated as JS by the reader, so Swagger UI renders the backslash.

const core = require('../../core')

const express = core.express
const world = require('./world.controller')
const { siteMode } = core.middleware

const worldRouter = express.Router()

worldRouter.get(
  '/status',
  // #swagger.tags = ['Public · Example Game']
  // #swagger.summary = 'The game world’s current status'
  // #swagger.description = 'What the game server last reported: whether it is up, how many players are on, and when that was. Answers with `online: false` and `stale: true` rather than failing when the game or its sidecar is unreachable — the site’s availability does not depend on the game’s.'
  /* #swagger.responses[200] = { description: 'The world’s status', content: { "application/json": { schema: { $ref: "#/components/schemas/ExamplegameWorldStatus" } } } } */
  siteMode,
  world.getStatus,
)

module.exports = worldRouter