Compare commits
57 Commits
feat/phase
...
fe86fc369d
| Author | SHA1 | Date | |
|---|---|---|---|
| fe86fc369d | |||
| 9b28c95305 | |||
| aad3a37c09 | |||
| 75c8ffc07a | |||
| a100195e7b | |||
| 4426d3e339 | |||
| 6046214d71 | |||
| 9938e71e07 | |||
| 2971b84d51 | |||
| b1584043a3 | |||
| c3c347d237 | |||
| 4e1ce2316a | |||
| 73f664c38e | |||
| e91e76bfa9 | |||
| 5f58a4cbf2 | |||
| 82b55e3084 | |||
| a0af01026e | |||
| 5c6735bd1d | |||
| 5e987518c6 | |||
| 3574bba4d5 | |||
| d01fd55f43 | |||
| 83c438885e | |||
| 391a4a131b | |||
| c8a293b8f6 | |||
| 916921551f | |||
| 7709b055a4 | |||
| 92a1a33121 | |||
| 283814dbf2 | |||
| 782e3df7e2 | |||
| e0d491d33b | |||
| ebd6ba8dbf | |||
| 289b6b3a8d | |||
| 5ba91717c0 | |||
| 2da014790e | |||
| 268e1c98fc | |||
| 12c416f5fc | |||
| ce13a44ed7 | |||
| b86f4cabf0 | |||
| e60812fb34 | |||
| 92f00ab20a | |||
| 3b4067fa37 | |||
| 1558111050 | |||
| f2e59a2426 | |||
| 18064062a9 | |||
| de9d25bbe7 | |||
| 58883951a4 | |||
| e71ff4acd4 | |||
| a34c2ce538 | |||
| 8b6efd5c0a | |||
| ebb3f71786 | |||
| c29ec94f46 | |||
| 31d914ba44 | |||
| b3cb6bf1eb | |||
| d89ce06bb8 | |||
| e8cb6061fe | |||
| a993b872ac | |||
| bcb633403f |
42
.dockerignore
Normal file
@@ -0,0 +1,42 @@
|
||||
# What must never reach the build context.
|
||||
#
|
||||
# Two entries here are load-bearing rather than housekeeping, and both are about
|
||||
# the bind mounts (PLAN.md §6, §7).
|
||||
#
|
||||
# brand/ is the OPERATOR's override. If a developer's local mount were copied
|
||||
# in, the image would ship somebody's test logo as if it were stock —
|
||||
# and, worse, it would win over brand-default/ on every deployment that
|
||||
# does not mount its own. The mount is the only way brand/ is allowed
|
||||
# to exist inside a container.
|
||||
#
|
||||
# data/ holds beta.sqlite: real addresses, given under a consent notice that
|
||||
# says where they are stored. A published image is world-readable to
|
||||
# anyone who can pull it. This line is the reason that cannot happen by
|
||||
# accident.
|
||||
#
|
||||
# brand-default/ is deliberately NOT here. It is baked in and must always be
|
||||
# complete; §7's whole per-file fallback rests on it.
|
||||
|
||||
node_modules
|
||||
dist
|
||||
.astro
|
||||
.output
|
||||
|
||||
brand
|
||||
data
|
||||
|
||||
.git
|
||||
.gitea
|
||||
.gitignore
|
||||
.dockerignore
|
||||
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
|
||||
# Authoring inputs and working notes, none of which the running site reads.
|
||||
PLAN.md
|
||||
*.log
|
||||
npm-debug.log*
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
70
.env.example
Normal file
@@ -0,0 +1,70 @@
|
||||
# runicgateway.com — production environment.
|
||||
#
|
||||
# Copy to `.env` beside docker-compose.yml on the host and fill in the two
|
||||
# secrets. Everything else has a working default; this file exists so the
|
||||
# defaults are visible rather than discovered.
|
||||
#
|
||||
# cp .env.example .env
|
||||
#
|
||||
# Nothing here is a credential for another service. The site talks to no API,
|
||||
# sends no mail (D7) and has no database server — the only state it keeps is a
|
||||
# SQLite file on the ./data mount.
|
||||
|
||||
# ---------------------------------------------------------------------------------------
|
||||
# Deployment
|
||||
# ---------------------------------------------------------------------------------------
|
||||
|
||||
# Which published build runs. `latest` follows main; pin `sha-<7>` for a
|
||||
# reproducible deploy or to roll back — every merge publishes both tags.
|
||||
IMAGE_TAG=latest
|
||||
|
||||
# Host port the container is published on.
|
||||
SITE_HOST_PORT=4321
|
||||
|
||||
# Which of the host's addresses that port is published on. The default is every
|
||||
# interface, so the site answers on the host's own address — http://<vm-ip>:4321
|
||||
# — which is what a proxy in another container, another machine, or a browser
|
||||
# elsewhere on the network needs.
|
||||
#
|
||||
# Narrow it if this host has a public address and you want only the proxy to
|
||||
# reach the container: 127.0.0.1 for a proxy on this same host, or one interface
|
||||
# address for the LAN but not a public NIC. Nothing else in the site changes.
|
||||
SITE_BIND_ADDR=0.0.0.0
|
||||
|
||||
# ---------------------------------------------------------------------------------------
|
||||
# The closed-beta signup (PLAN.md §8)
|
||||
# ---------------------------------------------------------------------------------------
|
||||
#
|
||||
# THE TWO BELOW ARE THE ONLY VALUES THAT REALLY WANT SETTING. Both default to a
|
||||
# random value generated per process, which is safe but forgetful: every restart
|
||||
# invalidates every rate-limit window and every rendered form. That is the right
|
||||
# default — a hard-coded salt shipped in a public repository would make every
|
||||
# deployment's ip_hash values identical and therefore reversible by anyone who
|
||||
# can read it — but it is not what you want on a host that restarts.
|
||||
#
|
||||
# Generate both once, keep them, and do not rotate them casually: changing the
|
||||
# salt orphans the rate-limit history of everyone already counted.
|
||||
#
|
||||
# openssl rand -hex 32
|
||||
|
||||
# Salts the ip_hash column. The raw IP address is never stored — /privacy says
|
||||
# so, and this is the mechanism that makes it true while still allowing a
|
||||
# per-connection limit.
|
||||
BETA_IP_SALT=
|
||||
|
||||
# Signs the hidden form token, so a script has to fetch the page before it can
|
||||
# post. Rotating this only invalidates forms currently open in a browser.
|
||||
BETA_FORM_KEY=
|
||||
|
||||
# Rows, across all time, above which the form closes and says so on the page.
|
||||
BETA_TOTAL_CAP=500
|
||||
|
||||
# What one connection may do, in a rolling hour and a rolling day.
|
||||
BETA_PER_HOUR=3
|
||||
BETA_PER_DAY=24
|
||||
|
||||
# Seconds between the page rendering and the form posting. Below the minimum is
|
||||
# treated as a script; above the maximum the form is stale and re-rendered.
|
||||
# Twelve hours is the default maximum.
|
||||
BETA_MIN_SECONDS=2
|
||||
BETA_MAX_SECONDS=43200
|
||||
48
.gitea/ISSUE_TEMPLATE/bug_report.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
name: Bug report
|
||||
about: Something on the site is broken, wrong, or behaving unexpectedly
|
||||
title: "[bug] "
|
||||
labels:
|
||||
- bug
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
<!-- A clear, concise description of the problem. -->
|
||||
|
||||
## Where
|
||||
|
||||
<!-- The URL, or the page and the section. If it is a documentation page, the heading. -->
|
||||
|
||||
- Page:
|
||||
- Viewport width, if it is a layout problem:
|
||||
- Browser and version:
|
||||
|
||||
## What happened, and what you expected
|
||||
|
||||
<!--
|
||||
Include exact wording for a factual error, and the console message if there is
|
||||
one. A screenshot helps for anything visual.
|
||||
-->
|
||||
|
||||
## Is it a factual error?
|
||||
|
||||
<!--
|
||||
The most valuable reports this repository gets are claims that are WRONG about
|
||||
the platform — a version, a command, a flag, a capability that no longer works
|
||||
that way. If so, say where the correct answer lives (which repository, which
|
||||
file), because the fix is usually to a data file or a check rather than to the
|
||||
sentence.
|
||||
-->
|
||||
|
||||
## Additional context
|
||||
|
||||
<!-- Anything else that helps. -->
|
||||
|
||||
<!--
|
||||
Security issue? Do NOT file it here — see SECURITY.md for the private route.
|
||||
|
||||
A problem with the PLATFORM rather than with this site (the website, the
|
||||
sidecar, the shard plugin, the installer, the Android app) belongs in that
|
||||
repository's tracker. This one only describes them.
|
||||
-->
|
||||
11
.gitea/ISSUE_TEMPLATE/config.yaml
Normal file
@@ -0,0 +1,11 @@
|
||||
blank_issues_enabled: true
|
||||
contact_links:
|
||||
- name: Security vulnerability
|
||||
url: https://gitea.whitlocktech.com/RunicGateway/runicgateway.com/src/branch/main/SECURITY.md
|
||||
about: Please do not open a public issue for security problems — report them privately instead (see SECURITY.md).
|
||||
- name: Questions, help and the Android beta
|
||||
url: https://discord.gg/t2Jav8yT4g
|
||||
about: Discord is the front door — instant, and it needs no account here. Bug reports are welcome there too.
|
||||
- name: A problem with the platform, not the site
|
||||
url: https://gitea.whitlocktech.com/RunicGateway
|
||||
about: The website, the sidecar, the shard plugin, the installer and the Android app each have their own tracker. This repository only describes them.
|
||||
38
.gitea/ISSUE_TEMPLATE/feature_request.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
name: Feature request
|
||||
about: Suggest a page, a section, or a change to how the site explains something
|
||||
title: "[feature] "
|
||||
labels:
|
||||
- enhancement
|
||||
---
|
||||
|
||||
## Problem / motivation
|
||||
|
||||
<!--
|
||||
What were you trying to find out, or do, when the site let you down? A missing
|
||||
page is easier to judge from the question that went unanswered than from the
|
||||
page title.
|
||||
-->
|
||||
|
||||
## Proposed solution
|
||||
|
||||
<!-- What you would like to see. -->
|
||||
|
||||
## Does it belong here?
|
||||
|
||||
<!--
|
||||
Two boundaries this repository holds deliberately (PLAN.md §1):
|
||||
|
||||
- The site TEACHES; `docs/` SPECIFIES. Protocol, module API, backend design and
|
||||
installer behaviour are normative in the docs repository — a page here links
|
||||
out rather than restating them, so that it cannot drift.
|
||||
- Absences are stated as data, not implied. If the request is for something the
|
||||
platform does not do yet, it may belong in src/data/notBuilt.mjs rather than
|
||||
as a page.
|
||||
|
||||
Say which side you think it falls on; being wrong about it is fine.
|
||||
-->
|
||||
|
||||
## Additional context
|
||||
|
||||
<!-- Mockups, links, related issues, the repository the change would describe. -->
|
||||
42
.gitea/PULL_REQUEST_TEMPLATE.md
Normal file
@@ -0,0 +1,42 @@
|
||||
<!--
|
||||
Thanks for contributing to Runic Gateway!
|
||||
Please fill out the sections below and check every box before requesting review.
|
||||
|
||||
Merging to main publishes: it builds the image, pushes it to the registry and
|
||||
deploys the site. There is no separate release step. See DEPLOY.md.
|
||||
-->
|
||||
|
||||
## What & why
|
||||
|
||||
<!-- What does this PR change, and why? Link any related issue: "Closes #123". -->
|
||||
|
||||
## How it was tested
|
||||
|
||||
<!--
|
||||
`npm run verify` output is the baseline. If the change touches a page, say what
|
||||
you looked at and at what width; if it touches the container, say whether you
|
||||
built and ran the image.
|
||||
-->
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] I have read [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
- [ ] `npm run verify` passes locally (all eleven checks and both test suites).
|
||||
- [ ] No fact is stated in prose — versions and platform facts come from `src/data/platform.json`.
|
||||
- [ ] `PLAN.md` still describes what this repository does; a decision it records is either
|
||||
unchanged or amended here, with the reasoning.
|
||||
- [ ] My commits are reasonably scoped, with Conventional Commit messages.
|
||||
|
||||
## AI-assisted contributions (required)
|
||||
|
||||
This project **requires disclosure of AI tool usage**. Please pick one:
|
||||
|
||||
- [ ] No AI tools were used to produce this contribution.
|
||||
- [ ] AI tools were used. Tool(s): `___________`. I have reviewed and understand
|
||||
every change, and take responsibility for it. AI-authored commits are
|
||||
marked with a `Co-Authored-By` / `Assisted-By` trailer.
|
||||
|
||||
## License
|
||||
|
||||
- [ ] I agree that my contribution is licensed under this project's license
|
||||
(**GNU GPL v3.0 or later**), and I have the right to contribute it.
|
||||
209
.gitea/workflows/build-image.yml
Normal file
@@ -0,0 +1,209 @@
|
||||
# Build the container image, publish it to Gitea's container registry, then roll
|
||||
# the site onto it — on every merge to main.
|
||||
#
|
||||
# Gitea Actions caution, learned elsewhere in this org and repeated from
|
||||
# pr-checks.yml because it costs one comment and has already cost months: never
|
||||
# leave an empty template expression anywhere in a `run:` script, not even inside
|
||||
# a comment. The runner silently SKIPS the whole step without failing the job,
|
||||
# and the problem is invisible in the workflow list.
|
||||
#
|
||||
# Two jobs, in sequence:
|
||||
#
|
||||
# build — builds and pushes the image (on `ubuntu-latest`)
|
||||
# deploy — `needs: build`, so it starts only after a clean build and push, and
|
||||
# pulls + recreates the stack on the host (on `rgcom`)
|
||||
#
|
||||
# Prerequisites, one-time:
|
||||
#
|
||||
# • A runner labelled `ubuntu-latest` whose jobs have the host Docker socket
|
||||
# mounted (/var/run/docker.sock), so `docker build` talks to the host daemon.
|
||||
# This also gives free layer caching between runs. The org already runs one.
|
||||
#
|
||||
# • A runner labelled `rgcom` ON the host that serves the site, able to reach
|
||||
# the Docker daemon and /opt/runicgateway.com — the directory holding the
|
||||
# production docker-compose.yml and .env. DEPLOY.md has the registration
|
||||
# command and the directory layout.
|
||||
#
|
||||
# • Two repository secrets (Settings → Actions → Secrets), both of which
|
||||
# already exist for pr-checks.yml's cross-repository checks:
|
||||
# REGISTRY_USER — the Gitea username owning the token below
|
||||
# REGISTRY_TOKEN — a token with write:package (and read:package)
|
||||
#
|
||||
# Produces, in gitea.whitlocktech.com/runicgateway/ :
|
||||
# runicgateway-site:latest + runicgateway-site:sha-<7>
|
||||
#
|
||||
# and deploys `:latest`, which is what docker-compose.yml defaults IMAGE_TAG to.
|
||||
#
|
||||
# WHY THIS REPOSITORY DEPLOYS AND D6 SAID IT WOULD NOT: D6 was written before
|
||||
# there was a host to deploy to, and read "ship the image, the org lead deploys".
|
||||
# The org lead amended it on 2026-08-25 (D54): a marketing site whose content is
|
||||
# its whole purpose is a bad fit for a manual step between merging a fix and the
|
||||
# fix being visible. What D6 was protecting — that a bad build cannot reach
|
||||
# production — is held by `needs: build` instead, plus every check in
|
||||
# pr-checks.yml having already run on the pull request.
|
||||
|
||||
name: Build and publish the image
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_dispatch: {}
|
||||
|
||||
concurrency:
|
||||
group: image-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
env:
|
||||
REGISTRY: gitea.whitlocktech.com
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Check out the merged commit
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Derive the image ref
|
||||
# The registry path must be lowercase for Docker; the org is `RunicGateway`.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
OWNER="$(echo "${{ github.repository_owner }}" | tr '[:upper:]' '[:lower:]')"
|
||||
SHORT_SHA="${GITHUB_SHA:0:7}"
|
||||
echo "IMAGE=${REGISTRY}/${OWNER}/runicgateway-site" >> "$GITHUB_ENV"
|
||||
echo "TAG=sha-${SHORT_SHA}" >> "$GITHUB_ENV"
|
||||
|
||||
- name: Verify the Docker daemon is reachable
|
||||
# Fails fast with a clear message if the host socket is not mounted into
|
||||
# the job container — the one hard runner prerequisite.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
if ! docker info >/dev/null 2>&1; then
|
||||
echo "::error::Docker daemon not reachable. Mount /var/run/docker.sock into the runner's job containers."
|
||||
exit 1
|
||||
fi
|
||||
echo "Docker daemon OK"
|
||||
|
||||
- name: Log in to the Gitea container registry
|
||||
run: |
|
||||
set -euo pipefail
|
||||
echo "${{ secrets.REGISTRY_TOKEN }}" \
|
||||
| docker login "${REGISTRY}" -u "${{ secrets.REGISTRY_USER }}" --password-stdin
|
||||
|
||||
- name: Build
|
||||
# Two tags from one build: `latest` for the compose default, `sha-<7>` so
|
||||
# a deploy can be pinned or rolled back to an exact commit.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
docker build -f Dockerfile \
|
||||
-t "${IMAGE}:latest" \
|
||||
-t "${IMAGE}:${TAG}" \
|
||||
.
|
||||
|
||||
- name: No layer may exceed the registry's request limit
|
||||
# Gitea is behind Cloudflare, which refuses a request body over 100 MB on
|
||||
# every plan below Enterprise, and `docker push` uploads each layer as one
|
||||
# monolithic PUT. An oversized layer is therefore rejected at the EDGE:
|
||||
# Gitea never sees it, the log says only `413 Payload Too Large` against a
|
||||
# blob digest, and the image is not published at all. That is what happened
|
||||
# on the first merge after phase 12, and the Dockerfile's three-layer
|
||||
# node_modules split is what fixed it.
|
||||
#
|
||||
# A split is a margin, not a guarantee, so this counts the layers before
|
||||
# the push rather than letting the next fat dependency rediscover the 413.
|
||||
# 90 MB, not 100: the cap is on the whole request, and the blob is not the
|
||||
# only thing in it.
|
||||
#
|
||||
# Measured by re-compressing what `docker save` writes, because the daemon
|
||||
# exposes uncompressed sizes only and the limit applies to the compressed
|
||||
# blob. gzip is what the push uses, so the numbers agree to within a per
|
||||
# cent; both archive layouts are handled, since a layer is already gzipped
|
||||
# in one of them and plain in the other.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
LIMIT_MB=90
|
||||
|
||||
docker save "${IMAGE}:${TAG}" -o /tmp/image.tar
|
||||
mkdir -p /tmp/layers
|
||||
tar -xf /tmp/image.tar -C /tmp/layers
|
||||
|
||||
WORST_MB=0
|
||||
WORST_FILE=""
|
||||
# Only files big enough to matter; everything else is metadata.
|
||||
while IFS= read -r f; do
|
||||
if [ "$(head -c 2 "$f" | od -An -tx1 | tr -d ' \n')" = "1f8b" ]; then
|
||||
SIZE=$(stat -c %s "$f") # already compressed
|
||||
else
|
||||
SIZE=$(gzip -c "$f" | wc -c) # compress it the way the push will
|
||||
fi
|
||||
MB=$(( SIZE / 1048576 ))
|
||||
if [ "$MB" -gt "$WORST_MB" ]; then
|
||||
WORST_MB=$MB
|
||||
WORST_FILE=$f
|
||||
fi
|
||||
done < <(find /tmp/layers -type f -size +8M)
|
||||
|
||||
rm -rf /tmp/image.tar /tmp/layers
|
||||
|
||||
echo "Largest layer: ${WORST_MB} MB compressed (limit ${LIMIT_MB} MB)"
|
||||
if [ "$WORST_MB" -gt "$LIMIT_MB" ]; then
|
||||
echo "::error::A layer is ${WORST_MB} MB compressed (${WORST_FILE}). Cloudflare rejects a request body over 100 MB, so this push would fail with 413 Payload Too Large and publish nothing. Split the layer in the Dockerfile — see the COPY block that splits node_modules."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
- name: Push
|
||||
run: |
|
||||
set -euo pipefail
|
||||
docker push "${IMAGE}:latest"
|
||||
docker push "${IMAGE}:${TAG}"
|
||||
|
||||
- name: Log out
|
||||
if: always()
|
||||
run: docker logout "${REGISTRY}" || true
|
||||
|
||||
deploy:
|
||||
# Roll the site onto the image `build` just pushed. `needs: build` makes this
|
||||
# wait for a clean build and push — if the build fails, deploy never fires and
|
||||
# the running container is left alone rather than torn down for nothing.
|
||||
needs: build
|
||||
runs-on: rgcom
|
||||
# Guard against a workflow_dispatch fired from a branch: only main is deployed.
|
||||
if: github.ref == 'refs/heads/main'
|
||||
# Until a runner with this label exists, this job simply QUEUES. That is the
|
||||
# intended behaviour and it breaks nothing: `build` has already published the
|
||||
# image, so `docker compose pull && up -d` by hand is available the whole time,
|
||||
# and the queued job runs the moment the runner registers.
|
||||
|
||||
steps:
|
||||
- name: Pull the fresh image and recreate the container
|
||||
# No `down` first, deliberately. There is one service and no database to
|
||||
# keep still, so `up -d` recreates it in place when the pulled digest
|
||||
# differs — a couple of seconds of connection refused behind the proxy
|
||||
# rather than the whole stack stopped while an image is fetched.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cd /opt/runicgateway.com
|
||||
docker compose pull
|
||||
docker compose up -d --remove-orphans
|
||||
docker compose ps
|
||||
|
||||
- name: Wait for the container to report healthy
|
||||
# The image's healthcheck watches an actual response, and `npm start` runs
|
||||
# the brand rewrite before the server starts — so "running" arrives well
|
||||
# before "serving". Without this the job would go green on a container
|
||||
# that is about to crash-loop on, say, an unwritable ./data.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cd /opt/runicgateway.com
|
||||
for attempt in $(seq 1 30); do
|
||||
STATUS="$(docker compose ps --format '{{.Health}}' site | head -n 1)"
|
||||
echo "attempt ${attempt}: ${STATUS:-unknown}"
|
||||
if [ "$STATUS" = "healthy" ]; then
|
||||
echo "Site is healthy."
|
||||
exit 0
|
||||
fi
|
||||
sleep 5
|
||||
done
|
||||
echo "::error::The site did not become healthy within 150s."
|
||||
docker compose logs --tail 100 site
|
||||
exit 1
|
||||
@@ -65,6 +65,40 @@ jobs:
|
||||
# the shorter form would pass locally and break only here.
|
||||
run: npm test
|
||||
|
||||
- name: Sidebar
|
||||
# PLAN.md §12, phase 8. src/config/sidebar.mjs holds two trees — the one Starlight
|
||||
# renders and the one §10 planned — and they must agree on groups, labels and
|
||||
# ORDER. Order because the order of "Getting started" IS the installation path.
|
||||
#
|
||||
# While pages were being written the planned tree was a checklist; now that every
|
||||
# page exists it is a hand-maintained second copy, and it had already drifted
|
||||
# unnoticed (phase 7 added Content under D37 and never updated it). Nothing caught
|
||||
# that because nothing read it.
|
||||
#
|
||||
# No token, no network, no build — so it runs early and fails fast.
|
||||
run: npm run check:sidebar
|
||||
|
||||
- name: Game vocabulary
|
||||
# PLAN.md §16, D63/D64 — the twelfth check, phase 14. The site may NAME the games it
|
||||
# supports anywhere, but a game's vocabulary (shard, guild, clan, uo-link, Oxide…)
|
||||
# belongs in that game's own docs group, its sidebar group, or a <GameExample> block
|
||||
# that labels it (D68). Core pages use core's words: a Team, a game server, the
|
||||
# sidecar, the bridge plugin, the game module.
|
||||
#
|
||||
# No token, no network, no build — so it runs early and fails fast.
|
||||
run: npm run check:terms
|
||||
|
||||
- name: Screenshots
|
||||
# PLAN.md §12, phase 9 (D45). src/data/screens.mjs is the one list of what the site
|
||||
# shows of itself: every entry must have a file, at the size the markup declares, and
|
||||
# every file must have an entry. The size half is the one that repays the check —
|
||||
# a re-capture taken at the wrong viewport looks perfectly fine on its own and only
|
||||
# reveals itself as a page that reflows while it decodes.
|
||||
#
|
||||
# No browser and no game server: the capture tool is an authoring script whose output
|
||||
# is committed, exactly like the brand assets, so CI only reads what it produced.
|
||||
run: npm run check:screens
|
||||
|
||||
- name: Production build
|
||||
run: npm run build
|
||||
|
||||
@@ -115,3 +149,64 @@ jobs:
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
|
||||
run: npm run check:quickstart
|
||||
|
||||
- name: Reference enumerations against their sources
|
||||
# PLAN.md §12, phase 8. The Reference section names things — every environment
|
||||
# variable, config key, installer command, visibility rung and canonical document.
|
||||
# §1 forbids re-specifying a contract, and this is what makes writing the NAMES
|
||||
# down safe anyway: each list is a SET comparison against the repository that owns
|
||||
# it, in both directions.
|
||||
#
|
||||
# The second direction is the one that earns its keep. A reference page does not
|
||||
# usually rot by describing something that vanished — it rots by quietly not
|
||||
# mentioning the three things added since it was written.
|
||||
#
|
||||
# Descriptions are deliberately NOT checked; nothing here can know whether a
|
||||
# one-line summary is still true, so it does not pretend to.
|
||||
#
|
||||
# Same token, and for the same reason: it reads five other repositories in the org.
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
|
||||
run: npm run check:reference
|
||||
|
||||
- name: The headers the server actually sends
|
||||
# PLAN.md §6 / D48, phase 10. Every other check reads dist/; this one starts
|
||||
# scripts/serve.mjs and reads the responses, because the defect it exists for
|
||||
# happened after the build was already correct. @astrojs/node matched a request to a
|
||||
# policy with a SUBSTRING test, so /modules/ was served the policy built for
|
||||
# /docs/modules/building-a-module — every file on disk right, the bytes on the wire
|
||||
# wrong, and the page rendered with its own stylesheet refused.
|
||||
#
|
||||
# It needs the build, so it cannot live in the "Unit tests" step above.
|
||||
run: npm run test:served
|
||||
|
||||
- name: Accessibility
|
||||
# PLAN.md §13, phase 10. Seven structural rules over every built page: one <h1> and
|
||||
# no skipped heading level, an alt attribute on every image, a label on every form
|
||||
# control, an accessible name on every link and button, <html lang>, one <main> with
|
||||
# a skip link that reaches it, and no positive tabindex.
|
||||
#
|
||||
# Structural on purpose. A static check cannot measure contrast on a rendered page
|
||||
# or find a focus trap, and a check that pretended to would be trusted for things it
|
||||
# cannot see. What it does catch is the class of defect that is invisible to a
|
||||
# sighted author and permanent once shipped — and it covers Starlight's forty pages
|
||||
# too, so a dependency upgrade that loses a label is a red build rather than a
|
||||
# discovery.
|
||||
#
|
||||
# After the build, because it reads dist/client. No token and no network.
|
||||
run: npm run check:a11y
|
||||
|
||||
- name: Content-Security-Policy
|
||||
# PLAN.md §6 / D48. The policy is a real response header — the Node adapter's
|
||||
# staticHeaders writes dist/_headers.json and the standalone server sends it — so
|
||||
# frame-ancestors applies and the operator's proxy needs no CSP config.
|
||||
#
|
||||
# The check that matters is the second one: every inline script and style must be
|
||||
# covered by a hash in ITS OWN page's policy. Astro does not hash <script is:inline>,
|
||||
# and Starlight ships six of them per documentation page, so the first build with CSP
|
||||
# enabled had a strict, correct header and a dead theme switcher — a failure with no
|
||||
# symptom except a console message. A Starlight upgrade can reintroduce it at any
|
||||
# time, which is why this runs on every PR rather than once.
|
||||
#
|
||||
# After the build, because it reads dist/. No token and no network.
|
||||
run: npm run check:csp
|
||||
|
||||
17
CODE_OF_CONDUCT.md
Normal file
@@ -0,0 +1,17 @@
|
||||
# Code of Conduct
|
||||
|
||||
This repository is covered by the Runic Gateway organisation's Code of Conduct — the Contributor
|
||||
Covenant, v2.1 — which applies identically across all ten repositories:
|
||||
|
||||
**[RunicGateway/docs → CODE_OF_CONDUCT.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/CODE_OF_CONDUCT.md)**
|
||||
|
||||
It covers the standards expected of everyone taking part, the scope (project spaces and public
|
||||
spaces where somebody represents the project), the enforcement guidelines, and **how to report
|
||||
unacceptable behaviour privately**.
|
||||
|
||||
Reporting goes to the organisation maintainer. That document carries the address; this file
|
||||
deliberately does not, for the same reason [SECURITY.md](SECURITY.md) does not — **D13** (`PLAN.md`
|
||||
§5) keeps the published contact address in one bind-mounted file so that changing it costs a file
|
||||
copy rather than a commit in ten repositories.
|
||||
|
||||
Reports are handled privately, and the reporter's identity is not shared with the person reported.
|
||||
141
CONTRIBUTING.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Contributing to runicgateway.com
|
||||
|
||||
Thanks for your interest. This repository is the **public marketing and documentation site** for
|
||||
[Runic Gateway][org] — the platform that puts a private game server's live state on a public website
|
||||
without ever exposing the game to the internet.
|
||||
|
||||
It is a site, not a component. Nothing else in the organisation depends on it, and it depends on
|
||||
everything: almost every sentence here describes something that lives in another repository.
|
||||
|
||||
By participating you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
|
||||
|
||||
## Read the plan first
|
||||
|
||||
**[`PLAN.md`](PLAN.md) is the design of record.** It is not a sketch — it carries the verified
|
||||
platform state, the org lead's fifty-odd decisions, the information architecture, the accuracy
|
||||
machinery and the build phases. A change that contradicts a decision recorded there needs the
|
||||
decision changed first, in the same pull request, with the reasoning written down.
|
||||
|
||||
Two things it records are worth knowing before you write a line:
|
||||
|
||||
- **§1 — the site never re-specifies a contract.** `docs/` is normative for the protocol, the module
|
||||
API, the backend design and the installer. This site teaches, links out, and quotes versions from
|
||||
data rather than prose. A page that restates a contract is a page that will be wrong later, and
|
||||
nothing will notice.
|
||||
- **§12 — the checks are the mechanism, and their failure is the feature.** When the platform moves,
|
||||
this repository goes red so that somebody updates the site. Do not route around a check; if one is
|
||||
wrong, fix the check and say why in the pull request.
|
||||
|
||||
## Ways to contribute
|
||||
|
||||
- **Report a bug** or **request a feature** through the [issue tracker][issues] — templates are
|
||||
provided.
|
||||
- **Improve a page, a check or the build** by opening a pull request.
|
||||
- **Never** report a security vulnerability in a public issue. See [SECURITY.md](SECURITY.md).
|
||||
|
||||
If you spot a claim on the site that is *wrong about the platform* — a version, a capability, a
|
||||
command that no longer exists — that is the most valuable report this repository can receive.
|
||||
|
||||
## Development setup
|
||||
|
||||
**Prerequisites:** Node 22 LTS or newer. Nothing else — no database, no game server, no container
|
||||
runtime for ordinary work.
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev # http://localhost:4321
|
||||
```
|
||||
|
||||
```bash
|
||||
npm run build # → dist/ (prerendered pages + the Node server entry)
|
||||
npm start # serve the built site, exactly as the container does
|
||||
```
|
||||
|
||||
Two directories are **bind mounts at runtime and not in the repository**: `brand/` overrides the
|
||||
stock branding per file, and `data/` holds the beta signup store. Both are optional locally; an
|
||||
absent `brand/` produces exactly the stock site, and `data/` is created on first write.
|
||||
|
||||
## The checks
|
||||
|
||||
There are twelve, plus two test suites. `npm run verify` runs all of them in dependency order, and
|
||||
that is what CI does on every pull request.
|
||||
|
||||
```bash
|
||||
npm run verify
|
||||
```
|
||||
|
||||
Three of them read other repositories over the Gitea API and need a token with access to the
|
||||
organisation, not just this repository:
|
||||
|
||||
```bash
|
||||
GITEA_TOKEN=<token> npm run check:facts # every version agrees with its authority
|
||||
GITEA_TOKEN=<token> npm run check:quickstart # the install page still matches website's own files
|
||||
GITEA_TOKEN=<token> npm run check:reference # every name the Reference lists still exists
|
||||
```
|
||||
|
||||
Without a token they fail rather than skip, deliberately: a check that silently passes when it could
|
||||
not do its job is worse than no check. CI maps the org-level `REGISTRY_TOKEN` secret into
|
||||
`GITEA_TOKEN` for those three steps.
|
||||
|
||||
The README's "The checks, and why they are not optional" section explains what each one guards.
|
||||
Read it before adding a page — several of them constrain how a page may be written, particularly
|
||||
`check:tokens` (no colour literal outside `src/styles/tokens.css`) and `check:links` (no commit
|
||||
permalinks into org repositories).
|
||||
|
||||
## Writing for this site
|
||||
|
||||
- **Understated honesty** (D8). The site reads as finished. Where something is not built, the
|
||||
absence is stated as data in `src/data/notBuilt.mjs` and rendered — never implied by silence and
|
||||
never dressed up as a roadmap.
|
||||
- **No version in prose.** Every externally-sourced fact lives in `src/data/platform.json` and is
|
||||
re-read from its authority by `check:facts`. If you find yourself typing a version number into a
|
||||
sentence, put it in the data file instead.
|
||||
- **No email address in `src/` or `scripts/`** (D13). The published contact is a `brand.json` field
|
||||
so that changing it stays a file copy and a restart. `check:facts` enforces this.
|
||||
- **British spelling**, in common with the rest of the organisation's prose.
|
||||
|
||||
## Branch and pull-request workflow
|
||||
|
||||
1. Branch from `main` with a descriptive name (`feature/…`, `fix/…`, `docs/…`, `chore/…`).
|
||||
2. Keep changes focused; small pull requests are easier to review.
|
||||
3. Run `npm run verify` before opening the pull request.
|
||||
4. Push and open a pull request against `main`. Fill out the template, including the **AI-assisted
|
||||
contributions** disclosure.
|
||||
5. A maintainer will review; address feedback with follow-up commits.
|
||||
|
||||
### Commit messages
|
||||
|
||||
[Conventional Commits](https://www.conventionalcommits.org/) — `type(scope): summary`, in common
|
||||
with every repository in the organisation. For example `fix(docs): correct the installer flag on the
|
||||
quickstart`.
|
||||
|
||||
### What merging does
|
||||
|
||||
Merging to `main` builds a container image, publishes it to the Gitea registry and **deploys it**
|
||||
(`.gitea/workflows/build-image.yml`). There is no separate release step and no manual promotion, so
|
||||
a merge is a publication. [`DEPLOY.md`](DEPLOY.md) describes the whole path, including how to roll
|
||||
back to a previous build.
|
||||
|
||||
## AI-assisted contributions (disclosure required)
|
||||
|
||||
This project is developed openly with AI assistance, and we ask the same transparency of everyone.
|
||||
**If you used an AI tool** (Claude, Copilot, ChatGPT, Cursor, etc.) to help produce a contribution,
|
||||
you must disclose it:
|
||||
|
||||
- Tick the AI-usage box in the pull-request template and name the tool(s).
|
||||
- Mark AI-authored commits with a trailer, e.g. `Co-Authored-By: Claude <noreply@anthropic.com>` or
|
||||
`Assisted-By: <tool>`.
|
||||
- You remain responsible for every line you submit: review it, understand it, and make sure it is
|
||||
correct and that you have the right to contribute it.
|
||||
|
||||
Disclosed AI assistance is welcome. Undisclosed AI-generated contributions are not, and may be
|
||||
closed.
|
||||
|
||||
## Licence
|
||||
|
||||
Runic Gateway is licensed under the **GNU General Public License v3.0 or later** (see
|
||||
[LICENSE](LICENSE)). By submitting a contribution you agree that it is licensed under the same terms
|
||||
(inbound = outbound) and that you have the right to contribute it.
|
||||
|
||||
[org]: https://gitea.whitlocktech.com/RunicGateway
|
||||
[issues]: https://gitea.whitlocktech.com/RunicGateway/runicgateway.com/issues
|
||||
409
DEPLOY.md
Normal file
@@ -0,0 +1,409 @@
|
||||
# Deploying runicgateway.com
|
||||
|
||||
The operator's guide. `PLAN.md` is the design of record and explains *why* the site is shaped this
|
||||
way; this file is what you follow on the host.
|
||||
|
||||
**What ships:** one container image, published to the Gitea registry, and the
|
||||
[`docker-compose.yml`](docker-compose.yml) in this repository. There is no installer and no
|
||||
`curl | bash`. The image is built and pushed by `.gitea/workflows/build-image.yml` on every merge to
|
||||
`main`, tagged `latest` and `sha-<7>`.
|
||||
|
||||
```
|
||||
gitea.whitlocktech.com/runicgateway/runicgateway-site:latest
|
||||
```
|
||||
|
||||
**What you provide:** a host with Docker, a reverse proxy that terminates TLS, and a DNS record.
|
||||
|
||||
---
|
||||
|
||||
## Contents
|
||||
|
||||
1. [What the site actually needs](#1-what-the-site-actually-needs)
|
||||
2. [First deploy](#2-first-deploy)
|
||||
3. [Putting a proxy in front of it](#3-putting-a-proxy-in-front-of-it)
|
||||
4. [DNS and TLS](#4-dns-and-tls)
|
||||
5. [Branding, without a rebuild](#5-branding-without-a-rebuild)
|
||||
6. [The closed-beta tester list](#6-the-closed-beta-tester-list)
|
||||
7. [Updating, and the automatic deploy](#7-updating-and-the-automatic-deploy)
|
||||
8. [Rolling back](#8-rolling-back)
|
||||
9. [Backups](#9-backups)
|
||||
10. [When something is wrong](#10-when-something-is-wrong)
|
||||
|
||||
---
|
||||
|
||||
## 1. What the site actually needs
|
||||
|
||||
Very little, and that is deliberate (`PLAN.md` §6).
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Runtime** | Docker, with Compose v2 (`docker compose`, not `docker-compose`) |
|
||||
| **CPU / RAM** | One core and 512 MB is comfortable. Every page but two is prerendered HTML |
|
||||
| **Disk** | ~750 MB for the image, plus a SQLite file that will not reach a megabyte |
|
||||
| **Network out** | Only to pull the image. The running site makes no outbound request of any kind |
|
||||
| **Network in** | One HTTP port, reached by your reverse proxy |
|
||||
| **Database** | None. No MariaDB, no Redis, no second service |
|
||||
| **Mail** | None. The site sends no email at all (D7) — there is nothing to configure |
|
||||
|
||||
It does **not** need the platform: no website, no sidecar, no shard. The site describes Runic
|
||||
Gateway; it does not talk to it.
|
||||
|
||||
## 2. First deploy
|
||||
|
||||
### 2.1 Create the directory
|
||||
|
||||
The compose file, the `.env` and both bind mounts live together. The automatic deploy
|
||||
([§7](#7-updating-and-the-automatic-deploy)) expects **`/opt/runicgateway.com`**; if you put it
|
||||
somewhere else, change the `cd` in `.gitea/workflows/build-image.yml`.
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/runicgateway.com
|
||||
sudo chown "$USER" /opt/runicgateway.com
|
||||
cd /opt/runicgateway.com
|
||||
```
|
||||
|
||||
Fetch the two files from this repository — the compose file, and the environment template:
|
||||
|
||||
```bash
|
||||
curl -fsSLO https://gitea.whitlocktech.com/RunicGateway/runicgateway.com/raw/branch/main/docker-compose.yml
|
||||
curl -fsSLO https://gitea.whitlocktech.com/RunicGateway/runicgateway.com/raw/branch/main/.env.example
|
||||
mv .env.example .env
|
||||
```
|
||||
|
||||
### 2.2 Create the two mounts
|
||||
|
||||
```bash
|
||||
mkdir -p brand data
|
||||
```
|
||||
|
||||
**`data/` must be writable by uid 1000**, which is what the container runs as. If you created it as
|
||||
another user:
|
||||
|
||||
```bash
|
||||
sudo chown -R 1000:1000 data
|
||||
```
|
||||
|
||||
Two failure modes this avoids, both of which look like a broken site rather than a permission
|
||||
problem:
|
||||
|
||||
- **A missing directory.** Docker creates a bind-mount source that does not exist, as `root:root`.
|
||||
The container then cannot open the store, and `/beta` renders with the form replaced by "the
|
||||
signup is temporarily unavailable" — correct behaviour, and a confusing thing to debug.
|
||||
- **`brand/` deleted later.** Same mechanism. An empty `brand/` is fine and produces exactly the
|
||||
stock site; a *missing* one gets recreated as root, and since the container only ever reads it,
|
||||
nothing breaks until the day you want to change the logo.
|
||||
|
||||
### 2.3 Fill in the two secrets
|
||||
|
||||
Open `.env`. Everything has a working default except `BETA_IP_SALT` and `BETA_FORM_KEY`, which
|
||||
default to a random value **per process** — safe, but forgotten on every restart, which means every
|
||||
rate-limit window resets and every open form goes stale.
|
||||
|
||||
```bash
|
||||
printf 'BETA_IP_SALT=%s\n' "$(openssl rand -hex 32)" >> .env
|
||||
printf 'BETA_FORM_KEY=%s\n' "$(openssl rand -hex 32)" >> .env
|
||||
```
|
||||
|
||||
(Then delete the two empty declarations the template shipped with, so the file has one of each.)
|
||||
|
||||
Do not rotate the salt casually: it is what makes the stored `ip_hash` values meaningful, so
|
||||
changing it orphans the rate-limit history of everyone already counted. The raw IP address is never
|
||||
stored — `/privacy` says so, and the salt is the mechanism that makes it true.
|
||||
|
||||
### 2.4 Log in to the registry and start
|
||||
|
||||
The image is published to the organisation's Gitea registry. If the package is not public-read, log
|
||||
in once with a token that has `read:package`:
|
||||
|
||||
```bash
|
||||
docker login gitea.whitlocktech.com
|
||||
```
|
||||
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
`ps` should show `site` as `running (healthy)` within about a minute. Health is a real HTTP request
|
||||
rather than a process check, and the delay is expected: `npm start` runs the brand rewrite before
|
||||
the server starts.
|
||||
|
||||
### 2.5 Confirm it from the host
|
||||
|
||||
```bash
|
||||
curl -sI http://127.0.0.1:4321/ | head -n 1
|
||||
curl -sI http://127.0.0.1:4321/ | grep -i content-security-policy | cut -c1-120
|
||||
```
|
||||
|
||||
The port is published on every interface by default ([§3.1](#31-forward-to-the-published-port)), so
|
||||
the same two commands work from any other machine on the network with the host's address in place of
|
||||
`127.0.0.1` — which is the quickest way to look at the site in a real browser before DNS or the
|
||||
proxy exists.
|
||||
|
||||
The second command matters more than the first. The site sends its **own** Content-Security-Policy,
|
||||
per page, built from the hashes of that page's inline scripts and styles. If it is missing, do not
|
||||
add one at the proxy — see below.
|
||||
|
||||
## 3. Putting a proxy in front of it
|
||||
|
||||
The container publishes on **port 4321 of every interface** by default and speaks plain HTTP, so it
|
||||
answers both on `http://127.0.0.1:4321` and on the host's own address — `http://<vm-ip>:4321`. Any
|
||||
reverse proxy will do; the site has no opinion about which. What it does have is four requirements,
|
||||
and the third is the one that is easy to get wrong and quiet when you do.
|
||||
|
||||
### 3.1 Forward to the published port
|
||||
|
||||
Whatever your proxy calls it: forward `runicgateway.com` (and `www.` if you want it) to
|
||||
`http://<host>:4321` — loopback if the proxy runs on this same machine, the host's address if it
|
||||
runs in another container or on another machine. There are no WebSockets, no long-polling, no
|
||||
streaming responses and no upload larger than a form field, so no timeout or buffering setting needs
|
||||
changing.
|
||||
|
||||
A proxy on a shared Docker network can address the service as `site:4321` instead and skip the host
|
||||
port entirely.
|
||||
|
||||
**Narrowing the binding.** `SITE_BIND_ADDR` in `.env` decides which addresses the port answers on,
|
||||
and nothing else in the site changes with it:
|
||||
|
||||
```bash
|
||||
SITE_BIND_ADDR=0.0.0.0 # every interface — the default
|
||||
SITE_BIND_ADDR=192.168.1.10 # one interface: the LAN, but not a public NIC
|
||||
SITE_BIND_ADDR=127.0.0.1 # loopback only: a proxy on THIS host and nothing else
|
||||
```
|
||||
|
||||
**On a host with a public address, the default means port 4321 answers from the internet directly**,
|
||||
beside whatever the proxy serves on 443 — plain HTTP, no TLS, and no proxy in the path to set
|
||||
`X-Forwarded-For` ([§3.2](#32-set-x-forwarded-for)), so signups arriving that way share one
|
||||
rate-limit bucket. There is no login and nothing to steal, so this is untidy rather than dangerous —
|
||||
but on a public host, firewall the port or narrow the binding.
|
||||
|
||||
### 3.2 Set `X-Forwarded-For`
|
||||
|
||||
**This one is load-bearing.** The beta signup rate-limits per client, and it reads the first entry of
|
||||
`X-Forwarded-For`, falling back to the connection's peer address. Behind a proxy that does not set
|
||||
the header, that peer address is *the proxy* — so every visitor on earth shares one bucket, and the
|
||||
third signup of any hour closes the form for everybody.
|
||||
|
||||
It fails toward refusing signups rather than toward accepting abuse, which is the right direction,
|
||||
but it is still a broken page. Most proxies set the header by default; confirm yours does.
|
||||
|
||||
`X-Forwarded-Proto` and `Host` are worth passing through as well, in common with any site behind a
|
||||
proxy.
|
||||
|
||||
### 3.3 Do not add security headers at the proxy
|
||||
|
||||
The container already sends `Content-Security-Policy`, `X-Content-Type-Options`, `Referrer-Policy`,
|
||||
`X-Frame-Options` and a `Permissions-Policy` (`PLAN.md` D48). That is deliberate: the image should be
|
||||
correct on its own, and a proxy somebody else configures is a promise this repository cannot check.
|
||||
|
||||
If your proxy adds its own, you get **two** of each. Browsers resolve a duplicate CSP by enforcing
|
||||
the intersection — that is, the *strictest* combination of both — and since this site's policy is a
|
||||
list of per-page hashes, a second generic policy from a proxy will forbid the page's own stylesheet
|
||||
and inline scripts. The site renders unstyled, the documentation theme switcher stops working, and
|
||||
the only symptom is a console message.
|
||||
|
||||
So: strip a global CSP for this host if your proxy adds one. The one header worth adding at the
|
||||
proxy is HSTS, which the container cannot sensibly set because it does not know whether it is behind
|
||||
TLS.
|
||||
|
||||
### 3.4 Give it a real hostname
|
||||
|
||||
Two absolute URLs are generated at build time — the sitemap and the OpenGraph `og:url` — so the site
|
||||
expects to be served at its own name rather than under a path. Serving it at `example.com/site/` will
|
||||
work visually and produce wrong metadata.
|
||||
|
||||
## 4. DNS and TLS
|
||||
|
||||
The domain is registered through **Cloudflare**, with DNS on Cloudflare (`PLAN.md` §14, N1).
|
||||
|
||||
1. In the Cloudflare dashboard, add an `A` record for `runicgateway.com` pointing at the host's
|
||||
public IP (and `AAAA` if it has a v6 address). Add `www` as a `CNAME` to the apex if you want it.
|
||||
2. Let your proxy obtain the certificate — Let's Encrypt over HTTP-01 works once the record
|
||||
resolves.
|
||||
|
||||
**If you leave Cloudflare's proxy on (the orange cloud)**, three of its features rewrite HTML and
|
||||
will break the hash-based CSP. Check them before assuming the site is at fault:
|
||||
|
||||
- **Rocket Loader** — injects a script into every page. Not covered by any hash. Turn it off.
|
||||
- **Auto Minify / HTML minification** — changes the bytes of inline `<style>` and `<script>`
|
||||
elements, so their hashes no longer match what the header declares. Turn it off.
|
||||
- **Email address obfuscation** — injects a script *and* rewrites the contact address into an
|
||||
obfuscated span. Turn it off; the address on this site is published deliberately (D13).
|
||||
|
||||
Everything else — caching, Brotli, HTTP/3, Always Use HTTPS — is fine. If you would rather not think
|
||||
about it, DNS-only (the grey cloud) works and the site loses nothing, since it uses no third-party
|
||||
resource at all.
|
||||
|
||||
## 5. Branding, without a rebuild
|
||||
|
||||
`brand/` is the override; the image's `brand-default/` is the stock. **Every file resolves against
|
||||
the mount first and the defaults second, per file**, so a directory holding only `theme.css`
|
||||
recolours the site and leaves every logo alone. `PLAN.md` §7 is the full account.
|
||||
|
||||
```
|
||||
brand/
|
||||
brand.json Site name, tagline, contact address, Discord invite, Gitea org,
|
||||
demo URL, Play opt-in URL
|
||||
logo.png ONE raster. Every size the site asks for — header at three pixel
|
||||
ratios, install icons, apple-touch, favicons, a real .ico — is
|
||||
derived from it on demand
|
||||
theme.css Redefines the custom properties in tokens.css. It wins by cascade
|
||||
layer, so it does not need to be loaded last
|
||||
```
|
||||
|
||||
```bash
|
||||
# edit or drop in a file, then:
|
||||
docker compose restart site
|
||||
```
|
||||
|
||||
The restart is what rewrites the brand text into the prerendered HTML and re-indexes search — a
|
||||
mounted site name has to reach forty-nine pages that were rendered before the file existed.
|
||||
|
||||
**One field needs no restart:** `betaOptInUrl`. `/beta` renders per request and reads it live, so the
|
||||
day the Play closed test opens, pasting the URL into `brand/brand.json` puts a working link on the
|
||||
confirmation screen on the very next request.
|
||||
|
||||
To see which source answered a given asset:
|
||||
|
||||
```bash
|
||||
curl -sI http://127.0.0.1:4321/brand/logo.png | grep -i x-brand-source
|
||||
```
|
||||
|
||||
`mount`, `default`, or `derived:mount` / `derived:default` when the size was generated on demand
|
||||
from whichever `logo.png` is in force.
|
||||
|
||||
## 6. The closed-beta tester list
|
||||
|
||||
There is no admin page, by design (`PLAN.md` §8) — the site has no authenticated surface at all. The
|
||||
list is managed from a shell against the mount.
|
||||
|
||||
```bash
|
||||
cd /opt/runicgateway.com
|
||||
|
||||
docker compose exec site node scripts/beta.mjs stats
|
||||
docker compose exec site node scripts/beta.mjs export # marks the rows exported
|
||||
docker compose exec site node scripts/beta.mjs export --all # everything, again
|
||||
docker compose exec site node scripts/beta.mjs remove someone@example.com
|
||||
```
|
||||
|
||||
`export` writes two files into `data/exports/` — a CSV record, and a `.txt` of one address per line,
|
||||
which is the format Google Play's tester list accepts. They are on the bind mount, so they are on the
|
||||
host at `./data/exports/` and can be copied off with `scp` like any other file.
|
||||
|
||||
`remove` is a deletion request, and it **overwrites** the address, the IP hash and the user agent
|
||||
rather than flagging the row. That is what `/privacy` promises; the row survives only as an anonymous
|
||||
record that a signup happened.
|
||||
|
||||
## 7. Updating, and the automatic deploy
|
||||
|
||||
Merging to `main` builds the image, pushes it, and **deploys it** (D54). No manual step, no release
|
||||
tag. What protects production is that every one of the eleven checks and both test suites have
|
||||
already run on the pull request, and the deploy job is `needs: build`, so a failed build never
|
||||
reaches the host.
|
||||
|
||||
That requires a Gitea Actions runner **on this host**, labelled `rgcom`, running jobs directly on
|
||||
the host rather than inside a container — it needs the host's Docker daemon and
|
||||
`/opt/runicgateway.com`.
|
||||
|
||||
```bash
|
||||
# On the host, once. Get the registration token from
|
||||
# Gitea → the repository → Settings → Actions → Runners → Create new runner
|
||||
act_runner register \
|
||||
--no-interactive \
|
||||
--instance https://gitea.whitlocktech.com \
|
||||
--token <REGISTRATION_TOKEN> \
|
||||
--name runicgateway-com-host \
|
||||
--labels rgcom:host
|
||||
```
|
||||
|
||||
`rgcom:host` — the `:host` suffix is what makes jobs run on the machine rather than in a job
|
||||
container. Without it the job starts in a container with no Docker socket and no
|
||||
`/opt/runicgateway.com`, and fails on the `cd`.
|
||||
|
||||
Make sure the user the runner runs as can talk to Docker (`docker ps` succeeds) and can read and
|
||||
write `/opt/runicgateway.com`.
|
||||
|
||||
**Until that runner exists, the deploy job just queues**, and nothing is harmed: the image has
|
||||
already been built and pushed by the time it would run, so the manual update below works throughout,
|
||||
and the queued job goes as soon as the runner registers.
|
||||
|
||||
**One way the automatic deploy can fail before it starts.** The registry is behind Cloudflare, which
|
||||
refuses a request body over 100 MB, and `docker push` uploads each image layer as a single request —
|
||||
so a layer that grows past that is rejected at the edge with `413 Payload Too Large`, publishing
|
||||
nothing. `needs: build` then keeps the deploy from running at all, which means the container you are
|
||||
already serving is left alone; the site is simply not updated. The workflow checks layer sizes before
|
||||
it pushes and fails with a message naming the layer, so this should announce itself rather than
|
||||
arriving as a `413`. Either way it is fixed in the `Dockerfile` (see the `COPY` block that splits
|
||||
`node_modules`) and nothing needs doing on the host.
|
||||
|
||||
**To update by hand instead** — always available, and what you do if the runner is down:
|
||||
|
||||
```bash
|
||||
cd /opt/runicgateway.com
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
The compose file has no `build:` at all, so a production host can only ever pull.
|
||||
|
||||
## 8. Rolling back
|
||||
|
||||
Every merge publishes two tags: `latest` and `sha-<7>` of the commit. To pin:
|
||||
|
||||
```bash
|
||||
cd /opt/runicgateway.com
|
||||
sed -i 's/^IMAGE_TAG=.*/IMAGE_TAG=sha-1806406/' .env
|
||||
docker compose pull && docker compose up -d
|
||||
```
|
||||
|
||||
Set it back to `latest` to resume following `main`. Note that while it is pinned, the automatic
|
||||
deploy still runs and still pulls — but Compose recreates the container on the *pinned* tag, so the
|
||||
site stays where you put it. That is the intended behaviour: a pin is a decision, and a merge should
|
||||
not quietly undo it.
|
||||
|
||||
The tags are listed under **Packages** on the organisation's Gitea page.
|
||||
|
||||
## 9. Backups
|
||||
|
||||
One file matters: `data/beta.sqlite`. The rest of the site is in the image and in git.
|
||||
|
||||
It is a live SQLite database in WAL mode, so **do not just `cp` it** — a copy taken mid-write can
|
||||
miss committed rows sitting in the `-wal` file. Either use SQLite's own backup, which is safe against
|
||||
a running writer:
|
||||
|
||||
```bash
|
||||
cd /opt/runicgateway.com
|
||||
docker compose exec site node -e "const db=require('better-sqlite3')(process.env.DATA_DIR+'/beta.sqlite');db.exec(\"VACUUM INTO '/app/data/beta-backup.sqlite'\");db.close()"
|
||||
mv data/beta-backup.sqlite /somewhere/safe/beta-$(date +%F).sqlite
|
||||
```
|
||||
|
||||
or stop the container first and copy all three files (`beta.sqlite`, `-wal`, `-shm`) together.
|
||||
|
||||
`brand/` is worth keeping too, if you have customised it — it is the one part of a running
|
||||
deployment that exists nowhere else.
|
||||
|
||||
## 10. When something is wrong
|
||||
|
||||
```bash
|
||||
cd /opt/runicgateway.com
|
||||
docker compose logs --tail 200 site
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
| Symptom | Cause worth checking first |
|
||||
|---|---|
|
||||
| Container restarts, or never becomes healthy | `data/` not writable by uid 1000 — `sudo chown -R 1000:1000 data` |
|
||||
| `/beta` says the signup is unavailable | Same. The rest of the site is unaffected, which is by design |
|
||||
| Every visitor hits the rate limit | The proxy is not setting `X-Forwarded-For` — [§3.2](#32-set-x-forwarded-for) |
|
||||
| Rate limits reset on every restart | `BETA_IP_SALT` is unset in `.env` — [§2.3](#23-fill-in-the-two-secrets) |
|
||||
| Pages render unstyled; console says `Refused to apply inline style` | A second CSP from the proxy or from Cloudflare Rocket Loader / minification — [§3.3](#33-do-not-add-security-headers-at-the-proxy), [§4](#4-dns-and-tls) |
|
||||
| A new logo or site name has not appeared | The mount needs a `docker compose restart site`, not just a file edit — [§5](#5-branding-without-a-rebuild) |
|
||||
| Search finds the old site name | Same restart; the boot rewrite re-indexes |
|
||||
| The site is stock despite files in `brand/` | Check the mount actually landed: `docker compose exec site ls /app/brand` |
|
||||
| A merge did not deploy, and the build job is red | If it failed on the layer check or on a `413`, a layer grew past Cloudflare's 100 MB request limit — [§7](#7-updating-and-the-automatic-deploy). The running container is untouched; the fix is in the Dockerfile, not on the host |
|
||||
|
||||
Everything the container writes goes to stdout, so `docker compose logs` is the whole log. The
|
||||
reverse proxy's access log is the only traffic data that exists — there are no analytics anywhere on
|
||||
the site (D9).
|
||||
132
Dockerfile
Normal file
@@ -0,0 +1,132 @@
|
||||
# runicgateway.com — the one container (PLAN.md §6).
|
||||
#
|
||||
# Two stages. The first has the whole toolchain and produces `dist/`; the second
|
||||
# carries the built site, the pruned runtime dependencies and nothing else.
|
||||
#
|
||||
# Debian slim rather than Alpine, deliberately. Two of the runtime dependencies
|
||||
# are native — `better-sqlite3` (the beta store, §8) and `sharp` (the brand
|
||||
# derivations, §7) — and both publish prebuilt binaries for glibc. On musl they
|
||||
# are compiled from source instead, which means a C++ toolchain, libvips headers
|
||||
# and several minutes in the image build, to save about sixty megabytes on a
|
||||
# thing that is pulled a few times a year. A third, `pagefind`, ships a platform
|
||||
# binary and is needed at RUN time, not just build time: the boot rewrite
|
||||
# re-indexes the site after the brand strings change.
|
||||
|
||||
# ---------------------------------------------------------------------------------------
|
||||
# Stage 1 — build
|
||||
# ---------------------------------------------------------------------------------------
|
||||
FROM node:22-bookworm-slim AS build
|
||||
|
||||
WORKDIR /build
|
||||
|
||||
# Dependencies first, so an edit to a page does not re-resolve the tree.
|
||||
COPY package.json package-lock.json ./
|
||||
RUN npm ci
|
||||
|
||||
# Then the source. .dockerignore keeps node_modules, dist and BOTH bind mounts out.
|
||||
COPY . .
|
||||
|
||||
# Prerenders every marketing, legal and documentation page, builds the Node
|
||||
# server entry for the two routes that run per request, and writes the per-route
|
||||
# Content-Security-Policy into dist/_headers.json (D48).
|
||||
#
|
||||
# No token and no network: everything the build reads is in this context. The
|
||||
# checks that DO need the Gitea API — facts, quickstart, reference — run in CI
|
||||
# against the pull request, which is the right place for them. An image build
|
||||
# that could fail because another repository's server was slow would be an image
|
||||
# build people learn to retry rather than read.
|
||||
RUN npm run build
|
||||
|
||||
# Drop the devDependencies from the tree the runtime stage inherits. Pruning
|
||||
# here rather than running a second `npm ci --omit=dev` below keeps the native
|
||||
# modules exactly as they were resolved and built once.
|
||||
RUN npm prune --omit=dev
|
||||
|
||||
# Set the two largest packages aside so the runtime stage can copy them as their
|
||||
# own layers. See the COPY block below for why a single node_modules layer could
|
||||
# not be pushed at all. Moving them rather than copying them twice is what keeps
|
||||
# the three layers disjoint: whatever is left in node_modules is exactly the
|
||||
# remainder, and a dependency added later lands in it automatically.
|
||||
RUN mkdir -p /split \
|
||||
&& mv node_modules/@pagefind /split/ \
|
||||
&& mv node_modules/@img /split/
|
||||
|
||||
# ---------------------------------------------------------------------------------------
|
||||
# Stage 2 — runtime
|
||||
# ---------------------------------------------------------------------------------------
|
||||
FROM node:22-bookworm-slim AS runtime
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
ENV NODE_ENV=production \
|
||||
HOST=0.0.0.0 \
|
||||
PORT=4321
|
||||
|
||||
# Both bind mounts, named here so the code's own `process.cwd()` defaults are
|
||||
# never what a container relies on. See docker-compose.yml.
|
||||
ENV BRAND_DIR=/app/brand \
|
||||
DATA_DIR=/app/data
|
||||
|
||||
# The stock brand, baked in and always complete (§7). Every /brand/* URL resolves
|
||||
# against the mount first and this second, per file.
|
||||
ENV BRAND_DEFAULT_DIR=/app/brand-default
|
||||
|
||||
# `dist/` is owned by `node` because the boot rewrite WRITES to it: applyBrand.mjs
|
||||
# rewrites the prerendered HTML from what it last applied to what the mount now
|
||||
# says, records that in dist/.brand-applied.json, and re-indexes dist/client/pagefind
|
||||
# so search finds the mounted site name. A read-only dist would make §7's promise
|
||||
# — recolour and rename by copying a file — fail at boot with a permission error.
|
||||
# node_modules arrives in THREE layers, not one, and the reason is the registry
|
||||
# rather than anything about the site.
|
||||
#
|
||||
# Gitea sits behind Cloudflare, which refuses a request body over 100 MB on every
|
||||
# plan below Enterprise, and `docker push` uploads each layer as one monolithic
|
||||
# PUT. A single `COPY node_modules` measured **108.8 MB compressed** — nine over —
|
||||
# so the first merge to `main` after phase 12 failed with `413 Payload Too Large`
|
||||
# on that one blob, from the edge, with Gitea never seeing the request. Nothing
|
||||
# was published, and `needs: build` meant nothing was deployed either.
|
||||
#
|
||||
# `@pagefind` (the search index binaries) and `@img` (sharp's libvips) are the two
|
||||
# packages that make it fat and both are needed at RUN time — the boot rewrite
|
||||
# re-indexes the site and re-derives the brand images — so the fix is where they
|
||||
# land, not whether they ship. Split, they measure 54.7 + 50.6 + 12.1 MB, the
|
||||
# largest with about 45 MB of headroom.
|
||||
#
|
||||
# That headroom is why the workflow counts layers before it pushes: this is a
|
||||
# margin, not a guarantee, and a dependency that grows past it would otherwise
|
||||
# come back as the same unreadable 413. See `.gitea/workflows/build-image.yml`.
|
||||
COPY --from=build --chown=node:node /build/node_modules ./node_modules
|
||||
COPY --from=build --chown=node:node /split/@pagefind ./node_modules/@pagefind
|
||||
COPY --from=build --chown=node:node /split/@img ./node_modules/@img
|
||||
COPY --from=build --chown=node:node /build/dist ./dist
|
||||
COPY --from=build --chown=node:node /build/brand-default ./brand-default
|
||||
COPY --from=build --chown=node:node /build/scripts ./scripts
|
||||
COPY --from=build --chown=node:node /build/package.json ./package.json
|
||||
|
||||
# `src/` is here for one reason: the tester-list CLI. §8 has no admin page by
|
||||
# design, so managing the closed beta is `docker compose exec site node
|
||||
# scripts/beta.mjs …`, and that reaches into src/lib/betaStore.mjs. Nothing
|
||||
# serving a request reads it — the pages were prerendered in stage 1.
|
||||
COPY --from=build --chown=node:node /build/src ./src
|
||||
|
||||
# Both mount points exist in the image, owned by the runtime user. An operator
|
||||
# who forgets a mount then gets a working stock site and an empty store rather
|
||||
# than a container that will not start; and `data/` being writable by uid 1000
|
||||
# BEFORE Docker creates it is what stops the store failing to open. If the host
|
||||
# directory is owned by someone else, `chown 1000:1000 ./data` on the host.
|
||||
RUN mkdir -p /app/brand /app/data && chown -R node:node /app/brand /app/data
|
||||
|
||||
USER node
|
||||
|
||||
EXPOSE 4321
|
||||
|
||||
# Cheap, and it tests the thing that actually breaks: `npm start` runs the brand
|
||||
# rewrite BEFORE the server, so a container can sit alive for a long moment with
|
||||
# nothing listening. A healthcheck that only watched the process would call that
|
||||
# healthy.
|
||||
HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
|
||||
CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT || 4321) + '/').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
|
||||
|
||||
# applyBrand.mjs, then serve.mjs. Not dist/server/entry.mjs directly — see the
|
||||
# header comment in scripts/serve.mjs for the adapter bug that wrapper exists for.
|
||||
CMD ["npm", "start"]
|
||||
@@ -32,6 +32,7 @@ Where the console offers free text about security practices, two things are wort
|
||||
| App info and performance | Other app data | No | No | Not collected by us. Stored on the device only. |
|
||||
| Messages | Other in-app messages | No | No | Not collected by us. Declare the relay hop in the console’s free-text security section if it asks. |
|
||||
| Messages | Other user-generated content | No | No | Not collected by us. |
|
||||
| Messages | Other in-app messages | No | No | Not collected by us. Stored on the device only. |
|
||||
| Device or other IDs | Device or other IDs | No | No | Not collected. |
|
||||
|
||||
## Each answer, and why it is the truthful one
|
||||
@@ -83,12 +84,23 @@ Push is off until you enable it. When you do, the app mints a random, unguessabl
|
||||
|
||||
**Messages → Other user-generated content.** Not collected by us.
|
||||
|
||||
Forum posts, Team activity, character and shard information, notification preferences: all of it is a live read or write against the deployment. Nothing is cached for offline use and nothing is duplicated anywhere else — the app with no signal is an app with no content, which is a limitation and also an accurate description of where the data lives.
|
||||
Forum posts, Team activity, character and shard information, notification preferences: all of it is a live read or write against the deployment. Apart from the notification snapshot described in the next entry, nothing is cached for offline use and nothing is duplicated anywhere else — the app with no signal is an app with almost no content, which is a limitation and also an accurate description of where the data lives.
|
||||
|
||||
- **Why that answer:** Content is written to the community’s own installation. We have no copy, no access and no way to obtain one.
|
||||
- **Retention:** Held by the deployment, under its operator’s policy
|
||||
- **Read from:** `PLAN.md §9 section 2`
|
||||
|
||||
### A snapshot of your notifications, so the inbox opens without a signal
|
||||
|
||||
**Messages → Other in-app messages.** Not collected by us. Stored on the device only.
|
||||
|
||||
The app keeps the most recent notifications it has already fetched — at most thirty, and only the first page — on the device, so opening the inbox shows you what you had rather than a spinner. It is a copy of what the deployment already sent you and it is refreshed from there; nothing is written here that was not read from your own account. It is scoped to the account that fetched it, so a second person signing in on the same phone is never shown the first one’s messages.
|
||||
|
||||
- **Why that answer:** The snapshot is written on the phone from data the deployment had already delivered. It is not uploaded anywhere, and no server we operate is on either end of it.
|
||||
- **Retention:** Until you sign out, or the thirty are pushed out by newer ones
|
||||
- **In detail:** Signing out deletes the snapshot outright. It lives in the app’s ordinary preference store rather than the encrypted one — sign-in tokens are the thing that store is for — which is worth stating plainly: on a device where someone has root, these are readable, and they are notification bodies rather than credentials.
|
||||
- **Read from:** `core/inbox/DataStoreInboxCache.kt, data/repository/AuthRepository.kt`
|
||||
|
||||
### No analytics, no crash reporting, no advertising
|
||||
|
||||
**Device or other IDs → Device or other IDs.** Not collected.
|
||||
@@ -116,4 +128,4 @@ Not part of the Data Safety form — that form is about the app — but a review
|
||||
- **Your browser’s user-agent string, truncated** — With the row; blanked on removal.
|
||||
- **The web server’s access log** — Short-term operational retention, then rotated away.
|
||||
|
||||
Last generated from data dated 2026-08-24. Regenerate with `npm run play:datasafety` after any change to what the app stores.
|
||||
Last generated from data dated 2026-09-01. Regenerate with `npm run play:datasafety` after any change to what the app stores.
|
||||
|
||||
108
README.md
@@ -11,11 +11,12 @@ closed beta: **players**, who want the app.
|
||||
platform state, the org lead's decisions, the information architecture, and the build phases. Read
|
||||
it before changing anything here.
|
||||
|
||||
**Status: phase 5 of 12 — the app and the beta.** The foundation, the branding pipeline, the
|
||||
homepage and the five marketing pages are built, and `/app/` and `/beta/` now join them: a signed
|
||||
APK beside the closed-test signup, backed by a SQLite store on a bind mount and an export CLI. Next
|
||||
are the legal pages (phase 6) and then the documentation — the installation path, which is the
|
||||
priority of the whole project — in phases 7 and 8.
|
||||
**Status: phase 12 of 12 — delivery. The site is built.** Fifty pages: ten marketing, legal and
|
||||
app pages and forty of documentation, with real screenshots of the product, full-text search, a
|
||||
per-page Content-Security-Policy, twelve checks that fail the build when the platform moves out from
|
||||
under a claim, and a closed-beta signup backed by SQLite on a bind mount. This phase is the part
|
||||
that makes it a deployment rather than a repository — the container image, the compose file, the
|
||||
publishing workflow and [`DEPLOY.md`](DEPLOY.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -31,21 +32,44 @@ npm run build # → dist/ (prerendered pages + the Node server entry)
|
||||
npm start # serve the built site
|
||||
```
|
||||
|
||||
Node 22 LTS or newer.
|
||||
Node 22 LTS or newer. Nothing else — no database, no game server, no container runtime.
|
||||
|
||||
## Running it in production
|
||||
|
||||
One container, pulled from the Gitea registry, with two bind mounts and a reverse proxy in front.
|
||||
**[`DEPLOY.md`](DEPLOY.md) is the operator's guide**: first deploy, what the proxy must and must not
|
||||
do, DNS and TLS, branding without a rebuild, managing the tester list, rolling back, and the
|
||||
symptoms table.
|
||||
|
||||
```bash
|
||||
docker compose pull && docker compose up -d
|
||||
```
|
||||
|
||||
Merging to `main` builds the image, publishes it as `runicgateway-site:latest` and `:sha-<7>`, and
|
||||
deploys it — `.gitea/workflows/build-image.yml`. There is no separate release step, so **a merge is
|
||||
a publication**.
|
||||
|
||||
## The checks, and why they are not optional
|
||||
|
||||
Two of them, both from `PLAN.md` §12. Neither is a linter; each one enforces a promise the site
|
||||
makes that would otherwise decay quietly.
|
||||
Twelve of them, from `PLAN.md` §12. None is a linter; each one enforces a promise the site makes
|
||||
that would otherwise decay quietly.
|
||||
|
||||
```bash
|
||||
npm run check:sidebar # the rendered docs tree still matches the planned one
|
||||
npm run check:terms # no game's vocabulary outside that game's section
|
||||
npm run check:screens # every screenshot has an entry, at the size declared
|
||||
npm run check:tokens # no colour literal outside the token file
|
||||
npm run check:brand # the branding pipeline's two quiet failures
|
||||
npm run check:datasafety # the Play declaration still matches /privacy
|
||||
npm run check # astro check
|
||||
npm test # the beta signup's decision path, and the policy data
|
||||
npm run build && npm run check:links # every internal link resolves (reads the build)
|
||||
npm run build # everything below reads the build
|
||||
npm run check:links # every internal link resolves
|
||||
GITEA_TOKEN=<token> npm run check:facts # every version agrees with its authority
|
||||
GITEA_TOKEN=<token> npm run check:quickstart # the install page still matches website's own files
|
||||
GITEA_TOKEN=<token> npm run check:reference # every name the Reference lists still exists
|
||||
npm run check:a11y # seven structural accessibility rules, every page
|
||||
npm run check:csp # every inline script and style is hashed in its policy
|
||||
npm run verify # all of the above, in that order
|
||||
```
|
||||
|
||||
@@ -81,6 +105,22 @@ carry are assembled from data files and template literals and a source scan sees
|
||||
also refuses a commit permalink into any org repository — those stop tracking the document they name
|
||||
without ever 404ing, which is the failure a link checker would otherwise call healthy.
|
||||
|
||||
**`checkA11y.mjs`** applies seven structural rules to every built page — one `<h1>` and no skipped
|
||||
heading level, an `alt` on every image, a label on every form control, an accessible name on every
|
||||
link and button, `<html lang>`, one `<main>` with a skip link that reaches it, and no positive
|
||||
`tabindex`. Structural on purpose: a static check cannot measure contrast on a rendered page or find
|
||||
a focus trap, and one that pretended to would be trusted for things it cannot see. It covers
|
||||
Starlight's forty pages as well as our ten, so a dependency upgrade that loses a label turns the
|
||||
build red rather than becoming a discovery.
|
||||
|
||||
**`checkCsp.mjs`** verifies that every route has a policy and that **every inline script and style is
|
||||
covered by a hash in its own page's policy**. That second rule is the one that earns its keep: Astro
|
||||
does not hash `<script is:inline>`, and Starlight ships six of them per documentation page, so the
|
||||
first build with CSP enabled had a strict, correct header and a dead theme switcher — a failure whose
|
||||
only symptom is a console message. When Starlight is upgraded and a hash stops matching,
|
||||
`npm run csp:hashes` rebuilds, re-harvests `src/config/cspHashes.mjs` and rebuilds again; read the
|
||||
diff before committing it, because that file is a list of scripts allowed to run.
|
||||
|
||||
**`npm test`** is the one check that reads none of the above. Everything else inspects built output,
|
||||
and the beta signup's logic does not appear there: a honeypot can stop working entirely and produce
|
||||
a build identical to one where it works. It covers the honeypot, the signed form token, the timing
|
||||
@@ -147,6 +187,40 @@ Regenerating the stock assets is a separate, manual step — `npm run brand:asse
|
||||
the emblem and the Cinzel outlines from the sibling checkouts in the workspace. Its output is
|
||||
committed so that CI never needs either.
|
||||
|
||||
## Security headers, and the one workaround in the server
|
||||
|
||||
`npm start` runs `scripts/applyBrand.mjs` and then `scripts/serve.mjs` — not
|
||||
`dist/server/entry.mjs` directly. `serve.mjs` is a thin wrapper around the adapter's own handler,
|
||||
and it exists for two reasons.
|
||||
|
||||
The first is a bug in `@astrojs/node`. Its `staticHeaders` option writes one Content-Security-Policy
|
||||
per prerendered route into `dist/_headers.json`, then looks the right one up per request with
|
||||
`headersMap.find((h) => h.pathname.includes(baselessPathname))` — a **substring** test taking the
|
||||
first match. So `/modules/` was served the policy built for `/docs/modules/building-a-module`,
|
||||
`/architecture/` got a docs page's, and `/`, being a substring of every path in the file, got
|
||||
whichever record came first. Because each policy is a list of per-page hashes, that is not a
|
||||
cosmetic mismatch: the browser refused the page's own stylesheet, and `/modules/` and
|
||||
`/architecture/` rendered unstyled with `Refused to apply inline style` in a console. The wrapper
|
||||
keeps the same `_headers.json` and matches by **equality**. It is deliberately small so it can be
|
||||
deleted whole once the upstream `find` is fixed; the test for that is whether `/modules/` and
|
||||
`/docs/modules/building-a-module` are served different policies.
|
||||
|
||||
The second is the handful of headers that have nothing to do with Astro: `X-Content-Type-Options`,
|
||||
`Referrer-Policy`, `X-Frame-Options` and a `Permissions-Policy` that turns off hardware this site has
|
||||
no reason to ask for. They are set in the container rather than written into an operator's
|
||||
reverse-proxy configuration, because the image should be correct on its own and a proxy somebody
|
||||
else configures is a promise this repository cannot check. The two routes that render per request —
|
||||
`/beta` and `/brand/*` — have no prerendered policy, so they get `frame-ancestors 'none'` on its own:
|
||||
the one directive a `<meta>` CSP cannot express, and therefore the one thing Astro's per-page meta
|
||||
tag leaves them missing.
|
||||
|
||||
`style-src-attr 'unsafe-inline'` is the single relaxation in the policy, and it is scoped to that
|
||||
directive. Starlight and Expressive Code write around 3,700 inline `style` attributes into the
|
||||
documentation — icon sizes, the theme select's width, and every syntax colour — which cannot be
|
||||
hashed, because CSP hashes cover `<style>` elements and never attributes. A style attribute cannot
|
||||
execute script, so this leaves `script-src`, the directive CSP exists for, untouched. The marketing
|
||||
pages emit no inline style attributes at all.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
@@ -170,12 +244,17 @@ src/
|
||||
lib/betaSignup.mjs Everything between a POST body and a row. Never throws.
|
||||
lib/tokens.mjs Reads tokens.css at build time, for the few values that leave CSS.
|
||||
config/sidebar.mjs The documentation journey, and the planned tree behind it.
|
||||
config/cspHashes.mjs GENERATED. Starlight's inline scripts, which Astro does not hash.
|
||||
brand-default/ The stock brand, baked into the image and always complete.
|
||||
scripts/ The build-time checks, plus applyBrand (boot), brand:assets (manual)
|
||||
and beta.mjs (the tester-list CLI).
|
||||
scripts/ The build-time checks, plus applyBrand and serve (boot),
|
||||
brand:assets (manual) and beta.mjs (the tester-list CLI).
|
||||
test/ node --test. The logic the other checks cannot see.
|
||||
PLAY_DATA_SAFETY.md GENERATED. The answers to Google Play's Data Safety form, from
|
||||
src/data/collection.mjs. Edit the data, run npm run play:datasafety.
|
||||
Dockerfile Two stages. Build with the toolchain, run with the pruned tree.
|
||||
docker-compose.yml Production. Pull-only, one service, both bind mounts.
|
||||
.env.example The two secrets worth setting, and every default made visible.
|
||||
DEPLOY.md The operator's guide: proxy, DNS, TLS, branding, backups.
|
||||
```
|
||||
|
||||
Two directories are bind mounts at runtime and are **not** in the repository: `brand/` overrides
|
||||
@@ -186,13 +265,18 @@ and §7.
|
||||
|
||||
Branch from `main` (`feature/…`, `fix/…`, `docs/…`, `chore/…`) and use
|
||||
[Conventional Commits](https://www.conventionalcommits.org/). Run `npm run verify` before opening a
|
||||
pull request.
|
||||
pull request. **[CONTRIBUTING.md](CONTRIBUTING.md)** has the rest, including the two rules from
|
||||
`PLAN.md` that constrain how a page may be written at all: the site never re-specifies a contract,
|
||||
and no fact is stated in prose.
|
||||
|
||||
**AI-assisted contributions must be disclosed**, per org policy: tick the box in the pull request
|
||||
template naming the tool, and mark AI-authored commits with a trailer such as
|
||||
`Co-Authored-By: Claude <noreply@anthropic.com>`. Undisclosed AI-generated contributions may be
|
||||
closed.
|
||||
|
||||
Security problems go to [SECURITY.md](SECURITY.md), never to a public issue. Everyone taking part is
|
||||
covered by the [Code of Conduct](CODE_OF_CONDUCT.md).
|
||||
|
||||
## Licence
|
||||
|
||||
GPL-3.0-or-later, in common with every repository in the organisation. See [LICENSE](LICENSE).
|
||||
|
||||
43
SECURITY.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Security Policy
|
||||
|
||||
**Please do not report security vulnerabilities through public issues, pull requests or the wiki.**
|
||||
A public report tips off attackers before a fix is available.
|
||||
|
||||
Report privately, using the contact route in the organisation's security policy:
|
||||
|
||||
**[RunicGateway/docs → SECURITY.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/SECURITY.md)**
|
||||
|
||||
That document is the single copy for all ten repositories, and it carries the address, what to
|
||||
include in a report and what to expect back.
|
||||
|
||||
## Why this file is a pointer rather than a copy
|
||||
|
||||
Every other repository in the organisation states the reporting address inline. This one does not,
|
||||
and the reason is a decision of record rather than an oversight: **D13** (`PLAN.md` §5) confines the
|
||||
published contact address to `brand.json`, a bind-mounted file, so that changing it is a file copy
|
||||
and a container restart rather than a commit. `scripts/checkFacts.mjs` fails the build if an address
|
||||
appears anywhere in `src/` or `scripts/`, and this file honours the same rule voluntarily — a
|
||||
hard-coded address in the repository root would be one more place to forget when the address moves.
|
||||
|
||||
## What is worth reporting here
|
||||
|
||||
This site holds one thing of value and has one writing endpoint.
|
||||
|
||||
- **The closed-beta signup** (`/beta`, `PLAN.md` §8) is the only route that writes. It stores an
|
||||
email address, a consent record and a **salted hash of the IP address** — never the address
|
||||
itself. Anything that lets a caller read rows, bypass the rate limit or the total cap, forge the
|
||||
signed form token, or recover an IP from a hash is in scope and worth reporting.
|
||||
- **The branding mount** (`GET /brand/*`, §7) reads files from a directory an operator controls.
|
||||
Path traversal out of that directory, or reaching a file type outside the route's allowlist, is in
|
||||
scope.
|
||||
- **The Content-Security-Policy** is a real response header written by `scripts/serve.mjs`. A page
|
||||
that is served no policy, or another page's policy, is a defect worth reporting — that exact bug
|
||||
has happened here once already (`PLAN.md` D48).
|
||||
|
||||
The site has **no authenticated surface at all**, by design: the tester list is managed from a shell
|
||||
against the bind mount, not from an admin page. There is no session, no cookie and no login to
|
||||
attack.
|
||||
|
||||
Vulnerabilities in the **platform itself** — the website, the sidecar, the shard plugin, the
|
||||
installer or the Android app — belong in the organisation's policy linked above, not here. This
|
||||
repository only describes them.
|
||||
@@ -3,6 +3,8 @@ import { defineConfig } from 'astro/config';
|
||||
import node from '@astrojs/node';
|
||||
import starlight from '@astrojs/starlight';
|
||||
|
||||
import { inlineScriptHashes, inlineStyleHashes } from './src/config/cspHashes.mjs';
|
||||
import { docsRedirects } from './src/config/redirects.mjs';
|
||||
import { docsSidebar } from './src/config/sidebar.mjs';
|
||||
|
||||
/**
|
||||
@@ -20,13 +22,76 @@ import { docsSidebar } from './src/config/sidebar.mjs';
|
||||
export default defineConfig({
|
||||
site: 'https://runicgateway.com',
|
||||
output: 'static',
|
||||
adapter: node({ mode: 'standalone' }),
|
||||
// `staticHeaders` is what turns §6's CSP from a promise into a response header (D48).
|
||||
// Without it the policy ships as a `<meta http-equiv>`, and a meta CSP silently ignores
|
||||
// `frame-ancestors` — the one directive that stops the site being framed. With it, the
|
||||
// build writes `_headers.json` next to the server entry and the standalone server sends
|
||||
// the policy as a real header on every prerendered route, so the operator's reverse proxy
|
||||
// needs no CSP configuration at all and cannot get it wrong.
|
||||
adapter: node({ mode: 'standalone', staticHeaders: true }),
|
||||
|
||||
build: {
|
||||
// Directory-style URLs, so every link in prose can end in a slash and mean it.
|
||||
format: 'directory',
|
||||
},
|
||||
|
||||
// Pages that moved into a game's own sidebar group (PLAN.md §16, D60). See the file.
|
||||
redirects: docsRedirects,
|
||||
|
||||
|
||||
security: {
|
||||
csp: {
|
||||
directives: [
|
||||
// The whole posture in one line: nothing loads from anywhere but this origin.
|
||||
// §6 could promise this without exceptions because the fonts are self-hosted and
|
||||
// D9 rules out analytics — there is no CDN to whitelist and no beacon to allow.
|
||||
"default-src 'self'",
|
||||
// Not covered by `default-src`, and each one closes a specific door: no injected
|
||||
// `<base>` can re-point every relative URL on the page, the signup form can only
|
||||
// post to us, no plugin content at all, and the site cannot be framed. The last
|
||||
// of those is the reason `staticHeaders` is on.
|
||||
"base-uri 'self'",
|
||||
"form-action 'self'",
|
||||
"object-src 'none'",
|
||||
"frame-ancestors 'none'",
|
||||
// One `url(data:image/svg+xml)` survives bundling into the stylesheet. Data URLs
|
||||
// are a real (if small) exfiltration-free risk surface, so this is the only
|
||||
// relaxation of `default-src` on the image directive and it is scoped to images.
|
||||
"img-src 'self' data:",
|
||||
],
|
||||
scriptDirective: {
|
||||
resources: [
|
||||
"'self'",
|
||||
// Pagefind (D47) compiles its index with `WebAssembly.instantiate`, which a
|
||||
// strict `script-src` blocks outright — search silently returns nothing. This
|
||||
// permits WASM compilation *only*; it does not restore `eval`.
|
||||
"'wasm-unsafe-eval'",
|
||||
],
|
||||
// Starlight's own `is:inline` scripts, which Astro does not hash because it never
|
||||
// parses them. Generated — see src/config/cspHashes.mjs and `npm run check:csp`.
|
||||
hashes: inlineScriptHashes,
|
||||
},
|
||||
styleDirective: {
|
||||
// No `'self'` here, though `style-src` needs it and gets it: Astro's default
|
||||
// already supplies it, and naming it alongside an `attribute`-kind resource makes
|
||||
// the build warn — browsers do not fall back from `style-src-attr` to `style-src`,
|
||||
// so a `'self'` written here would apply to neither scope the author meant.
|
||||
resources: [
|
||||
// Starlight and Expressive Code write ~3,700 inline `style` attributes into the
|
||||
// documentation — icon sizing, the theme select's width, and every syntax
|
||||
// colour, which Expressive Code emits as custom properties on the element. They
|
||||
// cannot be hashed (CSP hashes cover `<style>` elements, never attributes), and
|
||||
// Astro's own docs record Shiki as incompatible with CSP for exactly this
|
||||
// reason. Scoped to `style-src-attr` deliberately: a style attribute cannot
|
||||
// execute script, so this leaves the directive CSP exists for — `script-src` —
|
||||
// untouched. The marketing pages emit zero inline style attributes.
|
||||
{ resource: "'unsafe-inline'", kind: 'attribute' },
|
||||
],
|
||||
hashes: inlineStyleHashes,
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'Runic Gateway',
|
||||
@@ -49,6 +114,9 @@ export default defineConfig({
|
||||
// Starlight builds its own head, so the docs otherwise miss the brand stylesheet,
|
||||
// the manifest and the OG card entirely. See the component.
|
||||
Head: './src/components/DocsHead.astro',
|
||||
// One attribute, for one reason: Starlight's skip link targets the `<h1>`, and an
|
||||
// `<h1>` is not focusable. See the component (phase 11).
|
||||
PageTitle: './src/components/DocsPageTitle.astro',
|
||||
},
|
||||
credits: false,
|
||||
sidebar: docsSidebar,
|
||||
|
||||
104
docker-compose.yml
Normal file
@@ -0,0 +1,104 @@
|
||||
# runicgateway.com — production.
|
||||
#
|
||||
# Pull-only, in common with the rest of the org: `image:` and no `build:`, so a
|
||||
# production host can never accidentally build. The image is published to the
|
||||
# Gitea registry by .gitea/workflows/build-image.yml on every merge to main.
|
||||
#
|
||||
# Full operator guide, including DNS, TLS and the reverse proxy: DEPLOY.md.
|
||||
#
|
||||
# docker compose pull && docker compose up -d
|
||||
#
|
||||
# One service. §6 records why there is no second one: the dynamic surface is two
|
||||
# routes, and one container is one thing to deploy, one thing to patch and one
|
||||
# log to read.
|
||||
|
||||
services:
|
||||
site:
|
||||
# IMAGE_TAG defaults to `latest`. Pin a build for a reproducible deploy or a
|
||||
# rollback — e.g. IMAGE_TAG=sha-1806406 in .env; every merge publishes both.
|
||||
image: gitea.whitlocktech.com/runicgateway/runicgateway-site:${IMAGE_TAG:-latest}
|
||||
restart: unless-stopped
|
||||
|
||||
# Secrets and tuning for the beta signup (§8). The file is optional in the
|
||||
# sense that the site starts without it — but read the note in .env.example
|
||||
# about BETA_IP_SALT and BETA_FORM_KEY before deciding to skip it: their
|
||||
# defaults are random PER PROCESS, so leaving them unset means every restart
|
||||
# forgets who has been rate-limited.
|
||||
env_file: .env
|
||||
|
||||
volumes:
|
||||
# ---------------------------------------------------------------------------
|
||||
# The branding mount (§7). Read-only: nothing in the container ever writes
|
||||
# here, and the whole point of the directory is that a human puts files in
|
||||
# it from the host.
|
||||
#
|
||||
# May be empty, partial or complete. Every file resolves against this mount
|
||||
# first and the image's brand-default/ second, PER FILE — so a directory
|
||||
# holding only theme.css recolours the site and leaves every logo stock,
|
||||
# and an empty directory produces exactly the stock site.
|
||||
#
|
||||
# Changing a file here takes a RESTART, not a rebuild: `docker compose
|
||||
# restart site` re-runs the boot rewrite, which is what puts a new site
|
||||
# name into forty-nine prerendered pages. The exception is brand.json's
|
||||
# betaOptInUrl, which /beta reads live on every request — so the closed
|
||||
# test can be opened by editing one file, with no restart at all.
|
||||
- ./brand:/app/brand:ro
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# The beta signup store (§8): beta.sqlite and exports/. Read-WRITE, and the
|
||||
# only thing this site persists.
|
||||
#
|
||||
# A bind mount rather than a named volume because the tester list has to be
|
||||
# reachable from the host — `sqlite3 ./data/beta.sqlite`, a backup by `cp`,
|
||||
# and the CSV the export CLI writes into ./data/exports/ for pasting into
|
||||
# Play. A named volume would put all three behind `docker cp`.
|
||||
#
|
||||
# The container runs as uid 1000. Docker creates a MISSING bind-mount source
|
||||
# as root:root, and the store then fails to open — so create the directory
|
||||
# yourself and, if it is owned by someone else, `chown 1000:1000 ./data`.
|
||||
# DEPLOY.md has the two commands.
|
||||
- ./data:/app/data
|
||||
|
||||
# Published on ALL interfaces by default, so the site answers on the host's
|
||||
# own address — `http://<vm-ip>:4321` — and not only on its loopback. That is
|
||||
# what makes it reachable from the rest of the network: a proxy in another
|
||||
# container or on another machine, a browser on the LAN, a phone on the same
|
||||
# wifi checking the mobile layout.
|
||||
#
|
||||
# It is deliberately a variable rather than a fixed address, because the safe
|
||||
# binding depends on where this host sits. Set SITE_BIND_ADDR in .env to
|
||||
# narrow it without touching this file:
|
||||
#
|
||||
# SITE_BIND_ADDR=127.0.0.1 loopback only — a proxy on THIS host, nothing else
|
||||
# SITE_BIND_ADDR=192.168.1.10 one interface — the LAN, but not a public NIC
|
||||
# SITE_BIND_ADDR=0.0.0.0 every interface (the default)
|
||||
#
|
||||
# On a host with a public address, `0.0.0.0` means port 4321 answers from the
|
||||
# internet directly, beside whatever the proxy serves on 443 — plain HTTP, no
|
||||
# TLS. Firewall the port, or narrow the binding. DEPLOY.md, "Putting a proxy
|
||||
# in front of it".
|
||||
ports:
|
||||
- "${SITE_BIND_ADDR:-0.0.0.0}:${SITE_HOST_PORT:-4321}:4321"
|
||||
|
||||
# Repeats the image's own HEALTHCHECK so `docker compose ps` reports it even
|
||||
# when the image is pinned to an older tag that predates it. It watches an
|
||||
# actual response rather than the process, because `npm start` runs the brand
|
||||
# rewrite before the server: there is a real window where the container is up
|
||||
# and nothing is listening.
|
||||
#
|
||||
# The command is a QUOTED flow sequence, which is not a style choice: written as a
|
||||
# block sequence, YAML reads the `: ` inside `r.ok ? 0 : 1` as a key/value separator
|
||||
# and `docker compose config` refuses the file with "healthcheck.test.3 must be a
|
||||
# string". Keep the quotes.
|
||||
healthcheck:
|
||||
test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:4321/').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
start_period: 40s
|
||||
retries: 3
|
||||
|
||||
logging:
|
||||
driver: json-file
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
839
package-lock.json
generated
21
package.json
@@ -12,7 +12,7 @@
|
||||
"dev": "astro dev",
|
||||
"build": "astro build",
|
||||
"preview": "astro preview",
|
||||
"start": "node scripts/applyBrand.mjs && node ./dist/server/entry.mjs",
|
||||
"start": "node scripts/applyBrand.mjs && node scripts/serve.mjs",
|
||||
"check": "astro check",
|
||||
"check:facts": "node scripts/checkFacts.mjs",
|
||||
"check:tokens": "node scripts/checkTokens.mjs",
|
||||
@@ -20,11 +20,20 @@
|
||||
"check:links": "node scripts/checkLinks.mjs",
|
||||
"check:datasafety": "node scripts/playDataSafety.mjs --check",
|
||||
"check:quickstart": "node scripts/checkQuickstart.mjs",
|
||||
"check:reference": "node scripts/checkReference.mjs",
|
||||
"check:sidebar": "node scripts/checkSidebar.mjs",
|
||||
"check:terms": "node scripts/checkTerms.mjs",
|
||||
"check:screens": "node scripts/checkScreens.mjs",
|
||||
"check:a11y": "node scripts/checkA11y.mjs",
|
||||
"check:csp": "node scripts/checkCsp.mjs",
|
||||
"play:datasafety": "node scripts/playDataSafety.mjs",
|
||||
"beta": "node scripts/beta.mjs",
|
||||
"test": "node --test test/beta.test.mjs test/legal.test.mjs",
|
||||
"test": "node --test test/beta.test.mjs test/legal.test.mjs test/footer.test.mjs",
|
||||
"brand:assets": "node scripts/buildBrandAssets.mjs",
|
||||
"verify": "npm run check:tokens && npm run check:brand && npm run check:datasafety && npm run check && npm test && npm run build && npm run check:links && npm run check:facts && npm run check:quickstart"
|
||||
"screens:capture": "node scripts/captureScreens.mjs",
|
||||
"csp:hashes": "node scripts/checkCsp.mjs --reset && astro build && node scripts/checkCsp.mjs --write && astro build && node scripts/checkCsp.mjs",
|
||||
"verify": "npm run check:sidebar && npm run check:terms && npm run check:screens && npm run check:tokens && npm run check:brand && npm run check:datasafety && npm run check && npm test && npm run build && npm run check:links && npm run check:facts && npm run check:quickstart && npm run check:reference && npm run test:served && npm run check:a11y && npm run check:csp",
|
||||
"test:served": "node --test test/headers.test.mjs"
|
||||
},
|
||||
"dependencies": {
|
||||
"@astrojs/node": "^11.1.4",
|
||||
@@ -33,12 +42,14 @@
|
||||
"@fontsource-variable/inter": "^5.3.0",
|
||||
"astro": "^7.2.4",
|
||||
"better-sqlite3": "^12.11.1",
|
||||
"pagefind": "^1.5.2",
|
||||
"sharp": "^0.35.3"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@astrojs/check": "^0.9.10",
|
||||
"opentype.js": "^2.0.0",
|
||||
"yaml": "^2.8.1",
|
||||
"typescript": "^6.0.3"
|
||||
"puppeteer-core": "^23.11.1",
|
||||
"typescript": "^6.0.3",
|
||||
"yaml": "^2.8.1"
|
||||
}
|
||||
}
|
||||
|
||||
BIN
public/screens/admin-appearance.webp
Normal file
|
After Width: | Height: | Size: 62 KiB |
BIN
public/screens/admin-client-files.webp
Normal file
|
After Width: | Height: | Size: 114 KiB |
BIN
public/screens/admin-dashboard.webp
Normal file
|
After Width: | Height: | Size: 58 KiB |
BIN
public/screens/admin-modules.webp
Normal file
|
After Width: | Height: | Size: 73 KiB |
BIN
public/screens/admin-shard.webp
Normal file
|
After Width: | Height: | Size: 48 KiB |
BIN
public/screens/admin-users.webp
Normal file
|
After Width: | Height: | Size: 46 KiB |
BIN
public/screens/app-account.webp
Normal file
|
After Width: | Height: | Size: 55 KiB |
BIN
public/screens/app-drawer.webp
Normal file
|
After Width: | Height: | Size: 50 KiB |
BIN
public/screens/app-home.webp
Normal file
|
After Width: | Height: | Size: 136 KiB |
BIN
public/screens/app-market.webp
Normal file
|
After Width: | Height: | Size: 89 KiB |
BIN
public/screens/app-shard.webp
Normal file
|
After Width: | Height: | Size: 111 KiB |
BIN
public/screens/app-wiki.webp
Normal file
|
After Width: | Height: | Size: 82 KiB |
BIN
public/screens/guilds.webp
Normal file
|
After Width: | Height: | Size: 52 KiB |
BIN
public/screens/houses.webp
Normal file
|
After Width: | Height: | Size: 51 KiB |
BIN
public/screens/marketplace.webp
Normal file
|
After Width: | Height: | Size: 55 KiB |
BIN
public/screens/news.webp
Normal file
|
After Width: | Height: | Size: 73 KiB |
BIN
public/screens/shard-status.webp
Normal file
|
After Width: | Height: | Size: 38 KiB |
BIN
public/screens/spawn-atlas.webp
Normal file
|
After Width: | Height: | Size: 67 KiB |
@@ -229,10 +229,71 @@ const counts = new Map(replacements.map((r) => [r.field, 0]));
|
||||
counts.set('demoDeep', 0);
|
||||
let filesTouched = 0;
|
||||
|
||||
/**
|
||||
* The CSP (§6, D48) hashes every inline `<script>` and `<style>` in the build. This script
|
||||
* runs after that hashing and rewrites the same files, so a brand value that happened to
|
||||
* sit inside an inline block would change its bytes, invalidate its hash and get the block
|
||||
* refused by the browser — with no error anywhere except a console nobody has open. The
|
||||
* page would render perfectly and the script simply would not run.
|
||||
*
|
||||
* Nothing puts brand text in an inline script today, and the replacements are guarded by
|
||||
* MIN_REWRITABLE_LENGTH so they are unlikely to collide by accident. "Unlikely" is not the
|
||||
* standard for a failure this quiet, so the collision is checked rather than reasoned
|
||||
* about: if a rewrite ever lands inside an inline block, this refuses to write that file
|
||||
* and says so, and the page keeps its stock text instead of losing its behaviour.
|
||||
*/
|
||||
const INLINE_BLOCK = /<(script|style)(?![^>]*\bsrc\s*=)([^>]*)>([\s\S]*?)<\/\1>/g;
|
||||
|
||||
/**
|
||||
* The structured-data block (D50) is a `<script>` that no browser executes and no CSP hash
|
||||
* covers, so it is not one of the blocks this guard protects — and it MUST NOT be, because
|
||||
* it contains the site's name. Treating it as a script would make the guard refuse to
|
||||
* rewrite the homepage, which is §7 failing on the one page that matters most.
|
||||
*/
|
||||
const DATA_BLOCK = /type\s*=\s*["']application\/(ld\+json|json)["']/i;
|
||||
|
||||
const inlineRanges = (html) => {
|
||||
const ranges = [];
|
||||
INLINE_BLOCK.lastIndex = 0;
|
||||
let match;
|
||||
while ((match = INLINE_BLOCK.exec(html))) {
|
||||
if (match[1] === 'script' && DATA_BLOCK.test(match[2])) continue;
|
||||
// Where the block's CONTENT starts — measured back from the end of the whole match, so
|
||||
// the opening tag's attributes cannot throw the offset off: `</script>` is the tag name
|
||||
// plus three characters.
|
||||
const closing = match[1].length + 3;
|
||||
const start = match.index + match[0].length - closing - match[3].length;
|
||||
ranges.push([start, start + match[3].length]);
|
||||
}
|
||||
return ranges;
|
||||
};
|
||||
const hitsInlineBlock = (html, needle) => {
|
||||
if (!needle || !html.includes(needle)) return false;
|
||||
const ranges = inlineRanges(html);
|
||||
if (ranges.length === 0) return false;
|
||||
for (let at = html.indexOf(needle); at !== -1; at = html.indexOf(needle, at + 1)) {
|
||||
const end = at + needle.length;
|
||||
if (ranges.some(([from, to]) => at < to && end > from)) return true;
|
||||
}
|
||||
return false;
|
||||
};
|
||||
const inlineCollisions = [];
|
||||
|
||||
for (const file of walk(CLIENT)) {
|
||||
const before = readFileSync(file, 'utf8');
|
||||
let after = before;
|
||||
|
||||
if (path.extname(file) === '.html') {
|
||||
const colliding = replacements.filter(({ from }) => hitsInlineBlock(before, from));
|
||||
if (colliding.length) {
|
||||
inlineCollisions.push({
|
||||
file: path.relative(CLIENT, file),
|
||||
fields: [...new Set(colliding.map((c) => c.field))],
|
||||
});
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
for (const { field, from, to } of replacements) {
|
||||
if (!after.includes(from)) continue;
|
||||
counts.set(field, counts.get(field) + after.split(from).length - 1);
|
||||
@@ -270,6 +331,47 @@ if (counts.get('demoDeep')) {
|
||||
);
|
||||
}
|
||||
|
||||
// Pagefind builds its search index from the HTML at BUILD time (phase 10), so a rename
|
||||
// applied here reaches the pages but not the search results. Worth fixing when search
|
||||
// lands; recorded here rather than in a plan section nobody will re-read.
|
||||
if (inlineCollisions.length) {
|
||||
console.error(
|
||||
`\n[brand] ${inlineCollisions.length} file(s) were LEFT UNCHANGED: a brand value occurs ` +
|
||||
`inside an inline <script> or <style>, and rewriting it would break that block's CSP ` +
|
||||
`hash (§6, D48) — the page would render and the script would silently not run.\n`
|
||||
);
|
||||
for (const { file, fields } of inlineCollisions) {
|
||||
console.error(` ! ${file} (${fields.join(', ')})`);
|
||||
}
|
||||
console.error(
|
||||
`\n Those pages keep the stock text. Fix it by taking the brand value out of the inline\n` +
|
||||
` block — move it into markup the CSP does not hash, or into /brand/theme.css.\n`
|
||||
);
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------------------------------
|
||||
Search
|
||||
--------------------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Pagefind builds its index from the built HTML at BUILD time, so everything above reaches
|
||||
* the pages and none of it reaches the search results: a site renamed through the mount
|
||||
* would answer a search for its own name with the stock one, and every result title would
|
||||
* still carry the old suffix. Phase 2 recorded that and left it for this phase, when
|
||||
* search became site-wide (D47).
|
||||
*
|
||||
* The fix is to re-index, which is cheap and needs nothing the container does not already
|
||||
* have — Pagefind is what Starlight ran at build. It only runs when a rewrite actually
|
||||
* happened, so the stock deployment, which is the common case, still pays nothing.
|
||||
*/
|
||||
if (filesTouched > 0) {
|
||||
const pagefind = await import('pagefind');
|
||||
try {
|
||||
const { index } = await pagefind.createIndex();
|
||||
const { page_count } = await index.addDirectory({ path: CLIENT });
|
||||
await index.writeFiles({ outputPath: path.join(CLIENT, 'pagefind') });
|
||||
console.log(`[brand] re-indexed ${page_count} page(s) for search so results agree with it.`);
|
||||
} catch (error) {
|
||||
// Search degrading to stale titles is not a reason to refuse to serve the site.
|
||||
console.error(`[brand] could not rebuild the search index; it keeps the built one: ${error.message}`);
|
||||
} finally {
|
||||
await pagefind.close();
|
||||
}
|
||||
}
|
||||
|
||||
189
scripts/captureScreens.mjs
Normal file
@@ -0,0 +1,189 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* captureScreens.mjs — retakes the screenshots in `src/data/screens.mjs`.
|
||||
*
|
||||
* PLAN.md §13 phase 9, D4 / D45.
|
||||
*
|
||||
* node scripts/captureScreens.mjs # every web screen
|
||||
* node scripts/captureScreens.mjs shard-status admin-users
|
||||
* RG_DEMO=http://localhost:3000 node scripts/captureScreens.mjs
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* AN AUTHORING TOOL, LIKE buildBrandAssets.mjs — NOT A CHECK
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* This never runs in CI and CI never needs it: its output is committed, because the site
|
||||
* must build from a clean checkout with no game server, no database and no browser. What
|
||||
* CI runs is `checkScreens.mjs`, which only reads the files this produced.
|
||||
*
|
||||
* It exists because D4 asks for real screenshots of a real deployment, and the way real
|
||||
* screenshots rot is that the recipe for taking them lives in somebody's memory. The rig
|
||||
* is written down in PLAN.md §13; the framing — route, viewport, scroll offset, whether to
|
||||
* sign in — is written down in `screens.mjs`; and this turns the two into files.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* WHY puppeteer-core AND NOT puppeteer
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* `puppeteer` downloads its own Chromium — a hundred-odd megabytes fetched on every clean
|
||||
* install of a repository that needs a browser once per redesign. `puppeteer-core` drives
|
||||
* a Chrome that is already on the machine, which every machine that can look at this site
|
||||
* has. Point `RG_CHROME` at it if it is somewhere unusual.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* WHY IT SIGNS IN THROUGH THE API RATHER THAN THE LOGIN FORM
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* The administration screens need a session, and typing into the login form is the part of
|
||||
* a browser script most likely to break on a redesign — a moved field, a renamed button, a
|
||||
* React input that ignores synthetic typing. The session cookie is the only thing actually
|
||||
* wanted, so this asks the API for one from inside the page and lets the browser store it.
|
||||
* If that call stops returning 200 the script says so and stops, rather than quietly
|
||||
* screenshotting a login screen twelve times.
|
||||
*/
|
||||
|
||||
import { existsSync, mkdirSync, readdirSync } from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
import sharp from 'sharp';
|
||||
|
||||
import { screens, screensOf, WEB } from '../src/data/screens.mjs';
|
||||
|
||||
const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
const OUT = path.join(HERE, '..', 'public', 'screens');
|
||||
|
||||
const BASE = (process.env.RG_DEMO || 'http://localhost:3000').replace(/\/+$/, '');
|
||||
const USER = process.env.RG_ADMIN_USER || 'demoadmin';
|
||||
const PASS = process.env.RG_ADMIN_PASS || 'DemoReview!2026';
|
||||
|
||||
/** Where Chrome usually is, per platform. First hit wins; `RG_CHROME` beats all of them. */
|
||||
const CHROME_CANDIDATES = [
|
||||
process.env.RG_CHROME,
|
||||
'C:/Program Files/Google/Chrome/Application/chrome.exe',
|
||||
'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe',
|
||||
'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
|
||||
'/usr/bin/google-chrome',
|
||||
'/usr/bin/chromium',
|
||||
].filter(Boolean);
|
||||
|
||||
const wanted = process.argv.slice(2).filter((arg) => !arg.startsWith('-'));
|
||||
const todo = screensOf('web').filter((shot) => wanted.length === 0 || wanted.includes(shot.id));
|
||||
|
||||
if (todo.length === 0) {
|
||||
const known = screens.map((shot) => shot.id).join(', ');
|
||||
console.error(`Nothing to capture. Known ids: ${known}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const chrome = CHROME_CANDIDATES.find((candidate) => existsSync(candidate));
|
||||
|
||||
if (!chrome) {
|
||||
console.error(
|
||||
'No Chrome found. Set RG_CHROME to the browser executable — this script drives an\n' +
|
||||
'installed Chrome rather than downloading one (see the header).',
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const puppeteer = (await import('puppeteer-core')).default;
|
||||
|
||||
mkdirSync(OUT, { recursive: true });
|
||||
|
||||
const browser = await puppeteer.launch({
|
||||
executablePath: chrome,
|
||||
headless: 'new',
|
||||
defaultViewport: { ...WEB.viewport, deviceScaleFactor: WEB.scale },
|
||||
// Scrollbars are the browser's furniture, not the product's, and a colour profile that
|
||||
// is not sRGB makes the palette in a screenshot disagree with the palette on the page.
|
||||
args: ['--hide-scrollbars', '--force-color-profile=srgb'],
|
||||
});
|
||||
|
||||
/**
|
||||
* One page per privilege level rather than signing in and out around each shot: signing
|
||||
* out is the step that gets forgotten, and a public page captured with an admin session
|
||||
* shows a navigation bar the public never sees.
|
||||
*/
|
||||
const anon = await browser.newPage();
|
||||
const admin = await browser.newPage();
|
||||
|
||||
await admin.goto(BASE, { waitUntil: 'domcontentloaded' });
|
||||
|
||||
const status = await admin.evaluate(
|
||||
async (username, password) => {
|
||||
const res = await fetch('/api/v1/auth/login', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
credentials: 'include',
|
||||
body: JSON.stringify({ username, password }),
|
||||
});
|
||||
return res.status;
|
||||
},
|
||||
USER,
|
||||
PASS,
|
||||
);
|
||||
|
||||
if (status !== 200) {
|
||||
console.error(
|
||||
`Could not sign in as "${USER}" at ${BASE} (HTTP ${status}).\n` +
|
||||
'Seed the demo first — see PLAN.md §13 phase 9 and scripts/seedDemo.mjs.',
|
||||
);
|
||||
await browser.close();
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
let failures = 0;
|
||||
|
||||
for (const shot of todo) {
|
||||
const page = shot.admin ? admin : anon;
|
||||
const url = BASE + shot.route;
|
||||
|
||||
try {
|
||||
await page.goto(url, { waitUntil: 'networkidle2', timeout: 30_000 });
|
||||
|
||||
if (shot.scrollY) {
|
||||
await page.evaluate((y) => window.scrollTo(0, y), shot.scrollY);
|
||||
}
|
||||
|
||||
// Live pages settle after their first paint: a shard panel fills in from an event
|
||||
// stream, a list re-sorts once its data lands. A second is cheap and the difference
|
||||
// between a screenshot of the product and a screenshot of its loading state.
|
||||
await new Promise((resolve) => setTimeout(resolve, 1200));
|
||||
|
||||
const png = await page.screenshot({ type: 'png' });
|
||||
const file = path.join(OUT, `${shot.id}.webp`);
|
||||
|
||||
// Quality 82 is where UI text stops visibly softening; the files land near 150 KB,
|
||||
// which is what makes a page with five of them still a page and not a download.
|
||||
await sharp(png).webp({ quality: 82 }).toFile(file);
|
||||
|
||||
const meta = await sharp(file).metadata();
|
||||
|
||||
if (meta.width !== WEB.width || meta.height !== WEB.height) {
|
||||
console.error(
|
||||
` ! ${shot.id}: got ${meta.width}x${meta.height}, expected ${WEB.width}x${WEB.height}`,
|
||||
);
|
||||
failures++;
|
||||
continue;
|
||||
}
|
||||
|
||||
console.log(` + ${shot.id.padEnd(18)} ${shot.route.padEnd(20)} ${meta.width}x${meta.height}`);
|
||||
} catch (err) {
|
||||
console.error(` ! ${shot.id}: ${err.message}`);
|
||||
failures++;
|
||||
}
|
||||
}
|
||||
|
||||
await browser.close();
|
||||
|
||||
// A file left behind by a screen that has since been renamed or dropped is a file the
|
||||
// site still ships and nothing points at. Say so; do not delete somebody's work silently.
|
||||
if (wanted.length === 0) {
|
||||
const declared = new Set(screensOf('web').map((shot) => `${shot.id}.webp`));
|
||||
const phones = new Set(screensOf('phone').map((shot) => `${shot.id}.webp`));
|
||||
const orphans = readdirSync(OUT).filter((name) => !declared.has(name) && !phones.has(name));
|
||||
|
||||
if (orphans.length > 0) {
|
||||
console.log(`\nNot declared in screens.mjs, left alone: ${orphans.join(', ')}`);
|
||||
}
|
||||
}
|
||||
|
||||
console.log(`\n${todo.length - failures} captured, ${failures} failed.`);
|
||||
process.exit(failures > 0 ? 1 : 0);
|
||||
278
scripts/checkA11y.mjs
Normal file
@@ -0,0 +1,278 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* checkA11y.mjs — PLAN.md §13 phase 10.
|
||||
*
|
||||
* Every other rule this repository cares about is enforced by a script — the facts, the
|
||||
* links, the tokens, the sidebar, the screenshots, the CSP. Accessibility was the exception:
|
||||
* it was a thing someone checked once, by hand, on the pages they happened to open. This
|
||||
* makes it the eleventh check so a regression fails a build instead of waiting for a reader
|
||||
* who cannot use the page and will not file an issue.
|
||||
*
|
||||
* node scripts/checkA11y.mjs
|
||||
*
|
||||
* ── What it checks, and why each one ────────────────────────────────────────
|
||||
* A static check cannot measure contrast against a rendered page or find a focus trap, and
|
||||
* pretending otherwise would be worse than not checking. What it CAN do is catch the class
|
||||
* of defect that is invisible to a sighted author and permanent once shipped:
|
||||
*
|
||||
* 1. **One `<h1>` per page, and no skipped heading level.** The heading tree is the
|
||||
* document outline a screen-reader user navigates by. Two `<h1>`s or an `<h2>` under
|
||||
* nothing reads as a page with no structure at all.
|
||||
* 2. **Every `<img>` has an `alt`.** Not "a non-empty alt": `alt=""` is correct and
|
||||
* deliberate for the header mark, which sits inside a link that already says the
|
||||
* product's name. A MISSING attribute is what makes a screen reader read the filename.
|
||||
* 3. **Every form control has a label.** `<label for>`, a wrapping `<label>`,
|
||||
* `aria-label` or `aria-labelledby`. The signup form is the only place on this site
|
||||
* where a person is asked to type something, so it is the one place this must hold.
|
||||
* 4. **Every link and button has an accessible name.** An icon-only control with no text
|
||||
* and no `aria-label` is announced as "link", which is no name at all. The search
|
||||
* button is icon-only under 46rem, which is exactly this hazard.
|
||||
* 5. **`<html lang>` is set**, or a screen reader reads English prose with whatever voice
|
||||
* the reader last used.
|
||||
* 6. **One `<main>` per page and a skip link that points at it.** The site's header is a
|
||||
* lockup, four links and a search box in front of every page; without a working skip
|
||||
* link a keyboard user walks all six on every navigation.
|
||||
* 7. **No positive `tabindex`.** It reorders the tab sequence away from the visual one
|
||||
* and is almost never what the author meant.
|
||||
*
|
||||
* Both chromes are checked — the marketing pages and Starlight's forty. Starlight is
|
||||
* generally careful, so the docs half is a regression alarm on a dependency rather than a
|
||||
* review of our own markup, and it has already earned its place once: it is what would have
|
||||
* caught the `<h2>`-without-`<h1>` shape if a docs page had ever lost its title.
|
||||
*
|
||||
* No token and no network: everything read here is in `dist/`.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
||||
const clientDir = path.join(root, 'dist', 'client');
|
||||
|
||||
if (!fs.existsSync(clientDir)) {
|
||||
console.error('\ncheckA11y: dist/client does not exist. Run `npm run build` first.\n');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const failures = [];
|
||||
const fail = (page, what, detail) => failures.push({ page, what, detail });
|
||||
|
||||
const pages = [];
|
||||
const walk = (dir) => {
|
||||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) walk(full);
|
||||
else if (entry.name.endsWith('.html')) pages.push(full);
|
||||
}
|
||||
};
|
||||
walk(clientDir);
|
||||
|
||||
/* ---------------------------------------------------------------------------------------
|
||||
A very small amount of HTML reading
|
||||
|
||||
Not a parser. Everything below is a tag-level question — does this element carry this
|
||||
attribute, what text sits between these two tags — and a regex answers those on
|
||||
generated, well-formed output. A DOM parser would be a dependency, and this repository's
|
||||
checks are dependency-free on purpose (§12): the reader runs them the same way CI does.
|
||||
--------------------------------------------------------------------------------------- */
|
||||
|
||||
/** Takes the ATTRIBUTE STRING — what is between the tag name and the `>` — not the tag. */
|
||||
const attrs = (attrString) => {
|
||||
const found = new Map();
|
||||
const re = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
|
||||
let m;
|
||||
while ((m = re.exec(attrString))) {
|
||||
found.set(m[1].toLowerCase(), m[2] ?? m[3] ?? m[4] ?? '');
|
||||
}
|
||||
return found;
|
||||
};
|
||||
|
||||
/** Text a screen reader would announce: markup and comments stripped, entities loosened. */
|
||||
const textOf = (html) =>
|
||||
html
|
||||
.replace(/<!--[\s\S]*?-->/g, '')
|
||||
.replace(/<[^>]*>/g, ' ')
|
||||
.replace(/&[a-zA-Z#0-9]+;/g, ' ')
|
||||
.replace(/\s+/g, ' ')
|
||||
.trim();
|
||||
|
||||
/** An element's own accessible name, near enough for "is there one at all". */
|
||||
const named = (tag, inner) => {
|
||||
const a = attrs(tag);
|
||||
if (a.get('aria-label')?.trim()) return true;
|
||||
if (a.get('aria-labelledby')?.trim()) return true;
|
||||
if (a.get('title')?.trim()) return true;
|
||||
if (textOf(inner)) return true;
|
||||
// An image child with alt text names the control.
|
||||
for (const img of inner.matchAll(/<img\b([^>]*)>/gi)) {
|
||||
if (attrs(img[1]).get('alt')?.trim()) return true;
|
||||
}
|
||||
// An SVG with a title element does too.
|
||||
if (/<svg\b[^>]*>[\s\S]*?<title\b[^>]*>[^<]+<\/title>/i.test(inner)) return true;
|
||||
return false;
|
||||
};
|
||||
|
||||
for (const file of pages) {
|
||||
const page = '/' + path.relative(clientDir, file).replace(/\\/g, '/');
|
||||
|
||||
/**
|
||||
* Comments are stripped before anything is counted, and that is not a nicety: this
|
||||
* repository comments its markup heavily, and several of those comments quote the tags
|
||||
* they are explaining. `Base.astro`'s note about `data-pagefind-body` contains the text
|
||||
* "<main>", and the first run of this check reported every marketing page as having two
|
||||
* `<main>` landmarks because of it. Stripping once, up front, also keeps every offset
|
||||
* below measured against the same string.
|
||||
*/
|
||||
const html = fs.readFileSync(file, 'utf8').replace(/<!--[\s\S]*?-->/g, '');
|
||||
|
||||
// ── 5. lang ───────────────────────────────────────────────────────────────
|
||||
const htmlTag = /<html\b([^>]*)>/i.exec(html);
|
||||
if (!htmlTag) fail(page, '<html>', 'has no <html> element');
|
||||
else if (!attrs(htmlTag[1]).get('lang')?.trim()) fail(page, '<html>', 'has no lang attribute');
|
||||
|
||||
// ── 1. headings ───────────────────────────────────────────────────────────
|
||||
const headings = [...html.matchAll(/<h([1-6])\b([^>]*)>([\s\S]*?)<\/h\1>/gi)]
|
||||
// `aria-hidden` headings are decorative and out of the outline by definition.
|
||||
.filter((m) => attrs(m[2]).get('aria-hidden') !== 'true')
|
||||
.map((m) => ({ level: Number(m[1]), text: textOf(m[3]) }));
|
||||
|
||||
const h1s = headings.filter((h) => h.level === 1);
|
||||
if (h1s.length === 0) fail(page, 'headings', 'has no <h1>');
|
||||
if (h1s.length > 1) {
|
||||
fail(page, 'headings', `has ${h1s.length} <h1>s: ${h1s.map((h) => JSON.stringify(h.text)).join(', ')}`);
|
||||
}
|
||||
|
||||
let previous = 0;
|
||||
for (const heading of headings) {
|
||||
if (previous && heading.level > previous + 1) {
|
||||
fail(
|
||||
page,
|
||||
'headings',
|
||||
`jumps from h${previous} to h${heading.level} at ${JSON.stringify(heading.text.slice(0, 50))}`,
|
||||
);
|
||||
}
|
||||
previous = heading.level;
|
||||
}
|
||||
|
||||
// ── 2. images ─────────────────────────────────────────────────────────────
|
||||
for (const img of html.matchAll(/<img\b([^>]*)>/gi)) {
|
||||
const a = attrs(img[1]);
|
||||
if (!a.has('alt')) {
|
||||
fail(page, '<img>', `has no alt attribute: src=${a.get('src') ?? '(none)'}`);
|
||||
}
|
||||
}
|
||||
|
||||
// ── 3. form controls ──────────────────────────────────────────────────────
|
||||
const labelledIds = new Set(
|
||||
[...html.matchAll(/<label\b([^>]*)>/gi)]
|
||||
.map((m) => attrs(m[1]).get('for'))
|
||||
.filter(Boolean),
|
||||
);
|
||||
/**
|
||||
* A control wrapped in its own `<label>` needs no `for` and — this is the part that took
|
||||
* a wrong answer to find — needs no `id` either, so it cannot be recorded by id. Starlight
|
||||
* labels its theme and language selects exactly this way. What is recorded instead is the
|
||||
* character offset of each wrapped control, which identifies it uniquely without
|
||||
* requiring it to have any attributes at all.
|
||||
*/
|
||||
const wrappedAt = new Set();
|
||||
for (const label of html.matchAll(/<label\b[^>]*>([\s\S]*?)<\/label>/gi)) {
|
||||
const base = label.index + label[0].indexOf(label[1]);
|
||||
for (const control of label[1].matchAll(/<(input|select|textarea)\b[^>]*>/gi)) {
|
||||
wrappedAt.add(base + control.index);
|
||||
}
|
||||
}
|
||||
|
||||
for (const control of html.matchAll(/<(input|select|textarea)\b([^>]*)>/gi)) {
|
||||
const a = attrs(control[2]);
|
||||
const type = (a.get('type') ?? 'text').toLowerCase();
|
||||
// These are not things a person types into and are named by other means.
|
||||
if (['hidden', 'submit', 'button', 'reset', 'image'].includes(type)) continue;
|
||||
|
||||
const id = a.get('id');
|
||||
const hasLabel =
|
||||
wrappedAt.has(control.index) ||
|
||||
(id && labelledIds.has(id)) ||
|
||||
a.get('aria-label')?.trim() ||
|
||||
a.get('aria-labelledby')?.trim() ||
|
||||
a.get('title')?.trim();
|
||||
|
||||
if (!hasLabel) {
|
||||
fail(
|
||||
page,
|
||||
`<${control[1]}>`,
|
||||
`has no label: ${id ? `id="${id}"` : `name="${a.get('name') ?? '(none)'}"`} — ` +
|
||||
'a placeholder is not a label',
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ── 4. link and button names ──────────────────────────────────────────────
|
||||
for (const [, tag, attrString, inner] of html.matchAll(/<(a|button)\b([^>]*)>([\s\S]*?)<\/\1>/gi)) {
|
||||
const a = attrs(attrString);
|
||||
if (a.get('aria-hidden') === 'true') continue;
|
||||
// An <a> with no href is not a link; it is a target for one.
|
||||
if (tag.toLowerCase() === 'a' && !a.has('href')) continue;
|
||||
if (named(attrString, inner)) continue;
|
||||
|
||||
fail(
|
||||
page,
|
||||
`<${tag}>`,
|
||||
`has no accessible name: ${a.get('href') ? `href="${a.get('href')}"` : `class="${a.get('class') ?? ''}"`}`,
|
||||
);
|
||||
}
|
||||
|
||||
// ── 6. main and the skip link ─────────────────────────────────────────────
|
||||
const mains = [...html.matchAll(/<main\b([^>]*)>/gi)];
|
||||
if (mains.length === 0) fail(page, '<main>', 'has no <main> landmark');
|
||||
if (mains.length > 1) fail(page, '<main>', `has ${mains.length} <main> elements`);
|
||||
|
||||
const skip = /<a\b([^>]*class="[^"]*skip-link[^"]*"[^>]*)>/i.exec(html);
|
||||
if (skip) {
|
||||
const target = attrs(skip[1]).get('href') ?? '';
|
||||
if (!target.startsWith('#')) {
|
||||
fail(page, 'skip link', `points at ${JSON.stringify(target)}, which is not an in-page anchor`);
|
||||
} else {
|
||||
const id = target.slice(1);
|
||||
if (!new RegExp(`\\bid=["']${id}["']`).test(html)) {
|
||||
fail(page, 'skip link', `points at #${id}, and nothing on the page has that id`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ── 7. positive tabindex ──────────────────────────────────────────────────
|
||||
for (const m of html.matchAll(/\btabindex\s*=\s*["']?(-?\d+)/gi)) {
|
||||
if (Number(m[1]) > 0) {
|
||||
fail(page, 'tabindex', `is ${m[1]} — a positive tabindex reorders the tab sequence`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------------------------------
|
||||
Report
|
||||
--------------------------------------------------------------------------------------- */
|
||||
|
||||
if (failures.length === 0) {
|
||||
console.log(`checkA11y: ${pages.length} built pages pass all seven structural checks.`);
|
||||
} else {
|
||||
// Grouped by page: a shared component's defect otherwise prints fifty times and buries
|
||||
// the one page that has a real problem of its own.
|
||||
const byPage = new Map();
|
||||
for (const f of failures) {
|
||||
if (!byPage.has(f.page)) byPage.set(f.page, []);
|
||||
byPage.get(f.page).push(f);
|
||||
}
|
||||
|
||||
console.error(`\ncheckA11y: ${failures.length} problem(s) across ${byPage.size} page(s):\n`);
|
||||
for (const [page, items] of byPage) {
|
||||
console.error(` ${page}`);
|
||||
for (const item of items) console.error(` ✗ ${item.what}: ${item.detail}`);
|
||||
}
|
||||
console.error(`
|
||||
These are structural, so they are the same in every browser and for every reader. A defect
|
||||
repeated across many pages is usually one shared component — fix it there rather than on
|
||||
each page.
|
||||
`);
|
||||
process.exit(1);
|
||||
}
|
||||
263
scripts/checkCsp.mjs
Normal file
@@ -0,0 +1,263 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* checkCsp.mjs — PLAN.md §6 and D48, added in phase 10.
|
||||
*
|
||||
* §6 promises "a strict CSP with no external origins". D48 decided that promise should be
|
||||
* a real response header sent by the container itself, not a `<meta>` (which ignores
|
||||
* `frame-ancestors`) and not advice in an operator's proxy config (which lives outside the
|
||||
* artifact we ship and test). `astro.config.mjs` sets it up; this checks it arrived.
|
||||
*
|
||||
* node scripts/checkCsp.mjs # verify the built output
|
||||
* node scripts/checkCsp.mjs --write # rewrite src/config/cspHashes.mjs from the build
|
||||
* node scripts/checkCsp.mjs --reset # empty it, so the next harvest starts from nothing
|
||||
*
|
||||
* Three things are checked, and each one has already been wrong once:
|
||||
*
|
||||
* 1. **Every built route has a policy.** `staticHeaders` writes `dist/_headers.json`; a
|
||||
* route missing from it is a page served with no CSP at all, which is the failure mode
|
||||
* nobody notices because the page looks perfect.
|
||||
*
|
||||
* 2. **Every inline script and style is covered by its page's own policy.** This is the
|
||||
* real check. Astro does not hash `<script is:inline>`, and Starlight ships six of
|
||||
* them per documentation page — so the first build with CSP on had a strict, correct
|
||||
* header and a dead theme switcher. Hashing is verified per page against that page's
|
||||
* header, not against a global list, because that is what the browser does.
|
||||
*
|
||||
* 3. **The directives §6 actually promised are present.** A policy that lost
|
||||
* `frame-ancestors` in a refactor still passes checks 1 and 2 while no longer stopping
|
||||
* anything.
|
||||
*
|
||||
* `--write` harvests the hashes from check 2 into `src/config/cspHashes.mjs`, which
|
||||
* `astro.config.mjs` feeds back into the next build. So the sequence is reset → build →
|
||||
* write → build → verify, which is what `npm run csp:hashes` runs. It resets first because
|
||||
* harvesting only ever collects what the build did NOT cover — see `--reset` below.
|
||||
*
|
||||
* No token and no network: everything read here is in `dist/`.
|
||||
*/
|
||||
|
||||
import { createHash } from 'node:crypto';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
||||
const headersFile = path.join(root, 'dist', '_headers.json');
|
||||
const clientDir = path.join(root, 'dist', 'client');
|
||||
const hashesFile = path.join(root, 'src', 'config', 'cspHashes.mjs');
|
||||
|
||||
const write = process.argv.includes('--write');
|
||||
const reset = process.argv.includes('--reset');
|
||||
|
||||
const failures = [];
|
||||
const fail = (what, detail) => failures.push({ what, detail });
|
||||
|
||||
/**
|
||||
* Rewrites the two exported arrays in `src/config/cspHashes.mjs`, leaving every comment and
|
||||
* the JSDoc types above them untouched.
|
||||
*/
|
||||
const writeHashes = (script, style) => {
|
||||
const source = fs.readFileSync(hashesFile, 'utf8');
|
||||
const list = (hashes) =>
|
||||
hashes.size === 0 ? '[]' : `[\n${[...hashes].sort().map((h) => ` '${h}',`).join('\n')}\n]`;
|
||||
|
||||
fs.writeFileSync(
|
||||
hashesFile,
|
||||
source
|
||||
.replace(
|
||||
/export const inlineScriptHashes = [\s\S]*?;\n/,
|
||||
`export const inlineScriptHashes = ${list(script)};\n`,
|
||||
)
|
||||
.replace(
|
||||
/export const inlineStyleHashes = [\s\S]*?;\n/,
|
||||
`export const inlineStyleHashes = ${list(style)};\n`,
|
||||
),
|
||||
);
|
||||
};
|
||||
|
||||
/**
|
||||
* `--reset` empties the generated file, and `npm run csp:hashes` runs it FIRST.
|
||||
*
|
||||
* Without it the regeneration is not idempotent, and its failure mode is the worst
|
||||
* available: harvesting collects the blocks the build did not cover, so running it against
|
||||
* a build that is already correct finds nothing, writes two empty arrays and produces a
|
||||
* build with no hashes at all. Emptying first means the harvest always sees the same thing
|
||||
* — every inline block Astro does not hash on its own — whatever state the file was in.
|
||||
*/
|
||||
if (reset) {
|
||||
writeHashes(new Set(), new Set());
|
||||
console.log('checkCsp --reset: src/config/cspHashes.mjs emptied, ready to re-harvest.');
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// ── The build has to be there ───────────────────────────────────────────────
|
||||
if (!fs.existsSync(headersFile)) {
|
||||
console.error(`
|
||||
checkCsp: dist/_headers.json does not exist.
|
||||
|
||||
That file is written by the Node adapter's \`staticHeaders\` option, so either the build
|
||||
has not run (\`npm run build\`) or \`staticHeaders\` was turned off in astro.config.mjs —
|
||||
in which case the CSP is a <meta> tag and \`frame-ancestors\` is being ignored (D48).
|
||||
`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
/**
|
||||
* `_headers.json` is keyed by an internal route id, so the pathname lives in the record.
|
||||
* Normalised without a trailing slash: the file says `/docs/first-run`, the built page is
|
||||
* at `docs/first-run/index.html`, and `build.format: 'directory'` serves it at
|
||||
* `/docs/first-run/`.
|
||||
*/
|
||||
const byPath = new Map();
|
||||
for (const record of Object.values(JSON.parse(fs.readFileSync(headersFile, 'utf8')))) {
|
||||
const csp = record.headers?.find((h) => h.key.toLowerCase() === 'content-security-policy');
|
||||
byPath.set(record.pathname.replace(/\/$/, '') || '/', csp?.value ?? null);
|
||||
}
|
||||
|
||||
// ── Walk the built HTML ─────────────────────────────────────────────────────
|
||||
const pages = [];
|
||||
const walk = (dir) => {
|
||||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) walk(full);
|
||||
else if (entry.name === 'index.html' || entry.name.endsWith('.html')) pages.push(full);
|
||||
}
|
||||
};
|
||||
walk(clientDir);
|
||||
|
||||
/**
|
||||
* Inline only: anything with a `src` is a fetched file and is covered by `'self'`.
|
||||
* The body is hashed exactly as written, because that is what the browser hashes — one
|
||||
* byte of whitespace either side changes the digest.
|
||||
*/
|
||||
const INLINE_SCRIPT = /<script(?![^>]*\bsrc\s*=)([^>]*)>([\s\S]*?)<\/script>/g;
|
||||
const INLINE_STYLE = /<style([^>]*)>([\s\S]*?)<\/style>/g;
|
||||
|
||||
/**
|
||||
* `<script type="application/ld+json">` (D50) is a data block, not code: the browser never
|
||||
* executes it, and CSP's script-src is not enforced against it. Demanding a hash for one
|
||||
* would be wrong twice over — it would add the structured data's own text to the list of
|
||||
* scripts allowed to run, and that text changes whenever a fact or the brand name does, so
|
||||
* the generated hash file would churn on edits that cannot affect security.
|
||||
*/
|
||||
const DATA_BLOCK = /type\s*=\s*["']application\/(ld\+json|json)["']/i;
|
||||
|
||||
const sha256 = (body) => `sha256-${createHash('sha256').update(body, 'utf8').digest('base64')}`;
|
||||
|
||||
const harvested = { script: new Set(), style: new Set() };
|
||||
let inlineScripts = 0;
|
||||
let inlineStyles = 0;
|
||||
let uncovered = 0;
|
||||
|
||||
for (const file of pages) {
|
||||
const rel = path.relative(clientDir, file).replace(/\\/g, '/');
|
||||
const pathname = '/' + rel.replace(/index\.html$/, '').replace(/\.html$/, '').replace(/\/$/, '');
|
||||
const csp = byPath.get(pathname === '/' ? '/' : pathname.replace(/\/$/, ''));
|
||||
|
||||
if (csp === undefined) {
|
||||
fail(pathname, 'is a built page with no entry in dist/_headers.json — it ships with no CSP');
|
||||
continue;
|
||||
}
|
||||
if (csp === null) {
|
||||
fail(pathname, 'has an entry in dist/_headers.json but no Content-Security-Policy header');
|
||||
continue;
|
||||
}
|
||||
|
||||
const html = fs.readFileSync(file, 'utf8');
|
||||
|
||||
for (const [kind, re, counter] of [
|
||||
['script', INLINE_SCRIPT, 'inlineScripts'],
|
||||
['style', INLINE_STYLE, 'inlineStyles'],
|
||||
]) {
|
||||
re.lastIndex = 0;
|
||||
let match;
|
||||
while ((match = re.exec(html))) {
|
||||
const [, attrs, body] = match;
|
||||
if (kind === 'script' && DATA_BLOCK.test(attrs)) continue;
|
||||
// An empty inline block needs no hash; browsers do not enforce one.
|
||||
if (body.trim() === '') continue;
|
||||
if (counter === 'inlineScripts') inlineScripts++;
|
||||
else inlineStyles++;
|
||||
|
||||
const hash = sha256(body);
|
||||
if (csp.includes(hash)) continue;
|
||||
|
||||
uncovered++;
|
||||
harvested[kind].add(hash);
|
||||
if (!write) {
|
||||
fail(
|
||||
`${pathname} (inline <${kind}>)`,
|
||||
`${hash} is not in that page's policy — ${JSON.stringify(body.trim().slice(0, 60))}…`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ── The directives §6 promised, on a page that has to have them ─────────────
|
||||
const REQUIRED = [
|
||||
"default-src 'self'",
|
||||
"base-uri 'self'",
|
||||
"form-action 'self'",
|
||||
"object-src 'none'",
|
||||
"frame-ancestors 'none'",
|
||||
];
|
||||
const home = byPath.get('/');
|
||||
if (!home) {
|
||||
fail('/', 'the homepage has no CSP header at all');
|
||||
} else {
|
||||
for (const directive of REQUIRED) {
|
||||
if (!home.includes(directive)) fail('/ policy', `is missing "${directive}" (PLAN.md §6)`);
|
||||
}
|
||||
// The point of the whole exercise: a hash and 'unsafe-inline' in the same script
|
||||
// directive means browsers ignore 'unsafe-inline' — but if the hashes ever went away it
|
||||
// would quietly start applying.
|
||||
const scriptSrc = /script-src ([^;]*)/.exec(home)?.[1] ?? '';
|
||||
if (scriptSrc.includes("'unsafe-inline'")) {
|
||||
fail('/ policy', "script-src contains 'unsafe-inline' — D48 says the hashes carry this");
|
||||
}
|
||||
if (scriptSrc.includes("'unsafe-eval'")) {
|
||||
fail('/ policy', "script-src contains 'unsafe-eval' ('wasm-unsafe-eval' is the intended one)");
|
||||
}
|
||||
}
|
||||
|
||||
// ── --write: regenerate the hash file ───────────────────────────────────────
|
||||
if (write) {
|
||||
writeHashes(harvested.script, harvested.style);
|
||||
console.log(
|
||||
`checkCsp --write: harvested ${harvested.script.size} script and ${harvested.style.size} ` +
|
||||
`style hash(es) from ${pages.length} pages into src/config/cspHashes.mjs.`,
|
||||
);
|
||||
if (failures.length) {
|
||||
console.error('\ncheckCsp --write: the build is still wrong in ways hashes cannot fix:\n');
|
||||
for (const f of failures) console.error(` ✗ ${f.what}\n ${f.detail}`);
|
||||
process.exit(1);
|
||||
}
|
||||
console.log('Now rebuild so the next build embeds them (npm run csp:hashes does both).');
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// ── Report ──────────────────────────────────────────────────────────────────
|
||||
if (failures.length === 0) {
|
||||
console.log(
|
||||
`checkCsp: ${pages.length} pages carry a policy; ` +
|
||||
`${inlineScripts} inline script(s) and ${inlineStyles} inline style(s) are all hashed.`,
|
||||
);
|
||||
} else {
|
||||
console.error(`\ncheckCsp: ${failures.length} problem(s) with the Content-Security-Policy:\n`);
|
||||
for (const f of failures) console.error(` ✗ ${f.what}\n ${f.detail}`);
|
||||
if (uncovered) {
|
||||
console.error(`
|
||||
${uncovered} inline block(s) are not covered by a hash. In a browser this is silent: the
|
||||
page renders and the script simply never runs — Starlight's theme switch and mobile
|
||||
sidebar are inline scripts, so this is how the documentation loses them.
|
||||
|
||||
If the inline block is legitimate (usually: Starlight was upgraded), run
|
||||
|
||||
npm run csp:hashes
|
||||
|
||||
which rebuilds, harvests the hashes into src/config/cspHashes.mjs and rebuilds again.
|
||||
Read what changed before committing it — that file is a list of scripts allowed to run.
|
||||
`);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
@@ -60,8 +60,28 @@ async function api(pathname) {
|
||||
return res;
|
||||
}
|
||||
|
||||
const raw = async (repo, filePath, ref) =>
|
||||
(await api(`${repo}/raw/${filePath}?ref=${encodeURIComponent(ref)}`)).text();
|
||||
/**
|
||||
* A file's bytes, read through the `contents` endpoint rather than `raw`.
|
||||
*
|
||||
* `raw` answers with `Cache-Control: public, max-age=21600`, so the CDN in front of Gitea
|
||||
* serves a copy for six hours and this check can read a blob most of a working day old.
|
||||
* That is not theoretical: on the day of the engagement cutover it reported website's
|
||||
* MODULE_API_VERSION as 1.6.0 -- the value from two weeks earlier -- and failed a site
|
||||
* whose number was right. A check that goes red on stale data is a check people learn to
|
||||
* ignore, which is the one failure mode this file exists to avoid.
|
||||
*
|
||||
* `contents` answers `private, must-revalidate`, which the CDN does not cache, so it is
|
||||
* always the ref's current blob. The cost is a JSON parse and a base64 decode.
|
||||
*/
|
||||
async function raw(repo, filePath, ref) {
|
||||
const meta = await json(`${repo}/contents/${filePath}?ref=${encodeURIComponent(ref)}`);
|
||||
if (meta.encoding !== 'base64' || typeof meta.content !== 'string') {
|
||||
throw new Error(
|
||||
`${repo}:${filePath}@${ref} did not come back as a base64 file (encoding ${meta.encoding}).`
|
||||
);
|
||||
}
|
||||
return Buffer.from(meta.content, 'base64').toString('utf8');
|
||||
}
|
||||
|
||||
const json = async (pathname) => (await api(pathname)).json();
|
||||
|
||||
@@ -72,33 +92,42 @@ function extract(text, re, what, authority) {
|
||||
return m[1];
|
||||
}
|
||||
|
||||
// Every game the site quotes facts for (PLAN.md §16). Checks 1, 2, 4 and 5 run once per
|
||||
// game, and a row's label carries the game's key so a failure names which one moved.
|
||||
const GAMES = Object.entries(platform.games);
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 1. The wire protocol, from the sidecar itself
|
||||
// 1. Each game's wire protocol, from its sidecar
|
||||
// ---------------------------------------------------------------------------
|
||||
async function checkProtocol() {
|
||||
const authority = 'link main:sidecar/src/main.rs';
|
||||
const src = await raw('link', 'sidecar/src/main.rs', 'main');
|
||||
const value = extract(
|
||||
src,
|
||||
/pub const PROTOCOL_VERSION:\s*u32\s*=\s*(\d+)\s*;/,
|
||||
'PROTOCOL_VERSION',
|
||||
authority
|
||||
);
|
||||
record('protocol (sidecar)', platform.protocol, Number(value), authority);
|
||||
for (const [key, game] of GAMES) {
|
||||
const authority = `${game.sidecarRepo} main:sidecar/src/main.rs`;
|
||||
const src = await raw(game.sidecarRepo, 'sidecar/src/main.rs', 'main');
|
||||
const value = extract(
|
||||
src,
|
||||
/pub const PROTOCOL_VERSION:\s*u32\s*=\s*(\d+)\s*;/,
|
||||
'PROTOCOL_VERSION',
|
||||
authority
|
||||
);
|
||||
record(`${key} protocol (sidecar)`, game.protocol, Number(value), authority);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 2. The overlay's declared protocol — the third declaration site
|
||||
// 2. Each game plugin's declared protocol — the third declaration site
|
||||
//
|
||||
// CLAUDE.md: a protocol bump has to land in overlay.toml in the same PR as the emitters,
|
||||
// or the installer refuses to pair the sidecar with the overlay. If these two ever
|
||||
// disagree, the site must not print either number.
|
||||
// or the installer refuses to pair the sidecar with the plugin. If these two ever
|
||||
// disagree, the site must not print either number. Both games keep the file under the
|
||||
// same name at the root of their plugin repository.
|
||||
// ---------------------------------------------------------------------------
|
||||
async function checkOverlayProtocol() {
|
||||
const authority = 'servuo-plugins main:overlay.toml';
|
||||
const toml = await raw('servuo-plugins', 'overlay.toml', 'main');
|
||||
const value = extract(toml, /^\s*protocol\s*=\s*(\d+)\s*$/m, 'protocol', authority);
|
||||
record('protocol (overlay)', platform.protocol, Number(value), authority);
|
||||
for (const [key, game] of GAMES) {
|
||||
const authority = `${game.pluginRepo} main:overlay.toml`;
|
||||
const toml = await raw(game.pluginRepo, 'overlay.toml', 'main');
|
||||
const value = extract(toml, /^\s*protocol\s*=\s*(\d+)\s*$/m, 'protocol', authority);
|
||||
record(`${key} protocol (plugin)`, game.protocol, Number(value), authority);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -117,7 +146,7 @@ async function checkModuleApi() {
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 4. The capabilities the installed module actually declares
|
||||
// 4. The capabilities each game's module actually declares
|
||||
//
|
||||
// §12 names "module-uo's capability list" as one of the facts platform.json holds, and it
|
||||
// was the one fact nothing re-read. That mattered from phase 3 onwards, because the
|
||||
@@ -130,36 +159,109 @@ async function checkModuleApi() {
|
||||
// array is not a changed capability set. A slug appearing or disappearing is.
|
||||
// ---------------------------------------------------------------------------
|
||||
async function checkModuleCapabilities() {
|
||||
const authority = 'Module-uo main:module.json';
|
||||
const manifest = JSON.parse(await raw('Module-uo', 'module.json', 'main'));
|
||||
const declared = [...(manifest.capabilities || [])].sort();
|
||||
const expected = [...platform.moduleUoCapabilities].sort();
|
||||
for (const [key, game] of GAMES) {
|
||||
const authority = `${game.module.repo} main:module.json`;
|
||||
const manifest = JSON.parse(await raw(game.module.repo, 'module.json', 'main'));
|
||||
const declared = [...(manifest.capabilities || [])].sort();
|
||||
const expected = [...game.module.capabilities].sort();
|
||||
|
||||
record('moduleUoCapabilities', expected.join(' '), declared.join(' '), authority);
|
||||
record(`${key} module capabilities`, expected.join(' '), declared.join(' '), authority);
|
||||
// The range the module declares against core. The manifest docs use it as the worked
|
||||
// example of a caret range resolving across minor bumps, so it is a quoted fact.
|
||||
record(`${key} module coreApi`, game.module.coreApi, manifest.coreApi, authority);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 5. The current bundle
|
||||
// 5. Each game's current bundle
|
||||
//
|
||||
// The manifests live at the ROOT of the `bundles` branch — `current.json`,
|
||||
// `bundle-<tag>.json` — not under `bundles/`. Fetching the directory 404s.
|
||||
// One manifest per game on the installer's `bundles` branch, at
|
||||
// `v2/<game>/current.json` (schema 2). The ROOT `current.json` is the schema-1 manifest
|
||||
// from before the installer learned a second game; it is frozen and no longer read here,
|
||||
// because a check against a file that stopped moving passes forever.
|
||||
//
|
||||
// Each bundle is protocol-checked by CI when it is published, so its protocol is a third
|
||||
// independent read of the same number rather than a duplicate of checks 1 and 2.
|
||||
// ---------------------------------------------------------------------------
|
||||
async function checkBundle() {
|
||||
const authority = 'installer bundles:current.json';
|
||||
const current = JSON.parse(await raw('installer', 'current.json', 'bundles'));
|
||||
async function readBundle(game) {
|
||||
const file = `v2/${game.bundleGame}/current.json`;
|
||||
const authority = `installer bundles:${file}`;
|
||||
const current = JSON.parse(await raw('installer', file, 'bundles'));
|
||||
if (current.schema !== 2) {
|
||||
throw new Error(`${authority} is schema ${current.schema}, and this check reads schema 2.`);
|
||||
}
|
||||
return { current, authority };
|
||||
}
|
||||
|
||||
record('bundle.tag', platform.bundle.tag, current.bundle, authority);
|
||||
record('bundle.sidecar', platform.bundle.sidecar, current.link?.tag, authority);
|
||||
record('bundle.overlay', platform.bundle.overlay, current.overlay?.tag, authority);
|
||||
async function checkBundle() {
|
||||
const { uo, rust } = platform.games;
|
||||
|
||||
{
|
||||
const { current, authority } = await readBundle(uo);
|
||||
record('uo bundle.tag', uo.bundle.tag, current.bundle, authority);
|
||||
record('uo bundle.sidecar', uo.bundle.sidecar, current.sidecar?.tag, authority);
|
||||
record('uo bundle.overlay', uo.bundle.overlay, current.payload?.tag, authority);
|
||||
record('uo bundle.servuoMin', uo.bundle.servuoMin, current.payload?.compat?.min_version, authority);
|
||||
record('uo protocol (bundle)', uo.protocol, current.protocol, authority);
|
||||
}
|
||||
|
||||
{
|
||||
const { current, authority } = await readBundle(rust);
|
||||
const compat = current.payload?.compat ?? {};
|
||||
record('rust bundle.tag', rust.bundle.tag, current.bundle, authority);
|
||||
record('rust bundle.sidecar', rust.bundle.sidecar, current.sidecar?.tag, authority);
|
||||
record('rust bundle.plugin', rust.bundle.plugin, current.payload?.tag, authority);
|
||||
record('rust bundle.oxideMin', rust.bundle.oxideMin, compat.frameworks?.oxide?.min_version, authority);
|
||||
record('rust bundle.carbonMin', rust.bundle.carbonMin, compat.frameworks?.carbon?.min_version, authority);
|
||||
record(
|
||||
'rust bundle.requiresPlugins',
|
||||
[...rust.bundle.requiresPlugins].sort().join(' '),
|
||||
[...(compat.requires_plugins ?? [])].sort().join(' '),
|
||||
authority
|
||||
);
|
||||
record('rust bundle.runicnpc', rust.bundle.runicnpc, current.npc?.tag, authority);
|
||||
record('rust protocol (bundle)', rust.protocol, current.protocol, authority);
|
||||
// The bundle carries RunicNPC's API too; check 5b reads it from the plugin's own repo.
|
||||
record('runicnpc api (bundle)', platform.runicnpc.api, current.npc?.api, authority);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 5b. RunicNPC's own declarations
|
||||
//
|
||||
// RunicNPC stands alone as well as shipping in the Rust bundle (D61), so its facts are
|
||||
// read from its own `plugin.toml` too — the file its release workflow folds into the
|
||||
// manifest the installer and the egg read. The API version is the number a plugin author
|
||||
// calling `RunicNpc_*` relies on, and the site quotes it beside the API reference (D62).
|
||||
// ---------------------------------------------------------------------------
|
||||
async function checkRunicNpc() {
|
||||
const authority = 'runicnpc-rust main:plugin.toml';
|
||||
const toml = await raw('runicnpc-rust', 'plugin.toml', 'main');
|
||||
const npc = platform.runicnpc;
|
||||
|
||||
record('runicnpc api', npc.api, Number(extract(toml, /^\s*api\s*=\s*(\d+)\s*$/m, 'api', authority)), authority);
|
||||
record(
|
||||
'bundle.servuoMin',
|
||||
platform.bundle.servuoMin,
|
||||
current.overlay?.servuo?.min_version,
|
||||
'runicnpc oxideMin',
|
||||
npc.oxideMin,
|
||||
extract(toml, /^\s*min_oxide_version\s*=\s*"([^"]+)"/m, 'min_oxide_version', authority),
|
||||
authority
|
||||
);
|
||||
record(
|
||||
'runicnpc carbonMin',
|
||||
npc.carbonMin,
|
||||
extract(toml, /^\s*min_carbon_version\s*=\s*"([^"]+)"/m, 'min_carbon_version', authority),
|
||||
authority
|
||||
);
|
||||
const required = extract(toml, /^\s*requires_plugins\s*=\s*\[([^\]]*)\]/m, 'requires_plugins', authority)
|
||||
.split(',')
|
||||
.map((name) => name.trim().replace(/^"|"$/g, ''))
|
||||
.filter(Boolean);
|
||||
record(
|
||||
'runicnpc requiresPlugins',
|
||||
[...npc.requiresPlugins].sort().join(' '),
|
||||
required.sort().join(' '),
|
||||
authority
|
||||
);
|
||||
// The bundle is protocol-checked by CI when it is published, so this is a third
|
||||
// independent read of the same number rather than a duplicate of check 1.
|
||||
record('protocol (bundle)', platform.protocol, current.protocol, authority);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -329,6 +431,7 @@ async function main() {
|
||||
checkModuleApi,
|
||||
checkModuleCapabilities,
|
||||
checkBundle,
|
||||
checkRunicNpc,
|
||||
checkReleases,
|
||||
checkWebsiteHasNoReleases,
|
||||
checkAndroidApk,
|
||||
|
||||
@@ -55,12 +55,18 @@ const checked = [];
|
||||
const ok = (what) => checked.push(what);
|
||||
const fail = (what, detail) => failures.push({ what, detail });
|
||||
|
||||
/** Same raw-file accessor checkFacts.mjs uses, and for the same reason. */
|
||||
/** Same file accessor checkFacts.mjs uses, and for the same reason -- including the CDN one. */
|
||||
async function raw(repo, filePath, ref) {
|
||||
const url = `${BASE}/api/v1/repos/${ORG}/${repo}/raw/${filePath}?ref=${encodeURIComponent(ref)}`;
|
||||
const url = `${BASE}/api/v1/repos/${ORG}/${repo}/contents/${filePath}?ref=${encodeURIComponent(ref)}`;
|
||||
const res = await fetch(url, { headers: { Authorization: `token ${TOKEN}` } });
|
||||
if (!res.ok) throw new Error(`${res.status} ${res.statusText} for ${url}`);
|
||||
return res.text();
|
||||
const meta = await res.json();
|
||||
if (meta.encoding !== 'base64' || typeof meta.content !== 'string') {
|
||||
throw new Error(
|
||||
`${repo}:${filePath}@${ref} did not come back as a base64 file (encoding ${meta.encoding}).`
|
||||
);
|
||||
}
|
||||
return Buffer.from(meta.content, 'base64').toString('utf8');
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
309
scripts/checkReference.mjs
Normal file
@@ -0,0 +1,309 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* checkReference.mjs — PLAN.md §12, added in phase 8.
|
||||
*
|
||||
* The Reference section names things: every environment variable, every config key, every
|
||||
* installer command, every canonical document. §1 forbids re-specifying a contract, and
|
||||
* this is the machinery that makes writing the NAMES down safe anyway — the same bargain
|
||||
* checkQuickstart.mjs struck for the quickstart, applied to six more sources.
|
||||
*
|
||||
* Phase 15 (PLAN.md §16) added the Rust group's three: rust-link's `sidecar.toml` and its
|
||||
* environment overrides, the bridge plugin's `RunicGateway.json`, and the event kinds with the
|
||||
* class each is served under (D71).
|
||||
*
|
||||
* Each enumeration in `src/data/reference.mjs` is compared against its authority, read from
|
||||
* the repository that owns it over the Gitea API — never from a working tree, per §1's
|
||||
* process rule. Every comparison is a SET comparison in both directions:
|
||||
*
|
||||
* - a name this site lists that the source no longer has fails (the reference is stale);
|
||||
* - a name the source has that this site does not list fails (the reference is
|
||||
* incomplete, which is the failure mode a hand-maintained list actually has).
|
||||
*
|
||||
* The second direction is the one that earns its keep. A reference page does not usually
|
||||
* rot by describing something that vanished — it rots by quietly not mentioning the three
|
||||
* things added since it was written.
|
||||
*
|
||||
* Descriptions are deliberately NOT checked. Nothing here can know whether a one-line
|
||||
* summary is still true, so it does not pretend to; keeping them terse is the mitigation.
|
||||
*
|
||||
* GITEA_TOKEN=<token> node scripts/checkReference.mjs
|
||||
*
|
||||
* Anonymous raw fetches fail on this instance, so the token is required. A check that
|
||||
* silently skips itself is worse than no check.
|
||||
*/
|
||||
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
envVars,
|
||||
sidecarConfig,
|
||||
installerCommands,
|
||||
bridgeCfg,
|
||||
visibilityLadder,
|
||||
canonicalDocs,
|
||||
rustSidecarConfig,
|
||||
rustSidecarEnv,
|
||||
rustPluginConfig,
|
||||
rustEventKinds,
|
||||
} from '../src/data/reference.mjs';
|
||||
|
||||
const ROOT = fileURLToPath(new URL('..', import.meta.url));
|
||||
const platform = JSON.parse(readFileSync(path.join(ROOT, 'src/data/platform.json'), 'utf8'));
|
||||
|
||||
const BASE = platform.gitea.base;
|
||||
const ORG = platform.gitea.org;
|
||||
const TOKEN = process.env.GITEA_TOKEN?.trim();
|
||||
|
||||
const failures = [];
|
||||
const checked = [];
|
||||
const ok = (what) => checked.push(what);
|
||||
const fail = (what, detail) => failures.push({ what, detail });
|
||||
|
||||
/** Same file accessor checkFacts.mjs and checkQuickstart.mjs use, CDN caveat included. */
|
||||
async function raw(repo, filePath, ref = 'main') {
|
||||
const url = `${BASE}/api/v1/repos/${ORG}/${repo}/contents/${filePath}?ref=${encodeURIComponent(ref)}`;
|
||||
const res = await fetch(url, { headers: { Authorization: `token ${TOKEN}` } });
|
||||
if (!res.ok) throw new Error(`${res.status} ${res.statusText} for ${url}`);
|
||||
const meta = await res.json();
|
||||
if (meta.encoding !== 'base64' || typeof meta.content !== 'string') {
|
||||
throw new Error(
|
||||
`${repo}:${filePath}@${ref} did not come back as a base64 file (encoding ${meta.encoding}).`
|
||||
);
|
||||
}
|
||||
return Buffer.from(meta.content, 'base64').toString('utf8');
|
||||
}
|
||||
|
||||
/**
|
||||
* The one comparison this whole script performs, so the failure messages are identical
|
||||
* everywhere and say which direction broke.
|
||||
*/
|
||||
function compareSets(label, mine, theirs, hint) {
|
||||
const mineSet = new Set(mine);
|
||||
const theirsSet = new Set(theirs);
|
||||
|
||||
const stale = [...mineSet].filter((k) => !theirsSet.has(k));
|
||||
const missing = [...theirsSet].filter((k) => !mineSet.has(k));
|
||||
|
||||
for (const k of stale) {
|
||||
fail(`${label}: ${k}`, `listed here, but ${hint} no longer has it — remove it, and re-read the prose around it`);
|
||||
}
|
||||
for (const k of missing) {
|
||||
fail(`${label}: ${k}`, `is in ${hint} and NOT listed here — add it, or the reference is lying by omission`);
|
||||
}
|
||||
if (!stale.length && !missing.length) ok(`${label} (${mineSet.size})`);
|
||||
}
|
||||
|
||||
/** `KEY=value` lines. Commented-out suggestions are prose about a variable, not a key. */
|
||||
const envKeysOf = (text) =>
|
||||
text
|
||||
.split(/\r?\n/)
|
||||
.map((l) => l.match(/^([A-Z][A-Z0-9_]*)=/))
|
||||
.filter(Boolean)
|
||||
.map((m) => m[1]);
|
||||
|
||||
/** `Key=value` lines from the plugin's config, same rule about comments. */
|
||||
const cfgKeysOf = (text) =>
|
||||
text
|
||||
.split(/\r?\n/)
|
||||
.map((l) => l.match(/^([A-Za-z][A-Za-z0-9]*)=/))
|
||||
.filter(Boolean)
|
||||
.map((m) => m[1]);
|
||||
|
||||
/**
|
||||
* A sidecar's TOML keys, parsed from its serde structs rather than from a sample file,
|
||||
* because the sample is GENERATED by the binary on first run and no committed copy is
|
||||
* authoritative. Each `pub name: T` inside a `struct XCfg` is one key, and the struct name
|
||||
* gives the section. Both sidecars are written this way, so one parser serves both.
|
||||
*/
|
||||
function tomlKeysOf(configRs) {
|
||||
const keys = [];
|
||||
for (const m of configRs.matchAll(/struct\s+(\w+)Cfg\s*\{([\s\S]*?)\n\}/g)) {
|
||||
const section = m[1].toLowerCase();
|
||||
for (const f of m[2].matchAll(/pub\s+(\w+)\s*:/g)) keys.push(`${section}.${f[1]}`);
|
||||
}
|
||||
return keys;
|
||||
}
|
||||
|
||||
/** The body of a C# class, by brace counting from its opening brace. */
|
||||
function classBody(source, name) {
|
||||
const start = source.search(new RegExp(`class\\s+${name}\\b`));
|
||||
if (start < 0) return null;
|
||||
const open = source.indexOf('{', start);
|
||||
let depth = 0;
|
||||
for (let i = open; i < source.length; i++) {
|
||||
if (source[i] === '{') depth++;
|
||||
else if (source[i] === '}' && --depth === 0) return source.slice(open + 1, i);
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* The quoted strings inside `const NAME = Object.freeze([ … ])`, comments removed first —
|
||||
* the module's comments are prose, and prose has apostrophes.
|
||||
*/
|
||||
function frozenListOf(source, name) {
|
||||
const m = source.match(new RegExp(`const\\s+${name}\\s*=\\s*Object\\.freeze\\(\\[([\\s\\S]*?)\\]\\)`));
|
||||
if (!m) return null;
|
||||
const code = m[1].replace(/\/\/.*$/gm, '');
|
||||
return [...code.matchAll(/'([^'\n]+)'/g)].map((x) => x[1]);
|
||||
}
|
||||
|
||||
async function run() {
|
||||
if (!TOKEN) {
|
||||
console.error('checkReference: GITEA_TOKEN is not set. This check cannot run anonymously.');
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
// ── 1. Environment variables ──────────────────────────────────────────────
|
||||
compareSets(
|
||||
'env',
|
||||
Object.keys(envVars),
|
||||
envKeysOf(await raw('website', '.env.example')),
|
||||
'website main:.env.example',
|
||||
);
|
||||
|
||||
// ── 2. sidecar.toml ───────────────────────────────────────────────────────
|
||||
//
|
||||
// Parsed from the serde structs rather than from a sample file, because the sample is
|
||||
// GENERATED by the binary on first run and no committed copy is authoritative. Each
|
||||
// `pub name: T` inside a `struct XCfg` is one key, and the struct name gives the section.
|
||||
compareSets(
|
||||
'sidecar.toml',
|
||||
Object.keys(sidecarConfig),
|
||||
tomlKeysOf(await raw('link', 'sidecar/src/config.rs')),
|
||||
'link main:sidecar/src/config.rs',
|
||||
);
|
||||
|
||||
// ── 3. Installer commands ─────────────────────────────────────────────────
|
||||
const cliRs = await raw('installer', 'src/cli.rs');
|
||||
const cmdBlock = cliRs.match(/enum\s+Command\s*\{([\s\S]*?)\n\}/);
|
||||
const cmds = cmdBlock ? [...cmdBlock[1].matchAll(/^\s*([A-Z]\w*)\s*[,{]/gm)].map((m) => m[1]) : [];
|
||||
compareSets('installer command', Object.keys(installerCommands), cmds, 'installer main:src/cli.rs');
|
||||
|
||||
// ── 4. Bridge.cfg ─────────────────────────────────────────────────────────
|
||||
const bridgeKeys = Object.values(bridgeCfg).flatMap((group) => Object.keys(group));
|
||||
compareSets(
|
||||
'Bridge.cfg',
|
||||
bridgeKeys,
|
||||
cfgKeysOf(await raw('servuo-plugins', 'overlay/Config/Bridge.cfg')),
|
||||
'servuo-plugins main:overlay/Config/Bridge.cfg',
|
||||
);
|
||||
|
||||
// ── 5. The visibility ladder ──────────────────────────────────────────────
|
||||
//
|
||||
// A security boundary, so it is checked against the module that enforces it rather than
|
||||
// against prose. The order matters as much as the membership: it is a ladder, and a
|
||||
// reader reasoning about "staff and above" needs the rungs in the right sequence.
|
||||
const vis = await raw('Module-uo', 'server/utils/shardVisibility.js');
|
||||
const ladderMatch = vis.match(/const\s+LADDER\s*=\s*\[([\s\S]*?)\]/);
|
||||
const ladder = ladderMatch
|
||||
? [...ladderMatch[1].matchAll(/'([a-z_]+)'/g)].map((m) => m[1])
|
||||
: [];
|
||||
if (ladder.length === 0) {
|
||||
fail('visibility ladder', 'could not find LADDER in Module-uo main:server/utils/shardVisibility.js');
|
||||
} else if (ladder.join(' ') !== visibilityLadder.join(' ')) {
|
||||
fail(
|
||||
'visibility ladder',
|
||||
`order or membership differs — here "${visibilityLadder.join(' → ')}", upstream "${ladder.join(' → ')}"`,
|
||||
);
|
||||
} else ok(`visibility ladder (${ladder.length} rungs, in order)`);
|
||||
|
||||
// ── 6. Canonical documents ────────────────────────────────────────────────
|
||||
//
|
||||
// Existence only. A link to a document that moved is the single most likely way this
|
||||
// section breaks, and it is exactly what a build can answer.
|
||||
for (const docPath of Object.values(canonicalDocs).flatMap((group) => Object.keys(group))) {
|
||||
const url = `${BASE}/api/v1/repos/${ORG}/docs/contents/${docPath}?ref=main`;
|
||||
const res = await fetch(url, { headers: { Authorization: `token ${TOKEN}` } });
|
||||
if (res.ok) ok(`canonical doc ${docPath}`);
|
||||
else fail(`canonical doc ${docPath}`, `not found in docs main (HTTP ${res.status})`);
|
||||
}
|
||||
|
||||
// ── 7. Rust: rust-link's sidecar.toml, and the variables that override it ──
|
||||
//
|
||||
// PLAN.md §16, phase 15. The same parser as uo-link's — both sidecars declare their file
|
||||
// as serde structs — plus the environment overrides, which a Pterodactyl egg sets and an
|
||||
// operator meets on the panel before they ever see the file.
|
||||
const rustConfigRs = await raw('Rust-Link', 'sidecar/src/config.rs');
|
||||
compareSets(
|
||||
'rust-link sidecar.toml',
|
||||
Object.keys(rustSidecarConfig),
|
||||
tomlKeysOf(rustConfigRs),
|
||||
'Rust-Link main:sidecar/src/config.rs',
|
||||
);
|
||||
compareSets(
|
||||
'rust-link environment variable',
|
||||
Object.keys(rustSidecarEnv),
|
||||
[...rustConfigRs.matchAll(/get\("(RUSTLINK_[A-Z_]+)"\)/g)].map((m) => m[1]),
|
||||
'Rust-Link main:sidecar/src/config.rs',
|
||||
);
|
||||
for (const [envName, key] of Object.entries(rustSidecarEnv)) {
|
||||
if (!(key in rustSidecarConfig)) fail(`rust-link environment variable ${envName}`, `says it overrides "${key}", which is not a key listed here`);
|
||||
}
|
||||
|
||||
// ── 8. Rust: the bridge plugin's RunicGateway.json ────────────────────────
|
||||
//
|
||||
// The public fields of `PluginConfig`, which the framework serialises as the file.
|
||||
const pluginCs = await raw('Rust-Plugins', 'overlay/oxide/plugins/RunicGateway.cs');
|
||||
const pluginBody = classBody(pluginCs, 'PluginConfig');
|
||||
if (!pluginBody) {
|
||||
fail('RunicGateway.json', 'could not find class PluginConfig in Rust-Plugins main:overlay/oxide/plugins/RunicGateway.cs');
|
||||
} else {
|
||||
compareSets(
|
||||
'RunicGateway.json',
|
||||
Object.values(rustPluginConfig).flatMap((group) => Object.keys(group)),
|
||||
[...pluginBody.matchAll(/public\s+[\w<>[\],]+\s+(\w+)\s*=/g)].map((m) => m[1]),
|
||||
'Rust-Plugins main:overlay/oxide/plugins/RunicGateway.cs PluginConfig',
|
||||
);
|
||||
}
|
||||
|
||||
// ── 9. Rust: the event kinds, and who may see each ────────────────────────
|
||||
//
|
||||
// D71: checked against the module's own catalogue, because the module is what enforces
|
||||
// the boundary (the same reasoning as check 5). Three comparisons, each a security
|
||||
// statement: a kind listed public here must be public there, a presence kind must be one
|
||||
// of the module's presence kinds, and a staff kind must be staff there. A kind moved from
|
||||
// staff to public upstream fails this check twice over, which is the point.
|
||||
const catalogue = await raw('Module-Rust', 'server/catalogue.js');
|
||||
const upPublic = frozenListOf(catalogue, 'PUBLIC_KINDS');
|
||||
const upStaff = frozenListOf(catalogue, 'STAFF_KINDS');
|
||||
const upPresence = frozenListOf(catalogue, 'PRESENCE_KINDS');
|
||||
if (!upPublic || !upStaff || !upPresence) {
|
||||
fail('Rust event kinds', 'could not find PUBLIC_KINDS, STAFF_KINDS and PRESENCE_KINDS in Module-Rust main:server/catalogue.js');
|
||||
} else {
|
||||
const hint = 'Module-Rust main:server/catalogue.js';
|
||||
compareSets('Rust presence kind', Object.keys(rustEventKinds.presence), upPresence, `${hint} PRESENCE_KINDS`);
|
||||
compareSets(
|
||||
'Rust public kind',
|
||||
Object.keys(rustEventKinds.public),
|
||||
upPublic.filter((k) => !upPresence.includes(k)),
|
||||
`${hint} PUBLIC_KINDS (less its presence kinds)`,
|
||||
);
|
||||
compareSets('Rust staff kind', Object.keys(rustEventKinds.staff), upStaff, `${hint} STAFF_KINDS`);
|
||||
for (const k of upPresence) {
|
||||
if (!upPublic.includes(k)) fail(`Rust presence kind ${k}`, 'is a presence kind upstream but not a public one — the page explains presence as a narrowing of public, so re-read it');
|
||||
}
|
||||
}
|
||||
|
||||
// ── Report ────────────────────────────────────────────────────────────────
|
||||
if (failures.length === 0) {
|
||||
console.log(`checkReference: ${checked.length} enumeration check(s) passed against their sources.`);
|
||||
return;
|
||||
}
|
||||
|
||||
console.error(`\ncheckReference: ${failures.length} disagreement(s) with the platform:\n`);
|
||||
for (const f of failures) console.error(` ✗ ${f.what}\n ${f.detail}`);
|
||||
console.error(`
|
||||
The Reference section names things, which is only safe while the names are checked
|
||||
(§1, and the same bargain checkQuickstart.mjs struck). Update src/data/reference.mjs
|
||||
to match the source. Do not "fix" the check.
|
||||
`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
run().catch((err) => {
|
||||
console.error(`checkReference: ${err.message}`);
|
||||
process.exit(2);
|
||||
});
|
||||
171
scripts/checkScreens.mjs
Normal file
@@ -0,0 +1,171 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* checkScreens.mjs — the screenshots agree with what the pages say about them.
|
||||
*
|
||||
* PLAN.md §12, §13 phase 9, D45.
|
||||
*
|
||||
* node scripts/checkScreens.mjs
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* WHAT IT PROVES, AND WHY EACH ONE IS WORTH A CHECK
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* 1. EVERY DECLARED SCREEN HAS A FILE. A missing image is invisible in review — the page
|
||||
* still builds, still lays out, and only a reader sees the broken frame.
|
||||
*
|
||||
* 2. EVERY FILE IS THE DECLARED SIZE. `width` and `height` reach the markup as intrinsic
|
||||
* attributes, and an attribute that disagrees with the file is a page that jumps as the
|
||||
* image decodes. It also catches a re-capture taken at the wrong viewport, which looks
|
||||
* fine on its own and wrong beside the others.
|
||||
*
|
||||
* 3. NOTHING IN public/screens IS ORPHANED. A capture that stopped being referenced is a
|
||||
* file the container still ships and nobody looks at — and, worse, one that never gets
|
||||
* retaken, so it silently becomes the oldest thing in the repository.
|
||||
*
|
||||
* 4. EVERY DECLARED SCREEN IS ACTUALLY USED. The mirror of 3: an entry in `screens.mjs`
|
||||
* that no page renders is a capture being maintained for nothing. Usage is a literal
|
||||
* search for the id across `src/`, which is how both readers of the data refer to one —
|
||||
* `<Screenshot id="admin-users" />` and the `groupScreens` map on `/features/`.
|
||||
*
|
||||
* 5. THE ALT TEXT AND CAPTION SAY SOMETHING. An empty alt on an editorial image is an
|
||||
* accessibility failure the build cannot otherwise see, and a caption is the sentence
|
||||
* that makes a screenshot evidence rather than decoration.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* WHY IT READS THE PNG HEADER ITSELF
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* It does not: it reads the WebP header, and it does it with twenty lines rather than a
|
||||
* dependency. `sharp` is already here for the brand assets and could answer this, but this
|
||||
* check runs in CI on every pull request and a check that needs a native image library to
|
||||
* tell you a file is 1920 pixels wide is a check that will one day fail for a reason that
|
||||
* has nothing to do with screenshots.
|
||||
*/
|
||||
|
||||
import { readdirSync, readFileSync, existsSync } from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
import { screens, WEB, PHONE } from '../src/data/screens.mjs';
|
||||
|
||||
const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
const ROOT = path.join(HERE, '..');
|
||||
const DIR = path.join(ROOT, 'public', 'screens');
|
||||
const SRC = path.join(ROOT, 'src');
|
||||
|
||||
const problems = [];
|
||||
|
||||
/**
|
||||
* The pixel size of a WebP file, from its header.
|
||||
*
|
||||
* A RIFF container: "RIFF" size "WEBP" then one of three chunk types. Lossy ("VP8 ") and
|
||||
* lossless ("VP8L") pack the dimensions differently, and an animated or extended file
|
||||
* ("VP8X") states them outright. `cwebp` at quality 82 writes VP8 , but a future change of
|
||||
* encoder should not turn this check into a mystery, so all three are handled.
|
||||
*/
|
||||
function webpSize(file) {
|
||||
const buf = readFileSync(file);
|
||||
|
||||
if (buf.length < 30 || buf.toString('ascii', 0, 4) !== 'RIFF' || buf.toString('ascii', 8, 12) !== 'WEBP') {
|
||||
return null;
|
||||
}
|
||||
|
||||
const chunk = buf.toString('ascii', 12, 16);
|
||||
|
||||
if (chunk === 'VP8X') {
|
||||
return {
|
||||
width: 1 + (buf[24] | (buf[25] << 8) | (buf[26] << 16)),
|
||||
height: 1 + (buf[27] | (buf[28] << 8) | (buf[29] << 16)),
|
||||
};
|
||||
}
|
||||
|
||||
if (chunk === 'VP8L') {
|
||||
const bits = buf[21] | (buf[22] << 8) | (buf[23] << 16) | (buf[24] << 24);
|
||||
return { width: 1 + (bits & 0x3fff), height: 1 + ((bits >> 14) & 0x3fff) };
|
||||
}
|
||||
|
||||
if (chunk === 'VP8 ') {
|
||||
return {
|
||||
width: buf.readUInt16LE(26) & 0x3fff,
|
||||
height: buf.readUInt16LE(28) & 0x3fff,
|
||||
};
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/** Every file under `src/`, read once, so usage is a search rather than a guess. */
|
||||
function sourceText() {
|
||||
const out = [];
|
||||
|
||||
const walk = (dir) => {
|
||||
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) walk(full);
|
||||
else if (/\.(astro|mdx?|mjs|js|ts|tsx)$/.test(entry.name)) out.push(readFileSync(full, 'utf8'));
|
||||
}
|
||||
};
|
||||
|
||||
walk(SRC);
|
||||
return out;
|
||||
}
|
||||
|
||||
const sources = sourceText();
|
||||
const declared = new Set();
|
||||
|
||||
for (const shot of screens) {
|
||||
const name = `${shot.id}.webp`;
|
||||
const file = path.join(DIR, name);
|
||||
declared.add(name);
|
||||
|
||||
if (!existsSync(file)) {
|
||||
problems.push(
|
||||
`${shot.id}: no file at public/screens/${name}. ` +
|
||||
`Retake it: node scripts/captureScreens.mjs ${shot.id}`,
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
const want = shot.family === 'web' ? WEB : PHONE;
|
||||
const size = webpSize(file);
|
||||
|
||||
if (!size) {
|
||||
problems.push(`${shot.id}: public/screens/${name} is not a WebP this check can read.`);
|
||||
} else if (size.width !== want.width || size.height !== want.height) {
|
||||
problems.push(
|
||||
`${shot.id}: file is ${size.width}x${size.height}, ` +
|
||||
`declared ${want.width}x${want.height} for the "${shot.family}" family.`,
|
||||
);
|
||||
}
|
||||
|
||||
if (!shot.alt || shot.alt.length < 20) {
|
||||
problems.push(`${shot.id}: alt text is missing or too short to describe the screen.`);
|
||||
}
|
||||
|
||||
if (!shot.caption) {
|
||||
problems.push(`${shot.id}: no caption.`);
|
||||
}
|
||||
|
||||
const used = sources.some((text) => text.includes(`'${shot.id}'`) || text.includes(`"${shot.id}"`));
|
||||
|
||||
if (!used) {
|
||||
problems.push(
|
||||
`${shot.id}: declared but no page renders it. Use it, or delete the entry and its file.`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (existsSync(DIR)) {
|
||||
for (const name of readdirSync(DIR)) {
|
||||
if (!declared.has(name)) {
|
||||
problems.push(`public/screens/${name}: not declared in src/data/screens.mjs.`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (problems.length > 0) {
|
||||
console.error(`\ncheckScreens: ${problems.length} problem(s)\n`);
|
||||
for (const problem of problems) console.error(` - ${problem}`);
|
||||
console.error('');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log(`checkScreens: ${screens.length} screens, all present, sized and used.`);
|
||||
77
scripts/checkSidebar.mjs
Normal file
@@ -0,0 +1,77 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* checkSidebar.mjs — PLAN.md §12, added in phase 8.
|
||||
*
|
||||
* `src/config/sidebar.mjs` holds two trees: `docsSidebar`, which Starlight renders, and
|
||||
* `plannedSidebar`, the tree §10 planned. While pages were still being written the second
|
||||
* was a checklist. Now that every page exists it is a second copy of the first, maintained
|
||||
* by hand — and a hand-maintained copy with nothing reading it is exactly the shape of
|
||||
* thing §1 is about.
|
||||
*
|
||||
* It had already drifted, silently: phase 7 added the `Content` page under D37 and this
|
||||
* list was never updated. Nothing failed, because nothing read it. That is the whole
|
||||
* argument for this check.
|
||||
*
|
||||
* So the two must agree on groups, labels AND order. Order is checked because the order of
|
||||
* "Getting started" IS the installation path — §10 calls it the priority of the whole
|
||||
* project — and a reordering that nobody noticed would be a worse defect than a missing
|
||||
* page.
|
||||
*
|
||||
* node scripts/checkSidebar.mjs
|
||||
*
|
||||
* No token and no network: both trees are in this repository.
|
||||
*/
|
||||
|
||||
import { docsSidebar, plannedSidebar } from '../src/config/sidebar.mjs';
|
||||
|
||||
const failures = [];
|
||||
const fail = (what, detail) => failures.push({ what, detail });
|
||||
|
||||
const live = new Map(docsSidebar.map((g) => [g.label, g.items.map((i) => i.label)]));
|
||||
const planned = new Map(Object.entries(plannedSidebar));
|
||||
|
||||
// ── Groups ──────────────────────────────────────────────────────────────────
|
||||
for (const label of live.keys()) {
|
||||
if (!planned.has(label)) fail(`group ${label}`, 'is in the live sidebar and not in plannedSidebar');
|
||||
}
|
||||
for (const label of planned.keys()) {
|
||||
if (!live.has(label)) fail(`group ${label}`, 'is in plannedSidebar and not in the live sidebar');
|
||||
}
|
||||
|
||||
// ── Pages, in order ─────────────────────────────────────────────────────────
|
||||
for (const [label, liveItems] of live) {
|
||||
const plannedItems = planned.get(label);
|
||||
if (!plannedItems) continue;
|
||||
|
||||
for (const page of liveItems) {
|
||||
if (!plannedItems.includes(page)) fail(`${label} → ${page}`, 'is live but not in plannedSidebar');
|
||||
}
|
||||
for (const page of plannedItems) {
|
||||
if (!liveItems.includes(page)) fail(`${label} → ${page}`, 'is planned but has no live sidebar entry');
|
||||
}
|
||||
|
||||
// Only meaningful once membership matches; otherwise it just repeats the above.
|
||||
if (liveItems.length === plannedItems.length && liveItems.every((p) => plannedItems.includes(p))) {
|
||||
if (liveItems.join(' | ') !== plannedItems.join(' | ')) {
|
||||
fail(
|
||||
`${label} order`,
|
||||
`live "${liveItems.join(' → ')}" vs planned "${plannedItems.join(' → ')}"`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ── Report ──────────────────────────────────────────────────────────────────
|
||||
if (failures.length === 0) {
|
||||
const pages = [...live.values()].reduce((n, items) => n + items.length, 0);
|
||||
console.log(`checkSidebar: ${live.size} groups and ${pages} pages agree with plannedSidebar.`);
|
||||
} else {
|
||||
console.error(`\ncheckSidebar: ${failures.length} disagreement(s) between the two trees:\n`);
|
||||
for (const f of failures) console.error(` ✗ ${f.what}\n ${f.detail}`);
|
||||
console.error(`
|
||||
Both trees are in src/config/sidebar.mjs. Decide which one is right — if a page was
|
||||
deliberately added, renamed or reordered, plannedSidebar records that decision and
|
||||
should move with it.
|
||||
`);
|
||||
process.exit(1);
|
||||
}
|
||||
271
scripts/checkTerms.mjs
Normal file
@@ -0,0 +1,271 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* checkTerms.mjs — PLAN.md §16, D63 and D64. The twelfth check, added in phase 14.
|
||||
*
|
||||
* D63: outside a game's own section, the site may NAME the games it supports, but it may not
|
||||
* use their VOCABULARY. Core concepts keep core's names — a Team, a game server, the sidecar,
|
||||
* the bridge plugin, the game module — because that is what core itself calls them, and a
|
||||
* site that says "shard" on a core page is describing one game's deployment as though it were
|
||||
* the platform.
|
||||
*
|
||||
* D64: a convention that holds only while everyone remembers it does not hold. This is the
|
||||
* same argument `checkTokens.mjs` makes for colours, applied to words. The vocabulary problem
|
||||
* was measured before this check existed — "shard" 227 times in 45 files — and none of that
|
||||
* was anybody's decision; it was the residue of a site written while there was one game.
|
||||
*
|
||||
* What it reads, as of phase 14:
|
||||
*
|
||||
* - every page under `src/content/docs`, frontmatter included (a title and a description
|
||||
* are what a reader sees first, in the sidebar and in search results);
|
||||
* - `src/config/sidebar.mjs`, as DATA rather than as text: every group label and every
|
||||
* page label, in both trees. Its comments are not scanned, because a comment is not
|
||||
* something a reader of the site ever sees.
|
||||
*
|
||||
* Phase 17 widens it to all of `src/`, once the marketing pages have a game page to move
|
||||
* their game content to. That is also when it learns D67's screenshot tag.
|
||||
*
|
||||
* Where a game's words are allowed:
|
||||
*
|
||||
* - in that game's own docs directory (`GAME_DIRS`), and its own sidebar group — a group
|
||||
* whose label is the game's `name` in `platform.json`;
|
||||
* - between `<GameExample game="…">` tags on a core page (D68). The component prints the
|
||||
* game's name above the block, so the words arrive already labelled.
|
||||
*
|
||||
* What is NOT read, deliberately:
|
||||
*
|
||||
* - link targets and bare URLs. A repository is called what it is called, and an address is
|
||||
* not prose. The LINK TEXT is read, so `[Module-uo](…)` fails and `[releases](…)` passes;
|
||||
* - `import` lines and `{…}` expressions. They are code, and what an expression renders is
|
||||
* a value from `platform.json` or `src/data/`, which phase 17 brings into scope.
|
||||
*
|
||||
* node scripts/checkTerms.mjs
|
||||
*
|
||||
* No token and no network: everything it reads is in this repository.
|
||||
*/
|
||||
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { readdir } from 'node:fs/promises';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import path from 'node:path';
|
||||
|
||||
import { docsSidebar, plannedSidebar } from '../src/config/sidebar.mjs';
|
||||
|
||||
const ROOT = fileURLToPath(new URL('..', import.meta.url));
|
||||
const platform = JSON.parse(readFileSync(path.join(ROOT, 'src/data/platform.json'), 'utf8'));
|
||||
|
||||
/**
|
||||
* The words, each tagged with the game it belongs to. Matching is case-insensitive and on
|
||||
* word boundaries, so "shard" does not match `SHARD_VISIBILITY` and "wipe" does not match
|
||||
* "wiped" unless it is listed.
|
||||
*
|
||||
* A word is on this list because it is a game's name for something core has its own name for
|
||||
* (shard → game server, guild and clan → Team), or because it names one game's component
|
||||
* (uo-link → the sidecar, ServUO → the game server). Game NAMES — Ultima Online, UO, Rust —
|
||||
* are not on it: D63 allows them everywhere. Steam is not on it either: Steam sign-in is a
|
||||
* core identity provider, even though Rust was its first user.
|
||||
*/
|
||||
const TERMS = [
|
||||
{ game: 'uo', word: 'shard', re: /\bshards?\b/gi },
|
||||
{ game: 'uo', word: 'ServUO', re: /\bservuo\b/gi },
|
||||
{ game: 'uo', word: 'uo-link', re: /\buo-?link\b/gi },
|
||||
{ game: 'uo', word: 'Module-uo', re: /\bmodule-uo\b/gi },
|
||||
{ game: 'uo', word: 'Bridge.cfg', re: /\bbridge\.cfg\b/gi },
|
||||
{ game: 'uo', word: 'cliloc', re: /\bclilocs?\b/gi },
|
||||
{ game: 'uo', word: 'guild', re: /\bguilds?\b/gi },
|
||||
{ game: 'uo', word: 'IDOC', re: /\bidocs?\b/gi },
|
||||
{ game: 'rust', word: 'rust-link', re: /\brust-?link\b/gi },
|
||||
{ game: 'rust', word: 'Rust-Plugins', re: /\brust-plugins\b/gi },
|
||||
{ game: 'rust', word: 'Module-Rust', re: /\bmodule-rust\b/gi },
|
||||
{ game: 'rust', word: 'Oxide', re: /\boxide\b/gi },
|
||||
{ game: 'rust', word: 'Carbon', re: /\bcarbon\b/gi },
|
||||
{ game: 'rust', word: 'uMod', re: /\bumod\b/gi },
|
||||
{ game: 'rust', word: 'clan', re: /\bclans?\b/gi },
|
||||
{ game: 'rust', word: 'wipe', re: /\bwipes?\b/gi },
|
||||
];
|
||||
|
||||
/** Each game's own docs directory. A page under one may use that game's words. */
|
||||
const GAME_DIRS = {
|
||||
uo: 'src/content/docs/docs/ultima-online/',
|
||||
rust: 'src/content/docs/docs/rust/',
|
||||
};
|
||||
|
||||
/**
|
||||
* The allowlist: an exact phrase in one file that may use a word the rule would otherwise
|
||||
* refuse. Short on purpose, and every entry says why. An entry that no longer matches its
|
||||
* file fails the check too, so the list cannot rot into a set of permanent exemptions.
|
||||
*/
|
||||
const ALLOW = [
|
||||
{
|
||||
file: 'src/content/docs/docs/administration/notifications-and-email.mdx',
|
||||
text: 'Guild (server) ID',
|
||||
why: "Discord's own word, not a game's: it is the label on core's Discord Bot screen.",
|
||||
},
|
||||
];
|
||||
|
||||
for (const game of Object.keys(GAME_DIRS)) {
|
||||
if (!platform.games[game]) throw new Error(`checkTerms: GAME_DIRS names "${game}", which platform.json does not.`);
|
||||
}
|
||||
for (const t of TERMS) {
|
||||
if (!platform.games[t.game]) throw new Error(`checkTerms: "${t.word}" is tagged "${t.game}", which platform.json does not know.`);
|
||||
}
|
||||
|
||||
const failures = [];
|
||||
const fail = (where, detail) => failures.push({ where, detail });
|
||||
|
||||
/** Replace a span with spaces, keeping newlines, so later line numbers stay true. */
|
||||
const blank = (text) => text.replace(/[^\n]/g, ' ');
|
||||
|
||||
/** The game whose directory holds this file, or null for a core page. */
|
||||
function gameOfPath(relative) {
|
||||
const posix = relative.split(path.sep).join('/');
|
||||
for (const [game, dir] of Object.entries(GAME_DIRS)) if (posix.startsWith(dir)) return game;
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Turn an MDX source into the text a reader would actually see, with everything that is not
|
||||
* prose blanked out. Returns that text plus the GameExample regions, as offsets into it.
|
||||
*/
|
||||
function proseOf(source, relative) {
|
||||
let text = source;
|
||||
|
||||
// GameExample regions first, while the tags are still intact. Recorded, then the tags
|
||||
// themselves are blanked so the attribute does not read as prose.
|
||||
const regions = [];
|
||||
for (const m of text.matchAll(/<GameExample\s+game="([^"]*)"\s*>([\s\S]*?)<\/GameExample>/g)) {
|
||||
const game = m[1];
|
||||
if (!platform.games[game]) {
|
||||
fail(`${relative}:${lineOf(source, m.index)}`, `<GameExample game="${game}"> names a game platform.json does not have`);
|
||||
}
|
||||
regions.push({ game, start: m.index, end: m.index + m[0].length });
|
||||
}
|
||||
text = text.replace(/<\/?GameExample\b[^>]*>/g, blank);
|
||||
|
||||
text = text.replace(/<!--[\s\S]*?-->/g, blank); // HTML comments
|
||||
text = text.replace(/^import\s.*$/gm, blank); // MDX imports
|
||||
text = text.replace(/\]\([^)\s]*\)/g, (m) => '] ' + blank(m.slice(2))); // link targets, not their text
|
||||
text = text.replace(/\b(?:href|src)=(?:"[^"]*"|\{`[^`]*`\})/g, blank); // JSX/HTML link targets
|
||||
text = text.replace(/\bhttps?:\/\/[^\s)>"'`]+/g, blank); // bare URLs
|
||||
|
||||
// `{…}` expressions, outside code fences only — a fenced JSON example's braces are prose.
|
||||
// Innermost first, repeatedly, so nested and multi-line expressions both go.
|
||||
const parts = text.split(/(^```[\s\S]*?^```)/m);
|
||||
for (let i = 0; i < parts.length; i += 2) {
|
||||
let prev;
|
||||
do {
|
||||
prev = parts[i];
|
||||
parts[i] = parts[i].replace(/\{[^{}]*\}/g, blank);
|
||||
} while (parts[i] !== prev);
|
||||
}
|
||||
text = parts.join('');
|
||||
|
||||
return { text, regions };
|
||||
}
|
||||
|
||||
function lineOf(source, index) {
|
||||
return source.slice(0, index).split('\n').length;
|
||||
}
|
||||
|
||||
/** Hits for every term the given context may not use. */
|
||||
function scan(text, allowedGame) {
|
||||
const hits = [];
|
||||
for (const t of TERMS) {
|
||||
if (t.game === allowedGame) continue;
|
||||
t.re.lastIndex = 0;
|
||||
for (const m of text.matchAll(t.re)) hits.push({ term: t, value: m[0], index: m.index });
|
||||
}
|
||||
return hits;
|
||||
}
|
||||
|
||||
async function* walk(dir) {
|
||||
let entries;
|
||||
try {
|
||||
entries = await readdir(dir, { withFileTypes: true });
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
for (const entry of entries) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) yield* walk(full);
|
||||
else if (/\.mdx?$/.test(entry.name)) yield full;
|
||||
}
|
||||
}
|
||||
|
||||
// ── 1. The documentation pages ──────────────────────────────────────────────
|
||||
let files = 0;
|
||||
const allowUsed = new Set();
|
||||
|
||||
for await (const file of walk(path.join(ROOT, 'src', 'content', 'docs'))) {
|
||||
const relative = path.relative(ROOT, file).split(path.sep).join('/');
|
||||
const posix = relative;
|
||||
const source = readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
|
||||
files++;
|
||||
|
||||
let { text, regions } = proseOf(source, relative);
|
||||
|
||||
for (const [i, entry] of ALLOW.entries()) {
|
||||
if (entry.file !== posix) continue;
|
||||
if (text.includes(entry.text)) {
|
||||
allowUsed.add(i);
|
||||
text = text.split(entry.text).join(blank(entry.text));
|
||||
}
|
||||
}
|
||||
|
||||
const pageGame = gameOfPath(relative);
|
||||
for (const hit of scan(text, pageGame)) {
|
||||
const region = regions.find((r) => hit.index >= r.start && hit.index < r.end);
|
||||
if (region && region.game === hit.term.game) continue;
|
||||
const where = region ? `inside <GameExample game="${region.game}">` : pageGame ? `in the ${platform.games[pageGame].name} group` : 'on a core page';
|
||||
fail(
|
||||
`${relative}:${lineOf(source, hit.index)}`,
|
||||
`"${hit.value}" is ${platform.games[hit.term.game].name} vocabulary, ${where}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
for (const [i, entry] of ALLOW.entries()) {
|
||||
if (!allowUsed.has(i)) {
|
||||
fail(`allowlist: ${entry.file}`, `"${entry.text}" no longer appears there — remove the entry`);
|
||||
}
|
||||
}
|
||||
|
||||
// ── 2. The sidebar, as data ─────────────────────────────────────────────────
|
||||
const gameByName = new Map(Object.entries(platform.games).map(([key, g]) => [g.name, key]));
|
||||
const trees = [
|
||||
['docsSidebar', docsSidebar.map((g) => [g.label, g.items.map((i) => i.label)])],
|
||||
['plannedSidebar', Object.entries(plannedSidebar)],
|
||||
];
|
||||
let labels = 0;
|
||||
for (const [treeName, groups] of trees) {
|
||||
for (const [groupLabel, items] of groups) {
|
||||
const game = gameByName.get(groupLabel) ?? null;
|
||||
for (const label of [groupLabel, ...items]) {
|
||||
labels++;
|
||||
for (const hit of scan(label, game)) {
|
||||
fail(
|
||||
`src/config/sidebar.mjs ${treeName} → ${groupLabel}`,
|
||||
`"${label}" uses "${hit.value}", ${platform.games[hit.term.game].name} vocabulary, ${game ? `in the ${platform.games[game].name} group` : 'in a core group'}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ── Report ──────────────────────────────────────────────────────────────────
|
||||
if (failures.length === 0) {
|
||||
console.log(
|
||||
`checkTerms: ${files} docs pages and ${labels} sidebar labels use only their own game's words ` +
|
||||
`(${TERMS.length} terms, ${ALLOW.length} allowlisted phrase${ALLOW.length === 1 ? '' : 's'}).`,
|
||||
);
|
||||
} else {
|
||||
console.error(`\ncheckTerms: ${failures.length} game word(s) outside their game's section:\n`);
|
||||
for (const f of failures) console.error(` ✗ ${f.where}\n ${f.detail}`);
|
||||
console.error(`
|
||||
PLAN.md §16, D63: name the games anywhere, but keep their vocabulary in their own section.
|
||||
Use core's word instead — a Team, a game server, the sidecar, the bridge plugin, the game
|
||||
module. If a core page genuinely needs a game's real example, wrap it in
|
||||
<GameExample game="…"> (D68), which labels it with the game's name. Add to the allowlist
|
||||
in this script only for a word that is not a game's at all, and say why.
|
||||
`);
|
||||
process.exit(1);
|
||||
}
|
||||
469
scripts/seedDemo.mjs
Normal file
@@ -0,0 +1,469 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* seedDemo.mjs — the deployment the screenshots are taken of. PLAN.md §13 phase 9, D45.
|
||||
*
|
||||
* node scripts/seedDemo.mjs → seed (idempotent; safe to re-run)
|
||||
* node scripts/seedDemo.mjs --dry-run → say what it would do, write nothing
|
||||
*
|
||||
* Environment (all optional; the defaults are this machine's review stack):
|
||||
*
|
||||
* RG_BASE http://localhost:3000 the website the seed drives
|
||||
* RG_ADMIN_USER demoadmin an existing admin, created by website's own
|
||||
* RG_ADMIN_PASS DemoReview!2026 `npm run seed` — see PLAN.md §13 phase 9
|
||||
* RG_DEMO_PASS DemoReview!2026 the password every seeded cast member gets
|
||||
* UOLINK_BASE http://127.0.0.1:8080 sidecar REST, written to Admin → Shard
|
||||
* UOLINK_WS ws://127.0.0.1:8080/ws sidecar WebSocket
|
||||
* UOLINK_TOKEN (unset) sidecar auth token; skipped when absent
|
||||
* UOLINK_PROTOCOL (platform.json) wire protocol to pin — see the note below
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* WHY THE SEED DRIVES THE API AND NEVER THE DATABASE
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* Every row this creates could have been an INSERT, and every INSERT would have been a
|
||||
* second implementation of a rule the website already owns: how a body is sanitized, what
|
||||
* a slug may contain, which excerpt is derived when none is given, how a password is
|
||||
* hashed. A seed that writes SQL directly produces a database the product could not have
|
||||
* produced, and screenshots of that database show a product that does not exist.
|
||||
*
|
||||
* So this speaks HTTP to a running site, as an admin, through the same endpoints the admin
|
||||
* panel calls. The cost is that the site has to be up; the benefit is that the content is
|
||||
* real, and that this script keeps working when a column moves.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* WHY IT IS IDEMPOTENT RATHER THAN DESTRUCTIVE
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* Re-running must not double the news list, and must not erase a screenshot rig somebody
|
||||
* has been adjusting by hand. Every step therefore looks before it writes and reports
|
||||
* `= exists` rather than failing. That also makes the script usable as a repair: point it
|
||||
* at a stack that has drifted and it puts back only what is missing.
|
||||
*
|
||||
* What it deliberately does NOT create: anything the shard owns. Teams arrive from the
|
||||
* guild board over the bridge, the marketplace from player vendors, the atlas from real
|
||||
* spawners (PLAN.md §13 phase 9, D42). Seeding those would be inventing game state that
|
||||
* the product is supposed to be showing, which is exactly what D4 forbids.
|
||||
*/
|
||||
|
||||
import { readFileSync } from 'node:fs';
|
||||
|
||||
import platform from '../src/data/platform.json' with { type: 'json' };
|
||||
|
||||
const BASE = (process.env.RG_BASE || 'http://localhost:3000').replace(/\/+$/, '');
|
||||
const API = `${BASE}/api/v1`;
|
||||
const ADMIN_USER = process.env.RG_ADMIN_USER || 'demoadmin';
|
||||
const ADMIN_PASS = process.env.RG_ADMIN_PASS || 'DemoReview!2026';
|
||||
const DEMO_PASS = process.env.RG_DEMO_PASS || 'DemoReview!2026';
|
||||
const UOLINK_BASE = process.env.UOLINK_BASE || 'http://127.0.0.1:8080';
|
||||
const UOLINK_WS = process.env.UOLINK_WS || 'ws://127.0.0.1:8080/ws';
|
||||
const UOLINK_TOKEN = process.env.UOLINK_TOKEN || '';
|
||||
// The pinned wire protocol, read from `platform.json` rather than written down here.
|
||||
//
|
||||
// It was a literal `4` until the Asset Bridge cutover, with a note explaining that
|
||||
// `module-uo` pinned 3 on a fresh install while the sidecar spoke 4, so a new deployment
|
||||
// read nothing from its shard until somebody edited the number in Admin → Shard. That debt
|
||||
// has since been paid: the module's schema fragment defaults the column to the protocol its
|
||||
// build speaks and carries a one-shot migration per bump, so both a fresh install and an
|
||||
// upgraded one land on the right number by themselves.
|
||||
//
|
||||
// What remains is the rig's own reason to state it: this seed points a demo deployment at a
|
||||
// sidecar, and if it pins the wrong number every REST call comes back `409`. Reading it from
|
||||
// `platform.json` means the number is the one `checkFacts.mjs` verified against `link`'s
|
||||
// `main` — so the rig cannot quietly drift two protocols behind the platform again, which is
|
||||
// exactly what the literal did.
|
||||
const UOLINK_PROTOCOL = Number(process.env.UOLINK_PROTOCOL || platform.games.uo.protocol);
|
||||
|
||||
const DRY = process.argv.includes('--dry-run');
|
||||
|
||||
// ── The demo deployment's identity (D43) ───────────────────────────────────────────────
|
||||
//
|
||||
// A neutral demo brand rather than UOMysticmoon: the screenshots show the platform, not a
|
||||
// private shard, and §15's demo VM can wear the same identity so the imagery stays true the
|
||||
// day it exists. The name is deliberately "… Demo" rather than an invented community —
|
||||
// nobody should have to wonder whether they are looking at a real server they could join.
|
||||
// The published contact address lives in exactly one file in this repository (D13), and
|
||||
// `checkFacts.mjs` fails the build if a literal address appears anywhere else — including
|
||||
// here. So the demo wears the same address the site publishes, read from the same place.
|
||||
const brandDefault = JSON.parse(
|
||||
readFileSync(new URL('../brand-default/brand.json', import.meta.url), 'utf8'),
|
||||
);
|
||||
|
||||
const SETTINGS = {
|
||||
site_title: 'Runic Gateway Demo',
|
||||
site_mode: 'live',
|
||||
status_message: 'Live — the demo shard is up.',
|
||||
homepage_teaser:
|
||||
'A public demonstration of Runic Gateway: a self-hosted community site wired to a ' +
|
||||
'live game server. Everything on this site is real data from the shard behind it.',
|
||||
contact_email: brandDefault.contactEmail,
|
||||
};
|
||||
|
||||
// ── The cast ───────────────────────────────────────────────────────────────────────────
|
||||
//
|
||||
// Five accounts, one per role the admin screens distinguish, so a screenshot of the users
|
||||
// table shows the role column doing something. Names are ordinary fantasy given names and
|
||||
// belong to nobody.
|
||||
const USERS = [
|
||||
{ username: 'aldricmoss', role: 'moderator' },
|
||||
{ username: 'brannwen', role: 'editor' },
|
||||
{ username: 'sablequill', role: 'player' },
|
||||
{ username: 'tobinreed', role: 'player' },
|
||||
{ username: 'mirenavox', role: 'player' },
|
||||
];
|
||||
|
||||
// ── News, five-on-friday, the newsletter ───────────────────────────────────────────────
|
||||
//
|
||||
// Written as a small community's real output rather than lorem: a patch note, an event, a
|
||||
// maintenance notice and a Friday post. Bodies are short HTML because that is what the
|
||||
// editor stores, and the list screens show the excerpt anyway.
|
||||
const POSTS = [
|
||||
{
|
||||
category: 'news',
|
||||
title: 'Autumn patch: vendor search, and a fix for house decay',
|
||||
excerpt:
|
||||
'Player-vendor listings are now searchable from the site, and the decay timer no ' +
|
||||
'longer resets when a co-owner logs in.',
|
||||
body:
|
||||
'<p>The autumn patch is live. The headline change is that <strong>every player ' +
|
||||
'vendor on the shard is now searchable from this site</strong> — the marketplace ' +
|
||||
'page reads the same live feed the game does, so a listing appears within a minute ' +
|
||||
'of being priced.</p><p>We also fixed the house decay timer resetting when a ' +
|
||||
'co-owner logged in. That bug had been quietly keeping condemned houses alive since ' +
|
||||
'spring.</p><p>Full notes are on the wiki.</p>',
|
||||
published: true,
|
||||
},
|
||||
{
|
||||
category: 'news',
|
||||
title: 'The Harvest Moon festival opens this weekend',
|
||||
excerpt:
|
||||
'Three days of gatherings at the crossroads, with a champion spawn on the last ' +
|
||||
'night. Everyone is welcome, no signup needed.',
|
||||
body:
|
||||
'<p>The Harvest Moon festival runs from Friday evening to Sunday night at the ' +
|
||||
'crossroads north of town. There is no signup and no entry fee — turn up.</p>' +
|
||||
'<p>Saturday is the market day; bring anything you want to sell and we will set out ' +
|
||||
'extra vendor stalls. Sunday night closes with a champion spawn, which will be ' +
|
||||
'announced in game and on the shard status page here.</p>',
|
||||
published: true,
|
||||
},
|
||||
{
|
||||
category: 'news',
|
||||
title: 'Scheduled maintenance, Tuesday 03:00 UTC',
|
||||
excerpt:
|
||||
'About twenty minutes of downtime for a server restart and a world save. The site ' +
|
||||
'stays up throughout.',
|
||||
body:
|
||||
'<p>We are restarting the shard on Tuesday at 03:00 UTC for a world save and a ' +
|
||||
'server update. Expect about twenty minutes of downtime.</p><p>This site stays up ' +
|
||||
'while the shard is down — the status panel will simply show the shard as offline, ' +
|
||||
'and the marketplace and atlas will show their last known state.</p>',
|
||||
published: true,
|
||||
},
|
||||
{
|
||||
category: 'five-on-friday',
|
||||
title: 'Five on Friday: the ones who keep the roads clear',
|
||||
excerpt:
|
||||
'Five players who spent the week doing unglamorous work, and what they were up to.',
|
||||
body:
|
||||
'<p>Five people who made the week better for everybody else:</p><ol><li>Sable, for ' +
|
||||
'restocking the free reagent stall three times without being asked.</li><li>Tobin, ' +
|
||||
'for guiding two new players through their first dungeon.</li><li>Mirena, for the ' +
|
||||
'map corrections on the wiki.</li><li>Brannwen, for writing up the champion ' +
|
||||
'rotation.</li><li>Aldric, for handling a difficult report quietly and well.</li>' +
|
||||
'</ol>',
|
||||
published: true,
|
||||
},
|
||||
{
|
||||
category: 'newsletter',
|
||||
title: 'Monthly notes — what changed, and what is next',
|
||||
excerpt:
|
||||
'A month of changes in one place: the vendor search, the new guides, and what we ' +
|
||||
'are working on next.',
|
||||
body:
|
||||
'<p>A quiet, productive month. The vendor search shipped, the wiki gained four ' +
|
||||
'guides, and the guild boards now update on the site within a minute of a change in ' +
|
||||
'game.</p><p>Next month we are looking at the champion boards and at making the ' +
|
||||
'atlas easier to read on a phone.</p>',
|
||||
published: true,
|
||||
},
|
||||
];
|
||||
|
||||
// ── The wiki ───────────────────────────────────────────────────────────────────────────
|
||||
//
|
||||
// One category and four pages, because the wiki index screenshot needs a category with
|
||||
// enough in it to look like a wiki rather than a placeholder.
|
||||
const WIKI_CATEGORY = {
|
||||
slug: 'guides',
|
||||
title: 'Guides',
|
||||
description: 'How things work here, written by the people who play here.',
|
||||
};
|
||||
|
||||
const WIKI_PAGES = [
|
||||
{
|
||||
slug: 'getting-started',
|
||||
title: 'Getting started',
|
||||
excerpt: 'What to install, how to connect, and the first hour.',
|
||||
body:
|
||||
'<h2>Before you connect</h2><p>You need a game client and an account. Make the ' +
|
||||
'account on this site — the shard accepts accounts created here, and it saves you ' +
|
||||
'typing your password into a chat window.</p><h2>The first hour</h2><p>Start in ' +
|
||||
'town, take the newcomer quest, and do not sell your starting tools. If you get ' +
|
||||
'stuck, ask in Discord: somebody is usually around.</p>',
|
||||
},
|
||||
{
|
||||
slug: 'player-vendors',
|
||||
title: 'Player vendors',
|
||||
excerpt: 'How to hire one, how to price, and how the site search finds you.',
|
||||
body:
|
||||
'<h2>Hiring a vendor</h2><p>Any house you own or co-own can hold vendors. Hire one ' +
|
||||
'from an innkeeper and place it inside.</p><h2>Being findable</h2><p>Everything a ' +
|
||||
'vendor holds is published to the marketplace on this site within about a minute, ' +
|
||||
'including the price and the house it stands in. If a listing looks stale, the ' +
|
||||
'shard was probably down when you priced it — it will correct itself on the next ' +
|
||||
'sweep.</p>',
|
||||
},
|
||||
{
|
||||
slug: 'housing-and-decay',
|
||||
title: 'Housing and decay',
|
||||
excerpt: 'Placement rules, the decay timer, and what IDOC actually means here.',
|
||||
body:
|
||||
'<h2>Placement</h2><p>Houses can be placed anywhere the client allows, with the ' +
|
||||
'usual clearance rules. There is no lottery.</p><h2>Decay</h2><p>A house decays if ' +
|
||||
'nobody with access logs in for long enough. The site lists houses approaching ' +
|
||||
'collapse on the housing page, which is the same data the game uses — not a ' +
|
||||
'prediction.</p>',
|
||||
},
|
||||
{
|
||||
slug: 'community-rules',
|
||||
title: 'Community rules',
|
||||
excerpt: 'The short version: do not be the reason somebody stops playing.',
|
||||
body:
|
||||
'<h2>The rules</h2><ol><li>No harassment, in game or on the site.</li><li>No ' +
|
||||
'exploiting bugs — report them instead, and you will usually be thanked in ' +
|
||||
'public.</li><li>One account per person for events with prizes.</li></ol>' +
|
||||
'<h2>Appeals</h2><p>Every moderation action can be appealed from your account page. ' +
|
||||
'An appeal is read by somebody who was not involved in the original action.</p>',
|
||||
},
|
||||
];
|
||||
|
||||
// ── HTTP plumbing ──────────────────────────────────────────────────────────────────────
|
||||
//
|
||||
// One cookie jar, because the session is a cookie and `fetch` has no jar of its own. Only
|
||||
// the value of the auth cookie matters, so this keeps exactly that.
|
||||
|
||||
let cookie = '';
|
||||
let created = 0;
|
||||
let existed = 0;
|
||||
|
||||
function keepCookies(res) {
|
||||
const raw = res.headers.getSetCookie?.() ?? [];
|
||||
for (const line of raw) {
|
||||
const [pair] = line.split(';');
|
||||
if (pair.trim()) cookie = pair.trim();
|
||||
}
|
||||
}
|
||||
|
||||
async function call(method, path, body) {
|
||||
const res = await fetch(`${API}${path}`, {
|
||||
method,
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
...(cookie ? { Cookie: cookie } : {}),
|
||||
},
|
||||
...(body === undefined ? {} : { body: JSON.stringify(body) }),
|
||||
});
|
||||
keepCookies(res);
|
||||
const text = await res.text();
|
||||
let data = null;
|
||||
try {
|
||||
data = text ? JSON.parse(text) : null;
|
||||
} catch {
|
||||
data = text;
|
||||
}
|
||||
return { ok: res.ok, status: res.status, data };
|
||||
}
|
||||
|
||||
function say(mark, what) {
|
||||
console.log(` ${mark} ${what}`);
|
||||
if (mark === '+') created += 1;
|
||||
if (mark === '=') existed += 1;
|
||||
}
|
||||
|
||||
function fail(what, res) {
|
||||
console.error(`\n ! ${what} failed — HTTP ${res.status}`);
|
||||
console.error(` ${JSON.stringify(res.data)?.slice(0, 400)}`);
|
||||
process.exitCode = 1;
|
||||
}
|
||||
|
||||
// ── The steps ──────────────────────────────────────────────────────────────────────────
|
||||
|
||||
async function login() {
|
||||
const res = await call('POST', '/auth/login', { username: ADMIN_USER, password: ADMIN_PASS });
|
||||
if (!res.ok) {
|
||||
console.error(
|
||||
`\nCould not log in as "${ADMIN_USER}". Create the admin first, from the website repo:\n` +
|
||||
` cd website/server && DB_NAME=<demo db> ADMIN_USERNAME=${ADMIN_USER} ` +
|
||||
`ADMIN_PASSWORD='…' node db/seed.js\n`,
|
||||
);
|
||||
fail('login', res);
|
||||
process.exit(1);
|
||||
}
|
||||
console.log(`\nsigned in as ${ADMIN_USER} at ${BASE}`);
|
||||
}
|
||||
|
||||
async function settings() {
|
||||
console.log('\nsite settings (D43 — the neutral demo identity)');
|
||||
if (DRY) {
|
||||
for (const [k, v] of Object.entries(SETTINGS)) say('~', `${k} = ${v}`);
|
||||
return;
|
||||
}
|
||||
const res = await call('PUT', '/admin/settings', SETTINGS);
|
||||
if (!res.ok) return fail('settings', res);
|
||||
for (const [k, v] of Object.entries(SETTINGS)) say('+', `${k} = ${String(v).slice(0, 60)}`);
|
||||
}
|
||||
|
||||
async function uoLink() {
|
||||
console.log('\nshard connection (Admin → Shard)');
|
||||
if (!UOLINK_TOKEN) {
|
||||
say('~', 'UOLINK_TOKEN unset — leaving the sidecar config alone');
|
||||
return;
|
||||
}
|
||||
const now = await call('GET', '/admin/uo-link/config');
|
||||
if (now.status === 404) {
|
||||
say('~', 'no /admin/uo-link route — the uo module is not installed');
|
||||
return;
|
||||
}
|
||||
if (
|
||||
now.ok &&
|
||||
now.data?.config?.baseUrl === UOLINK_BASE &&
|
||||
now.data?.config?.protocol === UOLINK_PROTOCOL &&
|
||||
now.data?.config?.enabled
|
||||
) {
|
||||
say('=', `already pointed at ${UOLINK_BASE} (protocol ${UOLINK_PROTOCOL})`);
|
||||
return;
|
||||
}
|
||||
if (DRY) return say('~', `would point the site at ${UOLINK_BASE}`);
|
||||
const res = await call('PUT', '/admin/uo-link/config', {
|
||||
baseUrl: UOLINK_BASE,
|
||||
wsUrl: UOLINK_WS,
|
||||
token: UOLINK_TOKEN,
|
||||
protocol: UOLINK_PROTOCOL,
|
||||
enabled: true,
|
||||
});
|
||||
if (!res.ok) return fail('uo-link config', res);
|
||||
say('+', `pointed at ${UOLINK_BASE} (protocol ${UOLINK_PROTOCOL})`);
|
||||
}
|
||||
|
||||
async function users() {
|
||||
console.log('\naccounts');
|
||||
const list = await call('GET', '/admin/users');
|
||||
if (!list.ok) return fail('list users', list);
|
||||
const rows = Array.isArray(list.data) ? list.data : (list.data?.users ?? []);
|
||||
const have = new Set(rows.map((u) => u.username));
|
||||
for (const user of USERS) {
|
||||
if (have.has(user.username)) {
|
||||
say('=', `${user.username} (${user.role})`);
|
||||
continue;
|
||||
}
|
||||
if (DRY) {
|
||||
say('~', `${user.username} (${user.role})`);
|
||||
continue;
|
||||
}
|
||||
const res = await call('POST', '/admin/users', {
|
||||
username: user.username,
|
||||
password: DEMO_PASS,
|
||||
role: user.role,
|
||||
});
|
||||
if (!res.ok) {
|
||||
fail(`create ${user.username}`, res);
|
||||
continue;
|
||||
}
|
||||
say('+', `${user.username} (${user.role})`);
|
||||
}
|
||||
}
|
||||
|
||||
async function posts() {
|
||||
console.log('\nposts');
|
||||
const list = await call('GET', '/admin/posts');
|
||||
if (!list.ok) return fail('list posts', list);
|
||||
const rows = Array.isArray(list.data) ? list.data : (list.data?.posts ?? []);
|
||||
const have = new Set(rows.map((p) => p.title));
|
||||
for (const post of POSTS) {
|
||||
if (have.has(post.title)) {
|
||||
say('=', `${post.category}: ${post.title}`);
|
||||
continue;
|
||||
}
|
||||
if (DRY) {
|
||||
say('~', `${post.category}: ${post.title}`);
|
||||
continue;
|
||||
}
|
||||
const res = await call('POST', '/admin/posts', post);
|
||||
if (!res.ok) {
|
||||
fail(`create post "${post.title}"`, res);
|
||||
continue;
|
||||
}
|
||||
say('+', `${post.category}: ${post.title}`);
|
||||
}
|
||||
}
|
||||
|
||||
async function wiki() {
|
||||
console.log('\nwiki');
|
||||
const cats = await call('GET', '/admin/wiki/categories');
|
||||
if (!cats.ok) return fail('list wiki categories', cats);
|
||||
const catRows = Array.isArray(cats.data) ? cats.data : (cats.data?.categories ?? []);
|
||||
let category = catRows.find((c) => c.slug === WIKI_CATEGORY.slug);
|
||||
if (category) {
|
||||
say('=', `category ${WIKI_CATEGORY.slug}`);
|
||||
} else if (DRY) {
|
||||
say('~', `category ${WIKI_CATEGORY.slug}`);
|
||||
} else {
|
||||
const res = await call('POST', '/admin/wiki/categories', WIKI_CATEGORY);
|
||||
if (!res.ok) return fail('create wiki category', res);
|
||||
category = res.data?.category ?? res.data;
|
||||
say('+', `category ${WIKI_CATEGORY.slug}`);
|
||||
}
|
||||
|
||||
const pages = await call('GET', '/admin/wiki');
|
||||
if (!pages.ok) return fail('list wiki pages', pages);
|
||||
const pageRows = Array.isArray(pages.data) ? pages.data : (pages.data?.pages ?? []);
|
||||
const have = new Set(pageRows.map((p) => p.slug));
|
||||
for (const page of WIKI_PAGES) {
|
||||
if (have.has(page.slug)) {
|
||||
say('=', `page ${page.slug}`);
|
||||
continue;
|
||||
}
|
||||
if (DRY) {
|
||||
say('~', `page ${page.slug}`);
|
||||
continue;
|
||||
}
|
||||
const res = await call('POST', '/admin/wiki', {
|
||||
...page,
|
||||
category_id: category?.id ?? null,
|
||||
published: true,
|
||||
});
|
||||
if (!res.ok) {
|
||||
fail(`create wiki page "${page.slug}"`, res);
|
||||
continue;
|
||||
}
|
||||
say('+', `page ${page.slug}`);
|
||||
}
|
||||
}
|
||||
|
||||
// ── main ───────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
console.log(DRY ? '\nseedDemo — DRY RUN, nothing will be written' : '\nseedDemo');
|
||||
|
||||
await login();
|
||||
await settings();
|
||||
await uoLink();
|
||||
await users();
|
||||
await posts();
|
||||
await wiki();
|
||||
|
||||
console.log(
|
||||
`\n${DRY ? 'would create' : 'created'} ${created}, already present ${existed}` +
|
||||
(process.exitCode ? ' — with failures above' : ''),
|
||||
);
|
||||
console.log(
|
||||
'\nWhat this does NOT seed, on purpose: teams, the marketplace, houses, points boards\n' +
|
||||
'and the atlas. Those arrive from the shard over the bridge (D42) — start the sidecar\n' +
|
||||
'and the shard, and they populate themselves.\n',
|
||||
);
|
||||
204
scripts/serve.mjs
Normal file
@@ -0,0 +1,204 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* serve.mjs — the production entry point (PLAN.md §6, D48, D56).
|
||||
*
|
||||
* `npm start` runs `applyBrand.mjs` and then this, instead of `dist/server/entry.mjs`
|
||||
* directly. It is a thin wrapper around the adapter's own handler and exists for three
|
||||
* reasons, two of them things `@astrojs/node` gets wrong.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* 1. THE ADAPTER SERVES THE WRONG PAGE'S CONTENT-SECURITY-POLICY
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* `@astrojs/node`'s `staticHeaders` writes one policy per prerendered route into
|
||||
* `dist/_headers.json` and looks the right one up per request. The lookup, in
|
||||
* `dist/serve-static.js`, is:
|
||||
*
|
||||
* headersMap.find((header) => header.pathname.includes(baselessPathname))
|
||||
*
|
||||
* `String.includes` — a SUBSTRING test, not equality, taking the first match. So:
|
||||
*
|
||||
* - `/modules/` matches the record for `/docs/modules/building-a-module`,
|
||||
* - `/architecture/` matches `/docs/architecture/...`,
|
||||
* - and `/`, which is a substring of every path in the file, matches whichever record
|
||||
* happens to be first — here `/404`.
|
||||
*
|
||||
* Every prerendered page was therefore served some other page's policy. Because the
|
||||
* policies are per-page hash lists, that is not a cosmetic mismatch: the browser refused
|
||||
* the page's own stylesheet. `/modules/` and `/architecture/` rendered unstyled sections
|
||||
* with `Refused to apply inline style` in a console, and the homepage only looked fine
|
||||
* because it happens to share a hash with the 404 page.
|
||||
*
|
||||
* Astro's static-header machinery is otherwise exactly what §6 wants, so this replaces the
|
||||
* lookup rather than the mechanism: the same `_headers.json`, matched by pathname
|
||||
* EQUALITY. The workaround is deliberately small and obvious so it can be deleted whole
|
||||
* when the upstream `find` is fixed — the check for that is whether `/modules/` and
|
||||
* `/docs/modules/building-a-module` are served different policies.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* 2. THE HEADERS THAT ARE NOT CSP
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* A few security headers have nothing to do with Astro and no other place to live. They
|
||||
* are set here rather than written into an operator's reverse-proxy configuration (D48,
|
||||
* again): the container should be correct on its own, and a proxy someone else configures
|
||||
* is a promise this repository cannot check.
|
||||
*
|
||||
* The two routes that render per request — `/beta` and `/brand/*` — have no entry in
|
||||
* `_headers.json`, because nothing prerendered them. They get `frame-ancestors 'none'` on
|
||||
* its own, which is the one directive a `<meta>` CSP cannot express and therefore the one
|
||||
* thing Astro's per-page meta tag leaves them missing.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import http from 'node:http';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath, pathToFileURL } from 'node:url';
|
||||
|
||||
const here = path.dirname(fileURLToPath(import.meta.url));
|
||||
const root = path.join(here, '..');
|
||||
|
||||
const port = Number(process.env.PORT ?? 4321);
|
||||
const host = process.env.HOST ?? '0.0.0.0';
|
||||
|
||||
/* ---------------------------------------------------------------------------------------
|
||||
The policies, matched exactly
|
||||
--------------------------------------------------------------------------------------- */
|
||||
|
||||
const normalise = (pathname) => {
|
||||
const clean = pathname.split('?')[0].split('#')[0];
|
||||
const trimmed = clean.replace(/\/+$/, '');
|
||||
return trimmed === '' ? '/' : trimmed;
|
||||
};
|
||||
|
||||
const policies = new Map();
|
||||
const headersFile = path.join(root, 'dist', '_headers.json');
|
||||
|
||||
if (fs.existsSync(headersFile)) {
|
||||
for (const record of Object.values(JSON.parse(fs.readFileSync(headersFile, 'utf8')))) {
|
||||
const csp = record.headers?.find((h) => h.key.toLowerCase() === 'content-security-policy');
|
||||
if (csp) policies.set(normalise(record.pathname), csp.value);
|
||||
}
|
||||
} else {
|
||||
// Not fatal: the site still serves, with the per-page <meta> policy Astro also emits.
|
||||
// Loud, because a deployment silently losing its response-header CSP is exactly what §6
|
||||
// is trying to prevent.
|
||||
console.error(
|
||||
'[serve] dist/_headers.json is missing — pages will be served without a CSP response\n' +
|
||||
' header. Check that astro.config.mjs still sets `staticHeaders: true`.'
|
||||
);
|
||||
}
|
||||
|
||||
const FRAME_ONLY = "frame-ancestors 'none'";
|
||||
|
||||
/**
|
||||
* Headers with no page-by-page component. Each is the browser default made explicit, and
|
||||
* each closes something the CSP does not:
|
||||
*
|
||||
* - `X-Content-Type-Options` stops a browser guessing that a .txt is HTML.
|
||||
* - `Referrer-Policy` keeps the path of the page a reader came from out of requests to
|
||||
* other origins — there are none today (D9), and this is what keeps that true if a
|
||||
* link is ever followed off-site.
|
||||
* - `X-Frame-Options` says again, for anything too old to honour `frame-ancestors`.
|
||||
* - `Permissions-Policy` turns off hardware this site has no reason to ask for. A
|
||||
* marketing page requesting a camera should be impossible, not merely unlikely.
|
||||
*/
|
||||
const STATIC_HEADERS = {
|
||||
'X-Content-Type-Options': 'nosniff',
|
||||
'Referrer-Policy': 'strict-origin-when-cross-origin',
|
||||
'X-Frame-Options': 'DENY',
|
||||
'Permissions-Policy': 'camera=(), microphone=(), geolocation=(), payment=(), usb=()',
|
||||
};
|
||||
|
||||
/* ---------------------------------------------------------------------------------------
|
||||
The server
|
||||
--------------------------------------------------------------------------------------- */
|
||||
|
||||
// The adapter's entry starts its own listener on import unless this is set.
|
||||
process.env.ASTRO_NODE_AUTOSTART = 'disabled';
|
||||
|
||||
// `pathToFileURL`, not the bare path: on Windows an absolute path starts with a drive
|
||||
// letter, and Node's ESM loader reads `c:` as an unsupported URL scheme.
|
||||
const { handler } = await import(pathToFileURL(path.join(root, 'dist', 'server', 'entry.mjs')).href);
|
||||
|
||||
/* ---------------------------------------------------------------------------------------
|
||||
3. THE FORWARDED HEADERS THE ADAPTER DOES NOT READ
|
||||
--------------------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Make the request look, to the adapter, like what the browser actually sent.
|
||||
*
|
||||
* `@astrojs/node` builds the URL of every request from the connection and the `Host`
|
||||
* header alone — `astro/app/node`'s `createRequestFromNodeRequest`:
|
||||
*
|
||||
* const isEncrypted = "encrypted" in req.socket && req.socket.encrypted;
|
||||
* const protocol = isEncrypted ? "https" : "http";
|
||||
*
|
||||
* `x-forwarded-proto` is never consulted on this path. (`security.allowedDomains` does not
|
||||
* help: on this code path it gates only whether `Astro.clientAddress` may come from
|
||||
* `x-forwarded-for`.)
|
||||
*
|
||||
* Behind a proxy that terminates TLS — which is how this site is deployed, and the only
|
||||
* way it is deployed — that is fatal to the one route that accepts a POST. The browser
|
||||
* sends `Origin: https://runicgateway.com`; the container computes `http://runicgateway.com`
|
||||
* because its own socket is plaintext; and Astro's CSRF middleware compares the two for
|
||||
* EQUALITY:
|
||||
*
|
||||
* const isSameOrigin = request.headers.get("origin") === url.origin;
|
||||
*
|
||||
* So every beta signup, from every visitor, is answered `403 Cross-site POST form
|
||||
* submissions are forbidden`. No proxy configuration can fix it — a proxy cannot make this
|
||||
* container's socket encrypted — and nothing else on the site changes, so the symptom is a
|
||||
* form that silently refuses everyone while fifty pages look perfectly healthy.
|
||||
*
|
||||
* Both headers are trusted unconditionally, with no flag to set. The image is meant to be
|
||||
* deployed and work: it publishes on loopback for a proxy to reach, and an operator who has
|
||||
* to discover a `TRUST_PROXY` variable to make the signup work is an operator who ships a
|
||||
* dead form. Trusting them costs nothing here — a cross-site form submission cannot make a
|
||||
* victim's browser send `x-forwarded-proto`, so the CSRF check is exactly as strong as it
|
||||
* was, and the site has no cookie, session or credential to protect in the first place.
|
||||
*
|
||||
* `x-forwarded-host` is handled for the same reason at one remove: most proxies pass `Host`
|
||||
* through untouched, but some rewrite it to the upstream address and put the real name here
|
||||
* instead, which produces the identical mismatch.
|
||||
*/
|
||||
const firstForwarded = (value) => value?.toString().split(',')[0].trim();
|
||||
|
||||
const applyForwardedHeaders = (req) => {
|
||||
const proto = firstForwarded(req.headers['x-forwarded-proto']);
|
||||
if (proto === 'https' && !req.socket.encrypted) {
|
||||
// What `"encrypted" in req.socket` reads. Defined on the socket rather than passed
|
||||
// along, because the adapter is given the raw request and looks there itself.
|
||||
Object.defineProperty(req.socket, 'encrypted', { value: true, configurable: true });
|
||||
}
|
||||
|
||||
const forwardedHost = firstForwarded(req.headers['x-forwarded-host']);
|
||||
if (forwardedHost && !/[/\\]/.test(forwardedHost)) {
|
||||
req.headers.host = forwardedHost;
|
||||
}
|
||||
};
|
||||
|
||||
const server = http.createServer((req, res) => {
|
||||
applyForwardedHeaders(req);
|
||||
|
||||
const policy = policies.get(normalise(req.url ?? '/'));
|
||||
|
||||
for (const [key, value] of Object.entries(STATIC_HEADERS)) res.setHeader(key, value);
|
||||
res.setHeader('Content-Security-Policy', policy ?? FRAME_ONLY);
|
||||
|
||||
/**
|
||||
* The adapter will set its own (wrong) `Content-Security-Policy` from inside the static
|
||||
* handler, overwriting what was just set. Rather than race it, every later attempt to
|
||||
* set that one header is ignored — the correct value is already on the response, and
|
||||
* this request's policy cannot change halfway through serving it.
|
||||
*/
|
||||
const setHeader = res.setHeader.bind(res);
|
||||
res.setHeader = (name, value) => {
|
||||
if (String(name).toLowerCase() === 'content-security-policy') return res;
|
||||
return setHeader(name, value);
|
||||
};
|
||||
|
||||
handler(req, res);
|
||||
});
|
||||
|
||||
server.listen(port, host, () => {
|
||||
console.log(`[serve] listening on http://${host}:${port} — ${policies.size} prerendered policies`);
|
||||
});
|
||||
53
src/components/DocsPageTitle.astro
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
/**
|
||||
* Overrides Starlight's `PageTitle` for one attribute: `tabindex="-1"` on the heading.
|
||||
*
|
||||
* Phase 10 found and fixed this on the marketing chrome — following a skip link moves the
|
||||
* viewport but not the keyboard focus, because the target of the link is not focusable.
|
||||
* Chrome papers over it; not every browser does, and a reader who lands past the header
|
||||
* only to find Tab returning them to the top of the nav has not been skipped anywhere.
|
||||
* `Base.astro`'s `<main>` gained `tabindex="-1"` then.
|
||||
*
|
||||
* Phase 11's browser walk found the same defect still standing on the other forty pages.
|
||||
* Starlight's skip link points at the page's `<h1>` rather than at a landmark, and an
|
||||
* `<h1>` is no more focusable than a `<main>`, so the docs half of the site had the fix
|
||||
* that the marketing half had.
|
||||
*
|
||||
* The rest of this file is Starlight's own implementation, copied because the override
|
||||
* mechanism replaces a component rather than decorating it. That is a small drift risk —
|
||||
* if Starlight restyles its `h1`, this copy will not follow — so it is deliberately kept
|
||||
* to exactly what upstream has, with nothing of ours added beyond the attribute. The
|
||||
* check for drift is visual: a documentation title that stops matching the marketing
|
||||
* chrome's.
|
||||
*
|
||||
* The id is Starlight's `PAGE_TITLE_ID`, written out rather than imported: `./constants`
|
||||
* is not one of the subpaths the package exports, so importing it reaches past the
|
||||
* package's own boundary. It is what `SkipLink.astro` puts in its `href`, so the two must
|
||||
* agree; if a Starlight upgrade ever renames it, the skip link stops resolving at all and
|
||||
* the first Tab on a documentation page lands somewhere obviously wrong.
|
||||
*/
|
||||
const PAGE_TITLE_ID = '_top';
|
||||
---
|
||||
|
||||
<h1 id={PAGE_TITLE_ID} tabindex="-1">{Astro.locals.starlightRoute.entry.data.title}</h1>
|
||||
|
||||
<style>
|
||||
@layer starlight.core {
|
||||
h1 {
|
||||
margin-top: 1rem;
|
||||
font-size: var(--sl-text-h1);
|
||||
line-height: var(--sl-line-height-headings);
|
||||
font-weight: 600;
|
||||
color: var(--sl-color-white);
|
||||
}
|
||||
|
||||
/* Ours, and the only line that is: the heading is focusable now, so it can be
|
||||
focused, and a focus ring drawn around a page title reads as an error rather than
|
||||
as a destination. Removing it is safe only because this element is reachable by
|
||||
exactly one route — the skip link, which the reader took deliberately. It is never
|
||||
in the tab sequence. */
|
||||
h1:focus {
|
||||
outline: none;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
import { brand } from '../lib/brand.mjs';
|
||||
import { renderBrand } from '../lib/brand.mjs';
|
||||
import { legal } from '../data/legal.mjs';
|
||||
import { footerColumns } from '../data/footer.mjs';
|
||||
import platform from '../data/platform.json';
|
||||
|
||||
/**
|
||||
@@ -13,35 +14,15 @@ import platform from '../data/platform.json';
|
||||
* reader browses to alongside Features, it is a thing they go looking for, and the line
|
||||
* that already carries the licence and the copyright is where people look.
|
||||
*/
|
||||
// `/beta` renders per request, so the footer it gets must read the mount rather than the
|
||||
// value baked at build time. See `renderBrand` in src/lib/brand.mjs (phase 11).
|
||||
const brand = renderBrand(Astro);
|
||||
|
||||
const year = new Date().getFullYear();
|
||||
|
||||
const columns = [
|
||||
{
|
||||
heading: 'Product',
|
||||
links: [
|
||||
{ href: '/features/', label: 'Features' },
|
||||
{ href: '/architecture/', label: 'Architecture' },
|
||||
{ href: '/modules/', label: 'Modules' },
|
||||
{ href: '/app/', label: 'Android app' },
|
||||
],
|
||||
},
|
||||
{
|
||||
heading: 'Documentation',
|
||||
links: [
|
||||
{ href: '/docs/', label: 'Getting started' },
|
||||
{ href: '/docs/', label: 'Administration' },
|
||||
{ href: '/docs/', label: 'Building a module' },
|
||||
],
|
||||
},
|
||||
{
|
||||
heading: 'Project',
|
||||
links: [
|
||||
{ href: brand.giteaOrg, label: 'Source' },
|
||||
{ href: brand.discordInvite, label: 'Discord' },
|
||||
{ href: '/community/', label: 'Community' },
|
||||
],
|
||||
},
|
||||
];
|
||||
// The columns live in src/data/footer.mjs so a test can read them — see the note there,
|
||||
// and test/footer.test.mjs. The two Project links come from the mounted brand (§7).
|
||||
const columns = footerColumns(brand);
|
||||
|
||||
const isExternal = (href: string) => href.startsWith('http');
|
||||
---
|
||||
@@ -81,8 +62,9 @@ const isExternal = (href: string) => href.startsWith('http');
|
||||
</span>
|
||||
</p>
|
||||
<p class="site-footer__meta">
|
||||
<span class="chip chip--version">Protocol {platform.protocol}</span>
|
||||
<span class="chip chip--version">Bundle {platform.bundle.tag}</span>
|
||||
{/* D66, as on the hero: the shared version only. Each game's protocol and bundle
|
||||
are on that game's pages. */}
|
||||
<span class="chip chip--version">Module API {platform.moduleApi}</span>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
37
src/components/GameExample.astro
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
import platform from '../data/platform.json';
|
||||
|
||||
/**
|
||||
* A worked example that belongs to one game, quoted on a core page (PLAN.md §16, D68).
|
||||
*
|
||||
* D63 keeps a game's vocabulary inside that game's section, but a core page sometimes needs a
|
||||
* real example rather than an invented one: a module manifest, an event dimension, the flag
|
||||
* that tells the installer which game it is setting up. §1 prefers the real thing, because an
|
||||
* invented example is checked by nothing and goes stale without anybody noticing.
|
||||
*
|
||||
* So the example keeps its game's words and says whose they are. This prints the game's name
|
||||
* above the block — the same bargain D67 strikes for a screenshot: a game's words are honest
|
||||
* on a core page when the game is named right beside them. `scripts/checkTerms.mjs` reads the
|
||||
* `game` attribute and allows that game's words, and only that game's, between the tags.
|
||||
*
|
||||
* The name comes from `platform.json` rather than from the caller, so the label cannot say
|
||||
* one game while the attribute that the check reads says another.
|
||||
*/
|
||||
interface Props {
|
||||
/** A key of `platform.json`'s `games`: `uo` or `rust`. */
|
||||
game: keyof typeof platform.games;
|
||||
}
|
||||
|
||||
const { game } = Astro.props;
|
||||
const entry = platform.games[game];
|
||||
if (!entry) {
|
||||
throw new Error(
|
||||
`GameExample: unknown game "${game}". Use a key of platform.json's games: ${Object.keys(platform.games).join(', ')}.`,
|
||||
);
|
||||
}
|
||||
---
|
||||
|
||||
<figure class="game-example" data-game={game}>
|
||||
<figcaption class="game-example__label">{entry.name}</figcaption>
|
||||
<div class="game-example__body"><slot /></div>
|
||||
</figure>
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
import { brand } from '../lib/brand.mjs';
|
||||
import Search from './Search.astro';
|
||||
import { renderBrand } from '../lib/brand.mjs';
|
||||
|
||||
/**
|
||||
* The marketing header. The docs get Starlight's own header, themed to match in
|
||||
@@ -20,6 +21,10 @@ import { brand } from '../lib/brand.mjs';
|
||||
*/
|
||||
const { pathname } = Astro.url;
|
||||
|
||||
// `/beta` renders per request, so the lockup name it gets must read the mount rather than
|
||||
// the value baked at build time. See `renderBrand` in src/lib/brand.mjs (phase 11).
|
||||
const brand = renderBrand(Astro);
|
||||
|
||||
const links = [
|
||||
{ href: '/features/', label: 'Features' },
|
||||
{ href: '/docs/', label: 'Docs' },
|
||||
@@ -55,6 +60,8 @@ const isCurrent = (href: string) =>
|
||||
))
|
||||
}
|
||||
</nav>
|
||||
|
||||
<Search />
|
||||
</div>
|
||||
</header>
|
||||
|
||||
|
||||
81
src/components/Screenshot.astro
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
import { screenById, WEB, PHONE } from '../data/screens.mjs';
|
||||
|
||||
/**
|
||||
* One screenshot, as a figure with its caption. PLAN.md §13 phase 9, D4 / D44.
|
||||
*
|
||||
* -----------------------------------------------------------------------------------------
|
||||
* WHY THE PAGE PASSES AN ID AND NOTHING ELSE
|
||||
* -----------------------------------------------------------------------------------------
|
||||
* A marketing page and a documentation page show the same administration screen for
|
||||
* different reasons, and the thing they must not do is describe it differently. The alt
|
||||
* text and the caption therefore live with the capture in `screens.mjs`, next to the route
|
||||
* they came from, and a page asks for `admin-shard` rather than restating what is in it.
|
||||
*
|
||||
* It also means a re-capture cannot silently invalidate a caption: the sentence and the
|
||||
* frame it describes are edited in the same file.
|
||||
*
|
||||
* -----------------------------------------------------------------------------------------
|
||||
* WHY IT FAILS THE BUILD ON AN UNKNOWN ID
|
||||
* -----------------------------------------------------------------------------------------
|
||||
* The alternative is a page that renders a broken image, which looks like a deployment
|
||||
* problem rather than a typo and survives review. `checkScreens.mjs` covers the other
|
||||
* direction — a declared screen whose file is missing — so between them a screenshot is
|
||||
* either complete or the build stops.
|
||||
*/
|
||||
interface Props {
|
||||
/** An `id` from `src/data/screens.mjs`. */
|
||||
id: string;
|
||||
/** Suppress the caption where the surrounding prose already says it. */
|
||||
bare?: boolean;
|
||||
}
|
||||
|
||||
const { id, bare = false } = Astro.props;
|
||||
|
||||
const shot = screenById(id);
|
||||
|
||||
if (!shot) {
|
||||
throw new Error(`Screenshot "${id}" is not declared in src/data/screens.mjs`);
|
||||
}
|
||||
|
||||
const src = `/screens/${shot.id}.webp`;
|
||||
|
||||
// Intrinsic size comes from the family rather than the entry: every capture in a family is
|
||||
// taken at one geometry (see screens.mjs), and `checkScreens.mjs` asserts the files really
|
||||
// are that size, so these attributes cannot drift from the pixels.
|
||||
const { width, height } = shot.family === 'web' ? WEB : PHONE;
|
||||
---
|
||||
|
||||
<figure class="shot">
|
||||
<img
|
||||
src={src}
|
||||
alt={shot.alt}
|
||||
width={width}
|
||||
height={height}
|
||||
loading="lazy"
|
||||
decoding="async"
|
||||
/>
|
||||
{!bare && <figcaption>{shot.caption}</figcaption>}
|
||||
</figure>
|
||||
|
||||
<style>
|
||||
.shot {
|
||||
margin: 2rem 0;
|
||||
}
|
||||
|
||||
.shot img {
|
||||
display: block;
|
||||
width: 100%;
|
||||
height: auto;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: var(--radius-card);
|
||||
box-shadow: var(--shadow-card);
|
||||
}
|
||||
|
||||
.shot figcaption {
|
||||
margin: 0.85rem 0 0;
|
||||
color: var(--dim);
|
||||
font-size: 0.9rem;
|
||||
line-height: 1.5;
|
||||
}
|
||||
</style>
|
||||
279
src/components/Search.astro
Normal file
@@ -0,0 +1,279 @@
|
||||
---
|
||||
/**
|
||||
* Site search for the marketing pages (D47).
|
||||
*
|
||||
* The documentation has had search since phase 1 — Starlight builds a Pagefind index at the
|
||||
* end of every build and puts a box in its own header. The marketing pages were outside it
|
||||
* twice over: not indexed, so a reader searching "Teams" in the docs found the architecture
|
||||
* page and never the feature page; and with no box, so a reader who arrived on the homepage
|
||||
* had a four-item nav and no way to ask a question.
|
||||
*
|
||||
* D47 closed both. `Base.astro` marks its `<main>` as a Pagefind body, which puts the ten
|
||||
* marketing pages in the same index the docs already query, and this is the box.
|
||||
*
|
||||
* ── Why it is built this way ────────────────────────────────────────────────
|
||||
* The marketing pages ship almost no JavaScript, and Pagefind's own UI bundle is 120 kB
|
||||
* before the index and the WASM. Loading that on a homepage so that some visitors can
|
||||
* search would be a poor trade, so **nothing is fetched until the dialog is opened** —
|
||||
* the button is inert markup, and the first open injects the stylesheet and the script.
|
||||
* Opening search a second time costs nothing more.
|
||||
*
|
||||
* `<dialog>` rather than a hand-built overlay: the browser gives us the focus trap, the
|
||||
* inert background, Escape-to-close and the top layer for free, and every one of those is
|
||||
* a thing an accessibility pass would otherwise have to find missing.
|
||||
*
|
||||
* In `astro dev` there is no `/pagefind/` — the index is written by the build. Rather than
|
||||
* fail silently, the dialog says so.
|
||||
*/
|
||||
---
|
||||
|
||||
<div class="site-search">
|
||||
<button type="button" class="site-search__open" data-search-open aria-haspopup="dialog">
|
||||
<svg aria-hidden="true" focusable="false" viewBox="0 0 20 20" width="16" height="16">
|
||||
<circle cx="9" cy="9" r="6" fill="none" stroke="currentColor" stroke-width="2"></circle>
|
||||
<line x1="13.5" y1="13.5" x2="18" y2="18" stroke="currentColor" stroke-width="2" stroke-linecap="round"></line>
|
||||
</svg>
|
||||
<span>Search</span>
|
||||
<kbd aria-hidden="true">/</kbd>
|
||||
</button>
|
||||
|
||||
<dialog class="site-search__dialog" data-search-dialog aria-label="Search this site">
|
||||
<div class="site-search__panel">
|
||||
<div class="site-search__head">
|
||||
<h2 class="site-search__title">Search</h2>
|
||||
<button type="button" class="site-search__close" data-search-close>Close</button>
|
||||
</div>
|
||||
<div data-search-mount></div>
|
||||
<p class="site-search__note" data-search-note hidden>
|
||||
Search is built with the site, so it is not available in the dev server. Run
|
||||
<code>npm run build && npm start</code> to try it.
|
||||
</p>
|
||||
</div>
|
||||
</dialog>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
const dialog = document.querySelector<HTMLDialogElement>('[data-search-dialog]');
|
||||
const mount = document.querySelector<HTMLElement>('[data-search-mount]');
|
||||
const note = document.querySelector<HTMLElement>('[data-search-note]');
|
||||
|
||||
if (dialog && mount) {
|
||||
let loaded: Promise<void> | null = null;
|
||||
|
||||
/**
|
||||
* Pagefind's UI bundle is an IIFE that hangs `PagefindUI` off `window`, so it is a
|
||||
* `<script src>` and not a dynamic `import()`. Both are covered by `script-src 'self'`
|
||||
* (D48); the WASM the index needs is why that directive also carries
|
||||
* `'wasm-unsafe-eval'`.
|
||||
*/
|
||||
const load = () =>
|
||||
(loaded ??= new Promise<void>((resolve, reject) => {
|
||||
const css = document.createElement('link');
|
||||
css.rel = 'stylesheet';
|
||||
css.href = '/pagefind/pagefind-ui.css';
|
||||
document.head.append(css);
|
||||
|
||||
const js = document.createElement('script');
|
||||
js.src = '/pagefind/pagefind-ui.js';
|
||||
js.onload = () => {
|
||||
new (window as any).PagefindUI({
|
||||
element: mount,
|
||||
showSubResults: true,
|
||||
showImages: false,
|
||||
// `resetStyles: false` was tried and is wrong here. Pagefind's reset is what
|
||||
// styles its own input and buttons; without it they fall back to user-agent
|
||||
// defaults, which on this ground meant black text typed into a dark field and
|
||||
// a Clear button with a 1990s `outset` border. The palette is bound to our
|
||||
// tokens below instead, which is the supported way round.
|
||||
translations: {
|
||||
placeholder: 'Search the site and documentation',
|
||||
zero_results: 'Nothing found for [SEARCH_TERM]',
|
||||
},
|
||||
});
|
||||
resolve();
|
||||
};
|
||||
js.onerror = () => reject(new Error('pagefind-ui.js did not load'));
|
||||
document.head.append(js);
|
||||
}).catch((error) => {
|
||||
// A dev server, or a build served without its index. Say which.
|
||||
if (note) note.hidden = false;
|
||||
loaded = null;
|
||||
throw error;
|
||||
}));
|
||||
|
||||
const open = () => {
|
||||
// Deliberately not awaited: the dialog should appear at once and fill in, rather
|
||||
// than the button seeming dead for as long as the bundle takes.
|
||||
load().catch(() => {});
|
||||
if (!dialog.open) dialog.showModal();
|
||||
window.setTimeout(() => {
|
||||
dialog.querySelector<HTMLInputElement>('input[type="text"]')?.focus();
|
||||
}, 50);
|
||||
};
|
||||
|
||||
document
|
||||
.querySelectorAll<HTMLButtonElement>('[data-search-open]')
|
||||
.forEach((button) => button.addEventListener('click', open));
|
||||
|
||||
document
|
||||
.querySelectorAll<HTMLButtonElement>('[data-search-close]')
|
||||
.forEach((button) => button.addEventListener('click', () => dialog.close()));
|
||||
|
||||
// Clicking the backdrop closes it. `<dialog>` reports backdrop clicks as clicks on the
|
||||
// dialog itself, so the test is whether the click landed outside the panel's box.
|
||||
dialog.addEventListener('click', (event) => {
|
||||
if (event.target !== dialog) return;
|
||||
const box = dialog.getBoundingClientRect();
|
||||
const outside =
|
||||
event.clientX < box.left ||
|
||||
event.clientX > box.right ||
|
||||
event.clientY < box.top ||
|
||||
event.clientY > box.bottom;
|
||||
if (outside) dialog.close();
|
||||
});
|
||||
|
||||
/**
|
||||
* `/` and Ctrl/⌘-K, the two the documentation already answers to — the shortcut a
|
||||
* reader learns in the docs should work on the way back out.
|
||||
*/
|
||||
document.addEventListener('keydown', (event) => {
|
||||
if (dialog.open) return;
|
||||
const target = event.target as HTMLElement | null;
|
||||
const typing =
|
||||
target?.isContentEditable ||
|
||||
['INPUT', 'TEXTAREA', 'SELECT'].includes(target?.tagName ?? '');
|
||||
if (typing) return;
|
||||
|
||||
if (event.key === '/' || ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k')) {
|
||||
event.preventDefault();
|
||||
open();
|
||||
}
|
||||
});
|
||||
}
|
||||
</script>
|
||||
|
||||
<style>
|
||||
.site-search__open {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 0.5rem;
|
||||
padding: 0.4rem 0.7rem;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: var(--radius-pill);
|
||||
background: transparent;
|
||||
color: var(--muted);
|
||||
font: inherit;
|
||||
font-size: 0.92rem;
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
.site-search__open:hover {
|
||||
color: var(--ink);
|
||||
border-color: var(--gold);
|
||||
}
|
||||
|
||||
.site-search__open kbd {
|
||||
padding: 0 0.35rem;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 4px;
|
||||
font: inherit;
|
||||
font-size: 0.78rem;
|
||||
line-height: 1.4;
|
||||
}
|
||||
|
||||
/* Narrow viewports get the icon alone: the header has a lockup and four links to fit,
|
||||
and "Search" beside a magnifier is the word the icon already says. */
|
||||
@media (max-width: 46rem) {
|
||||
.site-search__open span,
|
||||
.site-search__open kbd {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.site-search__open {
|
||||
padding: 0.45rem;
|
||||
}
|
||||
}
|
||||
|
||||
.site-search__dialog {
|
||||
width: min(46rem, calc(100vw - 2rem));
|
||||
margin-inline: auto;
|
||||
margin-block-start: min(12vh, 6rem);
|
||||
padding: 0;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: var(--radius-panel);
|
||||
background: var(--panel-flat);
|
||||
color: var(--ink);
|
||||
}
|
||||
|
||||
.site-search__dialog::backdrop {
|
||||
background: var(--scrim);
|
||||
}
|
||||
|
||||
.site-search__panel {
|
||||
padding: 1.1rem 1.25rem 1.4rem;
|
||||
}
|
||||
|
||||
.site-search__head {
|
||||
display: flex;
|
||||
align-items: baseline;
|
||||
justify-content: space-between;
|
||||
gap: 1rem;
|
||||
margin-bottom: 0.85rem;
|
||||
}
|
||||
|
||||
.site-search__title {
|
||||
margin: 0;
|
||||
font-size: 1.05rem;
|
||||
letter-spacing: 0.02em;
|
||||
}
|
||||
|
||||
.site-search__close {
|
||||
border: 0;
|
||||
background: transparent;
|
||||
color: var(--muted);
|
||||
font: inherit;
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
.site-search__close:hover {
|
||||
color: var(--ink);
|
||||
}
|
||||
|
||||
.site-search__note {
|
||||
margin: 0.75rem 0 0;
|
||||
color: var(--muted);
|
||||
font-size: 0.92rem;
|
||||
}
|
||||
|
||||
/* Pagefind ships its own palette; these bind it to the site's tokens so the dialog is
|
||||
not a differently-coloured window sitting on the page. */
|
||||
.site-search__panel :global(.pagefind-ui) {
|
||||
--pagefind-ui-primary: var(--ink);
|
||||
--pagefind-ui-text: var(--ink);
|
||||
--pagefind-ui-background: var(--panel-flat);
|
||||
--pagefind-ui-border: var(--line);
|
||||
--pagefind-ui-tag: var(--bg);
|
||||
--pagefind-ui-border-width: 1px;
|
||||
--pagefind-ui-border-radius: var(--radius-input);
|
||||
--pagefind-ui-font: inherit;
|
||||
}
|
||||
|
||||
.site-search__panel :global(.pagefind-ui__result-link) {
|
||||
color: var(--gold);
|
||||
}
|
||||
|
||||
/* The match highlight. Pagefind marks matched terms with <mark>, and the user-agent
|
||||
default for that is black on pure yellow — legible, and a hole punched through the
|
||||
palette on every result. Gold at low opacity reads as a highlight against this ground
|
||||
without becoming the loudest thing on the page.
|
||||
|
||||
`.pagefind-ui--reset` is in the selector because Pagefind's reset declares
|
||||
`.pagefind-ui--reset mark { all: revert }`, which is the same specificity as a plain
|
||||
descendant rule and is injected after this stylesheet — so it won on order and put the
|
||||
yellow back. One more class is enough; `!important` is not needed and would be a worse
|
||||
way to say the same thing. */
|
||||
.site-search__panel :global(.pagefind-ui--reset mark) {
|
||||
background: color-mix(in srgb, var(--gold) 26%, transparent);
|
||||
color: var(--ink);
|
||||
}
|
||||
</style>
|
||||
75
src/components/StructuredData.astro
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
import platform from '../data/platform.json';
|
||||
import { brand } from '../lib/brand.mjs';
|
||||
|
||||
/**
|
||||
* Structured data for the homepage (D50, phase 10).
|
||||
*
|
||||
* Two blocks and no more. `Organization` so the project's name resolves to an entity with a
|
||||
* mark and a support channel rather than to whichever page happens to rank; and
|
||||
* `SoftwareApplication` because what the site describes is software someone installs, and
|
||||
* the licence and platform are facts a search result can usefully carry.
|
||||
*
|
||||
* ── What this deliberately is not ───────────────────────────────────────────
|
||||
* It carries no ratings, no counts, no price, no `aggregateRating` — the vocabulary is
|
||||
* full of fields that turn a result into an advert, and every one of them here would be
|
||||
* invented. §11's "understated honesty" applies to markup a reader never sees as much as to
|
||||
* the prose, and inventing a rating is the exact thing that gets structured data ignored.
|
||||
*
|
||||
* Breadcrumb and Article markup for the forty documentation pages was considered and
|
||||
* rejected: Starlight already renders breadcrumbs a reader can see, and forty more blocks
|
||||
* would be forty more places for a fact to go stale.
|
||||
*
|
||||
* ── Where the values come from ──────────────────────────────────────────────
|
||||
* Every one is read — `brand.mjs` for text, `platform.json` for the platform's facts —
|
||||
* so `checkFacts.mjs` already guards them and the mount already reaches them. Nothing here
|
||||
* is typed twice. It is a data block, not code: no browser executes it, no CSP hash covers
|
||||
* it, and `applyBrand.mjs` is free to rewrite the name inside it at boot (both scripts know
|
||||
* about `application/ld+json` explicitly, because both would otherwise get it wrong).
|
||||
*/
|
||||
const site = Astro.site!;
|
||||
const url = (p: string) => new URL(p, site).href;
|
||||
|
||||
const organization = {
|
||||
'@type': 'Organization',
|
||||
'@id': url('/#organization'),
|
||||
name: brand.siteName,
|
||||
url: url('/'),
|
||||
logo: url('/brand/icon-512.png'),
|
||||
description: brand.tagline,
|
||||
// The support front door (D10). The Gitea org is where the code is; Discord is where a
|
||||
// person gets an answer, so both are listed and neither is described as the other.
|
||||
sameAs: [brand.giteaOrg, brand.discordInvite].filter(Boolean),
|
||||
};
|
||||
|
||||
const application = {
|
||||
'@type': 'SoftwareApplication',
|
||||
'@id': url('/#software'),
|
||||
name: brand.siteName,
|
||||
url: url('/'),
|
||||
description: brand.tagline,
|
||||
applicationCategory: 'WebApplication',
|
||||
// What an operator actually runs it on: a container on their own host, and an Android
|
||||
// client. Not "Windows" — the installer runs there, the platform does not require it.
|
||||
operatingSystem: 'Linux, Windows, Android',
|
||||
license: 'https://www.gnu.org/licenses/gpl-3.0.html',
|
||||
// D66: the Module API is the one version every deployment shares. Each game has its own
|
||||
// bundle, so no single bundle tag describes the platform any more.
|
||||
softwareVersion: platform.moduleApi,
|
||||
publisher: { '@id': url('/#organization') },
|
||||
// Self-hosted and free, and `offers` is the only way the vocabulary can say so. Omitting
|
||||
// it reads as "price unknown"; stating zero is simply true.
|
||||
offers: {
|
||||
'@type': 'Offer',
|
||||
price: '0',
|
||||
priceCurrency: 'USD',
|
||||
},
|
||||
};
|
||||
|
||||
const graph = {
|
||||
'@context': 'https://schema.org',
|
||||
'@graph': [organization, application],
|
||||
};
|
||||
---
|
||||
|
||||
<script type="application/ld+json" set:html={JSON.stringify(graph)} is:inline />
|
||||
@@ -1,61 +1,36 @@
|
||||
---
|
||||
import { screensOf, PHONE } from '../../data/screens.mjs';
|
||||
|
||||
/**
|
||||
* The app's screenshot strip — defined now, empty until phase 9 (D26).
|
||||
* The app's screenshot strip. Reserved in phase 5 (D26), filled in phase 9.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* WHY A COMPONENT THAT RENDERS NOTHING IS WORTH COMMITTING
|
||||
* WHY THIS COMPONENT EXISTED FOR A PHASE WITH NOTHING IN IT
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* PLAN.md §10 says `/app/` shows "the 14 existing screenshots". They exist —
|
||||
* `docs/android/screenshots/` on the `docs` repository — and they are the wrong fourteen:
|
||||
* a trusted-device and recovery-code smoke test from 2026-07-22, captured against a
|
||||
* PLAN.md §10 said `/app/` shows "the 14 existing screenshots". They exist —
|
||||
* `docs/android/screenshots/` on the `docs` repository — and they are the wrong fourteen: a
|
||||
* trusted-device and recovery-code smoke test from 2026-07-22, captured against a
|
||||
* development instance with no seeded content, before the theming work that changed how
|
||||
* every screen looks. Five of them are two-factor prompts. The home shot is an empty page.
|
||||
*
|
||||
* Shipping them would break two things at once: D4, which says real screenshots from the
|
||||
* review stack rather than placeholders, and §1, because they would show an app that no
|
||||
* longer looks like that. D26 records the decision — the slot is reserved, phase 9 fills
|
||||
* it, and phase 9 is already the phase that stands up the review stack and seeds the
|
||||
* content the web screenshots need. Adding an emulator pass to a rig that is being built
|
||||
* anyway is most of the work already done, and it has the property that the phone shots
|
||||
* and the browser shots then show the same deployment on the same day.
|
||||
*
|
||||
* The component exists rather than the page carrying a `TODO` because a defined shape is
|
||||
* what makes phase 9 a data change instead of a design task: fill `shots`, and the section
|
||||
* appears with a heading, a caption line and a grid. Nothing else has to be decided then.
|
||||
* Shipping them would have broken D4 and §1 at once, so D26 reserved the slot for the phase
|
||||
* that stands up the review stack anyway. The shape was defined then and the data arrived
|
||||
* now, which is exactly what it was for: filling it was a data change.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* WHAT PHASE 9 SHOULD PUT HERE
|
||||
* WHY IT READS screens.mjs RATHER THAN HOLDING ITS OWN LIST
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* Portrait captures at the device's own pixel size, from an API 36 emulator pointed at the
|
||||
* seeded review stack, one per idea rather than one per screen: the shard hub with live
|
||||
* data, the marketplace, a character sheet, the news list, the notification settings, and
|
||||
* the drawer showing a deployment's own navigation. Six is plenty. Fourteen was never a
|
||||
* target — it was the number that happened to exist.
|
||||
* The draft carried its own `shots` array, written before there was anywhere else to put
|
||||
* one. There is now: `src/data/screens.mjs` holds every capture the site ships, web and
|
||||
* phone alike, and `scripts/checkScreens.mjs` proves each one exists at the size the markup
|
||||
* claims. A second list here would be the one nothing checks.
|
||||
*
|
||||
* They belong in `public/`, not `brand-default/`: these are editorial content shipped with
|
||||
* the image, not branding an operator overrides (§7).
|
||||
* The phone captures come from an emulator pointed at the same seeded deployment the web
|
||||
* screenshots were taken from, on the same day — which is the property D26 was really
|
||||
* after, since the app takes its colours, type and navigation from the site it connects to.
|
||||
*/
|
||||
|
||||
/**
|
||||
* One capture. `width` and `height` are the real pixel dimensions and are required rather
|
||||
* than optional: without them the page reflows as each image decodes, and a strip of six
|
||||
* phone screenshots is the worst possible place for that.
|
||||
*
|
||||
* Frontmatter is TypeScript, so this is an interface rather than the JSDoc typedef the
|
||||
* `.mjs` data files use — and it has to be typed explicitly, because an empty array
|
||||
* annotated by inference is `any[]` and `astro check` is right to refuse it.
|
||||
*/
|
||||
interface Shot {
|
||||
/** Site-absolute path under `/screens/`. */
|
||||
src: string;
|
||||
/** What the screen shows, for somebody who cannot see it. */
|
||||
alt: string;
|
||||
caption: string;
|
||||
width: number;
|
||||
height: number;
|
||||
}
|
||||
|
||||
const shots: Shot[] = [];
|
||||
const shots = screensOf('phone');
|
||||
---
|
||||
|
||||
{
|
||||
@@ -63,8 +38,8 @@ const shots: Shot[] = [];
|
||||
<section class="page section shots">
|
||||
<h2>What it looks like</h2>
|
||||
<p class="prose shots__lede">
|
||||
Captured against a real deployment with real content, not mocked up. The app takes
|
||||
its colours, type and navigation from the site it is connected to, so these show one
|
||||
Captured against a real deployment with real content, not mocked up. The app takes its
|
||||
colours, type and navigation from the site it is connected to, so these show one
|
||||
community's app rather than a neutral one.
|
||||
</p>
|
||||
|
||||
@@ -72,10 +47,10 @@ const shots: Shot[] = [];
|
||||
{shots.map((shot) => (
|
||||
<li class="shots__item">
|
||||
<img
|
||||
src={shot.src}
|
||||
src={`/screens/${shot.id}.webp`}
|
||||
alt={shot.alt}
|
||||
width={shot.width}
|
||||
height={shot.height}
|
||||
width={PHONE.width}
|
||||
height={PHONE.height}
|
||||
loading="lazy"
|
||||
decoding="async"
|
||||
/>
|
||||
|
||||
@@ -8,9 +8,11 @@ import platform from '../../data/platform.json';
|
||||
* The other two draw runtime shapes. This one draws a code boundary, and it is here because
|
||||
* it is the claim the whole project rests on: that a community platform can be built once
|
||||
* and pointed at any game. An evaluator has every reason to read that as marketing, so the
|
||||
* page draws the seam and then says plainly what does and does not prove it — one module
|
||||
* exists, the second is a paper exercise, and the exit criterion for calling the contract
|
||||
* proven is written down (§2, and the entries `/modules/` renders from `notBuilt.mjs`).
|
||||
* page draws the seam and then says plainly what does and does not prove it — two modules
|
||||
* exist, both built inside this project, and the exit criterion for calling the contract
|
||||
* proven by an outsider is written down (§2, §16, and the entries `/modules/` renders from
|
||||
* `notBuilt.mjs`). Until phase 13 this said one module and a paper exercise; Module-Rust's
|
||||
* release made that false.
|
||||
*
|
||||
* The Module API version is read from `platform.json` like every other number on this site
|
||||
* (§12). It is the one place a version genuinely belongs in this diagram: the seam is
|
||||
@@ -73,7 +75,7 @@ import platform from '../../data/platform.json';
|
||||
<!-- The module: everything that knows a game exists. -->
|
||||
<rect class="host" x="8" y="306" width="364" height="186" rx="14" />
|
||||
<text class="host-title" x="28" y="340">Game module</text>
|
||||
<text class="host-sub" x="28" y="360">one per deployment; UO today</text>
|
||||
<text class="host-sub" x="28" y="360">one per deployment; UO or Rust today</text>
|
||||
|
||||
<rect class="node" x="28" y="378" width="156" height="46" rx="10" />
|
||||
<text class="node-title" x="46" y="406">Routes</text>
|
||||
@@ -130,11 +132,12 @@ import platform from '../../data/platform.json';
|
||||
<section>
|
||||
<h3>What this does not yet prove</h3>
|
||||
<p>
|
||||
One module exists and it is Ultima Online. A second, for a different game, is a
|
||||
written dry-run that was deliberately never implemented — it exists to test whether
|
||||
the contract generalises on paper. Until somebody builds the second one, the seam is
|
||||
a well-argued design rather than a demonstrated one, and this site says so wherever
|
||||
it comes up.
|
||||
Two modules exist: Ultima Online, and Rust, which this project built second, from
|
||||
the Integration Kit. Where the Rust module needed something the contract did not
|
||||
yet offer, the gap was closed in core, for every module, rather than in a fork — so
|
||||
the seam now has two games on its far side instead of one. What two modules built
|
||||
inside this project cannot prove is that somebody outside it can do the same, and
|
||||
that is why the Integration Kit still says draft.
|
||||
</p>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
@@ -17,7 +17,7 @@ import { capabilityGroups, assertCapabilityCoverage } from '../../data/capabilit
|
||||
* what exists while quietly omitting the well-known things that do not is the exact failure
|
||||
* §1 is written to prevent.
|
||||
*/
|
||||
assertCapabilityCoverage(platform.moduleUoCapabilities);
|
||||
assertCapabilityCoverage(platform.games.uo.module.capabilities);
|
||||
---
|
||||
|
||||
<section class="page section caps">
|
||||
@@ -52,7 +52,7 @@ assertCapabilityCoverage(platform.moduleUoCapabilities);
|
||||
|
||||
<p class="caps__foot prose">
|
||||
Some things people reasonably expect are <strong>deliberately not built</strong> — a Matrix
|
||||
integration, more than one game module active at once, a second game module. They are
|
||||
integration, more than one game module active at once, a finished Integration Kit. They are
|
||||
listed rather than left out, on <a href="/features/">features</a> and{' '}
|
||||
<a href="/integrations/">integrations</a>.
|
||||
</p>
|
||||
|
||||
@@ -1,12 +1,10 @@
|
||||
---
|
||||
import platform from '../../data/platform.json';
|
||||
|
||||
/**
|
||||
* The data path (PLAN.md §13 phase 3), drawn as inline SVG per §11's motif rule — hand-drawn
|
||||
* geometry, used where it explains something, and no raster anywhere.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* THE LABELS ARE GENERIC, WITH UO AS THE CAPTION
|
||||
* THE LABELS ARE GENERIC; THE CAPTION NAMES THE GAMES
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* The org lead settled this before the diagram was drawn. The nodes say "your game server"
|
||||
* and "sidecar", not "ServUO shard" and "uo-link", because §10's rule is that a reader
|
||||
@@ -14,10 +12,12 @@ import platform from '../../data/platform.json';
|
||||
* repositories in order to connect a game server — and because the tagline promises a
|
||||
* platform, not a UO product.
|
||||
*
|
||||
* It does NOT hide what actually ships. The sub-labels and the caption name ServUO and
|
||||
* uo-link outright, because §1 says the technical truth wins and today there is exactly one
|
||||
* implementation of this shape. An operator running a shard has to see themselves in the
|
||||
* picture on the first screen.
|
||||
* It does NOT hide what actually ships: the caption names the games that ship on this shape,
|
||||
* because §1 says the technical truth wins and an operator has to see their game in the
|
||||
* picture on the first screen. Until phase 13 the sub-labels named ServUO and uo-link, which
|
||||
* was true while there was exactly one implementation. With two, naming one would mislead,
|
||||
* and D63 (PLAN.md §16) keeps each game's vocabulary on that game's own pages — so the
|
||||
* caption names the games and the diagram names nothing else.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* WHY THE SVG IS aria-hidden
|
||||
@@ -74,11 +74,11 @@ import platform from '../../data/platform.json';
|
||||
|
||||
<rect class="node" x="20" y="16" width="340" height="76" rx="12" />
|
||||
<text class="node-title" x="42" y="50">Your game server</text>
|
||||
<text class="node-sub" x="42" y="72">ServUO today · opens no inbound port</text>
|
||||
<text class="node-sub" x="42" y="72">opens no inbound port</text>
|
||||
|
||||
<rect class="node" x="20" y="148" width="340" height="76" rx="12" />
|
||||
<text class="node-title" x="42" y="182">Sidecar</text>
|
||||
<text class="node-sub" x="42" y="204">uo-link · the only network-facing part</text>
|
||||
<text class="node-sub" x="42" y="204">the only network-facing part</text>
|
||||
|
||||
<rect class="node node--self" x="20" y="280" width="340" height="76" rx="12" />
|
||||
<text class="node-title" x="42" y="314">Runic Gateway</text>
|
||||
@@ -90,8 +90,9 @@ import platform from '../../data/platform.json';
|
||||
</svg>
|
||||
|
||||
<p class="datapath__caption">
|
||||
Today that game server is a ServUO shard and that sidecar is uo-link. The shape is the
|
||||
contract; the implementations are what plug into it.
|
||||
Two games ship on this shape today, Ultima Online and Rust, each with its own plugin
|
||||
and its own sidecar. The shape is the contract; the implementations are what plug
|
||||
into it.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
@@ -109,8 +110,8 @@ import platform from '../../data/platform.json';
|
||||
<h3>The sidecar</h3>
|
||||
<p>
|
||||
A small service beside the game, and the only piece of the bridge anything else can
|
||||
reach. It speaks a versioned wire protocol — protocol {platform.protocol} today — so
|
||||
a mismatched pair is refused rather than misread, and it answers only your website's
|
||||
reach. It speaks a versioned wire protocol — each game pins its own — so a
|
||||
mismatched pair is refused rather than misread, and it answers only your website's
|
||||
backend, over an authenticated WebSocket and REST.
|
||||
</p>
|
||||
</li>
|
||||
|
||||
@@ -55,9 +55,9 @@ import platform from '../../data/platform.json';
|
||||
</div>
|
||||
|
||||
<div class="chips">
|
||||
<span class="chip chip--version">Protocol {platform.protocol}</span>
|
||||
{/* D66: only the version every deployment shares. A protocol and a bundle belong
|
||||
to a game, so they live on that game's pages rather than on the front door. */}
|
||||
<span class="chip chip--version">Module API {platform.moduleApi}</span>
|
||||
<span class="chip chip--version">Bundle {platform.bundle.tag}</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
44
src/components/home/WhatItLooksLike.astro
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
import Screenshot from '../Screenshot.astro';
|
||||
|
||||
/**
|
||||
* The homepage's one screenshot. PLAN.md §13 phase 9, D4 / D44.
|
||||
*
|
||||
* -----------------------------------------------------------------------------------------
|
||||
* WHY ONE, AND WHY THIS ONE
|
||||
* -----------------------------------------------------------------------------------------
|
||||
* `DataPath` above it draws the claim — a private game server, a sidecar, a public site —
|
||||
* and a diagram of a data path is a promise that the data arrives. This is the page where
|
||||
* it arrives, captured from a deployment wired to a running shard, so the section directly
|
||||
* under the diagram is the diagram's evidence.
|
||||
*
|
||||
* A gallery here would compete with `Capabilities` further down, which is the part of the
|
||||
* homepage that enumerates. So: one figure, the signature screen, and the rest of the set
|
||||
* on `/features/` where each one sits beside the claim it supports.
|
||||
*/
|
||||
---
|
||||
|
||||
<section class="page section looks">
|
||||
<p class="eyebrow">What it looks like</p>
|
||||
<h2>The other end of that diagram</h2>
|
||||
<p class="prose looks__lede">
|
||||
A demo deployment with a real shard behind it. The gold supply, the state of the link and
|
||||
the player online in Britain are all read from the game server over the bridge. None of it
|
||||
is typed in, and none of it is a mock-up.
|
||||
</p>
|
||||
|
||||
<Screenshot id="shard-status" />
|
||||
</section>
|
||||
|
||||
<style>
|
||||
.looks h2 {
|
||||
margin: 0.35rem 0 0.75rem;
|
||||
font-size: clamp(1.6rem, 3.2vw, 2.1rem);
|
||||
}
|
||||
|
||||
.looks__lede {
|
||||
margin: 0;
|
||||
max-width: 46rem;
|
||||
color: var(--muted);
|
||||
}
|
||||
</style>
|
||||
41
src/config/cspHashes.mjs
Normal file
@@ -0,0 +1,41 @@
|
||||
/**
|
||||
* cspHashes.mjs — GENERATED. Do not edit by hand.
|
||||
*
|
||||
* Regenerate with `npm run csp:hashes` (which builds, harvests and rebuilds).
|
||||
* `npm run check:csp` fails if this file no longer covers what the build emits.
|
||||
*
|
||||
* ── Why this file exists ────────────────────────────────────────────────────
|
||||
* Astro's `security.csp` (D48) hashes the scripts and styles it processes itself. It does
|
||||
* not hash `<script is:inline>` — by design, because an inline script is the author's own
|
||||
* text and Astro never parses it. Starlight ships six of them on every documentation page:
|
||||
* the theme provider, the theme-picker sync, the mobile menu, the sidebar scroll restore.
|
||||
*
|
||||
* That combination fails in the worst way available. The build succeeds, the header is
|
||||
* strict and correct, every page renders — and the theme switch, the mobile sidebar and
|
||||
* the sidebar's scroll position are dead, with the explanation only in a browser console
|
||||
* nobody opens. `'unsafe-inline'` would fix all six and give up the single directive CSP
|
||||
* exists to enforce, so instead the hashes are enumerated here and checked.
|
||||
*
|
||||
* These are Starlight's, not ours: a Starlight upgrade that edits one byte of one of those
|
||||
* scripts invalidates a hash. `check:csp` is what turns that from a silent breakage into a
|
||||
* red build, and regenerating this file is the acknowledgement that the upgrade was read.
|
||||
*/
|
||||
|
||||
/**
|
||||
* SHA-256 hashes of inline `<script>` bodies Astro does not hash for us.
|
||||
*
|
||||
* The template-literal type is not decoration: Astro types this option as `CspHashEntry[]`,
|
||||
* so a plain `string[]` fails `astro check`.
|
||||
*
|
||||
* @type {`sha256-${string}`[]}
|
||||
*/
|
||||
export const inlineScriptHashes = [
|
||||
'sha256-7eCV4jtsr4t4knb3c4FCRPeu7GGZeOUGE3XvWix0XOQ=',
|
||||
'sha256-GkZBRnvSuhtx/cvzvukVkX2JJZW+DdPlVr7BX8Tefqo=',
|
||||
'sha256-VWo5Wp4aqSj6nSgMpeAp9cKieaoIfwFUAunAVugI5gA=',
|
||||
'sha256-f/zAUE74ucc3JYp4r4QQvkJofoQdkOIhHYK+jeZ6eko=',
|
||||
'sha256-wX2yOADeV+NMngflD5uYi3vl50SHC4sfM1EmylVjlX4=',
|
||||
];
|
||||
|
||||
/** @type {`sha256-${string}`[]} SHA-256 hashes of inline `<style>` bodies Astro does not hash. */
|
||||
export const inlineStyleHashes = [];
|
||||
22
src/config/redirects.mjs
Normal file
@@ -0,0 +1,22 @@
|
||||
/**
|
||||
* Docs pages that moved, and where they went — PLAN.md §16, D60.
|
||||
*
|
||||
* Every page that moves keeps its old URL working, because the old URL is in somebody's
|
||||
* bookmarks, in an installer's output and in search results. With the Node adapter these are
|
||||
* not files in `dist/client`: the server answers each one with a real `301`.
|
||||
*
|
||||
* Its own file, rather than inline in `astro.config.mjs`, so that `test/headers.test.mjs` can
|
||||
* read the same list and assert every entry against the running server — the config cannot be
|
||||
* imported by plain Node, because Starlight ships TypeScript.
|
||||
*
|
||||
* Phase 14 moved the Ultima Online pages into their own group. `connect-a-game-server` did
|
||||
* NOT move: its URL is now the game-neutral hand-off page, which is a better landing for an
|
||||
* old link than a redirect into one game would be.
|
||||
*/
|
||||
export const docsRedirects = {
|
||||
'/docs/administration/the-shard-connection': '/docs/ultima-online/the-shard-connection/',
|
||||
'/docs/administration/client-files': '/docs/ultima-online/client-files/',
|
||||
'/docs/reference/bridge-cfg': '/docs/ultima-online/bridge-cfg/',
|
||||
'/docs/reference/sidecar-toml': '/docs/ultima-online/sidecar-toml/',
|
||||
'/docs/reference/event-catalog': '/docs/ultima-online/event-catalog/',
|
||||
};
|
||||
@@ -1,5 +1,6 @@
|
||||
/**
|
||||
* The documentation sidebar — PLAN.md §10 "Documentation", five groups, ~37 pages.
|
||||
* The documentation sidebar — PLAN.md §10 "Documentation": five core groups, then one group
|
||||
* per game after them (§16, D60).
|
||||
*
|
||||
* The pages themselves land in phases 7 and 8. This file exists in phase 1 because the
|
||||
* shape of the journey is a design decision that is already made, and because a sidebar
|
||||
@@ -22,7 +23,7 @@ export const docsSidebar = [
|
||||
{ label: 'Install the site', slug: 'docs/getting-started/install-the-site' },
|
||||
{ label: 'First run', slug: 'docs/getting-started/first-run' },
|
||||
{ label: 'Install a game module', slug: 'docs/getting-started/install-a-game-module' },
|
||||
{ label: 'Connect a game server', slug: 'docs/getting-started/connect-a-game-server' },
|
||||
{ label: 'Connect your game server', slug: 'docs/getting-started/connect-a-game-server' },
|
||||
{ label: 'Verify the whole stack', slug: 'docs/getting-started/verify-the-whole-stack' },
|
||||
],
|
||||
},
|
||||
@@ -36,20 +37,100 @@ export const docsSidebar = [
|
||||
{ label: 'Users and roles', slug: 'docs/administration/users-and-roles' },
|
||||
{ label: 'Authentication', slug: 'docs/administration/authentication' },
|
||||
{ label: 'Teams', slug: 'docs/administration/teams' },
|
||||
{ label: 'Scheduled events', slug: 'docs/administration/events' },
|
||||
{ label: 'Moderation', slug: 'docs/administration/moderation' },
|
||||
{ label: 'Notifications and email', slug: 'docs/administration/notifications-and-email' },
|
||||
{ label: 'Engagement rules', slug: 'docs/administration/engagement-rules' },
|
||||
{ label: 'Message templates', slug: 'docs/administration/message-templates' },
|
||||
{ label: 'Managing modules', slug: 'docs/administration/managing-modules' },
|
||||
{ label: 'The shard connection', slug: 'docs/administration/the-shard-connection' },
|
||||
{ label: 'Maintenance and upgrades', slug: 'docs/administration/maintenance-and-upgrades' },
|
||||
{ label: 'Troubleshooting', slug: 'docs/administration/troubleshooting' },
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Modules',
|
||||
items: [
|
||||
{ label: 'The module system', slug: 'docs/modules/the-module-system' },
|
||||
{ label: 'Installing modules', slug: 'docs/modules/installing-modules' },
|
||||
{ label: 'Module lifecycle', slug: 'docs/modules/module-lifecycle' },
|
||||
{ label: 'The module manifest', slug: 'docs/modules/the-module-manifest' },
|
||||
{ label: 'The module API', slug: 'docs/modules/the-module-api' },
|
||||
{ label: 'Building a module', slug: 'docs/modules/building-a-module' },
|
||||
{ label: 'The Integration Kit', slug: 'docs/modules/the-integration-kit' },
|
||||
{ label: 'Testing and release', slug: 'docs/modules/testing-and-release' },
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Architecture',
|
||||
items: [
|
||||
{ label: 'System architecture', slug: 'docs/architecture/system-architecture' },
|
||||
{ label: 'The bridge', slug: 'docs/architecture/the-bridge' },
|
||||
{ label: 'Authentication architecture', slug: 'docs/architecture/authentication-architecture' },
|
||||
{ label: 'Teams architecture', slug: 'docs/architecture/teams-architecture' },
|
||||
{ label: 'Events architecture', slug: 'docs/architecture/events-architecture' },
|
||||
{ label: 'Protocol versions', slug: 'docs/architecture/protocol-versions' },
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Reference',
|
||||
items: [
|
||||
{ label: 'Environment variables', slug: 'docs/reference/environment-variables' },
|
||||
{ label: 'Installer CLI', slug: 'docs/reference/installer-cli' },
|
||||
{ label: 'HTTP API', slug: 'docs/reference/http-api' },
|
||||
{ label: 'Canonical documents', slug: 'docs/reference/canonical-documents' },
|
||||
],
|
||||
},
|
||||
// One group per game, after Reference (PLAN.md §16, D60). Everything above this line is
|
||||
// core and is held to core's words by checkTerms.mjs (D63, D64). A group whose label is a
|
||||
// game's `name` in platform.json is that game's group, and may use that game's words — so
|
||||
// the label is load-bearing: renaming it here without renaming the game turns it core.
|
||||
{
|
||||
label: 'Ultima Online',
|
||||
items: [
|
||||
{ label: 'The Ultima Online module', slug: 'docs/ultima-online' },
|
||||
{ label: 'Connect a ServUO shard', slug: 'docs/ultima-online/connect-a-servuo-shard' },
|
||||
{ label: 'Verify the bridge', slug: 'docs/ultima-online/verify-the-bridge' },
|
||||
{ label: 'The shard connection', slug: 'docs/ultima-online/the-shard-connection' },
|
||||
{ label: 'Client files', slug: 'docs/ultima-online/client-files' },
|
||||
{ label: 'Troubleshooting', slug: 'docs/ultima-online/troubleshooting' },
|
||||
{ label: 'Bridge.cfg', slug: 'docs/ultima-online/bridge-cfg' },
|
||||
{ label: 'sidecar.toml', slug: 'docs/ultima-online/sidecar-toml' },
|
||||
{ label: 'Shard event catalog', slug: 'docs/ultima-online/event-catalog' },
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Rust',
|
||||
items: [
|
||||
{ label: 'The Rust module', slug: 'docs/rust' },
|
||||
{ label: 'Install the bridge', slug: 'docs/rust/install-the-bridge' },
|
||||
{ label: 'Connect the site', slug: 'docs/rust/connect-the-site' },
|
||||
{ label: 'Verify the bridge', slug: 'docs/rust/verify-the-bridge' },
|
||||
{ label: 'Linking Steam accounts', slug: 'docs/rust/linking-steam-accounts' },
|
||||
{ label: 'Permissions and groups', slug: 'docs/rust/permissions-and-groups' },
|
||||
{ label: 'Mod config from the site', slug: 'docs/rust/mod-config' },
|
||||
{ label: 'Who sees who is online', slug: 'docs/rust/who-sees-who-is-online' },
|
||||
{ label: 'Events, zones and rewards', slug: 'docs/rust/events-zones-and-rewards' },
|
||||
{ label: 'Optional plugins', slug: 'docs/rust/optional-plugins' },
|
||||
{ label: 'The live map', slug: 'docs/rust/the-live-map' },
|
||||
{ label: 'Troubleshooting', slug: 'docs/rust/troubleshooting' },
|
||||
{ label: 'sidecar.toml', slug: 'docs/rust/sidecar-toml' },
|
||||
{ label: 'RunicGateway.json', slug: 'docs/rust/runicgateway-json' },
|
||||
{ label: 'Event kinds', slug: 'docs/rust/event-kinds' },
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
/**
|
||||
* The full planned tree, kept next to the live sidebar so phases 7 and 8 have their
|
||||
* checklist in the place they will be working. Not exported into the Starlight config —
|
||||
* it names pages that do not exist yet.
|
||||
* The tree §10 planned, kept as the record of what was intended — every page it names now
|
||||
* exists, as of phase 8.
|
||||
*
|
||||
* It was the phases 7/8 checklist, and a checklist with nothing left on it is no longer
|
||||
* pulling its weight: it is a second copy of the tree above, maintained by hand, and it had
|
||||
* already drifted once (phase 7 added `Content` under D37 and this list was not updated,
|
||||
* which nothing caught because nothing reads it). `checkSidebar.mjs` now asserts the two
|
||||
* agree, which is what makes keeping it safe.
|
||||
*
|
||||
* Not exported into the Starlight config.
|
||||
*/
|
||||
export const plannedSidebar = {
|
||||
'Getting started': [
|
||||
@@ -58,20 +139,23 @@ export const plannedSidebar = {
|
||||
'Install the site',
|
||||
'First run',
|
||||
'Install a game module',
|
||||
'Connect a game server',
|
||||
'Connect your game server',
|
||||
'Verify the whole stack',
|
||||
],
|
||||
Administration: [
|
||||
'Configuration',
|
||||
'Branding and theming',
|
||||
'Navigation and pages',
|
||||
'Content',
|
||||
'Users and roles',
|
||||
'Authentication',
|
||||
'Teams',
|
||||
'Scheduled events',
|
||||
'Moderation',
|
||||
'Notifications and email',
|
||||
'Engagement rules',
|
||||
'Message templates',
|
||||
'Managing modules',
|
||||
'The shard connection',
|
||||
'Maintenance and upgrades',
|
||||
'Troubleshooting',
|
||||
],
|
||||
@@ -90,15 +174,42 @@ export const plannedSidebar = {
|
||||
'The bridge',
|
||||
'Authentication architecture',
|
||||
'Teams architecture',
|
||||
'Events architecture',
|
||||
'Protocol versions',
|
||||
],
|
||||
Reference: [
|
||||
'Environment variables',
|
||||
'Installer CLI',
|
||||
'sidecar.toml',
|
||||
'Bridge.cfg',
|
||||
'HTTP API',
|
||||
'Event catalog',
|
||||
'Canonical documents',
|
||||
],
|
||||
'Ultima Online': [
|
||||
'The Ultima Online module',
|
||||
'Connect a ServUO shard',
|
||||
'Verify the bridge',
|
||||
'The shard connection',
|
||||
'Client files',
|
||||
'Troubleshooting',
|
||||
'Bridge.cfg',
|
||||
'sidecar.toml',
|
||||
'Shard event catalog',
|
||||
],
|
||||
// PLAN.md §16, D70 (phase 15). RunicNPC's subgroup lands in phase 16 (D61).
|
||||
Rust: [
|
||||
'The Rust module',
|
||||
'Install the bridge',
|
||||
'Connect the site',
|
||||
'Verify the bridge',
|
||||
'Linking Steam accounts',
|
||||
'Permissions and groups',
|
||||
'Mod config from the site',
|
||||
'Who sees who is online',
|
||||
'Events, zones and rewards',
|
||||
'Optional plugins',
|
||||
'The live map',
|
||||
'Troubleshooting',
|
||||
'sidecar.toml',
|
||||
'RunicGateway.json',
|
||||
'Event kinds',
|
||||
],
|
||||
};
|
||||
|
||||
@@ -5,7 +5,7 @@ description: Local accounts and two-factor, SSO providers and the link-only poli
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
**Admin → Authentication** has four tabs: Local Accounts, Google, Discord and Custom
|
||||
**Admin → Authentication** has five tabs: Local Accounts, Google, Discord, Steam and Custom
|
||||
Providers. One session model sits behind all of them — a web cookie, a mobile bearer token
|
||||
and an SSO sign-in all produce the same session.
|
||||
|
||||
@@ -35,6 +35,19 @@ account is still a stranger.
|
||||
Configuring Google here also unlocks **email delivery**, which reuses the same OAuth client
|
||||
— see [Notifications and email](/docs/administration/notifications-and-email/).
|
||||
|
||||
### Steam
|
||||
|
||||
Steam signs people in with OpenID rather than OAuth, so it needs no client ID or secret — but
|
||||
it does need a **Steam Web API key**, for the name and avatar Steam's sign-in does not carry,
|
||||
and saving Steam as enabled without one is refused. It follows the same link-only policy, more
|
||||
strictly: **Steam never creates an account**, whatever registration allows. A person may link
|
||||
several Steam accounts, and each is listed on their account screen with its name, avatar and
|
||||
Steam ID.
|
||||
|
||||
A game module can also be told which Steam accounts a signed-in person has proved are theirs,
|
||||
which is how a game that knows its players by Steam account can recognise a member. The Rust
|
||||
module uses it — see [Linking Steam accounts](/docs/rust/linking-steam-accounts/).
|
||||
|
||||
## Trusted devices
|
||||
|
||||
A second factor that asks on every sign-in on the same laptop trains people to click
|
||||
|
||||
@@ -4,6 +4,7 @@ description: Colours, fonts and corners from the Appearance screen; logo, hero a
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import Screenshot from '../../../../components/Screenshot.astro';
|
||||
|
||||
One prebuilt image runs as any community's site. Nothing about your identity is compiled
|
||||
in — it is a theme row in the database, three image files on a mount, and a few environment
|
||||
@@ -31,6 +32,8 @@ Two things the screen tells you that are easy to miss:
|
||||
- **The accent reaches the mobile app and the Discord bot**, both of which theme themselves
|
||||
from this site's public branding. Changing it here changes them.
|
||||
|
||||
<Screenshot id="admin-appearance" />
|
||||
|
||||
## Brand assets
|
||||
|
||||
The same screen uploads three images, and each applies as soon as the upload finishes —
|
||||
|
||||
@@ -16,7 +16,7 @@ Two places hold configuration, and the line between them is not arbitrary.
|
||||
|
||||
The rule behind the split: **anything that needs a restart or a shell is environment;
|
||||
anything an administrator should be able to change without either is in the panel.** That
|
||||
is why the Discord bot token, the OAuth client secrets and the shard's auth token are *not*
|
||||
is why the Discord bot token, the OAuth client secrets and the game module's sidecar token are *not*
|
||||
environment variables — they are entered in the panel and stored encrypted.
|
||||
|
||||
## Settings
|
||||
@@ -59,9 +59,10 @@ per-Team settings:
|
||||
## Email
|
||||
|
||||
Configured on the same screen and covered in
|
||||
[Notifications and email](/docs/administration/notifications-and-email/): it is Gmail over
|
||||
OAuth2, it reuses the Google authentication client, and it must be set up on the
|
||||
[Authentication](/docs/administration/authentication/) page first.
|
||||
[Notifications and email](/docs/administration/notifications-and-email/): pick a mail
|
||||
transport, enter its host, port and credentials, and send a test. It depends on nothing
|
||||
else on the site — a relay is the recommended posture, a mailbox provider over SMTP the
|
||||
simplest, and your own MTA needs no credentials at all.
|
||||
|
||||
<Aside type="note" title="Until email is connected, the contact form is a mailto: link">
|
||||
That is a deliberate fallback rather than a failure — but it does mean the *Contact email*
|
||||
|
||||
@@ -27,7 +27,7 @@ glance.
|
||||
|
||||
<Aside type="caution" title="Publishing a news post announces it">
|
||||
Publishing is what triggers the announcement pipeline — the Discord `#news` leg, and any leg
|
||||
an installed module adds, such as the `uo` module's in-game town crier. It fires on
|
||||
an installed module adds, such as the Ultima Online module's in-game town crier. It fires on
|
||||
publication, so an accidental publish is an accidental announcement. See
|
||||
[Notifications and email](/docs/administration/notifications-and-email/).
|
||||
</Aside>
|
||||
|
||||
175
src/content/docs/docs/administration/engagement-rules.mdx
Normal file
@@ -0,0 +1,175 @@
|
||||
---
|
||||
title: Engagement rules
|
||||
description: Decide what your site mails and shows people — the rule editor, saved audiences, the trigger catalog and the send log that answers "did they actually get it".
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
[Notifications and email](/docs/administration/notifications-and-email/) is about where a
|
||||
message goes. [Message templates](/docs/administration/message-templates/) is about what it
|
||||
says. This page is the part in between: **what makes one get sent at all.**
|
||||
|
||||
A **rule** is four decisions — *when* (a trigger), *to whom* (an audience), *by what*
|
||||
(channels), and *how often* (timing). **Admin → Engagement → Rules.**
|
||||
|
||||
## Nothing sends until you turn it on
|
||||
|
||||
Every rule arrives switched **off**. That is true of the ones you make, and it is true of
|
||||
the ones your modules ship with them: install a game module and you get a shelf of ready
|
||||
rules, all dark, none of them mailing anybody. Turning one on is a deliberate, separate
|
||||
act.
|
||||
|
||||
The same caution runs through the rest of the screen. Every rule carries a **hard ceiling
|
||||
on sends per hour** — you cannot save one without a number — because the failure mode of an
|
||||
automated mailer is not a wrong message, it is ten thousand of them at four in the morning.
|
||||
|
||||
<Aside type="caution" title="Upgrading? Your Team emails are here now">
|
||||
Team notification email used to be its own pipeline. It is engagement rules now, and — like
|
||||
every other seeded rule — those four rules arrive **disabled**. If your members were getting
|
||||
Team mail before an upgrade, it stops until you turn them on. The admin dashboard says so
|
||||
while it is true.
|
||||
</Aside>
|
||||
|
||||
## What a rule is made of
|
||||
|
||||
**The trigger** is the event that fires it: a house falling into disrepair, a post being
|
||||
published, a login failing. Pick it from what is registered — see
|
||||
[the catalog](#the-trigger-catalog) below. A rule's trigger is **fixed once the rule
|
||||
exists**: its cooldowns, its pending messages and its whole send history are about one
|
||||
event, so changing it would silently be a different rule wearing the same name. Make a new
|
||||
one instead.
|
||||
|
||||
**The audience** is who hears about it. Some are built in — the person the event is about,
|
||||
everyone subscribed to it, staff. Others come from your modules and are named in their own
|
||||
vocabulary. You can also point a rule at a **saved audience** you composed yourself; see
|
||||
[Audiences](#audiences).
|
||||
|
||||
**The channels** are how it reaches them: on the site, by email, by push. A rule can name
|
||||
more than one, and each channel picks its own template — the same event can be a sentence
|
||||
in the inbox and a properly laid-out letter in the mail.
|
||||
|
||||
**The timing** is the part worth reading twice.
|
||||
|
||||
- A **delay** holds the message before it goes, so a situation that resolves itself never
|
||||
produces a message at all.
|
||||
- **Cancel on** names the events that call it back. A warning that a house is about to
|
||||
collapse waits fifteen minutes and is cancelled outright if the owner turns up and
|
||||
repairs it — nobody is told their house was in danger after it stopped being in danger.
|
||||
- A **cooldown** is the "not again for a while" limit, counted **per person, per subject
|
||||
and per channel**. Per subject, so a cooldown about one house says nothing about another.
|
||||
Per channel, so "one a day about this house" means one email *and* one inbox item, which
|
||||
is what an operator setting that limit means.
|
||||
|
||||
## Audiences
|
||||
|
||||
**Admin → Engagement → Audiences** is where you build a named set of people out of the ones
|
||||
your modules declare — *members of this Team*, *the sitting governors* — and combine them:
|
||||
all of these, any of these, none of these.
|
||||
|
||||
One rule governs the whole screen: **composition narrows and never widens.**
|
||||
|
||||
- The ceiling of a saved audience is **derived** from the tightest thing in it, never
|
||||
chosen. That is true of "any of" too, where the intuitive answer — the widest of the two —
|
||||
is the wrong one. A ceiling says what an expression is *allowed* to reach, not what it
|
||||
happens to resolve to today.
|
||||
- **"None of" is only offered inside an "all of" group.** Alone it would have to mean
|
||||
"everybody except these", which is a broadcast built out of a short list, and it is not
|
||||
offered anywhere it would mean that.
|
||||
- Two audiences with no relationship between them — staff and "the person this is about",
|
||||
say — have no honest combined ceiling, so the save is refused rather than guessing which
|
||||
side to take.
|
||||
|
||||
Before you save a rule, the editor shows you a **reach preview**: a number, never a list of
|
||||
names. It will also tell you when a number is a floor rather than an answer, and when an
|
||||
audience resolves to nobody at all and why.
|
||||
|
||||
## The ceiling, and why a rule will not offer the audience you expected
|
||||
|
||||
Every trigger declares the **widest audience a rule may ever give it**. It is the security
|
||||
boundary of the whole system, and it is set in code by whoever declared the event, not in
|
||||
the admin panel. Staff-only events cannot be widened into public ones by anybody, including
|
||||
you.
|
||||
|
||||
Seven values, and they are a **tree, not a ladder**:
|
||||
|
||||
| Ceiling | Who that is |
|
||||
| --- | --- |
|
||||
| `everyone` | Everyone, including signed-out visitors |
|
||||
| `authenticated` | Any signed-in user |
|
||||
| `subscribers` | Signed-in users subscribed to this event |
|
||||
| `members` | Members of a module-declared list |
|
||||
| `staff` | Staff only — admins, editors and moderators |
|
||||
| `admin` | Administrators only |
|
||||
| `owner` | Only the user the event is about |
|
||||
|
||||
<Aside type="note" title="Fewer people is not less exposure">
|
||||
The tempting reading is a ladder — that a staff-only event could obviously also go to just
|
||||
one person. It cannot, and the example is the whole argument: cheat detection is a
|
||||
staff-only event, and "just one person" would be *the player it was detected on*. The
|
||||
question a ceiling answers is never how many, it is **which**.
|
||||
</Aside>
|
||||
|
||||
So `staff` does not permit `owner`, `members` does not permit `subscribers`, and the editor
|
||||
simply does not offer you the audiences the trigger forbids. The one exception proves the
|
||||
rule: `admin` sits under `staff`, because every administrator really is staff.
|
||||
|
||||
## The trigger catalog
|
||||
|
||||
**Admin → Engagement → Triggers** lists every event a rule can be built on, and it is
|
||||
read-only on purpose — **there is no table behind it**. A trigger is declared in code, by
|
||||
the site or by an installed module, so what you are looking at is whatever registered on
|
||||
this boot. Uninstall a module and its triggers stop appearing; nothing was deleted.
|
||||
|
||||
Two things it shows that are invisible everywhere else:
|
||||
|
||||
- **The variables** each event carries, with an example of each. This is the list a template
|
||||
is allowed to reference — when a message comes out with a hole in it, this is the screen
|
||||
that says why.
|
||||
- **The ceiling**, so when the rule editor offers you a narrower set of audiences than you
|
||||
expected, you can see the number it is obeying.
|
||||
|
||||
### Dormant rules
|
||||
|
||||
A rule can be switched on and still be unable to fire — most often because the module that
|
||||
declared its trigger, or the audience it points at, is no longer installed. Those are
|
||||
badged **dormant** in the list, with the reason, because "this rule cannot fire" is a
|
||||
different fact from "this rule is off" and you need both. The on/off switch keeps working
|
||||
on a dormant rule, deliberately: a rule whose module has gone is exactly the rule you most
|
||||
want to be able to stop.
|
||||
|
||||
## The send log
|
||||
|
||||
**Admin → Engagement → Send Log** answers one question: *did that person get that message,
|
||||
and if not, why not?* Every attempt is a row — when, what fired it, which user, which
|
||||
channel, and the result. Filter by result to go straight to what failed.
|
||||
|
||||
| Result | What it means |
|
||||
| --- | --- |
|
||||
| **Sent** | Handed to the channel successfully |
|
||||
| **Failed** | The attempt errored — the reason is on the row, not hidden in a tooltip |
|
||||
| **Not sent** | Suppressed before it was attempted: unsubscribed, unverified, or on the [suppression list](/docs/administration/troubleshooting/) |
|
||||
| **Bounced** | The receiving server rejected it after the fact |
|
||||
| **Marked as spam** | The recipient reported it |
|
||||
|
||||
Test sends from the template editor land here too, labelled as such, so you can confirm
|
||||
your own test arrived before turning a rule on for real.
|
||||
|
||||
<Aside type="tip" title="Two things it will not show you, on purpose">
|
||||
**The email address.** The log stores a one-way hash of it — enough to tie a bounce back to
|
||||
a delivery, not enough to become a second address book.
|
||||
|
||||
**A name.** It holds the user id, and that is deliberate: joining the account list in would
|
||||
quietly turn a delivery log into a staff-readable directory. Paste the id into Moderation,
|
||||
which is where a person's record belongs.
|
||||
</Aside>
|
||||
|
||||
## What a game module brings
|
||||
|
||||
A module declares its own triggers and its own audiences, in its own vocabulary, and it may
|
||||
ship rules and message bodies to go with them. The Ultima Online module ships a large family
|
||||
of them — houses falling to ruin, vendors running out of gold, a governor being seated, a
|
||||
Team's fortunes — written in the voice of an in-world office rather than a system alert.
|
||||
|
||||
All of them arrive **disabled**, like every other seeded rule. Read the list in
|
||||
**Admin → Engagement → Triggers**, turn on the ones your site should send, and check the
|
||||
send log the first time each one fires.
|
||||
209
src/content/docs/docs/administration/events.mdx
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
title: Scheduled events
|
||||
description: Author an event as phases and steps, price it against this deployment's caps before it runs, and let it change a live game world unattended — with a ledger that makes the undo automatic.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import GameExample from '../../../../components/GameExample.astro';
|
||||
|
||||
An **event** is a scheduled, bounded, audited change to a live game world. You write it once
|
||||
as a sequence of phases, publish a version of it, put it on the calendar, and it runs — at
|
||||
four in the morning if that is when you scheduled it, with nobody watching.
|
||||
|
||||
That last clause is the whole reason this feature is shaped the way it is. Everything below
|
||||
that looks like extra ceremony — the switchboard, the caps, the dry run, the ledger — is
|
||||
there because the thing being automated is somebody's game world, and the person who
|
||||
authored the change is asleep when it happens.
|
||||
|
||||
**Core owns the engine; the installed module owns the meaning.** Core decides whether an
|
||||
action is permitted, when it runs, in what order, how many times, within what budget, what
|
||||
it created and who is told. The module says which verbs exist and performs them. Core never
|
||||
learns a game word: every label you see in the step editor came from the module that
|
||||
registered it.
|
||||
|
||||
## Where it is
|
||||
|
||||
**Admin → Events**, its own group in the sidebar:
|
||||
|
||||
| Row | Who sees it |
|
||||
|---|---|
|
||||
| **Events** — the definitions, and their runs | Admin, editor, moderator |
|
||||
| **Calendar** — month and list view, with series | Admin, editor, moderator |
|
||||
| **Actions** — what this deployment permits, and the caps | **Admin only** |
|
||||
| **My participation** — your own attendance | Everyone |
|
||||
|
||||
Reading is staff-wide on purpose. A moderator's power over this feature is the **run
|
||||
console** — the screen you open when an event is doing something wrong at two in the
|
||||
morning — and hiding it from the one role that exists for incident response would be a
|
||||
strange way to build an incident tool. The narrower gates are on the actions, not the rows:
|
||||
authoring is admin and editor, publishing a version and starting a run are admin only, and
|
||||
all of it is enforced on the server rather than by hiding a button.
|
||||
|
||||
## Authoring
|
||||
|
||||
A **definition** is the thing that gets listed, searched, scheduled and audited: a title, a
|
||||
slug, a storyline, a schedule, and an ordered list of **phases**. Each phase holds **steps**,
|
||||
and a step is one action with its parameters.
|
||||
|
||||
A phase advances on a condition — after a duration, or when something happens in the game a
|
||||
given number of times. The vocabulary of "something that happens" is the trigger catalog the
|
||||
installed module already ships, so a module gains phase conditions by declaring one more
|
||||
entry in a list it already had.
|
||||
|
||||
<Aside type="note" title="A timeline, not a node graph">
|
||||
The phase editor is a vertical list, deliberately. The condition grammar has no branching —
|
||||
it is `and` / `or` / `not` over comparisons and nothing else — and a canvas would advertise
|
||||
power the engine does not have. Phases in order, each with its steps, its advance condition,
|
||||
its budget draw and its failure policy, is exactly what it can do.
|
||||
</Aside>
|
||||
|
||||
### Versions are immutable, and a run pins one
|
||||
|
||||
Publishing takes a snapshot. The run that starts on Saturday holds the version that was
|
||||
published, not the one you edited on Friday — which is what makes a run reproducible and an
|
||||
audit answerable after a change. **A running event cannot be edited**; you edit the
|
||||
definition, publish a new version, and the next run picks it up.
|
||||
|
||||
## Nothing is enabled until you enable it
|
||||
|
||||
**Admin → Events → Actions** lists every action the installed modules registered, and
|
||||
**everything above a notification arrives switched off.** Installing a module must never
|
||||
start doing things to your world.
|
||||
|
||||
Each row has two controls: whether the action is permitted on this deployment at all, and its
|
||||
**per-run caps** — how much of a budget dimension one run may consume. Dimensions are
|
||||
declared by the module, and consumption is counted in the database with a conditional
|
||||
update, not checked in application code.
|
||||
|
||||
<GameExample game="uo">
|
||||
The Ultima Online module declares `uo.creatures`, `uo.bosses`, `uo.rewards` and others —
|
||||
one per kind of thing an event can spend.
|
||||
</GameExample>
|
||||
|
||||
That distinction matters more than it sounds. A stolen admin session has already passed every
|
||||
role check there is; it still cannot exceed the cap, because the cap is a condition on the
|
||||
`UPDATE` that spends the budget.
|
||||
|
||||
<Aside type="caution" title="A cap breach is a refusal, not a failure">
|
||||
A step that would exceed a cap does not run, does not retry, and is recorded `refused` with
|
||||
the dimension and both numbers — *"asks for 12 of `uo.creatures`; 0 of 5 is already spent this
|
||||
run"*. That is an authoring mistake being reported to the author, not an outage.
|
||||
</Aside>
|
||||
|
||||
## Dry run before anything unattended
|
||||
|
||||
**Verify** materialises the whole plan without touching the world: every step is dispatched
|
||||
with a verify flag, and you get back what *would* happen and what it *would* cost against the
|
||||
caps, in the module's own words. Refusals show up here, before the calendar entry exists.
|
||||
|
||||
A definition that has never been verified is exactly the one worth not scheduling. Verifying
|
||||
is cheap, and it is the last point a human sees the plan.
|
||||
|
||||
## Running one
|
||||
|
||||
Runs start on the schedule, or by hand. A **series** groups definitions into an arc, so a
|
||||
three-part story reads as one thing on the calendar rather than three unrelated entries.
|
||||
|
||||
The **run console** shows live status, the steps and their attempts, the budget consumed
|
||||
against each cap, any failures, and the cleanup. Its controls are:
|
||||
|
||||
- **Pause** and **resume** — resume carries a run past any settled step, including one that
|
||||
failed or was refused.
|
||||
- **Skip**, **retry** and **confirm** a single step. *Confirm* is how a human-cue step
|
||||
advances: the run posts the instruction, waits, and moves on when somebody says they did it.
|
||||
- **Advance** a phase by hand.
|
||||
- **Cancel**, with or without cleanup.
|
||||
|
||||
Every one of those is logged with the person who did it.
|
||||
|
||||
## What an event does to a world, and how it is undone
|
||||
|
||||
Two different things, and the difference is the whole safety story.
|
||||
|
||||
**What it owns.** Creatures, bosses, oracle NPCs, decoration, a temporary gate — things the
|
||||
run created. Each one is written to a **resource ledger** as it is made, with the run and
|
||||
step that made it.
|
||||
|
||||
**What it borrows.** A spawner's respawn timer, a starting skill cap, a seasonal flag — values
|
||||
that already existed and are being changed for the duration. Those are **leases**: the game
|
||||
keeps the original, the site records both halves, and the lease carries its own deadline.
|
||||
|
||||
<Aside type="tip" title="Cleanup is generated, never authored">
|
||||
There is no undo phase for you to write, and that is on purpose: an operator cannot be relied
|
||||
on to write the undo, and an aborted run never reaches the phase they wrote it in. Teardown
|
||||
steps are derived from the ledger and run on **every** terminal path — completion,
|
||||
cancellation and abort alike.
|
||||
|
||||
A lease is safer still. The game restores the baseline when the deadline passes whether or not
|
||||
it ever hears from the site again, and a lease is never written to disk — so a game-server
|
||||
restart puts every borrowed value back too.
|
||||
</Aside>
|
||||
|
||||
## The game server has its own switches
|
||||
|
||||
They live in the bridge plugin's config on the game server's host, not in the site's
|
||||
database, and no event can turn them on.
|
||||
|
||||
**`EventsEnabled` is off by default**, in both games. Turning it on is consenting to the site
|
||||
changing and watching your world unattended.
|
||||
|
||||
<GameExample game="uo">
|
||||
`EventsEnabled` is a different switch from `AdminWriteEnabled`. Turning the admin plane on is
|
||||
consenting to staff moderation driven from a screen somebody is looking at; turning events on
|
||||
is consenting to unattended changes. One switch could not honestly express both. Every key
|
||||
is in [`Bridge.cfg`](/docs/ultima-online/bridge-cfg/), which only the shard host can edit.
|
||||
</GameExample>
|
||||
|
||||
<GameExample game="rust">
|
||||
`EventsEnabled` is in each server's [`RunicGateway.json`](/docs/rust/runicgateway-json/). An
|
||||
administrator can edit it on the host, or from the site's
|
||||
[Mod config](/docs/rust/mod-config/) screen, which reaches the game host's config files
|
||||
through the bridge.
|
||||
</GameExample>
|
||||
|
||||
Beside it sit the game's own ceilings — how much one call may place, how long something it
|
||||
creates may stand, how much one run may own in total. **They refuse rather than clamp**, for
|
||||
the same reason the caps do: a quietly shortened request leaves the two halves disagreeing
|
||||
about what actually happened.
|
||||
|
||||
## What players see
|
||||
|
||||
The public calendar at `/site/events` carries what is scheduled, what is happening now, what
|
||||
finished recently, and published results. A run that was cancelled says so — *"Did not
|
||||
happen"* — rather than quietly disappearing.
|
||||
|
||||
**Listing is separate from publishing.** A definition has its own *listed* switch, because
|
||||
publishing is what makes an event runnable and a surprise invasion should not have to be
|
||||
advertised a fortnight in advance in order to be allowed to happen. Unlisting hides the
|
||||
definition, its runs and its results from the public pages and from a participant's own
|
||||
history; it hides nothing from staff.
|
||||
|
||||
Where a module can tell who took part, a run can keep a **participation ledger** — scores and
|
||||
ranks, published as a results table when the run finishes. Ranks are computed at publication
|
||||
and stored, so somebody added afterwards does not silently renumber a table people have
|
||||
already read. A signed-in person sees their own attendance under their account, and staff see
|
||||
theirs on the same screen.
|
||||
|
||||
## When something goes wrong
|
||||
|
||||
- **`degraded` is not `failed`.** If the game server disappears mid-run, the run degrades,
|
||||
world-changing steps park unattempted, and it recovers when the connection does. The public
|
||||
page does not say so — that is operator information.
|
||||
- **`refused` means a bound said no**, and it is reported with the numbers.
|
||||
- **The run log answers "why did phase 3 not start?"** as a query, not by reading a wall of
|
||||
text. It is kept for 90 days after a run reaches a terminal state — and a run still in
|
||||
flight keeps every line it has, however old, because the question it answers is still open.
|
||||
- **Cleanup can be re-run** from the run console if a teardown was interrupted.
|
||||
|
||||
## Where the record is
|
||||
|
||||
[`website/EVENTS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/EVENTS.md)
|
||||
is the design of record — the model, the data, the security argument and what was deliberately
|
||||
left out.
|
||||
[`website/MODULE_API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md)
|
||||
is the contract a module registers its verbs against, and
|
||||
[`link/ADMIN_CONTROLS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/ADMIN_CONTROLS.md)
|
||||
is what the site may ask a game to do at all.
|
||||
|
||||
For how the engine is put together, see
|
||||
[Events architecture](/docs/architecture/events-architecture/).
|
||||
@@ -102,7 +102,7 @@ Three rules for whatever proxy you use:
|
||||
- **Terminate TLS at the proxy.** The app speaks HTTP; it is not meant to hold a
|
||||
certificate.
|
||||
|
||||
## Upgrading the shard side
|
||||
## Upgrading the game server side
|
||||
|
||||
A different deployment on a different host, and it moves on its own schedule:
|
||||
|
||||
@@ -111,15 +111,18 @@ sudo runicgateway update # re-resolves the bundle; --verify to see it first
|
||||
sudo runicgateway doctor # confirm afterwards
|
||||
```
|
||||
|
||||
`update` replaces the sidecar and restarts its service, re-syncs the overlay, and tells you
|
||||
when ServUO needs restarting — it never restarts your shard itself. Because it resolves a
|
||||
**bundle**, the sidecar and the plugin move together and cannot end up disagreeing about the
|
||||
protocol.
|
||||
`update` replaces the sidecar and restarts its service, redeploys the bridge plugin, and
|
||||
tells you when the game server needs restarting — it never restarts your game server itself.
|
||||
Because it resolves a **bundle**, the sidecar and the plugin move together and cannot end up
|
||||
disagreeing about the protocol. Add the game's own flags as you did at install; see the
|
||||
[Installer CLI](/docs/reference/installer-cli/).
|
||||
|
||||
Each game can have its own day-two chores on top of this. Ultima Online's are in [its
|
||||
group](/docs/ultima-online/client-files/#after-a-client-update).
|
||||
|
||||
<Aside type="note" title="Update the two sides in either order, but verify after each">
|
||||
They are independent deployments joined by a version-checked contract: a mismatch is
|
||||
rejected with a `409` rather than mis-parsed. So the worst case is a bridge that refuses to
|
||||
pair until both sides are current — visible on
|
||||
[the shard connection screen](/docs/administration/the-shard-connection/), and not silent
|
||||
corruption.
|
||||
pair until both sides are current — visible on the game module's connection screen, and
|
||||
not silent corruption.
|
||||
</Aside>
|
||||
|
||||
@@ -4,10 +4,13 @@ description: The five states a module can be in, installing and upgrading, disab
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import Screenshot from '../../../../components/Screenshot.astro';
|
||||
|
||||
Installing your first module is [Getting started](/docs/getting-started/install-a-game-module/).
|
||||
This is what the screen means afterwards.
|
||||
|
||||
<Screenshot id="admin-modules" />
|
||||
|
||||
## The five states
|
||||
|
||||
`installed → enabled → started`, with `disabled` and `startup_failed` as recoverable
|
||||
@@ -38,6 +41,10 @@ Two consequences of how boots work:
|
||||
Paste the new release's install-manifest URL and press Install. The bundle is verified
|
||||
against its `sha256`, unpacked over the old one, and takes effect at the restart.
|
||||
|
||||
**A site runs one module.** Installing a module with a different id beside the one you have
|
||||
is refused with `409`, and nothing is downloaded. To change game, remove the installed module
|
||||
first.
|
||||
|
||||
An upgrade **deliberately leaves the state alone**: upgrading an enabled module must not
|
||||
silently switch it off, and re-installing a disabled one must not silently switch it on.
|
||||
|
||||
|
||||
133
src/content/docs/docs/administration/message-templates.mdx
Normal file
@@ -0,0 +1,133 @@
|
||||
---
|
||||
title: Message templates
|
||||
description: Edit what your site's email actually says — the block editor, the variable palette, the preview, test sends, and the send log that tells you whether a message arrived.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
Every message your site sends — password resets, invitations, notifications — is a
|
||||
**template** you can edit. They ship working, so a fresh site mails correctly before you
|
||||
open this screen at all. You come here when you want it to sound like your community.
|
||||
|
||||
**Admin → Engagement → Templates.**
|
||||
|
||||
## What is in the list
|
||||
|
||||
Each row is one message. The ones marked **system** are the ones the site itself depends
|
||||
on: the password reset, the invitation, the address-confirmation mail. You can edit every
|
||||
word of those, but you cannot delete them — a site with no password-reset body is a site
|
||||
where nobody can get back in.
|
||||
|
||||
The rest are the general-purpose bodies that rules send. Those you can delete, as long as
|
||||
no rule is currently pointing at one.
|
||||
|
||||
<Aside type="tip" title="Your edits survive upgrades">
|
||||
When you edit a shipped template, the site remembers that a person changed it. Later
|
||||
versions may ship an improved default for the same message — and it will **not** be applied
|
||||
over your words. You will see a note on the row telling you a newer default exists, and it
|
||||
is up to you whether to look at it.
|
||||
</Aside>
|
||||
|
||||
## Editing a message
|
||||
|
||||
The editor has the message on the left and a live preview on the right.
|
||||
|
||||
### The body is blocks, not HTML
|
||||
|
||||
You build a message out of pieces: a heading, a paragraph, a button, a divider, an image,
|
||||
or an item list. Add one from the row of buttons, click it to edit it, and use the arrows
|
||||
to move it. There is no HTML to write, which is deliberate — email HTML is a genuinely
|
||||
horrible format, and the blocks already produce something that survives Outlook.
|
||||
|
||||
### Variables are chosen, never typed
|
||||
|
||||
Under most text fields is a row of small grey names: `siteName`, `resetUrl`, `title`. Those
|
||||
are the **variables** this particular message is given when it is sent. Click one and it is
|
||||
inserted as a token; the message that goes out has the real value in its place.
|
||||
|
||||
You cannot invent a variable. If you type one the message is not given — a typo, or a name
|
||||
you remembered from a different message — the save is refused and the error names the
|
||||
variable. That is on purpose: a variable that does not exist renders as *nothing*, so
|
||||
without the check the mistake would be invisible until it reached somebody's inbox as a
|
||||
sentence with a hole in it.
|
||||
|
||||
To see every variable a given event provides, with an example of each, look at
|
||||
**Admin → Engagement → Triggers**.
|
||||
|
||||
### Both halves of the message
|
||||
|
||||
Every email goes out in two forms: the designed HTML one, and a plain-text one for clients
|
||||
that will not show HTML. The plain-text half is generated from your blocks automatically,
|
||||
and you can see it under the **Plain text** tab.
|
||||
|
||||
If the generated version is not good enough, write your own in **Plain-text part** at the
|
||||
bottom of the editor. Whatever you write there replaces the generated text completely.
|
||||
|
||||
A published message must have *something* in its text part. If every block you used
|
||||
contributes nothing to it — a message made only of dividers and images, say — the save is
|
||||
refused.
|
||||
|
||||
### Draft and published
|
||||
|
||||
A **draft** is not what goes out. While a message is a draft, the site sends the shipped
|
||||
default in its place, so you can leave something half-finished without breaking anything.
|
||||
Switch it to **Published** when you want your version to be the one people receive.
|
||||
|
||||
## The preview
|
||||
|
||||
The preview is rendered by the server using the same code that renders the real message, so
|
||||
what you see is what will arrive — not an approximation drawn by the browser.
|
||||
|
||||
It fills the variables in with example values, so you never need to trigger a real event to
|
||||
see what a message looks like.
|
||||
|
||||
Three controls are worth knowing:
|
||||
|
||||
- **Desktop / Mobile** — the same body at a reading-pane width and a phone width.
|
||||
- **Dark mode** — an approximation of what mail clients that invert light messages will do
|
||||
to yours. Worth a glance: a design that relies on a light background can come out as
|
||||
dark-on-dark for a large minority of readers.
|
||||
- **Plain text** — the other half of the message, as described above.
|
||||
|
||||
## Sending yourself a test
|
||||
|
||||
The **Send a test** box sends the message to any address you type, through whatever mail
|
||||
transport the site is configured with (**Admin → Settings → Email delivery** — see
|
||||
[Notifications and email](/docs/administration/notifications-and-email/)).
|
||||
|
||||
It sends **what is on screen**, saved or not. That is the point of it: try a wording, send
|
||||
it to yourself, look at it in a real inbox, and only then decide whether to save.
|
||||
|
||||
Test sends are recorded in the send log like any other message, including when they fail.
|
||||
|
||||
## Making a new template
|
||||
|
||||
You do not start from a blank page. Pick a message that is close to what you want, press
|
||||
**Duplicate**, and give the copy a key.
|
||||
|
||||
The **key** is how a rule refers to the template — `notify.team-welcome`, say. Lowercase
|
||||
letters, digits, dots and dashes, and it cannot be changed later, so pick one that will
|
||||
still make sense in a year.
|
||||
|
||||
The copy always starts as a draft. Once you are happy with it, publish it and point a rule
|
||||
at it in **Admin → Engagement → Rules**.
|
||||
|
||||
<Aside type="caution" title="A template a rule is using cannot be deleted">
|
||||
If you try, the site tells you which rules are still pointing at it. Repoint or delete
|
||||
those first. The alternative — letting the delete through — would leave a rule that quietly
|
||||
stops producing mail, and nothing on screen would say why.
|
||||
</Aside>
|
||||
|
||||
## Did it arrive?
|
||||
|
||||
**Admin → Engagement → Send Log** lists every message the site tried to deliver, newest
|
||||
first, successes and failures alike. When mail is not arriving, this is the screen that
|
||||
tells you whether the site tried and the relay refused, or whether it never tried at all.
|
||||
|
||||
Failures carry the reason the mail server gave, which is usually the actual answer — a
|
||||
rejected sender address, a bad password, a relay that will not accept your domain.
|
||||
|
||||
The log does not store anybody's email address. It keeps a one-way fingerprint instead, so
|
||||
that a bounce can be matched back to a delivery without the log itself becoming a second
|
||||
copy of your members' addresses. The rest of that screen — and the rules that decide a
|
||||
message is sent at all — is [Engagement rules](/docs/administration/engagement-rules/).
|
||||
@@ -10,7 +10,7 @@ not overlap.
|
||||
|
||||
| Screen | Is about | Comes from |
|
||||
|---|---|---|
|
||||
| **Moderation** | Your **Discord** guild — bans, kicks, mutes, warnings, joins, leaves, filter and spam hits | the bot, captured live |
|
||||
| **Moderation** | Your **Discord** server — bans, kicks, mutes, warnings, joins, leaves, filter and spam hits | the bot, captured live |
|
||||
| **Reports** | **Team forum content** members have reported | the site |
|
||||
| **Appeals** | Sanctions people are asking you to reverse | the site |
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Notifications and email
|
||||
description: Email over Gmail OAuth2, the announcement pipeline and its legs, the Discord bot, and opt-in push to the mobile app.
|
||||
description: Email over SMTP, the announcement pipeline and its legs, the Discord bot, and opt-in push to the mobile app.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
@@ -9,21 +9,67 @@ Four separate delivery paths, each optional, each off until you configure it. A
|
||||
configures none of them still works — it just never reaches anyone who is not looking at
|
||||
it.
|
||||
|
||||
This page is about the paths themselves. What decides that a particular message gets sent
|
||||
down one of them is a rule — see [Engagement rules](/docs/administration/engagement-rules/).
|
||||
|
||||
## Email
|
||||
|
||||
**Admin → Settings → Email delivery.** The site sends contact-form messages (and test
|
||||
messages) through **Gmail over OAuth2**, delivered to the *Contact email* setting.
|
||||
**Admin → Settings → Email delivery.** The site sends contact-form messages, invitations,
|
||||
password resets, team notifications and test messages through **SMTP**. Contact-form mail
|
||||
goes to the *Contact email* setting.
|
||||
|
||||
It reuses the **Google authentication client**, so the order is fixed: configure Google on
|
||||
the [Authentication](/docs/administration/authentication/) page first, then press **Connect
|
||||
Gmail** here. Until then the panel reads *Unconfigured* and says exactly that.
|
||||
You pick a mail transport and fill in the fields it asks for. There is no consent flow and
|
||||
no redirect to bounce through — it is a form, and the credentials go straight into the
|
||||
database encrypted at rest, write-only: the panel will tell you a password is *set*, and
|
||||
will never show it to you again.
|
||||
|
||||
The refresh token it stores is encrypted at rest like every other secret.
|
||||
### Three ways to point it somewhere
|
||||
|
||||
<Aside type="note" title="There is no SMTP option">
|
||||
Gmail over OAuth2 is the only supported delivery path today. Until it is connected, the
|
||||
contact form falls back to a `mailto:` link to the contact address — which works, and puts
|
||||
the message in the visitor's own mail client rather than in your logs.
|
||||
Any SMTP server works. Which one you should use depends on how much mail you expect to send.
|
||||
|
||||
**A relay — the recommended one.** Mailgun, SES, Postmark or equivalent: their host, port
|
||||
`587`, *Implicit TLS* **off**, and your API key as the password. Deliverability is the hard
|
||||
part of sending mail — reputation, DKIM, bounce handling — and this is the option where
|
||||
somebody else owns it. Use this for anything with real volume.
|
||||
|
||||
**A mailbox provider over SMTP — the simplest.** For example `smtp.gmail.com`, port `587`,
|
||||
*Implicit TLS* **off**, your address as the username, and an
|
||||
[app password](https://support.google.com/accounts/answer/185833) — not your account
|
||||
password, and it requires 2-Step Verification to be on. Fine for a small site; subject to
|
||||
the provider's daily send caps.
|
||||
|
||||
**Your own MTA.** If you already run mail on the same host: its address, port `25`,
|
||||
*Implicit TLS* **off**, username and password blank. The site treats a username with no
|
||||
password as incomplete, since that authenticates as nobody.
|
||||
|
||||
<Aside type="caution" title="The two fields that cause most failures">
|
||||
**Implicit TLS** belongs *on* only for port **465**. On port `587` leave it **off** — the
|
||||
connection still upgrades to TLS, using STARTTLS. Port 587 with it on does not report an
|
||||
error; it hangs.
|
||||
|
||||
**Send from** must be an address the account is allowed to send as. Unlike a username, this
|
||||
is not verified when you save it — a server that refuses your sender rejects the mail for
|
||||
SPF/DMARC reasons that look like nothing at all from the outside. **Send test** is what
|
||||
proves it, and it names this specifically when it happens.
|
||||
</Aside>
|
||||
|
||||
Until a transport is configured, the contact form falls back to a `mailto:` link to the
|
||||
contact address — which works, and puts the message in the visitor's own mail client rather
|
||||
than in your logs. Invitations surface a copyable accept link instead, and password resets
|
||||
still answer normally.
|
||||
|
||||
<Aside type="note" title="Upgrading from the Gmail connect flow">
|
||||
Earlier versions authorised a mailbox with a **Connect Gmail** consent flow that borrowed
|
||||
the Google authentication client. That flow has been removed.
|
||||
|
||||
If your site used it, mail **stops** on upgrade until you enter SMTP credentials — and
|
||||
nothing errors when it does, because every sender degrades politely. The admin dashboard
|
||||
warns you while it is true. `smtp.gmail.com` port 587 with an app password is the shortest
|
||||
route back.
|
||||
|
||||
Single sign-on is unaffected: the Google provider exists for SSO in its own right, and email
|
||||
merely borrowed its credentials. Removing the borrow also removes a trap — rotating the SSO
|
||||
secret used to break outbound mail silently.
|
||||
</Aside>
|
||||
|
||||
## Announcements
|
||||
@@ -36,7 +82,7 @@ at the wrong host.
|
||||
Which legs exist depends on what has registered one:
|
||||
|
||||
- **Discord `#news`** is core's, and needs the bot below.
|
||||
- **A module may add its own.** The `uo` module adds an in-game town crier, so a news post
|
||||
- **A module may add its own.** The Ultima Online module adds an in-game town crier, so a news post
|
||||
is announced to players who are logged into the game and never visit the site.
|
||||
|
||||
A leg brings its own settings with it — the town crier's duration is a module setting, not
|
||||
@@ -44,7 +90,7 @@ a core one — which is why they are documented with the module rather than here
|
||||
|
||||
## The Discord bot
|
||||
|
||||
**Admin → Discord Bot**: enable it, give it the guild (server) ID and the bot token, and
|
||||
**Admin → Discord Bot**: enable it, give it the **Guild (server) ID** and the bot token, and
|
||||
save. The token is stored **encrypted in the database** and is never an environment
|
||||
variable.
|
||||
|
||||
@@ -75,14 +121,45 @@ Two properties matter for what you have to trust:
|
||||
Without `NTFY_PUBLIC_URL` / `NTFY_ALLOWED_ORIGINS`, the app simply shows push as
|
||||
unavailable for your instance — nothing breaks.
|
||||
|
||||
A tickle raised by an engagement rule carries a pointer to the matching item in the
|
||||
[on-site inbox](#on-site-notifications) where there is one, so the app opens on the thing
|
||||
that happened rather than on a list. It is still only a pointer: the content is fetched, not
|
||||
delivered.
|
||||
|
||||
## On-site notifications
|
||||
|
||||
The third way to reach somebody, and the only one that needs no relay, no mailbox and no
|
||||
app: an item in their **notification inbox** on the site itself. A bell in the header
|
||||
carries the unread count; the list lives at **Account → Notifications**.
|
||||
|
||||
Two things are worth knowing before you enable a rule that uses it:
|
||||
|
||||
- **It is the one channel that is on by default.** Push and email are opt-in — both reach
|
||||
somebody somewhere else, so both have to be asked for. An inbox item is a row on a page
|
||||
the person chose to open, so it is opt-*out*: they switch it off per notification under
|
||||
Account → Notifications → Settings.
|
||||
- **The body is plain text, always.** The in-app template renders through the same block
|
||||
editor as your mail, but only the text of each block is stored, so nothing an operator
|
||||
writes can become markup on somebody else's page. Links are site-relative or dropped.
|
||||
|
||||
Old, read items are pruned nightly (90 days by default). **Unread items are never pruned** —
|
||||
an inbox that quietly deleted things nobody had seen would make the unread badge meaningless.
|
||||
|
||||
## Who receives what
|
||||
|
||||
The per-person side of this lives in the player portal, not the admin panel: each member
|
||||
chooses which Team and forum notifications they want, and how. Two defaults are worth
|
||||
knowing because they are not symmetrical:
|
||||
The per-person side of this lives in the player portal, not the admin panel: **Account →
|
||||
Notifications → Settings** is a grid of every notification against every channel, and each
|
||||
member sets their own. The defaults are not symmetrical, and the asymmetry is deliberate:
|
||||
|
||||
- **Push is opt-out** once a device is registered.
|
||||
- **Email is opt-in.**
|
||||
- **Push is opt-in.**
|
||||
- **On the site is opt-out** — see above.
|
||||
- **Muting a Team silences all three for that Team**, whatever the grid says, without
|
||||
touching any of their other Teams.
|
||||
|
||||
The operator's side of the same question — which events exist, and how wide an audience each
|
||||
one may ever be given — is [Engagement rules](/docs/administration/engagement-rules/). When
|
||||
a message went nowhere and you want to know why, the send log there is the screen that says.
|
||||
|
||||
<Aside type="caution" title="Nothing here retries">
|
||||
The announcement dispatcher sends once, and the Team notification bridge states plainly that
|
||||
|
||||
@@ -9,8 +9,8 @@ Teams are a core platform primitive: membership, roles, forums, notifications, m
|
||||
and the Discord integrations are all core's, and none of it knows what a Team *is* in your
|
||||
game.
|
||||
|
||||
**Core cannot create a Team.** Teams arrive from the installed module — with the `uo`
|
||||
module, they are the shard's guilds. On a deployment with no module, the Team machinery is
|
||||
**Core cannot create a Team.** Teams arrive from the installed game module, which maps
|
||||
whatever the game calls its groups of players onto a Team. On a deployment with no module, the Team machinery is
|
||||
present and permanently empty. That is not a bug to work around; it is the contract that
|
||||
lets the same forum, notification and moderation code serve any game.
|
||||
|
||||
@@ -25,15 +25,14 @@ reconciles them.
|
||||
**Admin → Teams** shows a sync panel per module: last attempt, last success, consecutive
|
||||
failures and the last error, with **Sync now** and **Resync now**.
|
||||
|
||||
The wording on that panel is exact and worth reading:
|
||||
|
||||
> Core has never had an answer it could trust. What is shown below is not a confirmed empty
|
||||
> shard.
|
||||
The wording on that panel is exact and worth reading. Until a sync has succeeded, it says
|
||||
that core has never had an answer it could trust, and that the list below it is not a
|
||||
confirmed empty one.
|
||||
|
||||
An empty list therefore means one of two very different things — there are no Teams, or
|
||||
nobody could ask. The panel tells you which, and a *last success: never* with a *last
|
||||
error* of `no uo-link configured` is the second. Fix
|
||||
[the shard connection](/docs/administration/the-shard-connection/) and sync again.
|
||||
nobody could ask. The panel tells you which: a *last success: never* with a *last error*
|
||||
that names the game connection is the second. Fix the game module's connection to its game
|
||||
server and sync again. Each game's group in the sidebar covers its own connection screen.
|
||||
|
||||
## Forums
|
||||
|
||||
@@ -48,6 +47,52 @@ Two rules are structural rather than settings:
|
||||
about a leader has to reach someone above them. See
|
||||
[Moderation](/docs/administration/moderation/).
|
||||
|
||||
## Team notification emails
|
||||
|
||||
**Team emails are sent by the engagement rules, and they arrive switched off.**
|
||||
|
||||
Someone posting in a Team forum used to send mail with no configuration at all. It now goes
|
||||
through the same engine as everything else the site sends: the forum post raises an event,
|
||||
an **engagement rule** decides who is told and through which message template, and the
|
||||
outbox delivers it. Push notifications to the app and the Discord bridge below are
|
||||
unaffected — only the email moved.
|
||||
|
||||
The practical consequence on an existing site: **nobody gets Team email until you turn a
|
||||
rule on.** Open **Admin → Engagement → Rules**. Four rules are waiting there, one per Team
|
||||
event, all switched off, and the screen says so at the top for as long as they all are.
|
||||
Switch on the ones your site wants.
|
||||
|
||||
| Rule | Sends when |
|
||||
|---|---|
|
||||
| **Team forum posts** | someone posts a new thread or reply |
|
||||
| **Team announcements** | a leader posts an announcement |
|
||||
| **Team — new member** | someone joins, at most once an hour per person |
|
||||
| **Team — leadership change** | a new leader is named, at most once an hour per person |
|
||||
|
||||
The first two are the ones most sites want. The last two describe things that already show
|
||||
up on the Team's activity feed and arrive from a sweep rather than from a person doing
|
||||
something — which is why they ship off and with a cooldown.
|
||||
|
||||
<Aside type="note" title="Members still control their own mail">
|
||||
A rule decides whether the site sends at all. Each member still chooses, per Team, between
|
||||
no email, one message per post, and a daily digest — on their own notifications screen or
|
||||
through the unsubscribe link in any Team email. Turning a rule on does not sign anybody up.
|
||||
</Aside>
|
||||
|
||||
**Digests are re-read at the moment they are sent**, not assembled as posts arrive. A site
|
||||
that was down for two days sends one digest rather than two days of backlog, a post a
|
||||
moderator hid is not in it, and somebody who lost access to a forum between the post and the
|
||||
send does not receive it.
|
||||
|
||||
**Unsubscribe links keep working.** A link in mail sent before this change still does what
|
||||
it says. What changed is that it is now precise: it stops the emails it came with and leaves
|
||||
that Team's push notifications alone, where before it silenced both.
|
||||
|
||||
You can change what any of these messages say — see
|
||||
[Message templates](/docs/administration/message-templates/) — decide which of them are sent
|
||||
at all under [Engagement rules](/docs/administration/engagement-rules/), and see who was
|
||||
actually sent what in **Admin → Engagement → Send log**.
|
||||
|
||||
## The Discord bridges
|
||||
|
||||
Two integrations, both optional, both configured from **Admin → Teams**.
|
||||
@@ -59,8 +104,8 @@ event leaves the site.
|
||||
|
||||
**Voice channels** — gives each Team a Discord voice channel of its own, with access
|
||||
granted by a per-Team role, so a Team's members can see and join theirs and nobody else
|
||||
can. It needs the bot reachable, and members need a linked Discord account and guild
|
||||
membership.
|
||||
can. It needs the bot reachable, and members need a linked Discord account and membership of
|
||||
your Discord server.
|
||||
|
||||
Its three settings deserve a thought each:
|
||||
|
||||
@@ -68,10 +113,10 @@ Its three settings deserve a thought each:
|
||||
|---|---|
|
||||
| **Minimum members** | How large a Team must be to get a channel. Every active member counts, linked account or not. |
|
||||
| **Grace window (days)** | How long a Team keeps its channel after it stops qualifying. A Team that recovers inside the window keeps the same channel; zero removes it on the next pass. |
|
||||
| **Staff roles** | Roles that can see and join every Team's channel. Guild administrators already can, so this is for staff who are not administrators. |
|
||||
| **Staff roles** | Roles that can see and join every Team's channel. Discord server administrators already can, so this is for staff who are not administrators. |
|
||||
|
||||
<Aside type="caution" title="Voice channels are a per-guild ceiling, not a per-Team one">
|
||||
Discord's role and channel limits apply to the whole guild, so a site with many small Teams
|
||||
<Aside type="caution" title="Voice channels are a per-server ceiling, not a per-Team one">
|
||||
Discord's role and channel limits apply to the whole Discord server, so a site with many small Teams
|
||||
can exhaust them. The minimum-members setting is the lever that keeps the count sane, and
|
||||
it is easier to raise it before provisioning than to unpick channels afterwards.
|
||||
</Aside>
|
||||
|
||||
@@ -67,44 +67,98 @@ deployment has nothing supervising it — `npm start` in a terminal, a container
|
||||
|
||||
## The game screens are empty or say offline
|
||||
|
||||
Work outwards from the game, and stop at the first check that fails.
|
||||
Work outwards from the game, and stop at the first check that fails. The order is the same
|
||||
for every game; the commands are each game's own.
|
||||
|
||||
1. **In game:** `[bridge status` — `connected=False` means the shard cannot reach the
|
||||
sidecar.
|
||||
2. **On the shard host:** `curl -s http://127.0.0.1:8080/health` — `plugin_connected: true`
|
||||
is the value that matters.
|
||||
3. **On the shard host:** `runicgateway doctor` — checks the install record, every overlay
|
||||
file hash, the service, and that the sidecar and overlay agree on a protocol.
|
||||
4. **On the site:** the [shard connection screen](/docs/administration/the-shard-connection/)
|
||||
— its four indicators say which link is broken.
|
||||
1. **On the game server:** the bridge plugin says whether it is connected to the sidecar.
|
||||
2. **On the game server's host:** the sidecar's `/health` answers without a token, and
|
||||
*plugin connected* is the value that matters.
|
||||
3. **On the game server's host:** `runicgateway doctor` checks the install record, the
|
||||
files it deployed, the service, and that the sidecar and the bridge plugin agree on a
|
||||
protocol.
|
||||
4. **On the site:** the game module's connection screen says which link is broken.
|
||||
|
||||
Two log lines with specific meanings: **`409`** is a protocol mismatch (set the Protocol
|
||||
field to what `/health` reports), and **`401`** is the auth token (read the live one back
|
||||
with `uo-link-sidecar --print-config`; do not retype it from a screenshot).
|
||||
Two responses from a sidecar mean the same thing for every game: **`409`** is a protocol
|
||||
mismatch (the sidecar refuses rather than mis-parsing), and **`401`** is the auth token.
|
||||
|
||||
<Aside type="note" title="“Nothing changed and it stopped working” usually means a ServUO update">
|
||||
An update to the server tree can revert `Scripts.csproj`, at which point the plugin sits in
|
||||
the tree and never compiles — and ServUO ignores the script build's exit code, so the boot
|
||||
looks clean. `doctor` catches it by comparing file hashes against the install record.
|
||||
</Aside>
|
||||
Each game's group in the sidebar has its own troubleshooting page with the exact commands:
|
||||
[Ultima Online](/docs/ultima-online/troubleshooting/) and [Rust](/docs/rust/troubleshooting/).
|
||||
|
||||
## Teams are missing
|
||||
|
||||
Check the sync panel on **Admin → Teams** before anything else: *last success: never* with
|
||||
`no uo-link configured` means the shard connection, not the Team machinery. And on a site
|
||||
with **no module installed**, an empty Team list is correct and final — core cannot create
|
||||
a Team. See [Teams](/docs/administration/teams/).
|
||||
an error naming the game connection means the module could not ask its game server, not
|
||||
that the Team machinery is broken. And on a site with **no module installed**, an empty
|
||||
Team list is correct and final — core cannot create a Team. See
|
||||
[Teams](/docs/administration/teams/).
|
||||
|
||||
## Email and announcements never arrive
|
||||
|
||||
- **The contact form opens a mail client.** Email delivery is not connected; that is the
|
||||
documented fallback. Connect Gmail in **Settings → Email delivery** — after configuring
|
||||
the Google provider, which it reuses.
|
||||
- **The contact form opens a mail client.** Email delivery is not configured; that is the
|
||||
documented fallback. Enter SMTP credentials in **Settings → Email delivery**. If this site
|
||||
used to send mail and stopped, the Gmail connect flow was removed — the admin dashboard
|
||||
says so, and [Notifications and email](/docs/administration/notifications-and-email/) has
|
||||
the migration.
|
||||
- **Mail is configured but nothing arrives, and there is no error.** Two usual causes, both
|
||||
invisible without a test send. *Implicit TLS* left on for port 587 hangs rather than
|
||||
failing; and a **Send from** address the server will not let you send as is rejected for
|
||||
SPF/DMARC reasons. Press **Send test** — its failure message names both cases.
|
||||
- **Email was working and the toggle is still on.** *Enable email sending* now gates every
|
||||
message, not just some of them. If it is off, nothing is sent, including the contact
|
||||
form.
|
||||
- **A published post announced nothing.** The Discord bot is a separate container. If the
|
||||
Discord Bot screen says *bot unreachable*, it is not running.
|
||||
- **A missed announcement does not come back.** Nothing retries; the post itself is still
|
||||
on the site.
|
||||
|
||||
## Nothing is sent for one particular event
|
||||
|
||||
Mail works, other notifications arrive, but this one thing never produces anything. The
|
||||
answer is almost always in **Engagement → Rules**, and it is one of four:
|
||||
|
||||
- **The rule is off.** Every rule ships disabled, including the ones your modules bring
|
||||
with them, so "installed" is not "on".
|
||||
- **The rule is badged *dormant*.** It is switched on but cannot fire — usually because the
|
||||
module that declared its trigger, or the audience it points at, is no longer installed.
|
||||
- **It fired and was held back by its own cooldown**, which is per person, per subject and
|
||||
per channel. The Send Log shows nothing for a message that was never queued.
|
||||
- **The audience resolves to nobody.** The rule editor's reach preview is the fastest way
|
||||
to find that out — it will tell you the count is zero and why.
|
||||
|
||||
[Engagement rules](/docs/administration/engagement-rules/) walks through all four.
|
||||
|
||||
## One person stopped receiving email
|
||||
|
||||
Everyone else is getting mail, so the transport is fine. Check
|
||||
**Engagement → Suppressions**, then **Engagement → Send Log**.
|
||||
|
||||
- **They are on the suppression list.** The site stops mailing an address once the
|
||||
receiving server says the mailbox does not exist. Addresses are stored one way and
|
||||
shown masked (`d***@example.com`), so search by their domain to find the row. If they
|
||||
have since fixed their mailbox, press **Lift a suppression** and type the full
|
||||
address — the screen genuinely does not have it, which is why you are asked.
|
||||
- **Suppression only affects engagement rules.** Password resets, invites and address
|
||||
verification still go out to a suppressed address, because those are things the person
|
||||
asked for themselves. So "they can reset their password but get no notifications" is
|
||||
the expected shape of this problem, not a contradiction.
|
||||
- **The Send Log says *Not sent*.** That is a suppression: nothing was sent to the mail
|
||||
server at all. *Bounced* means it was sent and the mailbox does not exist. *Failed*
|
||||
means the relay refused it for some other reason — that one is about your
|
||||
configuration, not about them.
|
||||
- **The Send Log has no row for them at all.** They were excluded before anything was
|
||||
queued. Either they have not opted in on **Notifications** for that stream, or
|
||||
*Require a verified email address* is on in **Settings** and they have not confirmed
|
||||
theirs. The rule editor's audience preview shows how many people each of those removes.
|
||||
|
||||
## Everyone stopped receiving email at once
|
||||
|
||||
Do **not** start clearing the suppression list — it is almost certainly not the cause.
|
||||
A whole-deployment stop is a transport problem: an expired password, a relay that has
|
||||
started refusing you, or *Enable email sending* switched off. The Send Log will show
|
||||
*Failed* rather than *Bounced* or *Not sent*, and **Settings → Email delivery** shows the
|
||||
last error. A wrong password never suppresses anybody; only the receiving server saying a
|
||||
specific mailbox does not exist does that.
|
||||
|
||||
## Uploads and modules fail with permission errors
|
||||
|
||||
Docker created a bind-mount source that the container user cannot write — usually because
|
||||
|
||||
@@ -4,6 +4,7 @@ description: The four roles and what each one reaches, creating accounts, and in
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import Screenshot from '../../../../components/Screenshot.astro';
|
||||
|
||||
## The four roles
|
||||
|
||||
@@ -24,6 +25,8 @@ Admin routes are re-validated against the database on **every request**, not jus
|
||||
Demoting an account takes effect at once — the open session does not keep its access until
|
||||
it expires.
|
||||
|
||||
<Screenshot id="admin-users" />
|
||||
|
||||
## Creating an account
|
||||
|
||||
**Admin → Users → + Add user** creates one directly: username, password, role, and it is
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: Authentication architecture
|
||||
description: One session model behind three very different front doors — cookies, bearer tokens and SSO — and where the boundaries actually are.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
The administrator's view of this is
|
||||
[Authentication](/docs/administration/authentication/). This is how it is built.
|
||||
|
||||
## One session service, three surfaces
|
||||
|
||||
The governing decision: **there is a single source of truth for sessions**, and every
|
||||
authentication surface produces the *same* session model.
|
||||
|
||||
```
|
||||
browser native app SSO provider
|
||||
(httpOnly JWT) (bearer + refresh) (OAuth2 / OIDC + PKCE)
|
||||
│ │ │
|
||||
└───────────────────┼────────────────────────┘
|
||||
▼
|
||||
sessionService
|
||||
createSession(user, authMethod)
|
||||
validateSession()
|
||||
```
|
||||
|
||||
Controllers call `createSession`; middleware calls `validateSession`. Nothing invents its
|
||||
own notion of "logged in".
|
||||
|
||||
That matters more than it sounds. Three front doors with three session implementations is
|
||||
three places for an authorization bug to hide, and the one that gets least attention is the
|
||||
one that gets exploited.
|
||||
|
||||
<Aside type="note" title="`utils/auth.js` is a facade">
|
||||
It exists for backward compatibility and is a thin wrapper. New work goes through the
|
||||
session service.
|
||||
</Aside>
|
||||
|
||||
## The three surfaces
|
||||
|
||||
**Web** — a JWT signed with `JWT_SECRET`, carried in an `httpOnly`, `sameSite=Lax` cookie.
|
||||
`secure` is decided **per request** (`COOKIE_SECURE=auto` → `secure: req.secure`), which is
|
||||
what lets one deployment work both over HTTPS through a proxy and over plain HTTP on a LAN
|
||||
address.
|
||||
|
||||
**Mobile** — short-lived bearer access tokens plus **rotated, hashed, revocable** refresh
|
||||
tokens. Hashed server-side, so a database disclosure does not hand over live sessions.
|
||||
|
||||
**SSO** — Google, Discord or a custom OIDC provider, PKCE-guarded.
|
||||
|
||||
## SSO is link-only, by policy
|
||||
|
||||
**An external identity must already be linked to an existing account.** Identities are
|
||||
never auto-provisioned.
|
||||
|
||||
This is a deliberate policy rather than an unimplemented feature. Auto-provisioning turns
|
||||
"anyone with a Google account" into "anyone with an account here", which is not a decision
|
||||
a site operator should make by installing an OAuth client.
|
||||
|
||||
## Admin is re-validated every request
|
||||
|
||||
Roles are **re-checked against the database on every admin request**, not trusted from the
|
||||
token.
|
||||
|
||||
The consequence is the point: a demoted user loses access **at once**, rather than when
|
||||
their token happens to expire. A stateless JWT that carried the role would keep asserting it
|
||||
for up to a day.
|
||||
|
||||
## Trusted devices gate the second factor only
|
||||
|
||||
A second, separate httpOnly cookie (`rg_trust`, 30 days by default) lets a browser or app
|
||||
**skip the TOTP step** on future logins — **never the password**.
|
||||
|
||||
Four properties, each chosen:
|
||||
|
||||
- It is **opaque and sha256-hashed server-side**, stored in a table. It is not a JWT claim,
|
||||
so the stateless session token is unchanged.
|
||||
- It is **per-row revocable**, from the admin panel or by the user.
|
||||
- It **deliberately outlives logout.** Logging out ends a session; it does not make the
|
||||
device untrusted, because the device is still the same device.
|
||||
- It is **cleared** on untrust, password change, password reset, or disabling TOTP.
|
||||
|
||||
**Recovery codes** (bcrypt, single-use) are the lockout fallback. Every trusted-device and
|
||||
MFA action is audit-logged.
|
||||
|
||||
## The login-hardening layer
|
||||
|
||||
Bot scoring with automatic IP banning, TOTP 2FA, a honeypot field, and rate limiting with
|
||||
backoff. The admin *Bot Activity* panel is deliberately **read plus emergency-unban only** —
|
||||
it is a window onto an automatic system, not a control surface for it.
|
||||
|
||||
## Where core's boundaries stop
|
||||
|
||||
Core's security boundaries end at **authentication, roles and the session**.
|
||||
|
||||
A module that serves game data brings its **own** audience rules, and core does not police
|
||||
them beyond the gates it hands over — `requireAuth`, `requireRole`, and the tier group
|
||||
gates. See [The module API](/docs/modules/the-module-api/#registerroutes-and-the-tier-gate).
|
||||
|
||||
The Ultima Online module's is the worked example, and it is a real boundary rather than a
|
||||
convenience filter: an admin-configurable, per-feature and per-field audience ladder with **fail-closed
|
||||
defaults**, applied at routes, at SSE subscribe time, *and* at the navigation. All three,
|
||||
because a surface that is filtered in only two of those places leaks through the third.
|
||||
|
||||
## Content Security Policy
|
||||
|
||||
`script-src 'self'` with **no inline script**, which is why [module chunks are served
|
||||
same-origin](/docs/modules/building-a-module/) and why an import map was never an option.
|
||||
|
||||
`form-action 'self'` is pinned explicitly rather than inherited, because it blocks an
|
||||
injected form POSTing credentials off-origin — an exfiltration path `connect-src` does not
|
||||
cover.
|
||||
|
||||
Violation reports go to a **same-origin** sink that stores nothing: reports describe attacks
|
||||
against this site and are not handed to a third-party collector. It parses both wire formats
|
||||
(browsers disagree), and always answers `204` even for malformed input — a `4xx` would make
|
||||
the error handler log attacker-supplied bodies and turn an open endpoint into a log-flood
|
||||
primitive.
|
||||
|
||||
## Canonical document
|
||||
|
||||
[`BACKEND_DESIGN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/BACKEND_DESIGN.md)
|
||||
§6 is normative for everything on this page.
|
||||
166
src/content/docs/docs/architecture/events-architecture.mdx
Normal file
@@ -0,0 +1,166 @@
|
||||
---
|
||||
title: Events architecture
|
||||
description: An event does not edit the world — it holds a lease. How a game-agnostic engine schedules changes to a live game world it cannot name.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
The Event System is a game-agnostic engine for **scheduled, bounded, audited** changes to a
|
||||
live game world. Core runs it and cannot name a single thing in your game.
|
||||
|
||||
The administrator's view is [Scheduled events](/docs/administration/events/).
|
||||
|
||||
## The two sentences the design turns on
|
||||
|
||||
**An event does not edit the world. It holds a lease.**
|
||||
|
||||
Anything an event changes that already existed is borrowed, not set: the game keeps the
|
||||
baseline, the site records both halves, and the lease carries its own deadline. When the
|
||||
deadline passes the game restores the value — whether or not it ever hears from the site
|
||||
again. A lease is never written to the game's save file either, so a server restart also
|
||||
puts every borrowed value back. That is the difference between automating a change and
|
||||
handing an unattended process a `[set` command.
|
||||
|
||||
**The module declares; core dispatches.** A module says a verb exists, what it costs and what
|
||||
it needs; core decides whether it is permitted, when it runs, in what order, how many times,
|
||||
within what budget, what it created and who is told. Nothing crosses that line as a string
|
||||
core interprets — the browser posts an action *id* and a params object, both validated
|
||||
against the registry before anything is dispatched. There is no passthrough field and no
|
||||
place a request body can name a game command.
|
||||
|
||||
## What is a table, and what deliberately is not
|
||||
|
||||
Eleven core tables, no ORM, and no migration system — which makes every table a permanent
|
||||
commitment. The rule applied was: **a table is for what must be queried, claimed or joined.**
|
||||
|
||||
| Kind | Where it lives |
|
||||
|---|---|
|
||||
| Definitions, series, versions, runs, steps, budget, resources, participants, gates, settings, log | Tables |
|
||||
| Phases | Configuration inside an immutable version snapshot. A phase has no identity a query needs; a step does |
|
||||
| Actions, budget dimensions, conditions | Registry entries a module declares at load. A stored one would outlive the module that can perform it |
|
||||
| A reward catalog | Neither. A reward is an ordinary action, so a granted reward is an ordinary ledger row |
|
||||
|
||||
**The step is the unit of execution, and it is a row** — one action invocation with a due
|
||||
time, a status, an attempt count and a claim. Retries, timeouts, duplicate execution and
|
||||
resumption after a crash are then all properties of that row rather than of a process's
|
||||
memory, which is what lets the runner be killed mid-run and pick up where it stopped.
|
||||
|
||||
**One run per occurrence, guaranteed by a unique index** on the definition, the scope and the
|
||||
scheduled instant — not by the claim. Two application instances cannot both start the same
|
||||
occurrence, because the second insert fails.
|
||||
|
||||
## Budgets are enforced in SQL
|
||||
|
||||
Consumption is spent with a conditional update:
|
||||
|
||||
```sql
|
||||
UPDATE event_run_budget
|
||||
SET consumed = consumed + ?
|
||||
WHERE run_id = ? AND dimension = ? AND consumed + ? <= cap
|
||||
```
|
||||
|
||||
No transaction, no read-then-write, and no way for two concurrent steps to both squeeze past
|
||||
the same ceiling.
|
||||
|
||||
<Aside type="tip" title="Why that is the strongest control here">
|
||||
A compromised admin session has already passed every role check the application has. It has
|
||||
not passed this one, because this one is not a check — it is a condition on the write. That is
|
||||
the reason per-run quotas were kept after the delegation model was dropped.
|
||||
</Aside>
|
||||
|
||||
## The ledger, and why cleanup is generated
|
||||
|
||||
Every world write appends to a resource ledger before it is confirmed: the run, the step, the
|
||||
owning module, an opaque kind and reference, and — for a borrowed value — the baseline
|
||||
alongside what was applied.
|
||||
|
||||
Teardown is then **derived from the ledger**, never authored, and runs on every terminal path:
|
||||
completion, cancellation and abort alike. An operator cannot be relied on to write the undo,
|
||||
and an aborted run never reaches the phase they wrote it in.
|
||||
|
||||
Two rules make that hold up:
|
||||
|
||||
- **A unique index across non-reverted rows** stops two events leasing the same target. The
|
||||
second one is refused rather than layered on top of the first.
|
||||
- **A restore is a compare-and-set.** If the current value is not what the lease applied,
|
||||
somebody else changed it since; the row is marked `drifted` rather than stamped over. The
|
||||
ledger would rather say "I do not know what happened here" than lie about having undone it.
|
||||
|
||||
## At-most-once, on a wire that can lose an answer
|
||||
|
||||
Every command the site sends the game carries an **idempotency key**, and the game executes a
|
||||
given key at most once — a repeat is answered with the original reply rather than re-run.
|
||||
|
||||
Without it, a lost acknowledgement is indistinguishable from a command that never applied, so
|
||||
every world write has to be declared un-retryable and one has to be *lost* rather than risk
|
||||
*doubling* it. The key is what makes a world-changing step an ordinary retried row like any
|
||||
other.
|
||||
|
||||
<Aside type="caution" title="The rule that pays for it">
|
||||
**Do not answer an error after changing the world.** The store treats a handler that ran and
|
||||
deliberately refused as a transient outcome and releases the key, so the answer is not frozen
|
||||
for ever — the acceptance walk found a refusal ("the last save was 227 seconds ago") replayed
|
||||
identically six times, with a number that could never age. A handler that has already changed
|
||||
something must not take that path.
|
||||
</Aside>
|
||||
|
||||
## Three layers, and the role check is only one of them
|
||||
|
||||
1. **Declaration** — a module says a verb exists. That is code the operator installed; it is
|
||||
not a permission.
|
||||
2. **Enablement** — an admin turns an action on for this deployment and sets its caps.
|
||||
Nothing above a notification is on by default.
|
||||
3. **Invocation** — the role check, then the cap, then the game's own switches. Admin routes
|
||||
are re-validated against the database on every request, so a demotion takes effect on the
|
||||
next click.
|
||||
|
||||
The game's switches are the layer outside the site's own database: they live in the bridge
|
||||
plugin's own config on the game server's host — `EventsEnabled`, in both games — and are off
|
||||
out of the box. No event and no role check can turn one on. On Rust an administrator can
|
||||
still edit that file from the game module's config screen, which reaches the host's config
|
||||
files through the bridge, so there it is a separate deliberate act rather than an unreachable
|
||||
one. The game's own ceilings **refuse rather than clamp** — because a silently shortened
|
||||
request leaves the two halves disagreeing about what happened.
|
||||
|
||||
<Aside type="note" title="Stated plainly">
|
||||
The module boundary is **not** a security boundary — a module runs in the same process with
|
||||
full access, and the module system's own documentation says so. None of the above defends
|
||||
against a hostile module. It defends against a compromised session and an operator mistake,
|
||||
both of which are made larger by *scheduling*: a change that happens while nobody is watching.
|
||||
That is why the caps and the leases matter more here than the role check does.
|
||||
</Aside>
|
||||
|
||||
## Where it meets everything else
|
||||
|
||||
- **[Engagement](/docs/administration/engagement-rules/)** — core registers `event.` triggers
|
||||
and owns none of the delivery. Who is told about a run is an ordinary rule.
|
||||
- **[The bridge](/docs/architecture/the-bridge/)** — every world verb becomes a command on the
|
||||
same versioned wire the game already speaks, through the same sidecar. Core still holds no
|
||||
game connection.
|
||||
- **[Teams](/docs/architecture/teams-architecture/)** — "this Team's members" is already a
|
||||
registered audience, so an event scoped to one Team needs no event-side feature at all.
|
||||
- **News** — an event does not write posts. A core action links an *existing* post to a run and
|
||||
enqueues it through the announcement pipeline, so the in-game town crier and Discord arrive
|
||||
as legs that already exist.
|
||||
|
||||
## What it deliberately does not do
|
||||
|
||||
- **No branching.** The condition grammar is `and` / `or` / `not` over comparisons, and the
|
||||
phase editor is a timeline rather than a canvas, because a canvas would promise power the
|
||||
engine has not got.
|
||||
- **No delegation, grants or proposal queue.** Permissions gate on the admin roles that
|
||||
already exist. The whole authorisation decision lives behind one function, which is what
|
||||
keeps a coordinator model a later option rather than a redesign.
|
||||
- **No event invoking another event.** It already works by composition — a second event's
|
||||
condition can be the first one completing.
|
||||
- **No mutation of game-owned content without a baseline.** If it cannot be restored, it
|
||||
cannot be leased, and it is out.
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`website/EVENTS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/EVENTS.md)
|
||||
is the design of record;
|
||||
[`website/MODULE_API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md)
|
||||
is the contract a module registers against; and
|
||||
[`link/v7.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v7.md)
|
||||
is the wire protocol the world verbs travel on.
|
||||
144
src/content/docs/docs/architecture/protocol-versions.mdx
Normal file
@@ -0,0 +1,144 @@
|
||||
---
|
||||
title: Protocol versions
|
||||
description: One number per game, declared in three places, that decides whether a game server and a sidecar are allowed to talk to each other.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import GameExample from '../../../../components/GameExample.astro';
|
||||
import platform from '../../../../data/platform.json';
|
||||
|
||||
The loopback wire protocol between the bridge plugin and the sidecar is a **versioned
|
||||
compatibility contract**, not a build dependency. Nothing compiles the three sides together,
|
||||
so the number is what stops a mismatch from being discovered as corrupted data.
|
||||
|
||||
Each game has its own protocol, numbered independently: {platform.games.uo.name} is on
|
||||
**{platform.games.uo.protocol}** and {platform.games.rust.name} on
|
||||
**{platform.games.rust.protocol}**. The two numbers are not comparable — they version two
|
||||
different wires. Everything below holds for both.
|
||||
|
||||
## Three declaration sites
|
||||
|
||||
The same number is written down in three places, and they must move together:
|
||||
|
||||
1. **The sidecar's source** declares `PROTOCOL_VERSION` — what the sidecar speaks.
|
||||
2. **The bridge plugin's release manifest** declares `protocol` — what the plugin speaks.
|
||||
3. **The bundle manifest** copies the plugin's number in CI, so a released pair carries its
|
||||
own claim.
|
||||
|
||||
<GameExample game="uo">
|
||||
| Where | What declares it |
|
||||
|---|---|
|
||||
| `link` `sidecar/src/main.rs` | `PROTOCOL_VERSION`, currently {platform.games.uo.protocol} |
|
||||
| `servuo-plugins` `overlay.toml` | `protocol`, currently {platform.games.uo.protocol} |
|
||||
</GameExample>
|
||||
|
||||
<GameExample game="rust">
|
||||
| Where | What declares it |
|
||||
|---|---|
|
||||
| `Rust-Link` `sidecar/src/main.rs` | `PROTOCOL_VERSION`, currently {platform.games.rust.protocol} |
|
||||
| `Rust-Plugins` `overlay.toml` | `protocol`, currently {platform.games.rust.protocol} |
|
||||
</GameExample>
|
||||
|
||||
<Aside type="caution" title="Bump the plugin's manifest in the same PR as the emitters">
|
||||
CI folds the plugin's manifest into the release manifest, and **the installer refuses to
|
||||
pair a bridge plugin and a sidecar whose protocol numbers disagree**.
|
||||
|
||||
A bump that lands separately from the emitters does not fail loudly — it silently fails to
|
||||
compose into a bundle, and the next release simply does not appear.
|
||||
</Aside>
|
||||
|
||||
## How a mismatch is caught
|
||||
|
||||
Two independent mechanisms, at two different boundaries.
|
||||
|
||||
**Sidecar ↔ website.** Every sidecar response carries its protocol version in a header. A
|
||||
mismatch is rejected with **`409`** rather than mis-parsed, and the game module's admin
|
||||
screen is where an administrator sees it.
|
||||
|
||||
**Bridge plugin ↔ sidecar.** The installer resolves a **bundle** — an exact,
|
||||
protocol-checked pair of sidecar and bridge plugin published by CI — and never "latest of
|
||||
each". That is the whole
|
||||
reason bundles exist: two independently released components that must agree cannot be
|
||||
allowed to be chosen independently.
|
||||
|
||||
## What a bump obliges
|
||||
|
||||
Changing a message shape means editing every side plus the specification: the bridge plugin,
|
||||
the sidecar, the game module, and the protocol document in `docs`.
|
||||
|
||||
**`website` is usually not on that list, and its absence is the interesting part.** Core
|
||||
holds no game connection and names no game noun, so most protocol bumps do not reach it at
|
||||
all. One reaches core only when what changes is the shape of something core owns — a ledger,
|
||||
a place to store a picture — rather than a game noun.
|
||||
|
||||
<GameExample game="uo">
|
||||
Protocol 8 taught the bridge to carry a game's own client files, and touched four
|
||||
repositories:
|
||||
|
||||
| Repository | What had to change |
|
||||
|---|---|
|
||||
| `servuo-plugins` | The extractors and the decoders they call, the switches and caps in `Bridge.cfg`, and `overlay.toml` |
|
||||
| `link` | `PROTOCOL_VERSION`, a cap on how large a line the shard may send, and the endpoints that carry the new commands |
|
||||
| `module-uo` | The importers, the admin screen, and the pages that render a picture |
|
||||
| `docs` | The protocol document and the integration guide |
|
||||
|
||||
Core's entire share of eight phases of work was a **deletion**: a developer tool it no longer
|
||||
needed. Everything the bump needed — somewhere to put a picture — core already offered every
|
||||
module.
|
||||
</GameExample>
|
||||
|
||||
**A protocol bump can also require a store migration**, because the sidecar persists what it
|
||||
forwards. That is not automatic, and it is rare: every frame is persisted whole, so a bump
|
||||
that only widens a frame, or adds a kind, or adds a guarantee about how a command is
|
||||
executed, asks nothing of a store that defines no schema for a frame's contents. That is the
|
||||
dumb-forwarder property paying for itself.
|
||||
|
||||
<GameExample game="uo">
|
||||
It has happened once: version 4 added a column to a table that already existed. Versions 5
|
||||
to 8 needed none. Version 8 is the largest bump the protocol has had, and it moves megabytes
|
||||
of artwork rather than events — and it changed **no line** of the sidecar's store, because
|
||||
the things it carries are answers to requests rather than events to keep.
|
||||
</GameExample>
|
||||
|
||||
## This is not the module API version
|
||||
|
||||
Two different numbers, versioning two different contracts, and confusing them is easy.
|
||||
|
||||
| | Versions | Lives in | Checked |
|
||||
|---|---|---|---|
|
||||
| **`PROTOCOL_VERSION`** | The game ↔ sidecar wire, one per game | The sidecar, the bridge plugin, the bundle | The sidecar's version header, and the installer's pairing check |
|
||||
| **`MODULE_API_VERSION`** | The website ↔ module contract | `website`, and every module's `coreApi` | At module load, before the module's code runs |
|
||||
|
||||
A module that never talks to a game server has no protocol version at all. See [The module
|
||||
manifest](/docs/modules/the-module-manifest/#coreapi-and-what-a-range-means).
|
||||
|
||||
## When a contract owes a bump
|
||||
|
||||
The rule this project settled on: **a contract owes a bump only once it has landed on
|
||||
`main`.**
|
||||
|
||||
While a version has only ever existed on a development branch, additions join it in place
|
||||
rather than forcing a new number. Once it has shipped, it is somebody else's dependency and
|
||||
a change to it is a change to a published contract.
|
||||
|
||||
## If you are building a bridge for another game
|
||||
|
||||
You do not inherit this protocol — you define your own between your plugin and your sidecar.
|
||||
What is worth inheriting is the **shape**:
|
||||
|
||||
- Declare the version on both sides, in files a release can read.
|
||||
- Make a released pair carry its own compatibility claim, so a deployment tool can refuse a
|
||||
bad combination rather than discovering it at runtime.
|
||||
- Reject a mismatch **loudly and early**. A `409` is a good outcome; a successful parse of a
|
||||
message you did not expect is not.
|
||||
|
||||
## Canonical documents
|
||||
|
||||
Each game's protocol has its own record in the
|
||||
[`docs` repository](https://gitea.whitlocktech.com/RunicGateway/docs). For Ultima Online,
|
||||
[`link/v8.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v8.md)
|
||||
is the current protocol's record, including its cross-repository obligations, and
|
||||
[`link/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md)
|
||||
§7 is the wire protocol. For Rust,
|
||||
[the Rust bridge protocol](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
|
||||
is both.
|
||||
162
src/content/docs/docs/architecture/system-architecture.mdx
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
title: System architecture
|
||||
description: The whole platform in one place — what each repository is, what talks to what, and the invariants that hold across all of them.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import GameExample from '../../../../components/GameExample.astro';
|
||||
|
||||
The drawn version of this, for evaluators, is on
|
||||
[Architecture](/architecture/). This page is the detailed account.
|
||||
|
||||
## Fourteen repositories, deployed independently
|
||||
|
||||
Nothing here is a monorepo. Each repository has its own history, its own CI and its own
|
||||
release cadence; what binds them is a set of **versioned contracts**, not a build.
|
||||
|
||||
Seven of them are core, and serve every game:
|
||||
|
||||
| Repository | What it is |
|
||||
|---|---|
|
||||
| `website` | The Node/Express + MariaDB + React site. The only internet-facing web app |
|
||||
| `installer` | Deploys a game server's side: the bridge plugin, and the sidecar with its service |
|
||||
| `Android-app` | Native Android client of the website API |
|
||||
| `Integration-kit` | The instruction book for putting a different game on the platform |
|
||||
| `docs` | Canonical design docs and the protocol specs |
|
||||
| `runicgateway.com` | This site |
|
||||
| `.profile` | The organisation landing page |
|
||||
|
||||
The other seven belong to a game. Each game has the same three: **a game module** that adds
|
||||
its screens to the site, **a sidecar** that is the only network-facing part of its bridge,
|
||||
and **a bridge plugin** that runs inside the game server and feeds the sidecar.
|
||||
|
||||
<GameExample game="uo">
|
||||
| Repository | Its part |
|
||||
|---|---|
|
||||
| `Module-uo` | The game module |
|
||||
| `link` | The sidecar, uo-link, in Rust |
|
||||
| `servuo-plugins` | The bridge plugin, a C# overlay ServUO compiles at boot |
|
||||
</GameExample>
|
||||
|
||||
<GameExample game="rust">
|
||||
| Repository | Its part |
|
||||
|---|---|
|
||||
| `Module-Rust` | The game module |
|
||||
| `Rust-Link` | The sidecar, rust-link, in Rust |
|
||||
| `Rust-Plugins` | The bridge plugin, for Oxide and Carbon |
|
||||
| `runicnpc-rust` | RunicNPC, an NPC plugin the bridge drives, which also works on its own |
|
||||
</GameExample>
|
||||
|
||||
## The layers
|
||||
|
||||
```
|
||||
Browser (React SPA) Native Android app
|
||||
│ cookie │ bearer
|
||||
└──────────┬─────────────────┘
|
||||
▼
|
||||
┌────────────────────────┐
|
||||
│ website (Node) │
|
||||
│ middleware → router │
|
||||
│ → controller → model │
|
||||
│ → db │
|
||||
└───────┬────────────┬───┘
|
||||
│ │ loads at boot
|
||||
▼ ▼
|
||||
MariaDB modules/<id>/ ← installed, never built
|
||||
│
|
||||
▼
|
||||
the game, via whatever
|
||||
bridge that module owns
|
||||
```
|
||||
|
||||
The backend is strictly layered — `middleware → router → controller → model → db` — with
|
||||
models in `.model.js` (logic) and `.db.js` (SQL) pairs, and **raw parameterised queries with
|
||||
no ORM anywhere**.
|
||||
|
||||
## Core is game-agnostic
|
||||
|
||||
Since the module system shipped on **2026-08-12**, nothing in core knows about any
|
||||
particular game. Routes, tables, pages, navigation and push streams for a game arrive from
|
||||
[a module](/docs/modules/the-module-system/) the operator installed. Core provides the seams;
|
||||
the module fills them.
|
||||
|
||||
That is why the architecture below describes a game module as something core *loads* rather
|
||||
than as part of the platform. There are two, and core depends on neither.
|
||||
|
||||
## The invariants
|
||||
|
||||
These hold across repository boundaries, and every one of them is load-bearing.
|
||||
|
||||
### The game is never network-reachable
|
||||
|
||||
The game server's bridge plugin **dials out** to the sidecar over loopback TCP,
|
||||
newline-delimited JSON, on `127.0.0.1`. The sidecar is the listener; the game opens no port.
|
||||
Only the sidecar is exposed, and only the website's backend talks to it.
|
||||
|
||||
See [The bridge](/docs/architecture/the-bridge/).
|
||||
|
||||
### A wedged sidecar can never stall the game
|
||||
|
||||
In the bridge plugin, `Emit()` enqueues onto a **bounded, drop-oldest** queue and returns
|
||||
immediately. It never touches the socket from the game's main thread. Every world read
|
||||
happens on the main thread; a dedicated writer thread drains the queue.
|
||||
|
||||
Dropping game events is strictly better than pausing the game to deliver them.
|
||||
|
||||
### The website degrades rather than fails
|
||||
|
||||
The sidecar REST client never throws — every call returns `{ ok, data, status }`. The public
|
||||
site still renders with the game shown offline.
|
||||
|
||||
That guarantee covers **reading the configuration too**: resolving the admin-managed config
|
||||
decrypts a stored token, which throws if the ciphertext cannot be authenticated (a rotated
|
||||
`SECRET_ENC_KEY`, or a database dump restored under a different key). That is caught inside
|
||||
the client and reported as unavailable, so a wrong key degrades the game's screens instead of
|
||||
500-ing it — and the admin config screen keeps working, which is the screen you need in order
|
||||
to recover.
|
||||
|
||||
### Sensitive events never reach the public
|
||||
|
||||
Ingested events fan out over two SSE channels: a **public allowlist** stream, and an
|
||||
**admin-only** stream that additionally carries staff audit, cheat detection and login
|
||||
attempts with IPs.
|
||||
|
||||
**The catalog is the module's; the boundary is core's.** A module declares which of its
|
||||
kinds are public-safe, and core enforces the split. A sensitive kind cannot reach the public
|
||||
channel.
|
||||
|
||||
### A failed module never takes the site down
|
||||
|
||||
The loader catches failures across a module's entire lifecycle and marks it
|
||||
`startup_failed`. The site comes up with that module's routes and navigation absent, and the
|
||||
admin panel says why. See [Module
|
||||
lifecycle](/docs/modules/module-lifecycle/#failure-is-contained-by-construction).
|
||||
|
||||
### Secrets are encrypted at rest
|
||||
|
||||
OAuth client secrets, the sidecar token, the Discord bot token and the mail transport's
|
||||
credentials are AES-256-GCM encrypted, keyed by `SECRET_ENC_KEY`. **The sidecar token and the
|
||||
mail credentials are write-only in the API** — neither is ever returned to any client; the
|
||||
email panel reports only that a password is *set*.
|
||||
|
||||
<Aside type="caution" title="Rotating that key orphans every stored secret">
|
||||
Nothing re-encrypts. What was stored under the old key can no longer be read, and every
|
||||
stored secret has to be entered again. See [Environment
|
||||
variables](/docs/reference/environment-variables/).
|
||||
</Aside>
|
||||
|
||||
## A deploy is two independent installs
|
||||
|
||||
Worth stating plainly, because it is the single most common misunderstanding: **the
|
||||
installer binary sets up the game server side only, and never contacts the website.** The website
|
||||
is a separate Docker deployment on, usually, a different machine.
|
||||
|
||||
The [installation path](/docs/getting-started/requirements/) walks both in order.
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`ARCHITECTURE.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/ARCHITECTURE.md)
|
||||
holds the canonical diagram, and
|
||||
[`BACKEND_DESIGN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/BACKEND_DESIGN.md)
|
||||
is the full API, schema and security contract. See [Canonical
|
||||
documents](/docs/reference/canonical-documents/) for the whole map.
|
||||
155
src/content/docs/docs/architecture/teams-architecture.mdx
Normal file
@@ -0,0 +1,155 @@
|
||||
---
|
||||
title: Teams architecture
|
||||
description: Teams is a contract, not a surface — how core owns every game's groups of players without ever learning what one is called.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
Most games have groups of players, and every game has its own word for them. Runic Gateway
|
||||
supports them as a **core platform primitive**, the **Team**, while core itself never learns
|
||||
what your game calls one.
|
||||
|
||||
The administrator's view is [Teams](/docs/administration/teams/).
|
||||
|
||||
## The sentence the design turns on
|
||||
|
||||
**Teams is a contract, not a surface.**
|
||||
|
||||
Core owns the tables, the sync, the access rules and the activity feed. It does **not** own
|
||||
the word for a Team, and therefore does not own the Team *page*. The module that owns the
|
||||
vocabulary owns the page.
|
||||
|
||||
That was not the first design. Core originally rendered Team pages with slots a module
|
||||
filled. It was inverted, and the inversion is the interesting part: instead of core naming
|
||||
places for a module's content, **a module declares a place on its own page for core to
|
||||
fill** — `registry.declareModuleSlot(id, name, { core })`, with core offering contributions
|
||||
rather than naming slots.
|
||||
|
||||
<Aside type="caution" title="Why the direction matters">
|
||||
The first version had core's fills naming three of the first game module's slots
|
||||
**literally**. It
|
||||
worked for exactly one module and silently did nothing for any other game — an empty page
|
||||
with nothing logged.
|
||||
|
||||
It was found by writing the Integration Kit for an audience outside this project, which is
|
||||
precisely what that book is for.
|
||||
</Aside>
|
||||
|
||||
## Six invariants
|
||||
|
||||
Each has a test named against it.
|
||||
|
||||
1. **Module unavailability is staleness, never emptiness.** No Team subsystem may apply a
|
||||
destructive result derived from a failed, timed-out or unanswered module call.
|
||||
2. **Four authority paths stay four.** Game membership, leadership, forum access and
|
||||
external-platform access are separate tables answering separate questions, resolved by
|
||||
separate predicates. **No predicate reads another's table.**
|
||||
3. **Non-contamination.** A manual forum grant never writes the membership projection, in
|
||||
either direction, ever. Both facts coexist; neither migrates into the other.
|
||||
4. **A Team's name is immutable for the life of its record.** A rename is an archive plus a
|
||||
create.
|
||||
5. **Core never interprets module vocabulary.** Activity kinds, Team metadata and capability
|
||||
strings are opaque. Core stores, gates and displays; it never branches on content it does
|
||||
not own.
|
||||
6. **The game never touches the website.** Everything crosses the sidecar.
|
||||
|
||||
Invariant 1 deserves emphasis, because it is the one a naive implementation gets wrong: if
|
||||
the module fails to answer "who is in this Team?", the answer is **not** "nobody". Treating
|
||||
a timeout as an empty roster would silently disband every Team on the site.
|
||||
|
||||
## The rename rule
|
||||
|
||||
Core's key is **(`module_id`, `external_id`, `name`) taken together** — not `external_id`
|
||||
alone.
|
||||
|
||||
| Situation | What core does |
|
||||
|---|---|
|
||||
| New `external_id` | Create a Team |
|
||||
| Known id, same name | Update in place |
|
||||
| Known id, **different name** | **Archive** the row and create a new one |
|
||||
| Id absent from an authoritative full list | Archive as disbanded, subject to invariant 1 |
|
||||
|
||||
The archived Team keeps its forum, activity history, grants and integration record; all
|
||||
become read-only. It stays reachable at its old slug, `noindex`, with a banner linking to
|
||||
the successor — so a Discord message from before the rename lands somewhere that explains
|
||||
itself instead of 404-ing.
|
||||
|
||||
This puts the whole of *"is this a rename or a different group?"* **inside the module**. If
|
||||
your game has no persistent group id, synthesise `external_id` from whatever is stable, or
|
||||
fold the name into it so every rename is a fresh id. Core only ever sees "an id appeared /
|
||||
an id's name changed / an id is gone".
|
||||
|
||||
## The module-facing interface
|
||||
|
||||
A module registers a provider:
|
||||
|
||||
```js
|
||||
api.registerTeamProvider({ getTeams, getTeamMembers, getTeamLeaders })
|
||||
```
|
||||
|
||||
and pushes through `ctx.teams`:
|
||||
|
||||
| Call | What it does |
|
||||
|---|---|
|
||||
| `ctx.teams.publish(event)` | An optimisation — makes a membership change visible at once |
|
||||
| `ctx.teams.reconcile({ reason })` | A debounced *request*; returns immediately |
|
||||
| `ctx.teams.activity.push(items)` | Writes the per-Team feed |
|
||||
|
||||
**`ctx.teams` is push-only, and that is the contract.** There is no reader. A module
|
||||
*answers* questions about Teams; it does not ask them. A `getTeamRoster` would be core
|
||||
offering to read back the module's own answer — which the module already holds.
|
||||
|
||||
All three are fire-and-forget and never reject, because they are called from inside
|
||||
game-event handlers and a storage problem of core's must not become the module's control
|
||||
flow. Correctness comes from reconciliation either way.
|
||||
|
||||
### The six event kinds
|
||||
|
||||
`team.created` · `team.disbanded` · `team.member.added` · `team.member.removed` ·
|
||||
`team.leader.added` · `team.leader.removed`
|
||||
|
||||
Six rather than four because **leadership is its own authority path**: a leadership change
|
||||
has to be expressible without pretending someone joined or left.
|
||||
|
||||
**`team.created` and `team.disbanded` only ask for a reconciliation.** Core will not invent
|
||||
a Team from a delta — it would have no name, no roster and no leaders — and will not archive
|
||||
one from a delta either, because an archive driven by a message that may simply have been
|
||||
repeated is destruction on no evidence.
|
||||
|
||||
### The activity feed
|
||||
|
||||
Each item carries an already-**rendered** `summary`, which core stores verbatim. Core cannot
|
||||
phrase "gained 15,000 gold" for a game whose vocabulary it does not know, and a core that
|
||||
templated it would have re-acquired exactly the semantics the module system exists to
|
||||
remove.
|
||||
|
||||
`visibility` defaults to `'members'` — **fail closed**. The module chooses it per item; core
|
||||
enforces it on read.
|
||||
|
||||
A `dedupeKey` collision is a **successful no-op**, which is what makes a sidecar reconnect
|
||||
backfill safe to replay.
|
||||
|
||||
## Untrusted game data becomes a public page
|
||||
|
||||
This is the sharpest edge in the whole subsystem: a group name chosen by a player becomes a
|
||||
page on a public website.
|
||||
|
||||
So game-sourced names go through **reserved-name screening**, and game-sourced overrides
|
||||
through an **approval gate**. Neither is optional, and neither is something a module can
|
||||
waive.
|
||||
|
||||
## What is deliberately out of scope
|
||||
|
||||
Multi-module namespacing, Team hierarchies and alliances, cross-Team messaging, and
|
||||
platform-only Teams with no game backing.
|
||||
|
||||
**Matrix is research, not a roadmap item.** Of the five capabilities a shared interface
|
||||
would name, a Matrix implementation could honestly provide two — it has no
|
||||
channel-with-overwrites, no role object, no voice channel, and no slash-command
|
||||
registration. The settled outcome was a *capability contract*, not an integration.
|
||||
|
||||
## Canonical document
|
||||
|
||||
[`TEAMS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/TEAMS.md)
|
||||
is normative — Part 1 for the invariants, Part 2 for the core, Parts 3–4 for pages and the
|
||||
activity feed.
|
||||
140
src/content/docs/docs/architecture/the-bridge.mdx
Normal file
@@ -0,0 +1,140 @@
|
||||
---
|
||||
title: The bridge
|
||||
description: How a game server reaches the website without ever being reachable itself — the sidecar, the loopback socket, and the rules that keep the game running.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
The bridge exists to answer one question safely: **how does a private game server's live
|
||||
state reach a public website?**
|
||||
|
||||
The answer is a **sidecar** — a small service that owns the connection to the game and the
|
||||
durable copy of what the game said. It is not optional, and the reasons are worth
|
||||
understanding before you build one for another game.
|
||||
|
||||
## The shape
|
||||
|
||||
```
|
||||
game server ──dials out──▶ sidecar ──HTTP + WS──▶ website
|
||||
(bridge plugin) 127.0.0.1 bearer + version (game module)
|
||||
newline JSON
|
||||
▲ │
|
||||
└────────── the game opens NO port ───────┘
|
||||
```
|
||||
|
||||
Three properties fall out of that diagram, and each is a rule rather than an
|
||||
implementation detail.
|
||||
|
||||
## 1. The game dials out
|
||||
|
||||
**The sidecar is the listener. The game connects to it.** The game server opens no port at all,
|
||||
and nothing on the internet can reach it even in principle.
|
||||
|
||||
This inverts the intuitive design — you would expect the thing with the data to serve it —
|
||||
and the inversion is the whole security argument. Only the sidecar is exposed, and only the
|
||||
website's backend talks to the sidecar.
|
||||
|
||||
The transport is deliberately boring: **newline-delimited JSON, one object per line**, over
|
||||
loopback TCP.
|
||||
|
||||
## 2. A wedged sidecar must never stall the game
|
||||
|
||||
This is the constraint the plugin is built around.
|
||||
|
||||
In the bridge plugin, `Emit()` **enqueues onto a bounded, drop-oldest queue and returns
|
||||
immediately**. It never touches the socket from the game's main thread. Every world read
|
||||
happens on the main thread; a dedicated writer thread drains the queue.
|
||||
|
||||
<Aside type="caution" title="Dropping events beats pausing the game">
|
||||
If the queue fills, the oldest events are discarded. That is the correct trade: a game
|
||||
server that stutters because a logging sidecar is slow is a broken game server, and no
|
||||
website feature is worth a lag spike.
|
||||
|
||||
Design your own plugin the same way. The game thread must never block on I/O — not on a
|
||||
socket, not on a lock held by a writer, not on a DNS lookup.
|
||||
</Aside>
|
||||
|
||||
Inbound commands get the mirror rule: **every inbound handler marshals to the main thread
|
||||
before touching world state.**
|
||||
|
||||
## 3. The sidecar persists before it forwards
|
||||
|
||||
The sidecar owns a durable store. It is not a proxy that translates and forgets — if the
|
||||
website is down, the game's events are still recorded, and a reconnecting website catches
|
||||
up.
|
||||
|
||||
This is what "a *thin* sidecar" means in the Integration Kit: thin in *logic*, not thin in
|
||||
responsibility. The sidecar is a **dumb forwarder** — it makes no access-control decisions
|
||||
and holds no policy. Access control and the admin-toggleable visibility scope live on the
|
||||
**website**, where an administrator can see and change them.
|
||||
|
||||
## Three ways in
|
||||
|
||||
**Live events** arrive over an outbound **WebSocket** and are routed by the module's ingest
|
||||
dispatcher. Kinds are handled differently by nature: state-changing kinds update tables,
|
||||
notable kinds append to an events log, and high-frequency kinds only update state rather
|
||||
than accumulating history.
|
||||
|
||||
**Point-in-time reads and commands** go over **REST**, through a client that never throws.
|
||||
|
||||
**Bulk reads** — a game's own files, such as its client artwork or its string table — are
|
||||
the newest and the least obvious, and so far only one game's bridge needs them. They go over the request/reply path in **pages**, with **one
|
||||
request in flight at a time** and a hard cap on how large a single line may be.
|
||||
|
||||
<Aside type="note" title="Why bulk data must not ride the event stream">
|
||||
It is the tempting shortcut, and it is wrong for a structural reason rather than a
|
||||
performance one: the sidecar **persists every event and broadcasts it to every connected
|
||||
client**. That is exactly what you want for "a player logged in" and exactly what you do not
|
||||
want for hundreds of megabytes of artwork, which is an *answer to a question somebody
|
||||
asked* rather than news.
|
||||
|
||||
Sending it as replies instead is what lets a protocol bump move megabytes without the
|
||||
sidecar's store changing by a line. The single slot is the other half: it is what keeps the queue
|
||||
between the game and the writer thread shallow, so rule 2 above still holds while a
|
||||
transfer is running.
|
||||
</Aside>
|
||||
|
||||
Every call carries `Authorization: Bearer <token>` and a protocol-version header. **A
|
||||
protocol mismatch fails fast with `409`** rather than being mis-parsed — see [Protocol
|
||||
versions](/docs/architecture/protocol-versions/).
|
||||
|
||||
## What a game server can say
|
||||
|
||||
Each game has its own event catalog, because each game has its own things worth telling a
|
||||
website about. Every catalog has the same structure, though: kinds the module declares,
|
||||
each one either safe for the public stream or kept to the admin one.
|
||||
|
||||
- **Ultima Online:** [its event catalog](/docs/ultima-online/event-catalog/), in the Ultima Online group
|
||||
- **Rust:** [its event kinds](/docs/rust/event-kinds/), in the Rust group
|
||||
|
||||
## Two design details worth stealing
|
||||
|
||||
**`server.hello` is per-connection, not per-boot.** The sidecar restarts independently of
|
||||
the game, so anything it needs up front must be re-sent on **every** connect. An earlier
|
||||
draft emitted a "started" event once at boot; a sidecar that came up second never received
|
||||
it and had no idea which game server it was attached to.
|
||||
|
||||
It carries a `bootId` — a GUID generated at server start, stable across sidecar reconnects
|
||||
and changed on every game restart. That is how the sidecar tells *"I reconnected"* (keep
|
||||
cached state) from *"the game restarted"* (discard it).
|
||||
|
||||
**Rosters are sets, not signatures.** A bridge that reports a Team's members should send
|
||||
the membership as a set rather than fold it into a checksum, because a sum can collide: one
|
||||
member joining and another leaving between two sweeps offset each other, and the Team reads
|
||||
as unchanged. A set can also be *differenced*, which is what makes per-member leave events
|
||||
possible for a game that raises no event for leaving. The Ultima Online bridge does exactly
|
||||
this; its [event catalog](/docs/ultima-online/event-catalog/#rosters-are-sets-not-signatures)
|
||||
has the details.
|
||||
|
||||
## Building one for another game
|
||||
|
||||
Both games' bridges have this shape; only their vocabulary differs. Chapters 3 and 4 of [the
|
||||
Integration Kit](/docs/modules/the-integration-kit/) cover the sidecar and the game-side
|
||||
plugin, and they are the two parts where the mistakes are most expensive.
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`link/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md)
|
||||
§5 and §7 are the data catalog and the wire protocol;
|
||||
[`link/INTEGRATION.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md)
|
||||
is the integration guide. Both are normative; this page is not.
|
||||
@@ -1,133 +1,52 @@
|
||||
---
|
||||
title: Connect a game server
|
||||
description: The installer binary on the shard host — what it deploys, what it asks, and the four values it prints for the website.
|
||||
title: Connect your game server
|
||||
description: The second install, on the machine that runs your game server — what every game's has in common, and where each game's own steps are.
|
||||
---
|
||||
|
||||
import platform from '../../../../data/platform.json';
|
||||
import { Aside, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
This is the second of the two installs, and it happens on the machine that runs your game
|
||||
server. One binary deploys the plugin, installs the sidecar, registers its service, and
|
||||
prints four values for you to paste into the website.
|
||||
server. It never contacts your website, and it never starts or stops your game server.
|
||||
|
||||
It never contacts your website, and it never starts or stops your shard.
|
||||
Every game's version of this step has the same shape:
|
||||
|
||||
## What gets deployed
|
||||
|
||||
| # | Component | Where it goes |
|
||||
|---|---|---|
|
||||
| 1 | **The plugin overlay** — C# source ServUO compiles at boot | into your ServUO tree |
|
||||
| 2 | **The uo-link sidecar** — a small Rust service | a system directory, plus a service |
|
||||
| 3 | **A record of the run** | `install.json`, with per-file hashes and backups |
|
||||
1. **The bridge plugin** goes onto the game server, where the game's own plugin system loads
|
||||
it.
|
||||
2. **The sidecar** goes onto the same host, as a service. It is the only part of the bridge
|
||||
that listens on a network.
|
||||
3. **You paste what the install prints into the site** — the sidecar's address and its auth
|
||||
token, plus whatever else that game's screen asks for — on the game module's admin screen.
|
||||
|
||||
```
|
||||
ServUO shard ──loopback TCP 127.0.0.1:7788──► uo-link sidecar ──HTTP + WebSocket──► website
|
||||
game server ──loopback, dials out──► sidecar ──HTTP + WebSocket──► website
|
||||
```
|
||||
|
||||
The shard **dials out**. It never listens for the website and is never reachable from the
|
||||
internet; only the sidecar is exposed, and only to your site.
|
||||
The game server **dials out** to the sidecar over loopback. It never listens for the website
|
||||
and is never reachable from the internet; only the sidecar is exposed, and only to your
|
||||
site.
|
||||
|
||||
## Install
|
||||
The [installer](/docs/reference/installer-cli/) ({platform.releases.installer}) does all of
|
||||
this for both games, told which one it is setting up. It installs a **bundle** — an exact,
|
||||
protocol-checked pair of sidecar and bridge plugin — never "the latest of each".
|
||||
|
||||
<Steps>
|
||||
## Pick your game
|
||||
|
||||
1. **Download the binary for your OS, and `SHA256SUMS`**, from the
|
||||
[installer releases page](https://gitea.whitlocktech.com/RunicGateway/installer/releases)
|
||||
({platform.releases.installer}).
|
||||
|
||||
Releases are **unsigned** — there is no code-signing certificate, so that checksum file
|
||||
is the whole trust anchor. Check it:
|
||||
|
||||
```bash
|
||||
sha256sum -c SHA256SUMS --ignore-missing
|
||||
chmod +x runicgateway-installer-linux-x86_64
|
||||
```
|
||||
|
||||
On Windows, `(Get-FileHash .\runicgateway-installer-windows-x86_64.exe -Algorithm SHA256).Hash`
|
||||
and compare. Windows will also show a SmartScreen prompt on first run, for the same
|
||||
reason.
|
||||
|
||||
2. **Stop the shard.** `ServUO.exe` locks `Scripts.dll` and rewrites `Saves/` on exit, so
|
||||
the installer refuses to deploy under a running server.
|
||||
|
||||
3. **Run it, elevated.**
|
||||
|
||||
```bash
|
||||
sudo ./runicgateway-installer-linux-x86_64 install
|
||||
```
|
||||
|
||||
Add `--verify` first if you want to see every change it would make and write nothing.
|
||||
|
||||
It asks four things: your ServUO root, whether to apply the optional patch tier, the
|
||||
hostname your website should use to reach this machine, and your site's URL (used only
|
||||
to print a link at the end).
|
||||
|
||||
4. **Read the summary.** It reports the overlay sync file by file, the sidecar binary and
|
||||
its verified hash, the config and database paths, and the service state. Then it says
|
||||
what you must do next — restart ServUO yourself, because it will not do that for you.
|
||||
|
||||
</Steps>
|
||||
|
||||
<Aside type="note" title="It installs a bundle, not “latest of each”">
|
||||
The three components version independently but must agree on one wire protocol, so what it
|
||||
resolves is a **bundle**: an exact, protocol-checked pair of sidecar and overlay versions
|
||||
({platform.bundle.tag} today — sidecar {platform.bundle.sidecar}, overlay {platform.bundle.overlay}).
|
||||
`--bundle <tag>` pins an exact past combination, so a reinstall in six months reproduces
|
||||
today's install rather than tomorrow's.
|
||||
</Aside>
|
||||
|
||||
## The patch tier is optional
|
||||
|
||||
Most of the plugin is *added* files, which is why the base install is a safe copy. Two
|
||||
features need edits to stock ServUO sources, and those are opt-in, off unless you say yes,
|
||||
and refused where the target lines are not stock. Skipping the tier costs you vendor-sale
|
||||
events and in-game moderation audit forwarding; everything else works.
|
||||
|
||||
The tier is written and tested against stock ServUO {platform.bundle.servuoMin}. On any
|
||||
other version it is unsupported and untested, and the prompt makes you answer past a
|
||||
warning.
|
||||
|
||||
## Paste the four values into the site
|
||||
|
||||
A successful run ends by printing the one step it cannot do for you:
|
||||
|
||||
```
|
||||
Base URL http://shard.example.com:8080
|
||||
WebSocket URL ws://shard.example.com:8080/ws
|
||||
Protocol version 4
|
||||
Auth token 4f9c… (also in sidecar.toml)
|
||||
```
|
||||
|
||||
Every value comes from asking the installed sidecar itself, so it cannot drift from what
|
||||
the service actually runs.
|
||||
|
||||
On the site, sign in as an administrator and open **Shard (uo-link)** in the admin
|
||||
sidebar — `/admin/uo/link`. Tick *Enable the shard integration*, paste **Base URL**,
|
||||
**WebSocket URL**, **Auth token** and **Protocol**, and save. The ingest client restarts
|
||||
immediately.
|
||||
|
||||
<Aside type="caution" title="Installer v0.1.0 prints an older path for that screen">
|
||||
It prints `…/admin/shard`. Since the shard screens became part of the `uo` module — and a
|
||||
module owns one path segment wherever it appears — the screen moved to **`/admin/uo/link`**.
|
||||
The old path does not fail visibly: the site sends you to the dashboard, which looks like the
|
||||
link worked. Use the sidebar, or the path above. Fixed for the next release.
|
||||
</Aside>
|
||||
|
||||
The token is encrypted at rest and **never returned to any client** — losing it means
|
||||
reading it back from `sidecar.toml` on the shard host, not from the website.
|
||||
| Game | Its steps |
|
||||
|---|---|
|
||||
| **{platform.games.uo.name}** | [Connecting the server](/docs/ultima-online/connect-a-servuo-shard/), then [verifying its bridge](/docs/ultima-online/verify-the-bridge/), in the Ultima Online group |
|
||||
| **{platform.games.rust.name}** | [Installing the bridge](/docs/rust/install-the-bridge/) — the installer, a Pterodactyl egg, or by hand — then [connecting the site](/docs/rust/connect-the-site/), in the Rust group |
|
||||
|
||||
## If the website is on a different machine
|
||||
|
||||
The sidecar binds `127.0.0.1:8080`, reachable only from the shard host. If the site runs
|
||||
elsewhere, widen the bind and then narrow the access:
|
||||
The sidecar listens on `127.0.0.1` by default, reachable only from the game server's host.
|
||||
If the site runs elsewhere, widen the sidecar's web bind and then narrow the access:
|
||||
|
||||
1. Set `[web] bind` in `sidecar.toml` to `0.0.0.0:8080` and restart the service.
|
||||
2. **Firewall that port to your website's address only.** The auth token is always on, but
|
||||
1. **Firewall that port to your website's address only.** The auth token is always on, but
|
||||
it travels as a plain bearer token — the sidecar speaks HTTP, not HTTPS.
|
||||
3. If the two hosts are not on a trusted network, put the sidecar behind a TLS reverse
|
||||
2. If the two hosts are not on a trusted network, put the sidecar behind a TLS reverse
|
||||
proxy or a VPN link and give the website the `https://` / `wss://` URLs.
|
||||
|
||||
Leave `[shard] bind` on `127.0.0.1:7788`. That socket accepts *inbound commands to the
|
||||
**Leave the sidecar's game-facing socket on loopback.** It accepts *inbound commands to the
|
||||
game*, and being loopback-only is what makes that safe.
|
||||
|
||||
Next: [Verify the whole stack](/docs/getting-started/verify-the-whole-stack/) — because a
|
||||
|
||||
@@ -4,6 +4,7 @@ description: Signing in as the first admin, what the site does before anyone vis
|
||||
---
|
||||
|
||||
import { Aside, Steps } from '@astrojs/starlight/components';
|
||||
import Screenshot from '../../../../components/Screenshot.astro';
|
||||
|
||||
The site is up and nobody can see it yet. That is the intended state: a new deployment
|
||||
**starts in maintenance mode**, showing visitors a "coming soon" page while the admin panel
|
||||
@@ -33,6 +34,8 @@ minute, and see [Authentication](/docs/administration/authentication/) for what
|
||||
**Web Bot Activity** screen shows and how to lift a ban.
|
||||
</Aside>
|
||||
|
||||
<Screenshot id="admin-dashboard" />
|
||||
|
||||
## What is already there
|
||||
|
||||
The first boot seeds a working site rather than an empty one:
|
||||
|
||||
@@ -6,12 +6,19 @@ description: Everything game-specific is a module. Installing one, what it adds,
|
||||
import platform from '../../../../data/platform.json';
|
||||
import { Aside, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
Core knows nothing about any game. Every game-specific screen — shard status, the map
|
||||
atlas, the player marketplace, character sheets — comes from a **module**, a directory on a
|
||||
mounted volume that the server loads at start.
|
||||
Core knows nothing about any game. Every game-specific screen — a game server's live
|
||||
status, its map, its leaderboards, its players' characters — comes from a **game module**, a
|
||||
directory on a mounted volume that the server loads at start.
|
||||
|
||||
Today there is one: **`uo`**, for ServUO shards, published as
|
||||
[`Module-uo`](https://gitea.whitlocktech.com/RunicGateway/Module-uo) ({platform.releases['Module-uo']}).
|
||||
There are two, both built inside this project, and a site runs **one** of them:
|
||||
|
||||
| Game | Module | Latest release |
|
||||
|---|---|---|
|
||||
| **{platform.games.uo.name}** | [releases](https://gitea.whitlocktech.com/RunicGateway/Module-uo/releases) | {platform.releases['Module-uo']} |
|
||||
| **{platform.games.rust.name}** | [releases](https://gitea.whitlocktech.com/RunicGateway/Module-Rust/releases) | {platform.releases['Module-Rust']} |
|
||||
|
||||
What each one adds is in its own group in the sidebar:
|
||||
[Ultima Online](/docs/ultima-online/) and [Rust](/docs/rust/).
|
||||
|
||||
## Install it
|
||||
|
||||
@@ -22,9 +29,8 @@ Today there is one: **`uo`**, for ServUO shards, published as
|
||||
2. **Paste the URL of a release's install manifest** into *Release install-manifest URL*
|
||||
and press **Install**.
|
||||
|
||||
For the current `uo` release that is the `module-uo-<version>.json` asset on
|
||||
[its releases page](https://gitea.whitlocktech.com/RunicGateway/Module-uo/releases).
|
||||
The site downloads the bundle, checks it against the `sha256` the manifest declares, and
|
||||
Every module release carries one: a `.json` asset named after the module and its
|
||||
version, on the releases page linked above. The site downloads the bundle, checks it against the `sha256` the manifest declares, and
|
||||
unpacks it onto the modules volume.
|
||||
|
||||
There is no catalog to browse, deliberately: a catalog would make core's release cadence
|
||||
@@ -50,28 +56,21 @@ must be in the allowlist at the bottom of the same screen — re-checked on ever
|
||||
It is seeded with `gitea.whitlocktech.com`, and an empty list forbids every install.
|
||||
</Aside>
|
||||
|
||||
## What the `uo` module adds
|
||||
## What a module adds
|
||||
|
||||
Watch the log at the restart and you will see exactly what it mounted:
|
||||
Watch the log at the restart and you will see exactly what it mounted: its routes, its
|
||||
database schema, and the line that says it started. Its screens appear in the navigation,
|
||||
and its admin screens in the admin sidebar.
|
||||
|
||||
```
|
||||
[uo] registered routes: public:/shard,/atlas admin:/shard,/uo-link player:/shard
|
||||
[modules] schema ensured for module "uo"
|
||||
[modules] module "uo" started
|
||||
```
|
||||
|
||||
Its capabilities are {platform.moduleUoCapabilities.join(', ')} — the shard console, the
|
||||
map atlas, the player-vendor marketplace, city governors, guilds, houses and IDOCs, champion
|
||||
boards, and the cliloc strings that make item names readable.
|
||||
|
||||
A module owns **one path segment** wherever it appears, so its pages live under `/uo/…`,
|
||||
`/admin/uo/…` and `/player/uo/…`. That boundary is visible in the URL on purpose.
|
||||
A module owns **one path segment** wherever it appears, so a module with the id `<id>` has
|
||||
its pages under `/<id>/…`, `/admin/<id>/…` and `/player/<id>/…`. That boundary is visible
|
||||
in the URL on purpose.
|
||||
|
||||
<Aside type="caution" title="A module with no game server behind it is empty, not broken">
|
||||
Installing `uo` does not connect anything. Its screens exist and report the shard as
|
||||
Installing a module does not connect anything. Its screens exist and report the game as
|
||||
offline until you
|
||||
[connect a game server](/docs/getting-started/connect-a-game-server/) — which is the same
|
||||
thing the public site does when the shard goes down, and is designed to be unremarkable.
|
||||
[connect your game server](/docs/getting-started/connect-a-game-server/) — which is the same
|
||||
thing the public site does when the game goes down, and is designed to be unremarkable.
|
||||
</Aside>
|
||||
|
||||
## The declarative alternative
|
||||
|
||||
@@ -93,7 +93,7 @@ it down. Docker Compose is the supervisor here, and this line is what makes it o
|
||||
## Two variables worth reading twice
|
||||
|
||||
**`SECRET_ENC_KEY`** encrypts secrets at rest — OAuth client secrets, the Discord bot
|
||||
token, the shard's auth token. In production the server **refuses to start** without it.
|
||||
token, the game module's sidecar token. In production the server **refuses to start** without it.
|
||||
Changing it later does not re-encrypt anything: what was stored under the old key can no
|
||||
longer be read, and every stored secret has to be entered again.
|
||||
|
||||
|
||||
@@ -3,11 +3,10 @@ title: Requirements
|
||||
description: What you need on the website host, and what you need on the game server host, before you begin.
|
||||
---
|
||||
|
||||
import platform from '../../../../data/platform.json';
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
Two hosts, two lists. They can be the same machine, but they are separate deployments and
|
||||
have nothing in common except the four values you will paste between them.
|
||||
have nothing in common except the few values you will paste between them.
|
||||
|
||||
## The website host
|
||||
|
||||
@@ -29,32 +28,28 @@ mounts and the reverse-proxy notes all read that way.
|
||||
|
||||
## The game server host
|
||||
|
||||
Only if you are connecting a game server. Today that means a ServUO shard, which is what
|
||||
the [`uo` module](/docs/getting-started/install-a-game-module/) and the installer support.
|
||||
Only if you are connecting a game server. Each game lists what its own host needs on its
|
||||
connect page, because each game's server asks for different things. These hold for every
|
||||
game:
|
||||
|
||||
| Requirement | Detail |
|
||||
|---|---|
|
||||
| **A working ServUO install** | It must currently boot and compile scripts cleanly. The installer deploys onto a healthy shard; it does not repair a broken one. |
|
||||
| **ServUO {platform.bundle.servuoMin}** *(patch tier only)* | The base install works on any reasonably current ServUO. The optional patch tier is written and tested against stock {platform.bundle.servuoMin}; on any other version it is unsupported, and skipping it still leaves you with a working bridge. |
|
||||
| **The shard stopped** | `ServUO.exe` locks `Scripts.dll` and rewrites `Saves/` on exit. The installer refuses to deploy under a running shard. |
|
||||
| **Administrator / root** | It writes into system directories and registers a service. |
|
||||
| **Outbound HTTPS** | To fetch the bundle and its two artifacts. No Gitea account and no git client are needed. |
|
||||
| **The sidecar on the same host as the shard** | The shard connects to `127.0.0.1:7788`. Splitting them is not supported — that loopback socket *is* the trust boundary for inbound commands. |
|
||||
| **A working game server** | It must boot and load plugins cleanly before you start. The installer deploys onto a healthy server; it does not repair a broken one. |
|
||||
| **Administrator / root** | The installer writes into system directories and registers a service. |
|
||||
| **Outbound HTTPS** | To fetch the bundle and its artifacts. No Gitea account and no git client are needed. |
|
||||
| **The sidecar on the same host as the game server** | The bridge plugin dials the sidecar over loopback. That loopback socket *is* the trust boundary for inbound commands to the game, so the two are never split across machines. |
|
||||
|
||||
<Aside type="caution" title="Back up before the shard install">
|
||||
The overlay overwrites `Scripts/Scripts.csproj`, a stock file, and the optional patch tier
|
||||
edits stock sources. A copy of `Scripts/` and `Config/` costs nothing and is the difference
|
||||
between an experiment and a gamble. The installer keeps its own backups too — see
|
||||
[Connect a game server](/docs/getting-started/connect-a-game-server/).
|
||||
</Aside>
|
||||
Then the game's own list: [Ultima Online](/docs/ultima-online/connect-a-servuo-shard/#what-the-shard-host-needs),
|
||||
or [Rust](/docs/rust/install-the-bridge/#before-you-begin).
|
||||
|
||||
## What you do not need
|
||||
|
||||
- **A Gitea account.** Everything the installers fetch is a public release asset.
|
||||
- **A build toolchain.** Not on either host. The site pulls images; the module arrives as a
|
||||
verified tarball; the shard plugin is C# source that ServUO itself compiles at boot.
|
||||
- **An inbound port on the game host** — for the *game*. The shard never listens for the
|
||||
website. If the website runs on a different machine from the shard, the **sidecar** needs
|
||||
to be reachable by the website, and that is the one hole you will open deliberately.
|
||||
verified tarball; the bridge plugin is source that the game server compiles itself.
|
||||
- **An inbound port on the game host** — for the *game*. The game server never listens for
|
||||
the website. If the website runs on a different machine from the game server, the
|
||||
**sidecar** needs to be reachable by the website, and that is the one hole you will open
|
||||
deliberately.
|
||||
|
||||
Next: [Install the site](/docs/getting-started/install-the-site/).
|
||||
|
||||
@@ -1,103 +1,53 @@
|
||||
---
|
||||
title: Verify the whole stack
|
||||
description: Four checks, one per link in the chain, that distinguish "files copied" from "the bridge works".
|
||||
description: Four checks, one per link in the chain, that distinguish "files copied" from "the bridge works" — the same four for every game.
|
||||
---
|
||||
|
||||
import { Aside, Steps } from '@astrojs/starlight/components';
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
A successful install is not a working bridge, and the failure is quiet in a specific way:
|
||||
**ServUO shells out to `dotnet build`, prints the output, ignores the exit code, and
|
||||
reloads the existing `Scripts.dll`.** A broken script build looks exactly like a clean boot.
|
||||
A successful install is not a working bridge. Files can be in the right place and the game
|
||||
server can boot cleanly while nothing reaches the site, and the site is *designed* to keep
|
||||
working when the game is unreachable — so a broken bridge does not announce itself.
|
||||
|
||||
So verify each link in the chain, in order. Each check tells you which one to fix.
|
||||
So verify each link in the chain, in order, starting at the game. Each check tells you which
|
||||
link to fix.
|
||||
|
||||
<Steps>
|
||||
| # | The link | What you check | What "working" means |
|
||||
|---|---|---|---|
|
||||
| 1 | **The bridge plugin loaded** | The game server's own console or log at boot | The plugin announces itself, with the sidecar address it will dial |
|
||||
| 2 | **The game server reached the sidecar** | The bridge plugin's status command, on the game server | It reports itself connected, and is not dropping events |
|
||||
| 3 | **The sidecar is healthy** | `curl -s http://127.0.0.1:<port>/health` on the game server's host. It needs no token | *plugin connected* is true. It is the one value in the whole sequence that distinguishes "files copied" from "the bridge works" |
|
||||
| 4 | **The website is ingesting** | The game module's connection screen, under **Admin** | It reads connected, and live events start arriving within seconds |
|
||||
|
||||
1. **The plugin compiled — watch the boot output.**
|
||||
The order is the same for every game. The commands and the screen names are not, so each
|
||||
game has its own page with the exact steps:
|
||||
|
||||
Start your shard the way you always do. You want the build to succeed *and* the bridge
|
||||
to announce itself:
|
||||
- **Ultima Online:** [Verify the bridge](/docs/ultima-online/verify-the-bridge/)
|
||||
- **Rust:** [Verify the bridge](/docs/rust/verify-the-bridge/)
|
||||
|
||||
```
|
||||
Core: Compiling scripts...
|
||||
Build succeeded.
|
||||
[Bridge] enabled=True endpoint=127.0.0.1:7788 queueCap=10000 …
|
||||
```
|
||||
## Two responses that mean the same for every game
|
||||
|
||||
If you scrolled past it, force the question:
|
||||
|
||||
```bash
|
||||
dotnet build Scripts/Scripts.csproj -c Release -p:Platform=x64 # must be 0 errors
|
||||
```
|
||||
|
||||
2. **The shard is connected — ask it in game.**
|
||||
|
||||
As an administrator:
|
||||
|
||||
```
|
||||
[bridge status
|
||||
```
|
||||
|
||||
It reports `connected=True depth=0 sent=… dropped=0`. `connected=False` means the shard
|
||||
cannot reach the sidecar. `dropped` climbing means the sidecar is wedged and the shard
|
||||
is shedding events rather than stalling — which is what it is designed to do, and why a
|
||||
broken bridge never freezes your game.
|
||||
|
||||
`[bridge reload` re-reads `Bridge.cfg` without a restart; `[bridge sweepnow` forces one
|
||||
pass of every stream.
|
||||
|
||||
3. **The sidecar is healthy — ask it over HTTP.**
|
||||
|
||||
`/health` needs no auth, so it is safe to curl on the shard host:
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8080/health
|
||||
```
|
||||
|
||||
```json
|
||||
{"status":"ok","protocol":4,"plugin_connected":true,"database":"ok","uptime":"2m"}
|
||||
```
|
||||
|
||||
**`plugin_connected: true` is the one that matters.** It is the only value in this whole
|
||||
sequence that distinguishes "files copied" from "the bridge works".
|
||||
|
||||
4. **The website is ingesting — look at the shard screen.**
|
||||
|
||||
On the site, open **Shard (uo-link)** (`/admin/uo/link`). The header should read
|
||||
**Connected**, with *Shard link: up* and *WS ingest: online*, and the live feed at the
|
||||
bottom should start showing events within seconds rather than sitting on
|
||||
*Waiting for shard events…*.
|
||||
|
||||
Then check the public side: the shard status page should stop reporting the game as
|
||||
offline.
|
||||
|
||||
</Steps>
|
||||
|
||||
## When one of them fails
|
||||
|
||||
| What you see | What it means |
|
||||
| What the site logs | What it means |
|
||||
|---|---|
|
||||
| Shard boots clean, nothing reaches the site | The classic silent failure — a stale `Scripts.dll`. Run the `dotnet build` line above and read the errors. |
|
||||
| `[bridge` is not a command | The plugin did not compile, or the bridge is disabled in `Bridge.cfg`. |
|
||||
| `connected=False` | The sidecar is not listening on `127.0.0.1:7788`. Check the service, and that `[shard] bind` matches `Host`/`Port` in `Bridge.cfg`. |
|
||||
| `/health` is fine locally, the site says offline | The website cannot reach port 8080 — bind address or firewall. The site is *designed* to render normally with the shard down, so this fails quietly. |
|
||||
| The site logs `409` from the sidecar | Protocol mismatch. Set the Protocol field to what `/health` reports rather than guessing; the sidecar rejects rather than mis-parsing. |
|
||||
| `401` from the sidecar | Wrong or missing token. Read the live one back with `uo-link-sidecar --print-config`; do not retype it from a screenshot. |
|
||||
| `409` from the sidecar | Protocol mismatch. The sidecar and the game module disagree on a wire protocol, and the sidecar refuses rather than mis-parsing. Set the protocol to what `/health` reports, or update whichever side is behind. |
|
||||
| `401` from the sidecar | Wrong or missing token. Read the live one back on the game server's host rather than retyping it from a screenshot. |
|
||||
|
||||
<Aside type="note" title="`runicgateway doctor` answers most of this in one command">
|
||||
Run on the shard host, it checks the install record, the ServUO tree, every overlay file
|
||||
hash, the patch tier, the sidecar, its service, `/health`, and that the sidecar and overlay
|
||||
agree on a protocol. Its output is the first thing anyone helping you will ask for. It
|
||||
exits non-zero when a check failed, so a monitoring system can run it too.
|
||||
Run on the game server's host, it checks the install record, the files it deployed, the
|
||||
sidecar, its service, `/health`, and that the sidecar and the bridge plugin agree on a
|
||||
protocol. Its output is the first thing anyone helping you will ask for. It exits non-zero
|
||||
when a check failed, so a monitoring system can run it too.
|
||||
</Aside>
|
||||
|
||||
## What "working" looks like a week later
|
||||
|
||||
- The public shard page shows live status, and the admin dashboard shows events arriving.
|
||||
- `dropped` in `[bridge status` stays at zero. A climbing number means the sidecar is
|
||||
wedged, not that the shard is unhealthy.
|
||||
- `doctor` is still green after a shard update — that is what catches an overlay file
|
||||
reverted by hand or by a ServUO upgrade.
|
||||
- The game module's public pages show live status, and the admin dashboard shows events
|
||||
arriving.
|
||||
- The bridge plugin is not dropping events. A climbing drop count means the sidecar is
|
||||
wedged, not that the game server is unhealthy: the plugin sheds events rather than
|
||||
stalling the game, which is what it is designed to do.
|
||||
- `doctor` is still green after a game server update. That is what catches a deployed file
|
||||
that an update put back to stock.
|
||||
|
||||
You have finished the installation path. From here,
|
||||
[Administration](/docs/administration/configuration/) covers running the site day to day.
|
||||
|
||||
@@ -8,26 +8,39 @@ import platform from '../../../data/platform.json';
|
||||
Runic Gateway puts a private game server's live state on a public website without ever
|
||||
exposing the game to the internet.
|
||||
|
||||
The shard dials **out** to a small sidecar over loopback; the sidecar is the only
|
||||
The game server dials **out** to a small sidecar over loopback; the sidecar is the only
|
||||
network-facing component, and only the website's backend is allowed to talk to it. The
|
||||
website degrades gracefully when the game is down, and sensitive events never reach the
|
||||
public event stream.
|
||||
|
||||
## What the platform is on today
|
||||
|
||||
Two versions are shared by every deployment, whichever game it runs:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr><td>Wire protocol</td><td>{platform.protocol}</td></tr>
|
||||
<tr><td>Module API</td><td>{platform.moduleApi}</td></tr>
|
||||
<tr><td>Current bundle</td><td>{platform.bundle.tag}</td></tr>
|
||||
<tr><td>uo-link sidecar</td><td>{platform.releases.link}</td></tr>
|
||||
<tr><td>Plugin overlay</td><td>{platform.bundle.overlay}</td></tr>
|
||||
<tr><td>Installer</td><td>{platform.releases.installer}</td></tr>
|
||||
<tr><td>ServUO (minimum)</td><td>{platform.bundle.servuoMin}</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
Every value in that table is read from `src/data/platform.json` and re-checked against its
|
||||
Everything else belongs to a game. Each game has its own wire protocol and its own bundle —
|
||||
the exact, protocol-checked pair of sidecar and game plugin the installer deploys:
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr><th></th><th>{platform.games.uo.name}</th><th>{platform.games.rust.name}</th></tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td>Game module</td><td>{platform.releases['Module-uo']}</td><td>{platform.releases['Module-Rust']}</td></tr>
|
||||
<tr><td>Wire protocol</td><td>{platform.games.uo.protocol}</td><td>{platform.games.rust.protocol}</td></tr>
|
||||
<tr><td>Current bundle</td><td>{platform.games.uo.bundle.tag}</td><td>{platform.games.rust.bundle.tag}</td></tr>
|
||||
<tr><td>Sidecar</td><td>{platform.games.uo.bundle.sidecar}</td><td>{platform.games.rust.bundle.sidecar}</td></tr>
|
||||
<tr><td>Game plugin</td><td>{platform.games.uo.bundle.overlay}</td><td>{platform.games.rust.bundle.plugin}</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
Every value in those tables is read from `src/data/platform.json` and re-checked against its
|
||||
source of truth on each build. None of it is typed into prose — including here.
|
||||
|
||||
## An install is two installs
|
||||
@@ -36,15 +49,16 @@ Worth stating before anything else, because it is a real trap: a Runic Gateway i
|
||||
two independent deployments.
|
||||
|
||||
1. **The site** is a Docker deployment — the website, a database, and a game module.
|
||||
2. **The shard side** is the installer binary, run on the game server's host. It sets up
|
||||
the plugin overlay and the sidecar, and it never contacts the website.
|
||||
2. **The game server side** is the installer binary, run on the game server's host. It sets
|
||||
up the bridge plugin and the sidecar, and it never contacts the website.
|
||||
|
||||
They meet at four values pasted into the module's shard screen, and at protocol
|
||||
{platform.protocol}, which both sides check before they will pair.
|
||||
They meet at the values the installer prints, pasted into the game module's connection
|
||||
screen, and at the game's wire protocol, which both sides check before they will pair.
|
||||
|
||||
You can stop after the first one. A site with no game server attached is a complete
|
||||
community website — news, wiki, pages, Teams, forums, accounts and moderation are all core,
|
||||
and none of them knows a game exists. The second install is what fills the game screens.
|
||||
community website — news, wiki, pages, Teams, forums, accounts, moderation and the event
|
||||
calendar are all core, and none of them knows a game exists. The second install is what
|
||||
fills the game screens, and what lets an event reach into a world.
|
||||
|
||||
## Start here
|
||||
|
||||
@@ -55,12 +69,15 @@ you should expect to see before you move on:
|
||||
2. [Install the site](/docs/getting-started/install-the-site/) — Docker Compose, pull-only
|
||||
3. [First run](/docs/getting-started/first-run/) — the first admin, and maintenance → live
|
||||
4. [Install a game module](/docs/getting-started/install-a-game-module/) — what makes the game screens exist
|
||||
5. [Connect a game server](/docs/getting-started/connect-a-game-server/) — the installer, on the shard host
|
||||
5. [Connect your game server](/docs/getting-started/connect-a-game-server/) — the installer, on the game server's host
|
||||
6. [Verify the whole stack](/docs/getting-started/verify-the-whole-stack/) — proving it works, rather than assuming
|
||||
|
||||
Then **Administration** covers running it: configuration, branding, content, users,
|
||||
authentication, Teams, moderation, notifications, modules, the shard connection, upgrades,
|
||||
and what to do when something is wrong.
|
||||
authentication, Teams, scheduled events, moderation, notifications, modules, upgrades, and
|
||||
what to do when something is wrong.
|
||||
|
||||
Everything that belongs to one game has its own group at the end of the sidebar, after
|
||||
**Reference**: [Ultima Online](/docs/ultima-online/) and [Rust](/docs/rust/).
|
||||
|
||||
## Where the truth lives
|
||||
|
||||
|
||||
161
src/content/docs/docs/modules/building-a-module.mdx
Normal file
@@ -0,0 +1,161 @@
|
||||
---
|
||||
title: Building a module
|
||||
description: The repository layout, the server half, and the client build — including the three things about bundling that everyone gets wrong once.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
Start from [the Integration Kit's template](/docs/modules/the-integration-kit/) rather than
|
||||
an empty directory. This page explains what the template is doing and why, so that when you
|
||||
change something you know what you are changing.
|
||||
|
||||
## The layout
|
||||
|
||||
One repository, both halves, versioned together:
|
||||
|
||||
```
|
||||
module.json id, version, coreApi, mounts, extensions
|
||||
server/index.js the entry point — exports register(ctx, api)
|
||||
server/db/schema.sql idempotent fragment, replayed every boot
|
||||
server/db/purge.sql destructive; only ever run by an explicit purge
|
||||
server/router/ routers and controllers
|
||||
server/model/ *.model.js (logic) + *.db.js (SQL) pairs
|
||||
client/src/entry.jsx registers routes, nav, providers
|
||||
client/src/shim/ the shared-dependency shims — see below
|
||||
client/dist/entry.js PREBUILT chunk, published by your CI
|
||||
```
|
||||
|
||||
`client/dist/` is committed by your **release**, not by hand — the operator never builds,
|
||||
so the built chunk has to be in the bundle.
|
||||
|
||||
## The server half
|
||||
|
||||
`server/index.js` exports one function, called once during core's require phase:
|
||||
|
||||
```js
|
||||
module.exports = function register(ctx, api) {
|
||||
const log = ctx.log('examplegame')
|
||||
|
||||
api.registerRoutes({
|
||||
public: { '/world': worldRouter(ctx) },
|
||||
})
|
||||
|
||||
api.onBoot(async (ctx) => {
|
||||
// anything that needs a live database goes HERE, not above
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
Follow core's own layering — `router → controller → model → db`, with `.model.js` (logic)
|
||||
and `.db.js` (SQL) pairs, and raw parameterised queries. There is no ORM anywhere in this
|
||||
project, and a module that introduces one is a module nobody else can read.
|
||||
|
||||
### The rule CI enforces
|
||||
|
||||
**Zero `require`/`import` may reach outside your own directory.** Not "few". Zero.
|
||||
|
||||
```bash
|
||||
npm run check:imports --prefix server
|
||||
```
|
||||
|
||||
If you need something from core that `ctx` does not offer, that is a gap in the contract —
|
||||
raise it, so the surface grows deliberately. Reaching into core's internals is how a module
|
||||
breaks on a refactor it had no part in.
|
||||
|
||||
## The client half
|
||||
|
||||
Your chunk is built with Vite in **library mode**, emitting one unhashed `dist/entry.js`.
|
||||
Unhashed deliberately: `module.json` names that file, and a hashed name would have to be
|
||||
discovered at runtime. Core answers the caching question instead, serving it `no-cache`.
|
||||
|
||||
Then three things about the bundling, each of which has already cost somebody a day.
|
||||
|
||||
### 1. Aliases replace `external` — they do not accompany it
|
||||
|
||||
This is the one that looks most like it should work.
|
||||
|
||||
Rollup asks `external` **before** Vite's alias resolver runs, so a specifier listed there is
|
||||
marked external and **never aliased**. The chunk then ships bare `import 'react'`
|
||||
specifiers, which a browser cannot resolve without an import map — and an import map has to
|
||||
be inline, which `script-src 'self'` forbids.
|
||||
|
||||
The first real module shipped with both, **built cleanly**, and emitted exactly that chunk.
|
||||
|
||||
```js
|
||||
rollupOptions: { external: [] }, // deliberately empty
|
||||
```
|
||||
|
||||
Alias only. Nothing in `external`. (`output.globals` does not rescue this either — it covers
|
||||
iife/umd and does nothing for an ES module.)
|
||||
|
||||
### 2. Use the array form of `resolve.alias`, with anchored regexes
|
||||
|
||||
Vite's **object** form does *prefix* matching, so a `react` key also rewrites
|
||||
`react/jsx-runtime` — silently, to the wrong shim. The chunk then fails at its first element
|
||||
with a message about `jsx` not being a function, which points nowhere near the cause.
|
||||
|
||||
```js
|
||||
alias: SHARED.map(({ specifier, shim }) => ({
|
||||
find: new RegExp(`^${escape(specifier)}$`),
|
||||
replacement: shim,
|
||||
}))
|
||||
```
|
||||
|
||||
`^react$` and `^react/jsx-runtime$` cannot collide.
|
||||
|
||||
### 3. Assert at resolution time, not by grepping the output
|
||||
|
||||
The risk is a missed alias welding a **second React** into your chunk. That loads fine and
|
||||
then throws about an invalid hook call somewhere unrelated.
|
||||
|
||||
The template fails the build if any shared package resolves into `node_modules`. Two details
|
||||
of how it does that are not interchangeable:
|
||||
|
||||
- It hooks **`transform`, not `load`**. `load` is first-wins, so an earlier plugin returning
|
||||
the module's contents means the guard is never called. Written against `load`, it sat in
|
||||
the build doing nothing while a deliberately-broken alias produced a green build with
|
||||
react-router welded in.
|
||||
- The list of packages that may not be bundled is stated **independently** of the alias
|
||||
list. Deriving one from the other means deleting an alias also deletes the guard against
|
||||
what that alias prevented.
|
||||
|
||||
<Aside type="caution" title="Why shims rather than plain externals">
|
||||
Each shared dependency is aliased to a two-line module re-exporting from `window.__rg`.
|
||||
|
||||
The **named** re-exports matter: `import { useState } from 'react'` compiles to a named
|
||||
import, and a shim with only a default export fails at link time in the browser with a
|
||||
message about the binding — not about the shim.
|
||||
|
||||
Route every shim through one file that reads `window.__rg` and throws a useful error when
|
||||
it is missing. Otherwise the first symptom of a core ordering fault is
|
||||
`Cannot read properties of undefined (reading 'react')` thrown from a file called
|
||||
`react.js`, which reads like *your* bundling is wrong when it is the opposite.
|
||||
</Aside>
|
||||
|
||||
Verify with:
|
||||
|
||||
```bash
|
||||
npm run build --prefix client # build BEFORE the tests — two of them read the chunk
|
||||
npm run check:externals --prefix client
|
||||
```
|
||||
|
||||
## Registering the client half
|
||||
|
||||
```js
|
||||
const { registry } = window.__rg
|
||||
|
||||
registry.registerRoutes(ID, {
|
||||
public: [{ path: 'world', element: <WorldStatus /> }],
|
||||
admin: [{ path: 'link', element: <Admin /> }],
|
||||
})
|
||||
registry.registerNav(ID, { … })
|
||||
```
|
||||
|
||||
Paths are **relative to your module's segment** — `path: 'link'` under `admin` becomes
|
||||
`/admin/<id>/link`. Check `window.__rg.version` against your `coreApi` range and refuse to
|
||||
register on a mismatch.
|
||||
|
||||
## Then
|
||||
|
||||
[Testing and release](/docs/modules/testing-and-release/) covers CI, the checks, and
|
||||
publishing the bundle and its manifest.
|
||||
122
src/content/docs/docs/modules/installing-modules.mdx
Normal file
@@ -0,0 +1,122 @@
|
||||
---
|
||||
title: Installing modules
|
||||
description: How a module reaches a deployment — the install manifest, the two surfaces that can install one, and which of them wins.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
There is no catalog, and there is no marketplace. A module is installed by **naming the
|
||||
URL of a release's install manifest**.
|
||||
|
||||
That is a design decision rather than an unfinished feature: a catalog would make core's
|
||||
release cadence decide which modules exist, and the whole point of the module system is
|
||||
that it does not.
|
||||
|
||||
<Aside type="note" title="Doing this once, as an operator?">
|
||||
[Install a game module](/docs/getting-started/install-a-game-module/) walks the happy path,
|
||||
and [Managing modules](/docs/administration/managing-modules/) covers the screen
|
||||
afterwards. This page is about how distribution works, for people publishing one.
|
||||
</Aside>
|
||||
|
||||
## What a release publishes
|
||||
|
||||
Two artifacts:
|
||||
|
||||
- **`<id>-<version>.tar.gz`** — the bundle: `module.json`, the server half, the prebuilt
|
||||
client chunk, and the SQL fragments.
|
||||
- **An install manifest** — small JSON carrying the bundle's URL and its **`sha256`**.
|
||||
|
||||
The manifest URL is the thing an operator pastes. The bundle is downloaded, **verified
|
||||
against the `sha256`**, and unpacked into `modules/<id>/` on the mounted volume.
|
||||
|
||||
<Aside type="caution" title="A site runs one module">
|
||||
An install whose `id` differs from a module already on the volume is refused with `409`
|
||||
before anything is downloaded. Upgrading the installed module is the only install a
|
||||
populated site accepts; to change game, remove the module first. The loader enforces the
|
||||
same rule at boot — see [Module lifecycle](/docs/modules/module-lifecycle/#the-scan).
|
||||
</Aside>
|
||||
|
||||
Nothing is compiled at any point in that sequence.
|
||||
|
||||
## The two surfaces
|
||||
|
||||
Both write the same `installed_modules` row, and neither needs a build step.
|
||||
|
||||
### The admin panel
|
||||
|
||||
Paste the manifest URL, press Install, then **restart** — a button on the same screen, not
|
||||
an instruction to go and restart the container. It runs the lifecycle shutdown and exits,
|
||||
and the supervisor declared in the shipped Compose file brings the process back.
|
||||
|
||||
That is why `restart: unless-stopped` is called out as load-bearing on [Install the
|
||||
site](/docs/getting-started/install-the-site/). Without a supervisor, that button takes the
|
||||
site down and leaves it down.
|
||||
|
||||
### The `MODULES` environment variable
|
||||
|
||||
For hosts managed by Compose rather than by clicking. Each entry is:
|
||||
|
||||
```
|
||||
<id>@<version>=<install manifest URL>
|
||||
```
|
||||
|
||||
Resolution runs **inside the server process**, before the volume is scanned — which is what
|
||||
lets it write the same provenance columns a panel install writes. A module already unpacked
|
||||
at the declared version is a no-op that makes **no network call at all**.
|
||||
|
||||
### By hand
|
||||
|
||||
`./modules` is a bind mount, deliberately rather than a named volume, so placing a module
|
||||
directory there yourself is a **supported install**. A named volume would have routed that
|
||||
through `docker cp`.
|
||||
|
||||
The image's own copy of `modules/` is excluded by `.dockerignore`, so a module sitting in a
|
||||
builder's working tree can never ship inside an image.
|
||||
|
||||
## Which surface wins
|
||||
|
||||
They govern different things, and the split is worth memorising:
|
||||
|
||||
- **The declaration owns what is on the volume.**
|
||||
- **The row owns whether a module runs.**
|
||||
|
||||
So uninstalling a declared module from the admin panel **returns its files at the next
|
||||
start and leaves it disabled**. The files come back because `MODULES` still declares them;
|
||||
it stays off because the row says so. That is the intended outcome, not a bug — but it
|
||||
surprises people who expect the panel to be the last word.
|
||||
|
||||
## Upgrades
|
||||
|
||||
Paste the new release's manifest URL and install over the top. The bundle is verified,
|
||||
unpacked over the old one, and takes effect at the restart.
|
||||
|
||||
An upgrade **deliberately leaves the state alone** — upgrading an enabled module must not
|
||||
silently switch it off, and re-installing a disabled one must not silently switch it on.
|
||||
|
||||
<Aside type="caution" title="Check the API range first">
|
||||
A module declares which core API versions it accepts. If a release needs a newer core than
|
||||
your image provides, upgrade the site first — see [The module
|
||||
manifest](/docs/modules/the-module-manifest/) for how that range is checked, and
|
||||
[Maintenance and upgrades](/docs/administration/maintenance-and-upgrades/) for the site
|
||||
half.
|
||||
</Aside>
|
||||
|
||||
## Removal
|
||||
|
||||
Covered in full on [Managing modules](/docs/administration/managing-modules/); the shape
|
||||
matters here because it constrains what you ship.
|
||||
|
||||
**Uninstall** is non-destructive: the row goes to `disabled`, the directory is removed, and
|
||||
the module's **tables and data are retained**.
|
||||
|
||||
**Purge** is separate, explicit, and destructive — it runs your `purge.sql`. It is offered
|
||||
in two places, and both are while the file is still on disk: as a standalone action on an
|
||||
installed module, and as an opt-in checkbox in the uninstall dialog.
|
||||
|
||||
That second placement exists because of a real ordering trap: **`purge.sql` lives inside the
|
||||
directory uninstall deletes**, so "purge afterwards" was never actually possible — it would
|
||||
have left a disabled row whose Purge button had nothing to run.
|
||||
|
||||
The consequence, accepted and stated: an operator who uninstalls without ticking the box
|
||||
keeps the tables, and getting rid of them later means reinstalling the module first. Write
|
||||
`purge.sql` on the assumption it may be run long after anyone remembers what it drops.
|
||||
110
src/content/docs/docs/modules/module-lifecycle.mdx
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: Module lifecycle
|
||||
description: What core does to your module on boot, in what order, and what happens when any step of it throws.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
The five states are on [Managing modules](/docs/administration/managing-modules/), from the
|
||||
operator's side. This is the same machine from inside the module — what core calls, when,
|
||||
and what it does with a throw.
|
||||
|
||||
## The scan
|
||||
|
||||
The loader reads `modules/*/module.json` from the filesystem **synchronously, at require
|
||||
time**. The database is not consulted: what is on the volume determines what mounts.
|
||||
|
||||
`MODULES_DIR` defaults to `<repo>/modules`, and Compose sets it to `/app/modules`. **A
|
||||
missing modules directory is not an error** — "no modules installed" is the normal state of
|
||||
bare core, and the loader must not make the mount mandatory to boot.
|
||||
|
||||
**A site runs one module.** The scan is alphabetical by directory name, and the first
|
||||
module directory it finds holds the site, whether or not that module then loads. Every
|
||||
other module directory is recorded `startup_failed` at the manifest stage **before any of
|
||||
its code is required**: no routes, navigation, tables or registrations. Its reason, in the
|
||||
log and on **Admin → Modules**, names both modules and says to remove one. The installer
|
||||
refuses the same thing earlier — an install whose id differs from the module already on the
|
||||
volume answers `409` before anything is downloaded — so the loader's rule is what catches a
|
||||
directory copied onto the volume by hand.
|
||||
|
||||
There is no dependency resolution between modules, because there is only ever one running.
|
||||
Do not build a module that expects another to load beside it.
|
||||
|
||||
## Validation, in order
|
||||
|
||||
Each step runs against your module. A failure at any step is **your module's failure and
|
||||
nobody else's**.
|
||||
|
||||
1. `module.json` parses, has no unknown keys, and its `id` matches the directory name.
|
||||
2. `coreApi` is satisfied by core's `MODULE_API_VERSION`.
|
||||
3. Declared `mounts` prefixes are well-formed and collide with nothing.
|
||||
4. Declared `extensions` slots all exist.
|
||||
5. `schema` and `purge` files exist and are readable, and their table names are namespaced
|
||||
or allowlisted.
|
||||
6. `require()` of your server entry succeeds and exports a function.
|
||||
7. `register(ctx, api)` returns without throwing, **and registers exactly what
|
||||
`module.json` declared**.
|
||||
|
||||
Step 7 is worth reading twice. The manifest is not documentation of what you register — it
|
||||
is a claim core holds you to. Registering something you did not declare fails, and so does
|
||||
declaring something you do not register.
|
||||
|
||||
<Aside type="note" title="Collision detection probes the live routers">
|
||||
Step 3 asks the actual tier routers whether a prefix is taken, rather than consulting a
|
||||
list of core's prefixes. A hardcoded table was tried and was already one prefix stale by
|
||||
the time it was written.
|
||||
|
||||
Mounting is also a **second pass** over the modules that survived validation, not part of
|
||||
the scan loop — otherwise the first module's layers would already be on the router while
|
||||
the second was validated, and the second would be told it collided with *core*, naming the
|
||||
wrong culprit.
|
||||
</Aside>
|
||||
|
||||
## Then the module runs
|
||||
|
||||
For each module that passed:
|
||||
|
||||
1. **Schema replay** — your `schema.sql` fragment is applied. It must be idempotent; it runs
|
||||
on every boot.
|
||||
2. **Routes and registrations** mount.
|
||||
3. **`onBoot(ctx)`** is called, if you export one. This is where long-lived work belongs:
|
||||
opening a stream, starting a poller, connecting to something.
|
||||
|
||||
On shutdown, **`onShutdown()`** is called. Disabling a module from the panel dispatches it
|
||||
too, so the module actually stops — releases its sockets, closes its streams — rather than
|
||||
merely becoming unreachable.
|
||||
|
||||
Enabling is deliberately **not** the mirror image: there is no `onBoot` re-dispatch, so the
|
||||
panel offers a restart instead. If your `onBoot` is expensive or stateful, that asymmetry is
|
||||
in your favour.
|
||||
|
||||
## Failure is contained, by construction
|
||||
|
||||
**A module that fails to load never takes the site down.**
|
||||
|
||||
The loader try/catches the module's **entire** lifecycle — require, validation, registration,
|
||||
schema replay, `onBoot` — not merely failures that surface after a router object was
|
||||
returned. Any failure at any point marks that module `startup_failed`, records the reason,
|
||||
and the site comes up with that module's routes and navigation absent.
|
||||
|
||||
Two consequences to design around:
|
||||
|
||||
- **A failed module is retried on every restart.** There is no backoff and no quarantine.
|
||||
A deterministically broken module re-records its failure each boot, which is the honest
|
||||
thing for it to do.
|
||||
- **`disabled` is the only state a boot leaves alone.** Every other non-disabled module is
|
||||
reset to `enabled` at boot and then recorded as `started` or `startup_failed`. Disabling
|
||||
is an operator's decision rather than an outcome, so it survives restarts untouched.
|
||||
|
||||
<Aside type="caution" title="Fail loudly and early">
|
||||
Because failure is contained, a broken module is easy to *not notice* — the site comes up
|
||||
fine and one section is missing. Validate your own configuration in `register()` or
|
||||
`onBoot()` and throw with a message naming what is wrong. `startup_failed` with a good
|
||||
reason is a far better outcome than a module that starts and then quietly does nothing.
|
||||
</Aside>
|
||||
|
||||
## Where the loader is specified
|
||||
|
||||
[`MODULE_API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md)
|
||||
Part 4 is the normative account of everything on this page, including the exact position of
|
||||
the `load()` call in `app.js` and why it is load-bearing in both directions.
|
||||
104
src/content/docs/docs/modules/testing-and-release.mdx
Normal file
@@ -0,0 +1,104 @@
|
||||
---
|
||||
title: Testing and release
|
||||
description: The checks a module should run before it ships, what a release artifact actually is, and how the version that ships gets decided.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
## The checks
|
||||
|
||||
Four, and each exists because something got past review without it.
|
||||
|
||||
```bash
|
||||
npm run check:imports --prefix server # zero imports leave the module directory
|
||||
npm run build --prefix client # build FIRST — two tests read the chunk
|
||||
npm run check:externals --prefix client # no shared dependency welded into the chunk
|
||||
npm test --prefix server && npm test --prefix client
|
||||
```
|
||||
|
||||
**`check:imports`** enforces [the zero-internal-imports
|
||||
rule](/docs/modules/building-a-module/#the-rule-ci-enforces). It is the mechanical form of
|
||||
the module boundary — without it, the boundary is a convention, and conventions lose.
|
||||
|
||||
**`check:externals`** is the one that catches a chunk shipping bare `import 'react'`
|
||||
specifiers, or a second React welded in. Both build cleanly. Neither works in a browser.
|
||||
|
||||
<Aside type="caution" title="Build before you test">
|
||||
Two client tests read the built chunk. Run them against a stale `dist/` and they will
|
||||
happily pass on last week's output.
|
||||
</Aside>
|
||||
|
||||
Also worth running your OpenAPI fragment check if you publish one — the filename is fixed
|
||||
at `swagger-fragment.json` in the bundle root, so a module cannot point core at some other
|
||||
file.
|
||||
|
||||
## What a release artifact is
|
||||
|
||||
**Not source.** An operator never builds anything, and that constraint shapes everything
|
||||
here.
|
||||
|
||||
A release is **the directory core's loader expects to find at `modules/<id>/`, already
|
||||
assembled** — the prebuilt client chunk, any runtime dependency installed, the schema
|
||||
fragment, the OpenAPI fragment — packed exactly as it will be unpacked.
|
||||
|
||||
Two artifacts ship:
|
||||
|
||||
- `<id>-<version>.tar.gz`
|
||||
- an **install manifest** carrying that tarball's URL and its `sha256`
|
||||
|
||||
The admin install downloads the tarball, verifies the hash, and unpacks it. **Nothing runs
|
||||
`npm` on the way.**
|
||||
|
||||
## The version that ships is the tag
|
||||
|
||||
The template derives the next version from conventional-commit subjects since the newest
|
||||
`v*` tag:
|
||||
|
||||
| Commits since the last tag | Result |
|
||||
|---|---|
|
||||
| `feat!:` or `BREAKING CHANGE` | major |
|
||||
| `feat:` | minor |
|
||||
| `fix:` / `perf:` | patch |
|
||||
| Nothing releasable | **no release is cut** |
|
||||
| First ever run, no tag | releases what `module.json` declares |
|
||||
|
||||
Your committed `module.json` version is a **floor and a starting point, not a record of the
|
||||
last release**. Name a version there above the newest tag and that version is what releases
|
||||
— which is still the natural way to say "this one is a minor" when a `coreApi` bump forces
|
||||
the question.
|
||||
|
||||
<Aside type="note" title="Why derived rather than declared">
|
||||
The obvious alternative is to let `module.json`'s version decide: you already have that
|
||||
number, and two sources for one number is how they drift.
|
||||
|
||||
This project's reference module shipped that way and moved off it. The cost of a declared
|
||||
version is paid on **every** release, and the drift it prevents is something review catches
|
||||
anyway — a week of merged work there produced no bundle at all, because none of it happened
|
||||
to touch that line.
|
||||
</Aside>
|
||||
|
||||
## Pin the core you build against
|
||||
|
||||
Keep a `ci/core-ref.json` naming the exact core commit your module is written against, and
|
||||
have CI assert your declared `coreApi` still holds against that core's
|
||||
`MODULE_API_VERSION`.
|
||||
|
||||
Moving that sha is the moment someone re-reads what changed. It is the same mechanism [the
|
||||
Integration Kit uses](/docs/modules/the-integration-kit/#the-pin-that-forces-a-re-read), and
|
||||
the reason a contract bump upstream becomes a visible decision in your repository rather
|
||||
than a silent one.
|
||||
|
||||
## Before you tag
|
||||
|
||||
A short list, all of it learned rather than invented:
|
||||
|
||||
- **The module boots on a real deployment**, not just in tests. [Failure is
|
||||
contained](/docs/modules/module-lifecycle/#failure-is-contained-by-construction), so a
|
||||
broken module is easy to not notice — the site comes up and one section is missing.
|
||||
- **`schema.sql` is genuinely idempotent.** It runs on every boot, not once.
|
||||
- **`purge.sql` still makes sense to someone who has forgotten your module**, because
|
||||
[that is who will run it](/docs/modules/installing-modules/#removal).
|
||||
- **Your `coreApi` range covers the oldest core you actually test against**, not just the
|
||||
newest one you have.
|
||||
- **Every capability string you publish is one you intend to keep.** Something outside your
|
||||
repository is branching on them.
|
||||
109
src/content/docs/docs/modules/the-integration-kit.mdx
Normal file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: The Integration Kit
|
||||
description: The instruction book for putting a different game on the platform — four chapters, a buildable template, and an honest account of its status.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
The [Integration
|
||||
Kit](https://gitea.whitlocktech.com/RunicGateway/Integration-kit) is a separate repository
|
||||
whose entire job is teaching someone **outside this project** how to put a different game on
|
||||
the platform.
|
||||
|
||||
<Aside type="caution" title="The kit describes itself as a draft, and so do we">
|
||||
In its own words: *the kit is finished when someone outside this project builds a working
|
||||
module for a new game by following it alone, without reading core's source. That has not
|
||||
happened yet.*
|
||||
|
||||
We are not going to describe it as finished before that happens. If you are the person who
|
||||
tries it, the places you get stuck are the most valuable thing the repository can receive —
|
||||
[open an issue](https://gitea.whitlocktech.com/RunicGateway/Integration-kit/issues) saying
|
||||
where you left the kit and what you did next.
|
||||
</Aside>
|
||||
|
||||
## What it covers
|
||||
|
||||
Three things, because the reasons live in the joins between them:
|
||||
|
||||
```
|
||||
your game server ──dials out──▶ your sidecar ──HTTP + WS──▶ website core
|
||||
(plugin: bounded queue, (owns the socket, (loads your module,
|
||||
writer thread) persists, then forwards) serves the pages)
|
||||
```
|
||||
|
||||
| Part | What it is |
|
||||
|---|---|
|
||||
| **The website module** | A bundle core loads at boot. The bulk of the work, and the only part every module needs |
|
||||
| **The sidecar** | A small service owning the connection to your game server, and the durable copy of what the game said. **Not optional** |
|
||||
| **The game-side plugin** | Whatever runs inside your game and feeds the sidecar, without ever letting the sidecar stall the game |
|
||||
|
||||
## The four chapters
|
||||
|
||||
| # | Chapter | What it covers |
|
||||
|---|---|---|
|
||||
| 1 | Your first module in twenty minutes | Copy the template, rename it, build it, install it, see a page. No theory |
|
||||
| 2 | The website module | `module.json`, `register(ctx, api)`, the schema fragment, the client chunk, packaging, and what a module must never do |
|
||||
| 3 | The sidecar | Why the website never talks to a game server, what "persist before you forward" means, and what a *thin* sidecar is |
|
||||
| 4 | The game-side plugin | The least code and the highest stakes: never block the game thread |
|
||||
|
||||
Before any of them, the kit points at the [Rust dry
|
||||
run](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust-dryrun.md)
|
||||
— a complete module designed on paper for a second game, and the shortest honest picture of
|
||||
the whole job. That module has since been built for real, as
|
||||
[the Rust module](https://gitea.whitlocktech.com/RunicGateway/Module-Rust), so the dry run now
|
||||
reads as the plan beside a finished result.
|
||||
|
||||
## The template is built, not just quoted
|
||||
|
||||
Chapters 1 and 2 quote `template/`, a real module that CI builds against a pinned core. The
|
||||
code in those chapters is **a tree that is proved rather than prose that looks like one**.
|
||||
|
||||
Chapters 3 and 4 cite the Ultima Online sidecar and bridge plugin by file and identifier rather than by
|
||||
line number, deliberately: those repositories move for their own reasons, and a line number
|
||||
in a book is wrong the moment they do.
|
||||
|
||||
## The kit never re-specifies a contract
|
||||
|
||||
This is its governing rule, and it is the same one this site follows.
|
||||
|
||||
> Nothing in these chapters is normative. Where a chapter and one of these documents
|
||||
> disagree, the document is right and the chapter has a bug.
|
||||
|
||||
| Authority | For |
|
||||
|---|---|
|
||||
| `MODULE_API.md` | Everything a module may do |
|
||||
| `MODULE_SYSTEM.md` | Why the module system is shaped this way, and how a module is installed and removed |
|
||||
| `link/PLAN.md` + `INTEGRATION.md` | The game ↔ sidecar wire protocol, as one real sidecar implements it |
|
||||
|
||||
The chapters teach the order to do things in, the reasoning, and **the mistakes that cost
|
||||
this project time**.
|
||||
|
||||
## The pin that forces a re-read
|
||||
|
||||
`ci/core-ref.json` pins the exact core commit the kit is written against, and CI asserts
|
||||
that the version `template/module.json` declares **equals** that core's
|
||||
`MODULE_API_VERSION`.
|
||||
|
||||
Equality, not "satisfies". That is the mechanism, not a bug: a contract bump in the website
|
||||
repository is *meant* to turn the kit red, so that someone re-reads the chapters before the
|
||||
pin moves.
|
||||
|
||||
<Aside type="note" title="It has already earned its keep">
|
||||
Writing the chapters against 1.6.0 found that core's inverted-slot fills named three of
|
||||
the first game module's slots **literally** — so the mechanism worked for that one module and silently
|
||||
did nothing for any other game, producing an empty page with nothing logged.
|
||||
|
||||
That is exactly the class of defect a book written for an audience outside this org exists
|
||||
to catch, and it was fixed in core before the pin moved.
|
||||
</Aside>
|
||||
|
||||
## Running its checks
|
||||
|
||||
Dependency-free Node scripts, from the repository root — which is also how a reader runs
|
||||
them:
|
||||
|
||||
```bash
|
||||
node scripts/checkLinks.js # every relative link resolves; no commit permalinks
|
||||
node scripts/checkRenameSites.js # the rename checklist matches the template tree
|
||||
node scripts/checkChapterPaths.js # every path a chapter names in backticks still exists
|
||||
```
|
||||
172
src/content/docs/docs/modules/the-module-api.mdx
Normal file
@@ -0,0 +1,172 @@
|
||||
---
|
||||
title: The module API
|
||||
description: The two arguments core hands your module — what you can reach, what you can register, and the rules that govern both.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import platform from '../../../../data/platform.json';
|
||||
|
||||
Your server entry point exports one function:
|
||||
|
||||
```js
|
||||
module.exports = function register(ctx, api) { /* … */ }
|
||||
```
|
||||
|
||||
`ctx` is what core lends you. `api` is what you register with it. Everything crossing the
|
||||
module boundary goes through one of the two.
|
||||
|
||||
The contract version is **`MODULE_API_VERSION`**, currently **{platform.moduleApi}**, and your manifest's
|
||||
[`coreApi` range](/docs/modules/the-module-manifest/#coreapi-and-what-a-range-means) is
|
||||
checked against it before your code is required.
|
||||
|
||||
## The entry point runs early
|
||||
|
||||
`register()` is called **once, synchronously, during core's require phase — not after the
|
||||
database is up.**
|
||||
|
||||
It must not `await`, must not touch the database, and must not throw for a reason a retry
|
||||
would fix. Everything needing a live database belongs in `onBoot`.
|
||||
|
||||
<Aside type="caution" title="This constraint is not stylistic">
|
||||
Core's route-manifest and OpenAPI generators both require the app with the connection pool
|
||||
pointed at a dead port. A module that queried at registration time would hang both.
|
||||
</Aside>
|
||||
|
||||
## `ctx` — what you can reach
|
||||
|
||||
Every member exists because a real module needed it. The surface is grown from demonstrated
|
||||
need, never speculation.
|
||||
|
||||
| Member | What it gives you |
|
||||
|---|---|
|
||||
| `ctx.express`, `ctx.validator` | Core's own `express` and `express-validator` namespaces |
|
||||
| `ctx.db.query`, `ctx.db.pool` | Parameterised SQL, and the pool for streaming work |
|
||||
| `ctx.log(namespace)` | `error` / `warn` / `info` / `debug`, each `(msg, meta?)` |
|
||||
| `ctx.settings` | `get`, `set`, `getInstanceName` |
|
||||
| `ctx.auth.getUserFromRequest(req)` | `{ id, username, role }` or `null` |
|
||||
| `ctx.push.publish` | Notification fan-out |
|
||||
| `ctx.secretBox` | `encrypt` / `decrypt` for secrets at rest |
|
||||
| `ctx.middleware` | `requireAuth`, `requireRole`, `siteMode`, `validate`, `noindex`, `rateLimit`, `accountChangeLimiter` |
|
||||
| `ctx.uploads` | `upload`, `UPLOAD_DIR`, `MIME_EXT` |
|
||||
| `ctx.posts` | `listAll`, `getById`, `linkAnnounceJob`, `markAnnounced` |
|
||||
| `ctx.paths.moduleRoot` | Absolute path to your own directory |
|
||||
| `ctx.activity.log` | The admin audit trail |
|
||||
| `ctx.users.getById` | Read a user |
|
||||
| `ctx.site.baseUrl` | Absolute base URL, no trailing slash |
|
||||
| `ctx.moduleId` | Your id, from the manifest |
|
||||
| `ctx.teams` | `publish`, `reconcile`, `activity.push` — see below |
|
||||
|
||||
`ctx` is frozen one level deep before you get it. That is a guard against accident, not
|
||||
against a hostile module — the boundary is organisational, [not a security
|
||||
boundary](/docs/modules/the-module-system/#the-boundary-is-not-a-sandbox).
|
||||
|
||||
### Three narrowings worth knowing
|
||||
|
||||
Core deliberately hands you **less** than the underlying utility exports.
|
||||
|
||||
- **`ctx.auth` is one function.** The full facade can mint sessions; minting is core's job.
|
||||
A module that needs an identity needs to *read* one.
|
||||
- **`ctx.settings` is three functions**, not the model's 24 — most of those are registration
|
||||
and app-links policy that is core's business.
|
||||
- **`ctx.posts` is four functions.** `create` / `update` / `remove` are the CMS, and the CMS
|
||||
is not a module's.
|
||||
|
||||
<Aside type="note" title="Why `ctx.express` has to exist">
|
||||
A module lives at `modules/<id>/`, outside `server/`, so Node's resolver never reaches
|
||||
core's `node_modules` and a plain `require('express')` simply fails. Even where it
|
||||
resolved, a second express in the process means a second `Router` prototype. Core owns one
|
||||
express, exactly as it owns one React.
|
||||
</Aside>
|
||||
|
||||
### `ctx.teams` is push-only, on purpose
|
||||
|
||||
There is no reader. A module **answers** questions about Teams; it does not ask them. Every
|
||||
Team table is core-internal, and a `getTeamRoster` would be core offering to read back the
|
||||
module's own answer — which the module already holds.
|
||||
|
||||
All three members are fire-and-forget and never reject, because they are called from inside
|
||||
game-event handlers and a storage problem of core's must not become your control flow.
|
||||
|
||||
See [Teams architecture](/docs/architecture/teams-architecture/) for the whole shape.
|
||||
|
||||
## `api` — what you register
|
||||
|
||||
```js
|
||||
api.registerRoutes({ public: {…}, admin: {…}, player: {…} })
|
||||
api.registerExtension(slot, router)
|
||||
api.registerNotificationStreams(streams)
|
||||
api.registerAnnounceLeg({ leg, label, dispatch, classify })
|
||||
api.registerPostHook({ onSaved, onDeleted })
|
||||
api.registerTeamProvider({ getTeams, getTeamMembers, getTeamLeaders })
|
||||
api.registerSlashCommands([{ name, description, options, access, handler }])
|
||||
api.onBoot(async (ctx) => {})
|
||||
api.onShutdown(async () => {})
|
||||
```
|
||||
|
||||
Every call is synchronous, and **calling one twice is an error** rather than a
|
||||
last-one-wins overwrite.
|
||||
|
||||
### Everything stages; nothing commits until you are known good
|
||||
|
||||
A claim's *shape* is checked at the call, so a malformed one throws with your own stack.
|
||||
Whether a name is *taken* can only be answered once the whole batch is in, and is checked
|
||||
when the loader commits.
|
||||
|
||||
The consequence is the one that matters: a module that registers two streams and then
|
||||
throws **has left nothing behind**. A half-registered catalog would be worse than a missing
|
||||
one — it is a subscribable stream that nothing will ever publish to.
|
||||
|
||||
### `registerRoutes` and the tier gate
|
||||
|
||||
One `express.Router()` per prefix per tier. The keys must match `module.json`'s `mounts`
|
||||
exactly, and prefixes are one segment — no nesting, no parameters.
|
||||
|
||||
**The tier gate is already applied.** A router registered under `admin` sits behind
|
||||
`noindex, isLoggedIn, requireRole('admin','editor','moderator')`; under `player`, behind
|
||||
`noindex, requireAuth`; under `public`, behind nothing, by design.
|
||||
|
||||
Add per-route gates on top of that. **Never re-implement the tier gate** — a module that
|
||||
rolls its own is a module whose access rules drift from core's.
|
||||
|
||||
Your router is mounted *inside* the tier, so it structurally cannot reach above its prefix.
|
||||
|
||||
## The client half
|
||||
|
||||
The client contract is its own thing. Core populates a global before it renders, and
|
||||
freezes it afterwards:
|
||||
|
||||
```js
|
||||
window.__rg = {
|
||||
version, // MODULE_API_VERSION — the same number as the server's
|
||||
react, // the React namespace
|
||||
reactDom, // react-dom/client
|
||||
router, // react-router-dom namespace
|
||||
jsxRuntime, // react/jsx-runtime
|
||||
registry, // routes, nav, feature providers, slots
|
||||
ui, // the shared component kit
|
||||
api, // the request primitive
|
||||
}
|
||||
```
|
||||
|
||||
Your chunk declares `react`, `react-dom` and `react-router-dom` as **externals** resolving
|
||||
to that global — a global rather than an import map precisely because an import map must be
|
||||
inline and `script-src 'self'` forbids inline script.
|
||||
|
||||
**`jsxRuntime` is not decoration.** Your bundler compiles every `.jsx` file to imports from
|
||||
`react/jsx-runtime` under the modern automatic runtime, and those must resolve to *core's*
|
||||
React like everything else. Without it on the global you would have to build with
|
||||
`jsxRuntime: 'classic'`; with it, you use the default your tooling already assumes.
|
||||
|
||||
**`version` is there so your entry can check it.** A module entry compares
|
||||
`window.__rg.version` against its own `coreApi` range and refuses to register on a
|
||||
mismatch, logging once — the client-side twin of the boot-time check.
|
||||
|
||||
You register routes, navigation and feature providers through `registry`. See [Building a
|
||||
module](/docs/modules/building-a-module/).
|
||||
|
||||
## The contract itself
|
||||
|
||||
[`MODULE_API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md)
|
||||
is normative and complete — Part 2 for the server contract, Part 3 for the client, Part 4
|
||||
for the loader's obligations and Part 5 for how they are enforced. This page is a map of
|
||||
it, not a substitute.
|
||||
123
src/content/docs/docs/modules/the-module-manifest.mdx
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: The module manifest
|
||||
description: Every key in module.json, what the loader does with each, and why a typo is a boot failure rather than an inert setting.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import platform from '../../../../data/platform.json';
|
||||
import GameExample from '../../../../components/GameExample.astro';
|
||||
|
||||
`module.json` sits at the root of your bundle. The loader reads it synchronously, before
|
||||
anything else about your module runs.
|
||||
|
||||
**Unknown top-level keys are rejected, not ignored.** A misspelled key is a loud failure
|
||||
rather than a silently-inert setting — which is the right trade when the alternative is a
|
||||
module that boots and mysteriously does half its job.
|
||||
|
||||
## A complete manifest
|
||||
|
||||
A real one, the Ultima Online module's, with the values that change every release elided:
|
||||
|
||||
<GameExample game="uo">
|
||||
```json
|
||||
{
|
||||
"id": "uo",
|
||||
"name": "Ultima Online",
|
||||
"version": "…",
|
||||
"coreApi": "…",
|
||||
"server": "server/index.js",
|
||||
"client": { "entry": "client/dist/entry.js" },
|
||||
"schema": "server/db/schema.sql",
|
||||
"purge": "server/db/purge.sql",
|
||||
"mounts": {
|
||||
"public": ["/shard", "/atlas"],
|
||||
"admin": ["/shard", "/uo-link"],
|
||||
"player": ["/shard"]
|
||||
},
|
||||
"extensions": ["admin.users.detail"],
|
||||
"capabilities": ["shard", "atlas", "market", "…"]
|
||||
}
|
||||
```
|
||||
</GameExample>
|
||||
|
||||
## The keys
|
||||
|
||||
| Key | Required | Meaning |
|
||||
|---|---|---|
|
||||
| `id` | yes | `^[a-z][a-z0-9-]{1,31}$`. The directory name, the `installed_modules` key, the URL segment, and the client registry key — all at once. **Must equal the directory it was read from.** |
|
||||
| `name` | yes | Human label for the admin Modules screen |
|
||||
| `version` | yes | Semver. Recorded on install; shown on failure |
|
||||
| `coreApi` | yes | Semver **range**, checked against core's `MODULE_API_VERSION` |
|
||||
| `server` | no | Server entry point, relative to the module root. Absent means a client-only module |
|
||||
| `client.entry` | no | The prebuilt ESM chunk, **in a subdirectory** — the directory it sits in is what gets served. Absent means a server-only module; present-but-empty is rejected, because it claims a client half and delivers none |
|
||||
| `schema` | no | Idempotent SQL fragment, replayed every boot |
|
||||
| `purge` | no | Destructive teardown. **Required if `schema` is present** |
|
||||
| `mounts` | no | Declared route prefixes per tier |
|
||||
| `extensions` | no | Core extension slots this module mounts into |
|
||||
| `capabilities` | no | Opaque strings published to clients for feature detection |
|
||||
|
||||
## `mounts` is a claim, not a description
|
||||
|
||||
The loader compares your declaration against what your module **actually registers**, and
|
||||
rejects a mismatch in either direction. Declaring a prefix you never mount fails; mounting
|
||||
one you never declared fails too.
|
||||
|
||||
Prefixes are validated against `^/[a-z0-9][a-z0-9-]*$`, and the keys must match what you
|
||||
register exactly.
|
||||
|
||||
<Aside type="caution" title="These are API prefixes, not page URLs">
|
||||
`mounts` governs your **server** routes. Your SPA pages are registered separately by the
|
||||
client half, and *those* are namespaced under your module id.
|
||||
|
||||
That is why the manifest above declares `admin` prefixes that are not its admin screens'
|
||||
URLs: the first is where its API routes live, the second is where the SPA puts its pages. Two
|
||||
different mechanisms, and [the module system](/docs/modules/the-module-system/) explains why
|
||||
the split is deliberate.
|
||||
</Aside>
|
||||
|
||||
## `capabilities` is for feature detection
|
||||
|
||||
Opaque strings, published by `GET /api/v1/public/modules` — and **only while the module is
|
||||
`started`**. Clients like the SPA and the Android app read them to decide what to show.
|
||||
|
||||
They are not permissions and not mount prefixes. Keep them stable: something outside your
|
||||
repository is branching on them.
|
||||
|
||||
## `coreApi` and what a range means
|
||||
|
||||
Core exports a single semver string, currently **{platform.moduleApi}**. Your range is
|
||||
checked at boot, before your code is required.
|
||||
|
||||
A **minor** bump adds members without removing any or changing a signature, so an older
|
||||
caret range keeps resolving against a newer core. The {platform.games.uo.name} module
|
||||
declares <code>{platform.games.uo.module.coreApi}</code> and runs on {platform.moduleApi};
|
||||
the {platform.games.rust.name} module declares
|
||||
<code>{platform.games.rust.module.coreApi}</code>.
|
||||
|
||||
Use a caret range against the oldest core you actually support and test against. Pinning
|
||||
exactly buys nothing and strands you on the next additive release.
|
||||
|
||||
<Aside type="note" title="Not the same number as the protocol version">
|
||||
`coreApi` versions the **website module contract**. `PROTOCOL_VERSION` versions **a game's
|
||||
wire** and says nothing about a website module. See [Protocol
|
||||
versions](/docs/architecture/protocol-versions/).
|
||||
</Aside>
|
||||
|
||||
## Schema and purge
|
||||
|
||||
`schema` runs on **every boot**, so it must be idempotent — `CREATE TABLE IF NOT EXISTS`,
|
||||
and additive migrations written so a replay is harmless. Table names must be namespaced or
|
||||
allowlisted; the loader checks.
|
||||
|
||||
`purge` is required whenever `schema` is present, because a module that can create tables
|
||||
must offer a way to remove them. It is only ever run by an explicit purge — never as part
|
||||
of an uninstall.
|
||||
|
||||
Remember [where `purge.sql` lives](/docs/modules/installing-modules/#removal): inside the
|
||||
directory an uninstall deletes. Write it to be run by someone who no longer remembers what
|
||||
your module created.
|
||||
|
||||
## The full specification
|
||||
|
||||
[`MODULE_API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md)
|
||||
§2.1 is normative for the manifest, and §2.6 for the schema fragments.
|
||||