Compare commits
1 Commits
6046214d71
...
feat/phase
| Author | SHA1 | Date | |
|---|---|---|---|
| 084ee0bb6c |
@@ -1,42 +0,0 @@
|
|||||||
# 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
@@ -1,70 +0,0 @@
|
|||||||
# 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
|
|
||||||
@@ -1,48 +0,0 @@
|
|||||||
---
|
|
||||||
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.
|
|
||||||
-->
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
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.
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
---
|
|
||||||
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. -->
|
|
||||||
@@ -1,42 +0,0 @@
|
|||||||
<!--
|
|
||||||
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.
|
|
||||||
@@ -1,209 +0,0 @@
|
|||||||
# 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,30 +65,6 @@ jobs:
|
|||||||
# the shorter form would pass locally and break only here.
|
# the shorter form would pass locally and break only here.
|
||||||
run: npm test
|
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: 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
|
- name: Production build
|
||||||
run: npm run build
|
run: npm run build
|
||||||
|
|
||||||
@@ -139,64 +115,3 @@ jobs:
|
|||||||
env:
|
env:
|
||||||
GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
|
GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
|
||||||
run: npm run check:quickstart
|
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
|
|
||||||
|
|||||||
@@ -1,17 +0,0 @@
|
|||||||
# 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
@@ -1,141 +0,0 @@
|
|||||||
# 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 eleven, 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
@@ -1,409 +0,0 @@
|
|||||||
# 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
@@ -1,132 +0,0 @@
|
|||||||
# 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,7 +32,6 @@ 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. |
|
| 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 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 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. |
|
| Device or other IDs | Device or other IDs | No | No | Not collected. |
|
||||||
|
|
||||||
## Each answer, and why it is the truthful one
|
## Each answer, and why it is the truthful one
|
||||||
@@ -84,23 +83,12 @@ 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.
|
**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. 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.
|
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.
|
||||||
|
|
||||||
- **Why that answer:** Content is written to the community’s own installation. We have no copy, no access and no way to obtain one.
|
- **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
|
- **Retention:** Held by the deployment, under its operator’s policy
|
||||||
- **Read from:** `PLAN.md §9 section 2`
|
- **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
|
### No analytics, no crash reporting, no advertising
|
||||||
|
|
||||||
**Device or other IDs → Device or other IDs.** Not collected.
|
**Device or other IDs → Device or other IDs.** Not collected.
|
||||||
@@ -128,4 +116,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.
|
- **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.
|
- **The web server’s access log** — Short-term operational retention, then rotated away.
|
||||||
|
|
||||||
Last generated from data dated 2026-09-01. Regenerate with `npm run play:datasafety` after any change to what the app stores.
|
Last generated from data dated 2026-08-24. Regenerate with `npm run play:datasafety` after any change to what the app stores.
|
||||||
|
|||||||
107
README.md
@@ -11,12 +11,11 @@ closed beta: **players**, who want the app.
|
|||||||
platform state, the org lead's decisions, the information architecture, and the build phases. Read
|
platform state, the org lead's decisions, the information architecture, and the build phases. Read
|
||||||
it before changing anything here.
|
it before changing anything here.
|
||||||
|
|
||||||
**Status: phase 12 of 12 — delivery. The site is built.** Fifty pages: ten marketing, legal and
|
**Status: phase 5 of 12 — the app and the beta.** The foundation, the branding pipeline, the
|
||||||
app pages and forty of documentation, with real screenshots of the product, full-text search, a
|
homepage and the five marketing pages are built, and `/app/` and `/beta/` now join them: a signed
|
||||||
per-page Content-Security-Policy, eleven checks that fail the build when the platform moves out from
|
APK beside the closed-test signup, backed by a SQLite store on a bind mount and an export CLI. Next
|
||||||
under a claim, and a closed-beta signup backed by SQLite on a bind mount. This phase is the part
|
are the legal pages (phase 6) and then the documentation — the installation path, which is the
|
||||||
that makes it a deployment rather than a repository — the container image, the compose file, the
|
priority of the whole project — in phases 7 and 8.
|
||||||
publishing workflow and [`DEPLOY.md`](DEPLOY.md).
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -32,43 +31,21 @@ npm run build # → dist/ (prerendered pages + the Node server entry)
|
|||||||
npm start # serve the built site
|
npm start # serve the built site
|
||||||
```
|
```
|
||||||
|
|
||||||
Node 22 LTS or newer. Nothing else — no database, no game server, no container runtime.
|
Node 22 LTS or newer.
|
||||||
|
|
||||||
## 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
|
## The checks, and why they are not optional
|
||||||
|
|
||||||
Eleven of them, from `PLAN.md` §12. None is a linter; each one enforces a promise the site makes
|
Two of them, both from `PLAN.md` §12. Neither is a linter; each one enforces a promise the site
|
||||||
that would otherwise decay quietly.
|
makes that would otherwise decay quietly.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm run check:sidebar # the rendered docs tree still matches the planned one
|
|
||||||
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:tokens # no colour literal outside the token file
|
||||||
npm run check:brand # the branding pipeline's two quiet failures
|
npm run check:brand # the branding pipeline's two quiet failures
|
||||||
npm run check:datasafety # the Play declaration still matches /privacy
|
npm run check:datasafety # the Play declaration still matches /privacy
|
||||||
npm run check # astro check
|
npm run check # astro check
|
||||||
npm test # the beta signup's decision path, and the policy data
|
npm test # the beta signup's decision path, and the policy data
|
||||||
npm run build # everything below reads the build
|
npm run build && npm run check:links # every internal link resolves (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: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
|
npm run verify # all of the above, in that order
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -104,22 +81,6 @@ 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
|
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.
|
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,
|
**`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
|
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
|
a build identical to one where it works. It covers the honeypot, the signed form token, the timing
|
||||||
@@ -186,40 +147,6 @@ 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
|
the emblem and the Cinzel outlines from the sibling checkouts in the workspace. Its output is
|
||||||
committed so that CI never needs either.
|
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
|
## Layout
|
||||||
|
|
||||||
```
|
```
|
||||||
@@ -243,17 +170,12 @@ src/
|
|||||||
lib/betaSignup.mjs Everything between a POST body and a row. Never throws.
|
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.
|
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/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.
|
brand-default/ The stock brand, baked into the image and always complete.
|
||||||
scripts/ The build-time checks, plus applyBrand and serve (boot),
|
scripts/ The build-time checks, plus applyBrand (boot), brand:assets (manual)
|
||||||
brand:assets (manual) and beta.mjs (the tester-list CLI).
|
and beta.mjs (the tester-list CLI).
|
||||||
test/ node --test. The logic the other checks cannot see.
|
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
|
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.
|
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
|
Two directories are bind mounts at runtime and are **not** in the repository: `brand/` overrides
|
||||||
@@ -264,18 +186,13 @@ and §7.
|
|||||||
|
|
||||||
Branch from `main` (`feature/…`, `fix/…`, `docs/…`, `chore/…`) and use
|
Branch from `main` (`feature/…`, `fix/…`, `docs/…`, `chore/…`) and use
|
||||||
[Conventional Commits](https://www.conventionalcommits.org/). Run `npm run verify` before opening a
|
[Conventional Commits](https://www.conventionalcommits.org/). Run `npm run verify` before opening a
|
||||||
pull request. **[CONTRIBUTING.md](CONTRIBUTING.md)** has the rest, including the two rules from
|
pull request.
|
||||||
`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
|
**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
|
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
|
`Co-Authored-By: Claude <noreply@anthropic.com>`. Undisclosed AI-generated contributions may be
|
||||||
closed.
|
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
|
## Licence
|
||||||
|
|
||||||
GPL-3.0-or-later, in common with every repository in the organisation. See [LICENSE](LICENSE).
|
GPL-3.0-or-later, in common with every repository in the organisation. See [LICENSE](LICENSE).
|
||||||
|
|||||||
43
SECURITY.md
@@ -1,43 +0,0 @@
|
|||||||
# 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,7 +3,6 @@ import { defineConfig } from 'astro/config';
|
|||||||
import node from '@astrojs/node';
|
import node from '@astrojs/node';
|
||||||
import starlight from '@astrojs/starlight';
|
import starlight from '@astrojs/starlight';
|
||||||
|
|
||||||
import { inlineScriptHashes, inlineStyleHashes } from './src/config/cspHashes.mjs';
|
|
||||||
import { docsSidebar } from './src/config/sidebar.mjs';
|
import { docsSidebar } from './src/config/sidebar.mjs';
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -21,72 +20,13 @@ import { docsSidebar } from './src/config/sidebar.mjs';
|
|||||||
export default defineConfig({
|
export default defineConfig({
|
||||||
site: 'https://runicgateway.com',
|
site: 'https://runicgateway.com',
|
||||||
output: 'static',
|
output: 'static',
|
||||||
// `staticHeaders` is what turns §6's CSP from a promise into a response header (D48).
|
adapter: node({ mode: 'standalone' }),
|
||||||
// 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: {
|
build: {
|
||||||
// Directory-style URLs, so every link in prose can end in a slash and mean it.
|
// Directory-style URLs, so every link in prose can end in a slash and mean it.
|
||||||
format: 'directory',
|
format: 'directory',
|
||||||
},
|
},
|
||||||
|
|
||||||
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: [
|
integrations: [
|
||||||
starlight({
|
starlight({
|
||||||
title: 'Runic Gateway',
|
title: 'Runic Gateway',
|
||||||
@@ -109,9 +49,6 @@ export default defineConfig({
|
|||||||
// Starlight builds its own head, so the docs otherwise miss the brand stylesheet,
|
// Starlight builds its own head, so the docs otherwise miss the brand stylesheet,
|
||||||
// the manifest and the OG card entirely. See the component.
|
// the manifest and the OG card entirely. See the component.
|
||||||
Head: './src/components/DocsHead.astro',
|
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,
|
credits: false,
|
||||||
sidebar: docsSidebar,
|
sidebar: docsSidebar,
|
||||||
|
|||||||
@@ -1,104 +0,0 @@
|
|||||||
# 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
20
package.json
@@ -12,7 +12,7 @@
|
|||||||
"dev": "astro dev",
|
"dev": "astro dev",
|
||||||
"build": "astro build",
|
"build": "astro build",
|
||||||
"preview": "astro preview",
|
"preview": "astro preview",
|
||||||
"start": "node scripts/applyBrand.mjs && node scripts/serve.mjs",
|
"start": "node scripts/applyBrand.mjs && node ./dist/server/entry.mjs",
|
||||||
"check": "astro check",
|
"check": "astro check",
|
||||||
"check:facts": "node scripts/checkFacts.mjs",
|
"check:facts": "node scripts/checkFacts.mjs",
|
||||||
"check:tokens": "node scripts/checkTokens.mjs",
|
"check:tokens": "node scripts/checkTokens.mjs",
|
||||||
@@ -20,19 +20,11 @@
|
|||||||
"check:links": "node scripts/checkLinks.mjs",
|
"check:links": "node scripts/checkLinks.mjs",
|
||||||
"check:datasafety": "node scripts/playDataSafety.mjs --check",
|
"check:datasafety": "node scripts/playDataSafety.mjs --check",
|
||||||
"check:quickstart": "node scripts/checkQuickstart.mjs",
|
"check:quickstart": "node scripts/checkQuickstart.mjs",
|
||||||
"check:reference": "node scripts/checkReference.mjs",
|
|
||||||
"check:sidebar": "node scripts/checkSidebar.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",
|
"play:datasafety": "node scripts/playDataSafety.mjs",
|
||||||
"beta": "node scripts/beta.mjs",
|
"beta": "node scripts/beta.mjs",
|
||||||
"test": "node --test test/beta.test.mjs test/legal.test.mjs test/footer.test.mjs",
|
"test": "node --test test/beta.test.mjs test/legal.test.mjs",
|
||||||
"brand:assets": "node scripts/buildBrandAssets.mjs",
|
"brand:assets": "node scripts/buildBrandAssets.mjs",
|
||||||
"screens:capture": "node scripts/captureScreens.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"
|
||||||
"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: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": {
|
"dependencies": {
|
||||||
"@astrojs/node": "^11.1.4",
|
"@astrojs/node": "^11.1.4",
|
||||||
@@ -41,14 +33,12 @@
|
|||||||
"@fontsource-variable/inter": "^5.3.0",
|
"@fontsource-variable/inter": "^5.3.0",
|
||||||
"astro": "^7.2.4",
|
"astro": "^7.2.4",
|
||||||
"better-sqlite3": "^12.11.1",
|
"better-sqlite3": "^12.11.1",
|
||||||
"pagefind": "^1.5.2",
|
|
||||||
"sharp": "^0.35.3"
|
"sharp": "^0.35.3"
|
||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"@astrojs/check": "^0.9.10",
|
"@astrojs/check": "^0.9.10",
|
||||||
"opentype.js": "^2.0.0",
|
"opentype.js": "^2.0.0",
|
||||||
"puppeteer-core": "^23.11.1",
|
"yaml": "^2.8.1",
|
||||||
"typescript": "^6.0.3",
|
"typescript": "^6.0.3"
|
||||||
"yaml": "^2.8.1"
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
|
Before Width: | Height: | Size: 62 KiB |
|
Before Width: | Height: | Size: 114 KiB |
|
Before Width: | Height: | Size: 58 KiB |
|
Before Width: | Height: | Size: 73 KiB |
|
Before Width: | Height: | Size: 48 KiB |
|
Before Width: | Height: | Size: 46 KiB |
|
Before Width: | Height: | Size: 55 KiB |
|
Before Width: | Height: | Size: 50 KiB |
|
Before Width: | Height: | Size: 136 KiB |
|
Before Width: | Height: | Size: 89 KiB |
|
Before Width: | Height: | Size: 111 KiB |
|
Before Width: | Height: | Size: 82 KiB |
|
Before Width: | Height: | Size: 52 KiB |
|
Before Width: | Height: | Size: 51 KiB |
|
Before Width: | Height: | Size: 55 KiB |
|
Before Width: | Height: | Size: 73 KiB |
|
Before Width: | Height: | Size: 38 KiB |
|
Before Width: | Height: | Size: 67 KiB |
@@ -229,71 +229,10 @@ const counts = new Map(replacements.map((r) => [r.field, 0]));
|
|||||||
counts.set('demoDeep', 0);
|
counts.set('demoDeep', 0);
|
||||||
let filesTouched = 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)) {
|
for (const file of walk(CLIENT)) {
|
||||||
const before = readFileSync(file, 'utf8');
|
const before = readFileSync(file, 'utf8');
|
||||||
let after = before;
|
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) {
|
for (const { field, from, to } of replacements) {
|
||||||
if (!after.includes(from)) continue;
|
if (!after.includes(from)) continue;
|
||||||
counts.set(field, counts.get(field) + after.split(from).length - 1);
|
counts.set(field, counts.get(field) + after.split(from).length - 1);
|
||||||
@@ -331,47 +270,6 @@ if (counts.get('demoDeep')) {
|
|||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
if (inlineCollisions.length) {
|
// Pagefind builds its search index from the HTML at BUILD time (phase 10), so a rename
|
||||||
console.error(
|
// applied here reaches the pages but not the search results. Worth fixing when search
|
||||||
`\n[brand] ${inlineCollisions.length} file(s) were LEFT UNCHANGED: a brand value occurs ` +
|
// lands; recorded here rather than in a plan section nobody will re-read.
|
||||||
`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();
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|||||||
@@ -1,189 +0,0 @@
|
|||||||
#!/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);
|
|
||||||
@@ -1,278 +0,0 @@
|
|||||||
#!/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);
|
|
||||||
}
|
|
||||||
@@ -1,263 +0,0 @@
|
|||||||
#!/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,28 +60,8 @@ async function api(pathname) {
|
|||||||
return res;
|
return res;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
const raw = async (repo, filePath, ref) =>
|
||||||
* A file's bytes, read through the `contents` endpoint rather than `raw`.
|
(await api(`${repo}/raw/${filePath}?ref=${encodeURIComponent(ref)}`)).text();
|
||||||
*
|
|
||||||
* `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();
|
const json = async (pathname) => (await api(pathname)).json();
|
||||||
|
|
||||||
@@ -92,42 +72,33 @@ function extract(text, re, what, authority) {
|
|||||||
return m[1];
|
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. Each game's wire protocol, from its sidecar
|
// 1. The wire protocol, from the sidecar itself
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
async function checkProtocol() {
|
async function checkProtocol() {
|
||||||
for (const [key, game] of GAMES) {
|
const authority = 'link main:sidecar/src/main.rs';
|
||||||
const authority = `${game.sidecarRepo} main:sidecar/src/main.rs`;
|
const src = await raw('link', 'sidecar/src/main.rs', 'main');
|
||||||
const src = await raw(game.sidecarRepo, 'sidecar/src/main.rs', 'main');
|
const value = extract(
|
||||||
const value = extract(
|
src,
|
||||||
src,
|
/pub const PROTOCOL_VERSION:\s*u32\s*=\s*(\d+)\s*;/,
|
||||||
/pub const PROTOCOL_VERSION:\s*u32\s*=\s*(\d+)\s*;/,
|
'PROTOCOL_VERSION',
|
||||||
'PROTOCOL_VERSION',
|
authority
|
||||||
authority
|
);
|
||||||
);
|
record('protocol (sidecar)', platform.protocol, Number(value), authority);
|
||||||
record(`${key} protocol (sidecar)`, game.protocol, Number(value), authority);
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
// 2. Each game plugin's declared protocol — the third declaration site
|
// 2. The overlay'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,
|
// 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 plugin. If these two ever
|
// or the installer refuses to pair the sidecar with the overlay. If these two ever
|
||||||
// disagree, the site must not print either number. Both games keep the file under the
|
// disagree, the site must not print either number.
|
||||||
// same name at the root of their plugin repository.
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
async function checkOverlayProtocol() {
|
async function checkOverlayProtocol() {
|
||||||
for (const [key, game] of GAMES) {
|
const authority = 'servuo-plugins main:overlay.toml';
|
||||||
const authority = `${game.pluginRepo} main:overlay.toml`;
|
const toml = await raw('servuo-plugins', 'overlay.toml', 'main');
|
||||||
const toml = await raw(game.pluginRepo, 'overlay.toml', 'main');
|
const value = extract(toml, /^\s*protocol\s*=\s*(\d+)\s*$/m, 'protocol', authority);
|
||||||
const value = extract(toml, /^\s*protocol\s*=\s*(\d+)\s*$/m, 'protocol', authority);
|
record('protocol (overlay)', platform.protocol, Number(value), authority);
|
||||||
record(`${key} protocol (plugin)`, game.protocol, Number(value), authority);
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
@@ -146,7 +117,7 @@ async function checkModuleApi() {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
// 4. The capabilities each game's module actually declares
|
// 4. The capabilities the installed module actually declares
|
||||||
//
|
//
|
||||||
// §12 names "module-uo's capability list" as one of the facts platform.json holds, and it
|
// §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
|
// was the one fact nothing re-read. That mattered from phase 3 onwards, because the
|
||||||
@@ -159,109 +130,36 @@ async function checkModuleApi() {
|
|||||||
// array is not a changed capability set. A slug appearing or disappearing is.
|
// array is not a changed capability set. A slug appearing or disappearing is.
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
async function checkModuleCapabilities() {
|
async function checkModuleCapabilities() {
|
||||||
for (const [key, game] of GAMES) {
|
const authority = 'Module-uo main:module.json';
|
||||||
const authority = `${game.module.repo} main:module.json`;
|
const manifest = JSON.parse(await raw('Module-uo', 'module.json', 'main'));
|
||||||
const manifest = JSON.parse(await raw(game.module.repo, 'module.json', 'main'));
|
const declared = [...(manifest.capabilities || [])].sort();
|
||||||
const declared = [...(manifest.capabilities || [])].sort();
|
const expected = [...platform.moduleUoCapabilities].sort();
|
||||||
const expected = [...game.module.capabilities].sort();
|
|
||||||
|
|
||||||
record(`${key} module capabilities`, expected.join(' '), declared.join(' '), authority);
|
record('moduleUoCapabilities', 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. Each game's current bundle
|
// 5. The current bundle
|
||||||
//
|
//
|
||||||
// One manifest per game on the installer's `bundles` branch, at
|
// The manifests live at the ROOT of the `bundles` branch — `current.json`,
|
||||||
// `v2/<game>/current.json` (schema 2). The ROOT `current.json` is the schema-1 manifest
|
// `bundle-<tag>.json` — not under `bundles/`. Fetching the directory 404s.
|
||||||
// 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 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 };
|
|
||||||
}
|
|
||||||
|
|
||||||
async function checkBundle() {
|
async function checkBundle() {
|
||||||
const { uo, rust } = platform.games;
|
const authority = 'installer bundles:current.json';
|
||||||
|
const current = JSON.parse(await raw('installer', 'current.json', 'bundles'));
|
||||||
|
|
||||||
{
|
record('bundle.tag', platform.bundle.tag, current.bundle, authority);
|
||||||
const { current, authority } = await readBundle(uo);
|
record('bundle.sidecar', platform.bundle.sidecar, current.link?.tag, authority);
|
||||||
record('uo bundle.tag', uo.bundle.tag, current.bundle, authority);
|
record('bundle.overlay', platform.bundle.overlay, current.overlay?.tag, 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(
|
record(
|
||||||
'runicnpc oxideMin',
|
'bundle.servuoMin',
|
||||||
npc.oxideMin,
|
platform.bundle.servuoMin,
|
||||||
extract(toml, /^\s*min_oxide_version\s*=\s*"([^"]+)"/m, 'min_oxide_version', authority),
|
current.overlay?.servuo?.min_version,
|
||||||
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
|
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);
|
||||||
}
|
}
|
||||||
|
|
||||||
// ---------------------------------------------------------------------------
|
// ---------------------------------------------------------------------------
|
||||||
@@ -431,7 +329,6 @@ async function main() {
|
|||||||
checkModuleApi,
|
checkModuleApi,
|
||||||
checkModuleCapabilities,
|
checkModuleCapabilities,
|
||||||
checkBundle,
|
checkBundle,
|
||||||
checkRunicNpc,
|
|
||||||
checkReleases,
|
checkReleases,
|
||||||
checkWebsiteHasNoReleases,
|
checkWebsiteHasNoReleases,
|
||||||
checkAndroidApk,
|
checkAndroidApk,
|
||||||
|
|||||||
@@ -55,18 +55,12 @@ const checked = [];
|
|||||||
const ok = (what) => checked.push(what);
|
const ok = (what) => checked.push(what);
|
||||||
const fail = (what, detail) => failures.push({ what, detail });
|
const fail = (what, detail) => failures.push({ what, detail });
|
||||||
|
|
||||||
/** Same file accessor checkFacts.mjs uses, and for the same reason -- including the CDN one. */
|
/** Same raw-file accessor checkFacts.mjs uses, and for the same reason. */
|
||||||
async function raw(repo, filePath, ref) {
|
async function raw(repo, filePath, ref) {
|
||||||
const url = `${BASE}/api/v1/repos/${ORG}/${repo}/contents/${filePath}?ref=${encodeURIComponent(ref)}`;
|
const url = `${BASE}/api/v1/repos/${ORG}/${repo}/raw/${filePath}?ref=${encodeURIComponent(ref)}`;
|
||||||
const res = await fetch(url, { headers: { Authorization: `token ${TOKEN}` } });
|
const res = await fetch(url, { headers: { Authorization: `token ${TOKEN}` } });
|
||||||
if (!res.ok) throw new Error(`${res.status} ${res.statusText} for ${url}`);
|
if (!res.ok) throw new Error(`${res.status} ${res.statusText} for ${url}`);
|
||||||
const meta = await res.json();
|
return res.text();
|
||||||
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');
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|||||||
@@ -1,197 +0,0 @@
|
|||||||
#!/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.
|
|
||||||
*
|
|
||||||
* 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,
|
|
||||||
} 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]);
|
|
||||||
|
|
||||||
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.
|
|
||||||
const configRs = await raw('link', 'sidecar/src/config.rs');
|
|
||||||
const sidecarKeys = [];
|
|
||||||
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)) sidecarKeys.push(`${section}.${f[1]}`);
|
|
||||||
}
|
|
||||||
compareSets('sidecar.toml', Object.keys(sidecarConfig), sidecarKeys, '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.keys(canonicalDocs)) {
|
|
||||||
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})`);
|
|
||||||
}
|
|
||||||
|
|
||||||
// ── 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);
|
|
||||||
});
|
|
||||||
@@ -1,171 +0,0 @@
|
|||||||
#!/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.`);
|
|
||||||
@@ -1,77 +0,0 @@
|
|||||||
#!/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);
|
|
||||||
}
|
|
||||||
@@ -1,469 +0,0 @@
|
|||||||
#!/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',
|
|
||||||
);
|
|
||||||
@@ -1,204 +0,0 @@
|
|||||||
#!/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`);
|
|
||||||
});
|
|
||||||
@@ -1,53 +0,0 @@
|
|||||||
---
|
|
||||||
/**
|
|
||||||
* 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,7 +1,6 @@
|
|||||||
---
|
---
|
||||||
import { renderBrand } from '../lib/brand.mjs';
|
import { brand } from '../lib/brand.mjs';
|
||||||
import { legal } from '../data/legal.mjs';
|
import { legal } from '../data/legal.mjs';
|
||||||
import { footerColumns } from '../data/footer.mjs';
|
|
||||||
import platform from '../data/platform.json';
|
import platform from '../data/platform.json';
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -14,15 +13,35 @@ import platform from '../data/platform.json';
|
|||||||
* reader browses to alongside Features, it is a thing they go looking for, and the line
|
* 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.
|
* 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 year = new Date().getFullYear();
|
||||||
|
|
||||||
// The columns live in src/data/footer.mjs so a test can read them — see the note there,
|
const columns = [
|
||||||
// and test/footer.test.mjs. The two Project links come from the mounted brand (§7).
|
{
|
||||||
const columns = footerColumns(brand);
|
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' },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
];
|
||||||
|
|
||||||
const isExternal = (href: string) => href.startsWith('http');
|
const isExternal = (href: string) => href.startsWith('http');
|
||||||
---
|
---
|
||||||
@@ -62,9 +81,8 @@ const isExternal = (href: string) => href.startsWith('http');
|
|||||||
</span>
|
</span>
|
||||||
</p>
|
</p>
|
||||||
<p class="site-footer__meta">
|
<p class="site-footer__meta">
|
||||||
{/* D66, as on the hero: the shared version only. Each game's protocol and bundle
|
<span class="chip chip--version">Protocol {platform.protocol}</span>
|
||||||
are on that game's pages. */}
|
<span class="chip chip--version">Bundle {platform.bundle.tag}</span>
|
||||||
<span class="chip chip--version">Module API {platform.moduleApi}</span>
|
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
|||||||
@@ -1,6 +1,5 @@
|
|||||||
---
|
---
|
||||||
import Search from './Search.astro';
|
import { brand } from '../lib/brand.mjs';
|
||||||
import { renderBrand } from '../lib/brand.mjs';
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The marketing header. The docs get Starlight's own header, themed to match in
|
* The marketing header. The docs get Starlight's own header, themed to match in
|
||||||
@@ -21,10 +20,6 @@ import { renderBrand } from '../lib/brand.mjs';
|
|||||||
*/
|
*/
|
||||||
const { pathname } = Astro.url;
|
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 = [
|
const links = [
|
||||||
{ href: '/features/', label: 'Features' },
|
{ href: '/features/', label: 'Features' },
|
||||||
{ href: '/docs/', label: 'Docs' },
|
{ href: '/docs/', label: 'Docs' },
|
||||||
@@ -60,8 +55,6 @@ const isCurrent = (href: string) =>
|
|||||||
))
|
))
|
||||||
}
|
}
|
||||||
</nav>
|
</nav>
|
||||||
|
|
||||||
<Search />
|
|
||||||
</div>
|
</div>
|
||||||
</header>
|
</header>
|
||||||
|
|
||||||
|
|||||||
@@ -1,81 +0,0 @@
|
|||||||
---
|
|
||||||
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>
|
|
||||||
@@ -1,279 +0,0 @@
|
|||||||
---
|
|
||||||
/**
|
|
||||||
* 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>
|
|
||||||
@@ -1,75 +0,0 @@
|
|||||||
---
|
|
||||||
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,36 +1,61 @@
|
|||||||
---
|
---
|
||||||
import { screensOf, PHONE } from '../../data/screens.mjs';
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The app's screenshot strip. Reserved in phase 5 (D26), filled in phase 9.
|
* The app's screenshot strip — defined now, empty until phase 9 (D26).
|
||||||
*
|
*
|
||||||
* ---------------------------------------------------------------------------------------
|
* ---------------------------------------------------------------------------------------
|
||||||
* WHY THIS COMPONENT EXISTED FOR A PHASE WITH NOTHING IN IT
|
* WHY A COMPONENT THAT RENDERS NOTHING IS WORTH COMMITTING
|
||||||
* ---------------------------------------------------------------------------------------
|
* ---------------------------------------------------------------------------------------
|
||||||
* PLAN.md §10 said `/app/` shows "the 14 existing screenshots". They exist —
|
* 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
|
* `docs/android/screenshots/` on the `docs` repository — and they are the wrong fourteen:
|
||||||
* trusted-device and recovery-code smoke test from 2026-07-22, captured against a
|
* 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
|
* 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.
|
* every screen looks. Five of them are two-factor prompts. The home shot is an empty page.
|
||||||
*
|
*
|
||||||
* Shipping them would have broken D4 and §1 at once, so D26 reserved the slot for the phase
|
* Shipping them would break two things at once: D4, which says real screenshots from the
|
||||||
* that stands up the review stack anyway. The shape was defined then and the data arrived
|
* review stack rather than placeholders, and §1, because they would show an app that no
|
||||||
* now, which is exactly what it was for: filling it was a data change.
|
* 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.
|
||||||
*
|
*
|
||||||
* ---------------------------------------------------------------------------------------
|
* ---------------------------------------------------------------------------------------
|
||||||
* WHY IT READS screens.mjs RATHER THAN HOLDING ITS OWN LIST
|
* WHAT PHASE 9 SHOULD PUT HERE
|
||||||
* ---------------------------------------------------------------------------------------
|
* ---------------------------------------------------------------------------------------
|
||||||
* The draft carried its own `shots` array, written before there was anywhere else to put
|
* Portrait captures at the device's own pixel size, from an API 36 emulator pointed at the
|
||||||
* one. There is now: `src/data/screens.mjs` holds every capture the site ships, web and
|
* seeded review stack, one per idea rather than one per screen: the shard hub with live
|
||||||
* phone alike, and `scripts/checkScreens.mjs` proves each one exists at the size the markup
|
* data, the marketplace, a character sheet, the news list, the notification settings, and
|
||||||
* claims. A second list here would be the one nothing checks.
|
* 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 phone captures come from an emulator pointed at the same seeded deployment the web
|
* They belong in `public/`, not `brand-default/`: these are editorial content shipped with
|
||||||
* screenshots were taken from, on the same day — which is the property D26 was really
|
* the image, not branding an operator overrides (§7).
|
||||||
* after, since the app takes its colours, type and navigation from the site it connects to.
|
|
||||||
*/
|
*/
|
||||||
|
|
||||||
const shots = screensOf('phone');
|
/**
|
||||||
|
* 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[] = [];
|
||||||
---
|
---
|
||||||
|
|
||||||
{
|
{
|
||||||
@@ -38,8 +63,8 @@ const shots = screensOf('phone');
|
|||||||
<section class="page section shots">
|
<section class="page section shots">
|
||||||
<h2>What it looks like</h2>
|
<h2>What it looks like</h2>
|
||||||
<p class="prose shots__lede">
|
<p class="prose shots__lede">
|
||||||
Captured against a real deployment with real content, not mocked up. The app takes its
|
Captured against a real deployment with real content, not mocked up. The app takes
|
||||||
colours, type and navigation from the site it is connected to, so these show one
|
its colours, type and navigation from the site it is connected to, so these show one
|
||||||
community's app rather than a neutral one.
|
community's app rather than a neutral one.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
@@ -47,10 +72,10 @@ const shots = screensOf('phone');
|
|||||||
{shots.map((shot) => (
|
{shots.map((shot) => (
|
||||||
<li class="shots__item">
|
<li class="shots__item">
|
||||||
<img
|
<img
|
||||||
src={`/screens/${shot.id}.webp`}
|
src={shot.src}
|
||||||
alt={shot.alt}
|
alt={shot.alt}
|
||||||
width={PHONE.width}
|
width={shot.width}
|
||||||
height={PHONE.height}
|
height={shot.height}
|
||||||
loading="lazy"
|
loading="lazy"
|
||||||
decoding="async"
|
decoding="async"
|
||||||
/>
|
/>
|
||||||
|
|||||||
@@ -8,11 +8,9 @@ import platform from '../../data/platform.json';
|
|||||||
* The other two draw runtime shapes. This one draws a code boundary, and it is here because
|
* 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
|
* 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
|
* 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 — two modules
|
* page draws the seam and then says plainly what does and does not prove it — one module
|
||||||
* exist, both built inside this project, and the exit criterion for calling the contract
|
* exists, the second is a paper exercise, and the exit criterion for calling the contract
|
||||||
* proven by an outsider is written down (§2, §16, and the entries `/modules/` renders from
|
* proven is written down (§2, and the entries `/modules/` renders from `notBuilt.mjs`).
|
||||||
* `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
|
* 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
|
* (§12). It is the one place a version genuinely belongs in this diagram: the seam is
|
||||||
@@ -75,7 +73,7 @@ import platform from '../../data/platform.json';
|
|||||||
<!-- The module: everything that knows a game exists. -->
|
<!-- The module: everything that knows a game exists. -->
|
||||||
<rect class="host" x="8" y="306" width="364" height="186" rx="14" />
|
<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-title" x="28" y="340">Game module</text>
|
||||||
<text class="host-sub" x="28" y="360">one per deployment; UO or Rust today</text>
|
<text class="host-sub" x="28" y="360">one per deployment; UO today</text>
|
||||||
|
|
||||||
<rect class="node" x="28" y="378" width="156" height="46" rx="10" />
|
<rect class="node" x="28" y="378" width="156" height="46" rx="10" />
|
||||||
<text class="node-title" x="46" y="406">Routes</text>
|
<text class="node-title" x="46" y="406">Routes</text>
|
||||||
@@ -132,12 +130,11 @@ import platform from '../../data/platform.json';
|
|||||||
<section>
|
<section>
|
||||||
<h3>What this does not yet prove</h3>
|
<h3>What this does not yet prove</h3>
|
||||||
<p>
|
<p>
|
||||||
Two modules exist: Ultima Online, and Rust, which this project built second, from
|
One module exists and it is Ultima Online. A second, for a different game, is a
|
||||||
the Integration Kit. Where the Rust module needed something the contract did not
|
written dry-run that was deliberately never implemented — it exists to test whether
|
||||||
yet offer, the gap was closed in core, for every module, rather than in a fork — so
|
the contract generalises on paper. Until somebody builds the second one, the seam is
|
||||||
the seam now has two games on its far side instead of one. What two modules built
|
a well-argued design rather than a demonstrated one, and this site says so wherever
|
||||||
inside this project cannot prove is that somebody outside it can do the same, and
|
it comes up.
|
||||||
that is why the Integration Kit still says draft.
|
|
||||||
</p>
|
</p>
|
||||||
</section>
|
</section>
|
||||||
</div>
|
</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
|
* what exists while quietly omitting the well-known things that do not is the exact failure
|
||||||
* §1 is written to prevent.
|
* §1 is written to prevent.
|
||||||
*/
|
*/
|
||||||
assertCapabilityCoverage(platform.games.uo.module.capabilities);
|
assertCapabilityCoverage(platform.moduleUoCapabilities);
|
||||||
---
|
---
|
||||||
|
|
||||||
<section class="page section caps">
|
<section class="page section caps">
|
||||||
@@ -52,7 +52,7 @@ assertCapabilityCoverage(platform.games.uo.module.capabilities);
|
|||||||
|
|
||||||
<p class="caps__foot prose">
|
<p class="caps__foot prose">
|
||||||
Some things people reasonably expect are <strong>deliberately not built</strong> — a Matrix
|
Some things people reasonably expect are <strong>deliberately not built</strong> — a Matrix
|
||||||
integration, more than one game module active at once, a finished Integration Kit. They are
|
integration, more than one game module active at once, a second game module. They are
|
||||||
listed rather than left out, on <a href="/features/">features</a> and{' '}
|
listed rather than left out, on <a href="/features/">features</a> and{' '}
|
||||||
<a href="/integrations/">integrations</a>.
|
<a href="/integrations/">integrations</a>.
|
||||||
</p>
|
</p>
|
||||||
|
|||||||
@@ -1,10 +1,12 @@
|
|||||||
---
|
---
|
||||||
|
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
|
* 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.
|
* geometry, used where it explains something, and no raster anywhere.
|
||||||
*
|
*
|
||||||
* ---------------------------------------------------------------------------------------
|
* ---------------------------------------------------------------------------------------
|
||||||
* THE LABELS ARE GENERIC; THE CAPTION NAMES THE GAMES
|
* THE LABELS ARE GENERIC, WITH UO AS THE CAPTION
|
||||||
* ---------------------------------------------------------------------------------------
|
* ---------------------------------------------------------------------------------------
|
||||||
* The org lead settled this before the diagram was drawn. The nodes say "your game server"
|
* 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
|
* and "sidecar", not "ServUO shard" and "uo-link", because §10's rule is that a reader
|
||||||
@@ -12,12 +14,10 @@
|
|||||||
* repositories in order to connect a game server — and because the tagline promises a
|
* repositories in order to connect a game server — and because the tagline promises a
|
||||||
* platform, not a UO product.
|
* platform, not a UO product.
|
||||||
*
|
*
|
||||||
* It does NOT hide what actually ships: the caption names the games that ship on this shape,
|
* It does NOT hide what actually ships. The sub-labels and the caption name ServUO and
|
||||||
* because §1 says the technical truth wins and an operator has to see their game in the
|
* uo-link outright, because §1 says the technical truth wins and today there is exactly one
|
||||||
* picture on the first screen. Until phase 13 the sub-labels named ServUO and uo-link, which
|
* implementation of this shape. An operator running a shard has to see themselves in the
|
||||||
* was true while there was exactly one implementation. With two, naming one would mislead,
|
* picture on the first screen.
|
||||||
* 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
|
* WHY THE SVG IS aria-hidden
|
||||||
@@ -74,11 +74,11 @@
|
|||||||
|
|
||||||
<rect class="node" x="20" y="16" width="340" height="76" rx="12" />
|
<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-title" x="42" y="50">Your game server</text>
|
||||||
<text class="node-sub" x="42" y="72">opens no inbound port</text>
|
<text class="node-sub" x="42" y="72">ServUO today · opens no inbound port</text>
|
||||||
|
|
||||||
<rect class="node" x="20" y="148" width="340" height="76" rx="12" />
|
<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-title" x="42" y="182">Sidecar</text>
|
||||||
<text class="node-sub" x="42" y="204">the only network-facing part</text>
|
<text class="node-sub" x="42" y="204">uo-link · the only network-facing part</text>
|
||||||
|
|
||||||
<rect class="node node--self" x="20" y="280" width="340" height="76" rx="12" />
|
<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>
|
<text class="node-title" x="42" y="314">Runic Gateway</text>
|
||||||
@@ -90,9 +90,8 @@
|
|||||||
</svg>
|
</svg>
|
||||||
|
|
||||||
<p class="datapath__caption">
|
<p class="datapath__caption">
|
||||||
Two games ship on this shape today, Ultima Online and Rust, each with its own plugin
|
Today that game server is a ServUO shard and that sidecar is uo-link. The shape is the
|
||||||
and its own sidecar. The shape is the contract; the implementations are what plug
|
contract; the implementations are what plug into it.
|
||||||
into it.
|
|
||||||
</p>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
@@ -110,8 +109,8 @@
|
|||||||
<h3>The sidecar</h3>
|
<h3>The sidecar</h3>
|
||||||
<p>
|
<p>
|
||||||
A small service beside the game, and the only piece of the bridge anything else can
|
A small service beside the game, and the only piece of the bridge anything else can
|
||||||
reach. It speaks a versioned wire protocol — each game pins its own — so a
|
reach. It speaks a versioned wire protocol — protocol {platform.protocol} today — so
|
||||||
mismatched pair is refused rather than misread, and it answers only your website's
|
a mismatched pair is refused rather than misread, and it answers only your website's
|
||||||
backend, over an authenticated WebSocket and REST.
|
backend, over an authenticated WebSocket and REST.
|
||||||
</p>
|
</p>
|
||||||
</li>
|
</li>
|
||||||
|
|||||||
@@ -55,9 +55,9 @@ import platform from '../../data/platform.json';
|
|||||||
</div>
|
</div>
|
||||||
|
|
||||||
<div class="chips">
|
<div class="chips">
|
||||||
{/* D66: only the version every deployment shares. A protocol and a bundle belong
|
<span class="chip chip--version">Protocol {platform.protocol}</span>
|
||||||
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">Module API {platform.moduleApi}</span>
|
||||||
|
<span class="chip chip--version">Bundle {platform.bundle.tag}</span>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
|
|||||||
@@ -1,44 +0,0 @@
|
|||||||
---
|
|
||||||
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>
|
|
||||||
@@ -1,41 +0,0 @@
|
|||||||
/**
|
|
||||||
* 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 = [];
|
|
||||||
@@ -36,67 +36,20 @@ export const docsSidebar = [
|
|||||||
{ label: 'Users and roles', slug: 'docs/administration/users-and-roles' },
|
{ label: 'Users and roles', slug: 'docs/administration/users-and-roles' },
|
||||||
{ label: 'Authentication', slug: 'docs/administration/authentication' },
|
{ label: 'Authentication', slug: 'docs/administration/authentication' },
|
||||||
{ label: 'Teams', slug: 'docs/administration/teams' },
|
{ label: 'Teams', slug: 'docs/administration/teams' },
|
||||||
{ label: 'Scheduled events', slug: 'docs/administration/events' },
|
|
||||||
{ label: 'Moderation', slug: 'docs/administration/moderation' },
|
{ label: 'Moderation', slug: 'docs/administration/moderation' },
|
||||||
{ label: 'Notifications and email', slug: 'docs/administration/notifications-and-email' },
|
{ 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: 'Managing modules', slug: 'docs/administration/managing-modules' },
|
||||||
{ label: 'The shard connection', slug: 'docs/administration/the-shard-connection' },
|
{ label: 'The shard connection', slug: 'docs/administration/the-shard-connection' },
|
||||||
{ label: 'Client files', slug: 'docs/administration/client-files' },
|
|
||||||
{ label: 'Maintenance and upgrades', slug: 'docs/administration/maintenance-and-upgrades' },
|
{ label: 'Maintenance and upgrades', slug: 'docs/administration/maintenance-and-upgrades' },
|
||||||
{ label: 'Troubleshooting', slug: 'docs/administration/troubleshooting' },
|
{ 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: 'sidecar.toml', slug: 'docs/reference/sidecar-toml' },
|
|
||||||
{ label: 'Bridge.cfg', slug: 'docs/reference/bridge-cfg' },
|
|
||||||
{ label: 'HTTP API', slug: 'docs/reference/http-api' },
|
|
||||||
{ label: 'Shard event catalog', slug: 'docs/reference/event-catalog' },
|
|
||||||
{ label: 'Canonical documents', slug: 'docs/reference/canonical-documents' },
|
|
||||||
],
|
|
||||||
},
|
|
||||||
];
|
];
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The tree §10 planned, kept as the record of what was intended — every page it names now
|
* The full planned tree, kept next to the live sidebar so phases 7 and 8 have their
|
||||||
* exists, as of phase 8.
|
* checklist in the place they will be working. Not exported into the Starlight config —
|
||||||
*
|
* it names pages that do not exist yet.
|
||||||
* 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 = {
|
export const plannedSidebar = {
|
||||||
'Getting started': [
|
'Getting started': [
|
||||||
@@ -112,18 +65,13 @@ export const plannedSidebar = {
|
|||||||
'Configuration',
|
'Configuration',
|
||||||
'Branding and theming',
|
'Branding and theming',
|
||||||
'Navigation and pages',
|
'Navigation and pages',
|
||||||
'Content',
|
|
||||||
'Users and roles',
|
'Users and roles',
|
||||||
'Authentication',
|
'Authentication',
|
||||||
'Teams',
|
'Teams',
|
||||||
'Scheduled events',
|
|
||||||
'Moderation',
|
'Moderation',
|
||||||
'Notifications and email',
|
'Notifications and email',
|
||||||
'Engagement rules',
|
|
||||||
'Message templates',
|
|
||||||
'Managing modules',
|
'Managing modules',
|
||||||
'The shard connection',
|
'The shard connection',
|
||||||
'Client files',
|
|
||||||
'Maintenance and upgrades',
|
'Maintenance and upgrades',
|
||||||
'Troubleshooting',
|
'Troubleshooting',
|
||||||
],
|
],
|
||||||
@@ -142,7 +90,6 @@ export const plannedSidebar = {
|
|||||||
'The bridge',
|
'The bridge',
|
||||||
'Authentication architecture',
|
'Authentication architecture',
|
||||||
'Teams architecture',
|
'Teams architecture',
|
||||||
'Events architecture',
|
|
||||||
'Protocol versions',
|
'Protocol versions',
|
||||||
],
|
],
|
||||||
Reference: [
|
Reference: [
|
||||||
@@ -151,7 +98,7 @@ export const plannedSidebar = {
|
|||||||
'sidecar.toml',
|
'sidecar.toml',
|
||||||
'Bridge.cfg',
|
'Bridge.cfg',
|
||||||
'HTTP API',
|
'HTTP API',
|
||||||
'Shard event catalog',
|
'Event catalog',
|
||||||
'Canonical documents',
|
'Canonical documents',
|
||||||
],
|
],
|
||||||
};
|
};
|
||||||
|
|||||||
@@ -4,7 +4,6 @@ description: Colours, fonts and corners from the Appearance screen; logo, hero a
|
|||||||
---
|
---
|
||||||
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
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
|
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
|
in — it is a theme row in the database, three image files on a mount, and a few environment
|
||||||
@@ -32,8 +31,6 @@ 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
|
- **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.
|
from this site's public branding. Changing it here changes them.
|
||||||
|
|
||||||
<Screenshot id="admin-appearance" />
|
|
||||||
|
|
||||||
## Brand assets
|
## Brand assets
|
||||||
|
|
||||||
The same screen uploads three images, and each applies as soon as the upload finishes —
|
The same screen uploads three images, and each applies as soon as the upload finishes —
|
||||||
|
|||||||
@@ -1,103 +0,0 @@
|
|||||||
---
|
|
||||||
title: Client files
|
|
||||||
description: Creature portraits, item pictures and the game's own name table — where they come from, the one button that imports them, and why nothing here happens on a restart.
|
|
||||||
---
|
|
||||||
|
|
||||||
import Screenshot from '../../../../components/Screenshot.astro';
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
|
||||||
|
|
||||||
Most of what a game shows you is not text. Ultima Online keeps its creature artwork, its
|
|
||||||
item graphics and even its item *names* inside the client files, and a site that cannot read
|
|
||||||
them shows a bestiary of words and a marketplace of numbers.
|
|
||||||
|
|
||||||
With the `uo` module installed, **Client files** appears in the admin sidebar at
|
|
||||||
`/admin/uo/files`. It is where those three things arrive.
|
|
||||||
|
|
||||||
<Screenshot id="admin-client-files" />
|
|
||||||
|
|
||||||
## Where they come from
|
|
||||||
|
|
||||||
A ServUO shard cannot boot without a UO client — it resolves one at startup to read the
|
|
||||||
world's own data. So the files were already on the shard host, and the shard reads and
|
|
||||||
decodes them there, handing the results over the bridge like everything else.
|
|
||||||
|
|
||||||
**Nothing is converted on a desktop and nothing is uploaded.** Earlier versions of this
|
|
||||||
platform asked an operator to install a third-party tool, build a converter against it and
|
|
||||||
copy the output onto the web host. That path is gone.
|
|
||||||
|
|
||||||
## Three things, one page
|
|
||||||
|
|
||||||
| Section | Fills | How it arrives |
|
|
||||||
|---|---|---|
|
|
||||||
| **Creature portraits** | The bestiary and the spawn atlas | One picture per creature body, imported as a **set** |
|
|
||||||
| **Item and land pictures** | Marketplace listings and character sheets | **One at a time**, shortly after a page asks for one |
|
|
||||||
| **Item and title names (clilocs)** | Anywhere an item is named | The whole table at once — tens of thousands of names |
|
|
||||||
|
|
||||||
They are one page because they are one job: they come out of one client install, and they
|
|
||||||
all change at the same moment — when you patch it.
|
|
||||||
|
|
||||||
<Aside type="caution" title="Nothing here happens on a restart">
|
|
||||||
Boot deliberately never asks the shard for client files. A client patch is an event **you**
|
|
||||||
know about and the website does not, and a site that re-read hundreds of megabytes on every
|
|
||||||
restart to discover nothing had changed would pay for the rare case forever.
|
|
||||||
|
|
||||||
So after you patch your client, the site keeps serving the old pictures and the old names
|
|
||||||
until somebody presses a button on this page. That is the whole reason the page exists.
|
|
||||||
</Aside>
|
|
||||||
|
|
||||||
## Update, or re-import everything
|
|
||||||
|
|
||||||
Every section offers the same pair, and the difference is worth knowing:
|
|
||||||
|
|
||||||
- **Update** asks the shard what changed first and transfers only that. When nothing has, it
|
|
||||||
costs one small round trip and answers *"unchanged"*.
|
|
||||||
- **Re-import everything** fetches the lot. It is for the case the first cannot see — you
|
|
||||||
restored a backup, or lost the uploads volume, and the database still remembers pictures
|
|
||||||
that are no longer on disk.
|
|
||||||
|
|
||||||
Item and land pictures work differently, because there are tens of thousands of item
|
|
||||||
graphics times every dye colour and importing them as a set would be absurd. They arrive
|
|
||||||
lazily instead. The two buttons there — *Fetch waiting pictures* and *Refresh the ones I
|
|
||||||
have* — exist for the two moments waiting is the wrong answer: you have just linked a shard,
|
|
||||||
or you have just patched a client.
|
|
||||||
|
|
||||||
## When the page says something is wrong
|
|
||||||
|
|
||||||
Every one of these is a reported state with a reason, not an error. The site keeps serving
|
|
||||||
whatever is already imported in all of them.
|
|
||||||
|
|
||||||
| What you see | What it means |
|
|
||||||
|---|---|
|
|
||||||
| **The shard is busy with another client-file request** | Not a fault. The shard serves one of these at a time, and an import — or the item-picture pass refilling itself — is holding it. It frees itself. |
|
|
||||||
| **The shard is not answering for client files** | The ordinary bridge problem: see [The shard connection](/docs/administration/the-shard-connection/). |
|
|
||||||
| **…set `AssetsEnabled` on the shard** | The asset plane is switched off in [`Bridge.cfg`](/docs/reference/bridge-cfg/). It is a separate switch on purpose — turning it on is consenting to the website reading this host's client files. |
|
|
||||||
| **The shard host cannot render images** | A Linux host with no `libgdiplus`. Names are unaffected, because they have no pixels in them. |
|
|
||||||
| **Waiting for you: *n* pictures … no longer offered** | The shard stopped offering artwork this site holds. A deletion is never silent here; it waits for you to approve or dismiss it. |
|
|
||||||
|
|
||||||
<Aside type="note" title="Linux shard hosts need one package">
|
|
||||||
ServUO runs under Mono on Linux, and the library it decodes sprites with is a thin layer
|
|
||||||
over **`libgdiplus`** — in the *decode* path, not merely the encode. Without it the shard
|
|
||||||
cannot read a single sprite.
|
|
||||||
|
|
||||||
`sudo apt-get install libgdiplus`, or `dnf install libgdiplus`. `runicgateway doctor` checks
|
|
||||||
for it, and Windows shard hosts need nothing. See
|
|
||||||
[Requirements](/docs/getting-started/requirements/).
|
|
||||||
</Aside>
|
|
||||||
|
|
||||||
## What it will not do
|
|
||||||
|
|
||||||
- **It never writes to the game.** Everything on this plane is a read.
|
|
||||||
- **It never overwrites your own artwork.** A portrait you drew and named yourself always
|
|
||||||
wins over an imported one.
|
|
||||||
- **Creatures with no artwork stay as text.** That is normal rather than a failure — a stock
|
|
||||||
client has no animation for most ghost and gargoyle bodies, and the shard reports nothing
|
|
||||||
rather than guessing. A wrong picture is worse than no picture.
|
|
||||||
|
|
||||||
## Canonical documents
|
|
||||||
|
|
||||||
[`link/v8.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v8.md)
|
|
||||||
is the asset plane's design of record;
|
|
||||||
[`link/SHARD_PREREQS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/SHARD_PREREQS.md)
|
|
||||||
covers what a shard host needs first, and
|
|
||||||
[`website/UPGRADE_NOTES.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/UPGRADE_NOTES.md)
|
|
||||||
is what to do on a site that was running before this existed.
|
|
||||||
@@ -59,10 +59,9 @@ per-Team settings:
|
|||||||
## Email
|
## Email
|
||||||
|
|
||||||
Configured on the same screen and covered in
|
Configured on the same screen and covered in
|
||||||
[Notifications and email](/docs/administration/notifications-and-email/): pick a mail
|
[Notifications and email](/docs/administration/notifications-and-email/): it is Gmail over
|
||||||
transport, enter its host, port and credentials, and send a test. It depends on nothing
|
OAuth2, it reuses the Google authentication client, and it must be set up on the
|
||||||
else on the site — a relay is the recommended posture, a mailbox provider over SMTP the
|
[Authentication](/docs/administration/authentication/) page first.
|
||||||
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">
|
<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*
|
That is a deliberate fallback rather than a failure — but it does mean the *Contact email*
|
||||||
|
|||||||
@@ -1,175 +0,0 @@
|
|||||||
---
|
|
||||||
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
|
|
||||||
guild'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 shard should send, and check the
|
|
||||||
send log the first time each one fires.
|
|
||||||
@@ -1,191 +0,0 @@
|
|||||||
---
|
|
||||||
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';
|
|
||||||
|
|
||||||
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 (`uo.creatures`, `uo.bosses`, `uo.rewards` and so on), and consumption
|
|
||||||
is counted in the database with a conditional update, not checked in application code.
|
|
||||||
|
|
||||||
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 on the shard host, outside the site's reach, and the site cannot turn them on.
|
|
||||||
|
|
||||||
**`EventsEnabled` is off by default, and it 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 this on is consenting to the site changing and watching your world
|
|
||||||
unattended. One switch could not honestly express both.
|
|
||||||
|
|
||||||
Beside it sit the game's own ceilings — how many creatures one call may spawn, how long a gate
|
|
||||||
may stand, how much one run may own in total, how often the world may be saved. **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. See
|
|
||||||
[Bridge.cfg](/docs/reference/bridge-cfg/) for every key.
|
|
||||||
|
|
||||||
## 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/).
|
|
||||||
@@ -116,13 +116,6 @@ when ServUO needs restarting — it never restarts your shard itself. Because it
|
|||||||
**bundle**, the sidecar and the plugin move together and cannot end up disagreeing about the
|
**bundle**, the sidecar and the plugin move together and cannot end up disagreeing about the
|
||||||
protocol.
|
protocol.
|
||||||
|
|
||||||
<Aside type="caution" title="After you patch the UO client, press one more button">
|
|
||||||
Creature portraits, item pictures and the name table are read from that client, and the
|
|
||||||
site deliberately never re-reads them on its own — a restart does not, and neither does
|
|
||||||
`update`. They keep serving the old artwork until somebody presses *Update* on
|
|
||||||
**Admin → Client files**. It is one round trip when nothing has changed.
|
|
||||||
</Aside>
|
|
||||||
|
|
||||||
<Aside type="note" title="Update the two sides in either order, but verify after each">
|
<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
|
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
|
rejected with a `409` rather than mis-parsed. So the worst case is a bridge that refuses to
|
||||||
|
|||||||
@@ -4,13 +4,10 @@ description: The five states a module can be in, installing and upgrading, disab
|
|||||||
---
|
---
|
||||||
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
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/).
|
Installing your first module is [Getting started](/docs/getting-started/install-a-game-module/).
|
||||||
This is what the screen means afterwards.
|
This is what the screen means afterwards.
|
||||||
|
|
||||||
<Screenshot id="admin-modules" />
|
|
||||||
|
|
||||||
## The five states
|
## The five states
|
||||||
|
|
||||||
`installed → enabled → started`, with `disabled` and `startup_failed` as recoverable
|
`installed → enabled → started`, with `disabled` and `startup_failed` as recoverable
|
||||||
@@ -41,10 +38,6 @@ Two consequences of how boots work:
|
|||||||
Paste the new release's install-manifest URL and press Install. The bundle is verified
|
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.
|
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
|
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.
|
silently switch it off, and re-installing a disabled one must not silently switch it on.
|
||||||
|
|
||||||
|
|||||||
@@ -1,133 +0,0 @@
|
|||||||
---
|
|
||||||
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 shard.
|
|
||||||
|
|
||||||
**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.house-idoc`, 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/).
|
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: Notifications and email
|
title: Notifications and email
|
||||||
description: Email over SMTP, the announcement pipeline and its legs, the Discord bot, and opt-in push to the mobile app.
|
description: Email over Gmail OAuth2, the announcement pipeline and its legs, the Discord bot, and opt-in push to the mobile app.
|
||||||
---
|
---
|
||||||
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
import { Aside } from '@astrojs/starlight/components';
|
||||||
@@ -9,67 +9,21 @@ 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
|
configures none of them still works — it just never reaches anyone who is not looking at
|
||||||
it.
|
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
|
## Email
|
||||||
|
|
||||||
**Admin → Settings → Email delivery.** The site sends contact-form messages, invitations,
|
**Admin → Settings → Email delivery.** The site sends contact-form messages (and test
|
||||||
password resets, team notifications and test messages through **SMTP**. Contact-form mail
|
messages) through **Gmail over OAuth2**, delivered to the *Contact email* setting.
|
||||||
goes to the *Contact email* setting.
|
|
||||||
|
|
||||||
You pick a mail transport and fill in the fields it asks for. There is no consent flow and
|
It reuses the **Google authentication client**, so the order is fixed: configure Google on
|
||||||
no redirect to bounce through — it is a form, and the credentials go straight into the
|
the [Authentication](/docs/administration/authentication/) page first, then press **Connect
|
||||||
database encrypted at rest, write-only: the panel will tell you a password is *set*, and
|
Gmail** here. Until then the panel reads *Unconfigured* and says exactly that.
|
||||||
will never show it to you again.
|
|
||||||
|
|
||||||
### Three ways to point it somewhere
|
The refresh token it stores is encrypted at rest like every other secret.
|
||||||
|
|
||||||
Any SMTP server works. Which one you should use depends on how much mail you expect to send.
|
<Aside type="note" title="There is no SMTP option">
|
||||||
|
Gmail over OAuth2 is the only supported delivery path today. Until it is connected, the
|
||||||
**A relay — the recommended one.** Mailgun, SES, Postmark or equivalent: their host, port
|
contact form falls back to a `mailto:` link to the contact address — which works, and puts
|
||||||
`587`, *Implicit TLS* **off**, and your API key as the password. Deliverability is the hard
|
the message in the visitor's own mail client rather than in your logs.
|
||||||
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>
|
</Aside>
|
||||||
|
|
||||||
## Announcements
|
## Announcements
|
||||||
@@ -121,45 +75,14 @@ Two properties matter for what you have to trust:
|
|||||||
Without `NTFY_PUBLIC_URL` / `NTFY_ALLOWED_ORIGINS`, the app simply shows push as
|
Without `NTFY_PUBLIC_URL` / `NTFY_ALLOWED_ORIGINS`, the app simply shows push as
|
||||||
unavailable for your instance — nothing breaks.
|
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
|
## Who receives what
|
||||||
|
|
||||||
The per-person side of this lives in the player portal, not the admin panel: **Account →
|
The per-person side of this lives in the player portal, not the admin panel: each member
|
||||||
Notifications → Settings** is a grid of every notification against every channel, and each
|
chooses which Team and forum notifications they want, and how. Two defaults are worth
|
||||||
member sets their own. The defaults are not symmetrical, and the asymmetry is deliberate:
|
knowing because they are not symmetrical:
|
||||||
|
|
||||||
|
- **Push is opt-out** once a device is registered.
|
||||||
- **Email is opt-in.**
|
- **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">
|
<Aside type="caution" title="Nothing here retries">
|
||||||
The announcement dispatcher sends once, and the Team notification bridge states plainly that
|
The announcement dispatcher sends once, and the Team notification bridge states plainly that
|
||||||
|
|||||||
@@ -48,52 +48,6 @@ Two rules are structural rather than settings:
|
|||||||
about a leader has to reach someone above them. See
|
about a leader has to reach someone above them. See
|
||||||
[Moderation](/docs/administration/moderation/).
|
[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
|
## The Discord bridges
|
||||||
|
|
||||||
Two integrations, both optional, both configured from **Admin → Teams**.
|
Two integrations, both optional, both configured from **Admin → Teams**.
|
||||||
|
|||||||
@@ -4,7 +4,6 @@ description: The module's shard screen — connection settings, what the status
|
|||||||
---
|
---
|
||||||
|
|
||||||
import platform from '../../../../data/platform.json';
|
import platform from '../../../../data/platform.json';
|
||||||
import Screenshot from '../../../../components/Screenshot.astro';
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
import { Aside } from '@astrojs/starlight/components';
|
||||||
|
|
||||||
With the `uo` module installed, **Shard (uo-link)** appears in the admin sidebar at
|
With the `uo` module installed, **Shard (uo-link)** appears in the admin sidebar at
|
||||||
@@ -14,8 +13,6 @@ the controls that ride on it.
|
|||||||
Setting it up for the first time is
|
Setting it up for the first time is
|
||||||
[Connect a game server](/docs/getting-started/connect-a-game-server/).
|
[Connect a game server](/docs/getting-started/connect-a-game-server/).
|
||||||
|
|
||||||
<Screenshot id="admin-shard" />
|
|
||||||
|
|
||||||
## Connection
|
## Connection
|
||||||
|
|
||||||
Four fields, all four printed by the installer, plus the switch that turns the integration
|
Four fields, all four printed by the installer, plus the switch that turns the integration
|
||||||
@@ -26,7 +23,7 @@ on:
|
|||||||
| **Base URL (REST)** | `http://<shard host>:8080` — point-in-time queries |
|
| **Base URL (REST)** | `http://<shard host>:8080` — point-in-time queries |
|
||||||
| **WebSocket URL (feed)** | `ws://<shard host>:8080/ws` — the live event feed |
|
| **WebSocket URL (feed)** | `ws://<shard host>:8080/ws` — the live event feed |
|
||||||
| **Auth token** | The sidecar's token |
|
| **Auth token** | The sidecar's token |
|
||||||
| **Protocol** | {platform.games.uo.protocol} today |
|
| **Protocol** | {platform.protocol} today |
|
||||||
|
|
||||||
Saving restarts the ingest client, so a change takes effect immediately.
|
Saving restarts the ingest client, so a change takes effect immediately.
|
||||||
|
|
||||||
@@ -81,13 +78,6 @@ lines, and a duration in seconds. Re-posting the same id **replaces** that messa
|
|||||||
The id is the useful part — give a recurring announcement a stable one and you can update or
|
The id is the useful part — give a recurring announcement a stable one and you can update or
|
||||||
withdraw it without waiting for it to expire.
|
withdraw it without waiting for it to expire.
|
||||||
|
|
||||||
## Client files
|
|
||||||
|
|
||||||
The other half of what the bridge carries has its own screen: creature portraits, item
|
|
||||||
pictures and the game's own name table, read from the UO client on the shard host. It is
|
|
||||||
**Client files**, at `/admin/uo/files`, and it is where an operator goes after patching that
|
|
||||||
client — nothing imports on a restart. See [Client files](/docs/administration/client-files/).
|
|
||||||
|
|
||||||
## What reaches the public
|
## What reaches the public
|
||||||
|
|
||||||
Events from the shard fan out over two separate streams, and the split is a security
|
Events from the shard fan out over two separate streams, and the split is a security
|
||||||
|
|||||||
@@ -88,23 +88,6 @@ the tree and never compiles — and ServUO ignores the script build's exit code,
|
|||||||
looks clean. `doctor` catches it by comparing file hashes against the install record.
|
looks clean. `doctor` catches it by comparing file hashes against the install record.
|
||||||
</Aside>
|
</Aside>
|
||||||
|
|
||||||
## The bestiary has no pictures, or items show numbers
|
|
||||||
|
|
||||||
Those come out of the UO client on the shard host, and **nothing imports them on a
|
|
||||||
restart** — a button on **Admin → Client files** is the only thing that does. Check that
|
|
||||||
page first: it reports why rather than failing.
|
|
||||||
|
|
||||||
| What it says | What to do |
|
|
||||||
|---|---|
|
|
||||||
| Counts are zero and no import is recorded | Press *Update*. On a shard that was linked before this existed, nobody ever has. |
|
|
||||||
| *…set `AssetsEnabled` on the shard* | The asset plane is off in `Bridge.cfg`. It is a separate switch on purpose. |
|
|
||||||
| *The shard host cannot render images* | A Linux host with no `libgdiplus`. Install it and press *Update* again. Names are unaffected either way. |
|
|
||||||
| *The shard is busy with another client-file request* | Not a fault. Something ordinary holds the slot; it frees itself. |
|
|
||||||
| Pictures were fine and went blank | Check the uploads volume before anything else — the database still remembers pictures that are no longer on disk, and *Re-import everything* is the button for exactly that. |
|
|
||||||
|
|
||||||
Items reading as numbers rather than names is the same page, different section: it means the
|
|
||||||
cliloc table has not been imported. See [Client files](/docs/administration/client-files/).
|
|
||||||
|
|
||||||
## Teams are missing
|
## Teams are missing
|
||||||
|
|
||||||
Check the sync panel on **Admin → Teams** before anything else: *last success: never* with
|
Check the sync panel on **Admin → Teams** before anything else: *last success: never* with
|
||||||
@@ -114,71 +97,14 @@ a Team. See [Teams](/docs/administration/teams/).
|
|||||||
|
|
||||||
## Email and announcements never arrive
|
## Email and announcements never arrive
|
||||||
|
|
||||||
- **The contact form opens a mail client.** Email delivery is not configured; that is the
|
- **The contact form opens a mail client.** Email delivery is not connected; that is the
|
||||||
documented fallback. Enter SMTP credentials in **Settings → Email delivery**. If this site
|
documented fallback. Connect Gmail in **Settings → Email delivery** — after configuring
|
||||||
used to send mail and stopped, the Gmail connect flow was removed — the admin dashboard
|
the Google provider, which it reuses.
|
||||||
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
|
- **A published post announced nothing.** The Discord bot is a separate container. If the
|
||||||
Discord Bot screen says *bot unreachable*, it is not running.
|
Discord Bot screen says *bot unreachable*, it is not running.
|
||||||
- **A missed announcement does not come back.** Nothing retries; the post itself is still
|
- **A missed announcement does not come back.** Nothing retries; the post itself is still
|
||||||
on the site.
|
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
|
## Uploads and modules fail with permission errors
|
||||||
|
|
||||||
Docker created a bind-mount source that the container user cannot write — usually because
|
Docker created a bind-mount source that the container user cannot write — usually because
|
||||||
|
|||||||
@@ -4,7 +4,6 @@ description: The four roles and what each one reaches, creating accounts, and in
|
|||||||
---
|
---
|
||||||
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
import { Aside } from '@astrojs/starlight/components';
|
||||||
import Screenshot from '../../../../components/Screenshot.astro';
|
|
||||||
|
|
||||||
## The four roles
|
## The four roles
|
||||||
|
|
||||||
@@ -25,8 +24,6 @@ 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
|
Demoting an account takes effect at once — the open session does not keep its access until
|
||||||
it expires.
|
it expires.
|
||||||
|
|
||||||
<Screenshot id="admin-users" />
|
|
||||||
|
|
||||||
## Creating an account
|
## Creating an account
|
||||||
|
|
||||||
**Admin → Users → + Add user** creates one directly: username, password, role, and it is
|
**Admin → Users → + Add user** creates one directly: username, password, role, and it is
|
||||||
|
|||||||
@@ -1,123 +0,0 @@
|
|||||||
---
|
|
||||||
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).
|
|
||||||
|
|
||||||
`module-uo`'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.
|
|
||||||
@@ -1,163 +0,0 @@
|
|||||||
---
|
|
||||||
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 the site cannot reach: `EventsEnabled` and
|
|
||||||
`AdminWriteEnabled` live in a file on the shard host and are off out of the box, and 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 a guild-scoped event 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.
|
|
||||||
@@ -1,123 +0,0 @@
|
|||||||
---
|
|
||||||
title: Protocol versions
|
|
||||||
description: One number, declared in three repositories, that decides whether a shard and a sidecar are allowed to talk to each other.
|
|
||||||
---
|
|
||||||
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
|
||||||
import platform from '../../../../data/platform.json';
|
|
||||||
|
|
||||||
The loopback wire protocol between the game 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. The examples below are the {platform.games.uo.name} bridge's; the
|
|
||||||
{platform.games.rust.name} bridge declares its number in the same three kinds of place.
|
|
||||||
|
|
||||||
## Three declaration sites
|
|
||||||
|
|
||||||
The same number is written down in three places, and they must move together.
|
|
||||||
|
|
||||||
| Where | What declares it |
|
|
||||||
|---|---|
|
|
||||||
| `link/sidecar/src/main.rs` | `PROTOCOL_VERSION`, currently {platform.games.uo.protocol} — what the sidecar speaks |
|
|
||||||
| `servuo-plugins/overlay.toml` | `protocol`, currently {platform.games.uo.protocol} — what the plugin overlay speaks |
|
|
||||||
| The bundle manifest | Copied from `overlay.toml` by CI, so a released pair carries its own claim |
|
|
||||||
|
|
||||||
<Aside type="caution" title="Bump the overlay in the same PR as the emitters">
|
|
||||||
CI folds `overlay.toml` into the release manifest, and **the installer refuses to pair an
|
|
||||||
overlay 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 `X-UOLink-Version`. A mismatch is
|
|
||||||
rejected with **`409`** rather than mis-parsed. The website's protocol expectation is
|
|
||||||
admin-managed, alongside the base URL and token, on the shard configuration screen.
|
|
||||||
|
|
||||||
**Overlay ↔ sidecar.** The installer resolves a **bundle** — an exact, protocol-checked
|
|
||||||
sidecar and overlay pair 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 most recent
|
|
||||||
bump — **8**, which taught the bridge to carry a game's own client files — 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 |
|
|
||||||
|
|
||||||
**`website` is 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. The
|
|
||||||
one before this did, because what changed then was not a game *noun* but the shape of a
|
|
||||||
thing core owns the ledger for. This one did not reach core because everything it needed —
|
|
||||||
somewhere to put a picture — core already offered every module. Its entire share of eight
|
|
||||||
phases of work was a **deletion**: a developer tool it no longer needed.
|
|
||||||
|
|
||||||
**A protocol bump can also require a store migration**, because the sidecar persists what it
|
|
||||||
forwards. That is not automatic, and it has happened once: version 4 added a column to a
|
|
||||||
table that already existed. Versions 5, 6, 7 and 8 needed none, because every frame is
|
|
||||||
persisted whole — 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.
|
|
||||||
|
|
||||||
Version 8 puts it more sharply still. It is the largest bump this 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. A
|
|
||||||
forwarder that holds no opinion about what it forwards has nothing to migrate.
|
|
||||||
|
|
||||||
## 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 | `link`, `servuo-plugins`, the bundle | `X-UOLink-Version`, 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
|
|
||||||
|
|
||||||
[`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/v7.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v7.md)
|
|
||||||
the one before it;
|
|
||||||
[`link/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md)
|
|
||||||
§7 is the wire protocol, and
|
|
||||||
[`link/INTEGRATION.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md)
|
|
||||||
the integration guide.
|
|
||||||
@@ -1,142 +0,0 @@
|
|||||||
---
|
|
||||||
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';
|
|
||||||
|
|
||||||
The drawn version of this, for evaluators, is on
|
|
||||||
[Architecture](/architecture/). This page is the detailed account.
|
|
||||||
|
|
||||||
## Ten 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.
|
|
||||||
|
|
||||||
| Repository | What it is |
|
|
||||||
|---|---|
|
|
||||||
| `website` | The Node/Express + MariaDB + React site. The only internet-facing web app |
|
|
||||||
| `Module-uo` | All the *Ultima Online* code, installed into the site as a module |
|
|
||||||
| `link` | The **uo-link sidecar**, in Rust — the only network-facing bridge component |
|
|
||||||
| `servuo-plugins` | The in-game plugin, C#, that feeds the sidecar |
|
|
||||||
| `installer` | Deploys the shard side: sidecar plus plugin overlay |
|
|
||||||
| `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 spec |
|
|
||||||
| `runicgateway.com` | This site |
|
|
||||||
| `.profile` | The organisation landing page |
|
|
||||||
|
|
||||||
## 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 `module-uo` as *the worked example* rather than
|
|
||||||
as part of the platform. It is the module every other module is measured against, not a
|
|
||||||
component core depends on.
|
|
||||||
|
|
||||||
## The invariants
|
|
||||||
|
|
||||||
These hold across repository boundaries, and every one of them is load-bearing.
|
|
||||||
|
|
||||||
### The game is never network-reachable
|
|
||||||
|
|
||||||
The ServUO shard **dials out** over loopback TCP `127.0.0.1:7788`, newline-delimited JSON,
|
|
||||||
to the sidecar. 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
|
|
||||||
|
|
||||||
On the C# side, `Emit()` enqueues onto a **bounded, drop-oldest** queue and returns
|
|
||||||
immediately. It never touches the socket from the game's core thread. Every world read
|
|
||||||
happens on the core 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 shard 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 shard surface 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 shard 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.
|
|
||||||
@@ -1,153 +0,0 @@
|
|||||||
---
|
|
||||||
title: Teams architecture
|
|
||||||
description: Teams is a contract, not a surface — how core owns guilds, clans and corporations without ever learning what one is called.
|
|
||||||
---
|
|
||||||
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
|
||||||
|
|
||||||
Most games have groups: guilds, clans, corporations, tribes, crews. Runic Gateway supports
|
|
||||||
them as a **core platform primitive**, while core itself never learns what yours is called.
|
|
||||||
|
|
||||||
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 `module-uo`'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.
|
|
||||||
@@ -1,148 +0,0 @@
|
|||||||
---
|
|
||||||
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
|
|
||||||
|
|
||||||
```
|
|
||||||
ServUO shard ──dials out──▶ uo-link sidecar ──HTTP + WS──▶ website
|
|
||||||
(C# plugin) 127.0.0.1:7788 (Rust) bearer + version (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 shard 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.
|
|
||||||
|
|
||||||
On the C# side, `Emit()` **enqueues onto a bounded, drop-oldest queue and returns
|
|
||||||
immediately**. It never touches the socket from the game's core thread. Every world read
|
|
||||||
happens on the core 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 core 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 client artwork, its string table, its spawn files — are the
|
|
||||||
newest and the least obvious. 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 house went IDOC" 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 let the same 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 an `X-UOLink-Version` header. **A
|
|
||||||
protocol mismatch fails fast with `409`** rather than being mis-parsed — see [Protocol
|
|
||||||
versions](/docs/architecture/protocol-versions/).
|
|
||||||
|
|
||||||
## What the shard can say
|
|
||||||
|
|
||||||
The catalog spans sessions and identity, character state, economy and commerce, housing and
|
|
||||||
IDOC, combat and PvP, progression, cheat detection and staff audit, and server lifecycle.
|
|
||||||
A representative line looks like:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{"t":1752,"kind":"vendor.sale",
|
|
||||||
"buyer":{"serial":"0x1A2B","acct":"PerryAdimn"},
|
|
||||||
"owner":{"serial":"0x33C1","acct":"Feng"},
|
|
||||||
"item":{"serial":"0x4001A2","type":"Longsword","amount":1},
|
|
||||||
"price":75000,"commission":3750}
|
|
||||||
```
|
|
||||||
|
|
||||||
The full catalog is the [Shard event catalog](/docs/reference/event-catalog/).
|
|
||||||
|
|
||||||
## 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 shard 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.** Guild membership is compared as a set rather than
|
|
||||||
folded into a checksum, because a sum can collide: one member joining and another leaving
|
|
||||||
between two sweeps offset each other, and the guild 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.
|
|
||||||
|
|
||||||
On a guild's **first** sweep there is no prior set, so nothing is reported as leaving — an
|
|
||||||
unknown roster becoming known is not 155 people leaving at once.
|
|
||||||
|
|
||||||
## Building one for another game
|
|
||||||
|
|
||||||
The bridge is not UO-specific in shape, only in vocabulary. 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.
|
|
||||||
@@ -71,7 +71,7 @@ internet; only the sidecar is exposed, and only to your site.
|
|||||||
<Aside type="note" title="It installs a bundle, not “latest of each”">
|
<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
|
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
|
resolves is a **bundle**: an exact, protocol-checked pair of sidecar and overlay versions
|
||||||
({platform.games.uo.bundle.tag} today — sidecar {platform.games.uo.bundle.sidecar}, overlay {platform.games.uo.bundle.overlay}).
|
({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
|
`--bundle <tag>` pins an exact past combination, so a reinstall in six months reproduces
|
||||||
today's install rather than tomorrow's.
|
today's install rather than tomorrow's.
|
||||||
</Aside>
|
</Aside>
|
||||||
@@ -83,7 +83,7 @@ features need edits to stock ServUO sources, and those are opt-in, off unless yo
|
|||||||
and refused where the target lines are not stock. Skipping the tier costs you vendor-sale
|
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.
|
events and in-game moderation audit forwarding; everything else works.
|
||||||
|
|
||||||
The tier is written and tested against stock ServUO {platform.games.uo.bundle.servuoMin}. On any
|
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
|
other version it is unsupported and untested, and the prompt makes you answer past a
|
||||||
warning.
|
warning.
|
||||||
|
|
||||||
@@ -107,16 +107,10 @@ sidebar — `/admin/uo/link`. Tick *Enable the shard integration*, paste **Base
|
|||||||
immediately.
|
immediately.
|
||||||
|
|
||||||
<Aside type="caution" title="Installer v0.1.0 prints an older path for that screen">
|
<Aside type="caution" title="Installer v0.1.0 prints an older path for that screen">
|
||||||
v0.1.0 prints `…/admin/shard`. Since the shard screens became part of the `uo` module — and
|
It prints `…/admin/shard`. Since the shard screens became part of the `uo` module — and a
|
||||||
a module owns one path segment wherever it appears — the screen moved to
|
module owns one path segment wherever it appears — the screen moved to **`/admin/uo/link`**.
|
||||||
**`/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.
|
||||||
The old path does not fail visibly: the site has no route for it, so it sends you to the
|
|
||||||
dashboard, and that looks like the link worked. The four values you were just told to paste
|
|
||||||
then have nowhere to go. Use the sidebar, or the path above.
|
|
||||||
|
|
||||||
Fixed in **v0.1.1**, which prints the real path. Only matters if you are running the older
|
|
||||||
binary.
|
|
||||||
</Aside>
|
</Aside>
|
||||||
|
|
||||||
The token is encrypted at rest and **never returned to any client** — losing it means
|
The token is encrypted at rest and **never returned to any client** — losing it means
|
||||||
|
|||||||
@@ -4,7 +4,6 @@ description: Signing in as the first admin, what the site does before anyone vis
|
|||||||
---
|
---
|
||||||
|
|
||||||
import { Aside, Steps } from '@astrojs/starlight/components';
|
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
|
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
|
**starts in maintenance mode**, showing visitors a "coming soon" page while the admin panel
|
||||||
@@ -34,8 +33,6 @@ minute, and see [Authentication](/docs/administration/authentication/) for what
|
|||||||
**Web Bot Activity** screen shows and how to lift a ban.
|
**Web Bot Activity** screen shows and how to lift a ban.
|
||||||
</Aside>
|
</Aside>
|
||||||
|
|
||||||
<Screenshot id="admin-dashboard" />
|
|
||||||
|
|
||||||
## What is already there
|
## What is already there
|
||||||
|
|
||||||
The first boot seeds a working site rather than an empty one:
|
The first boot seeds a working site rather than an empty one:
|
||||||
|
|||||||
@@ -60,7 +60,7 @@ Watch the log at the restart and you will see exactly what it mounted:
|
|||||||
[modules] module "uo" started
|
[modules] module "uo" started
|
||||||
```
|
```
|
||||||
|
|
||||||
Its capabilities are {platform.games.uo.module.capabilities.join(', ')} — the shard console, the
|
Its capabilities are {platform.moduleUoCapabilities.join(', ')} — the shard console, the
|
||||||
map atlas, the player-vendor marketplace, city governors, guilds, houses and IDOCs, champion
|
map atlas, the player-vendor marketplace, city governors, guilds, houses and IDOCs, champion
|
||||||
boards, and the cliloc strings that make item names readable.
|
boards, and the cliloc strings that make item names readable.
|
||||||
|
|
||||||
|
|||||||
@@ -35,21 +35,12 @@ the [`uo` module](/docs/getting-started/install-a-game-module/) and the installe
|
|||||||
| Requirement | Detail |
|
| 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. |
|
| **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.games.uo.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.games.uo.bundle.servuoMin}; on any other version it is unsupported, and skipping it still leaves you with a working bridge. |
|
| **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. |
|
||||||
| **`libgdiplus`** *(Linux shard hosts only)* | Only needed for **artwork**. ServUO runs under Mono on Linux, and the library it decodes sprites with is a thin layer over this one — in the decode path, not merely the encode. Without it creature portraits and item pictures stay empty, and names and the spawn atlas are unaffected because neither touches a pixel. `sudo apt-get install libgdiplus`; `doctor` checks for it. **Windows hosts need nothing.** |
|
|
||||||
| **The shard stopped** | `ServUO.exe` locks `Scripts.dll` and rewrites `Saves/` on exit. The installer refuses to deploy under a running shard. |
|
| **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. |
|
| **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. |
|
| **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. |
|
| **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. |
|
||||||
|
|
||||||
<Aside type="note" title="You do not need to install a game client for this">
|
|
||||||
You already have one. A ServUO shard cannot boot without a UO client — it resolves one at
|
|
||||||
startup to read the world's own data — so the artwork, the animations and the name table
|
|
||||||
the site shows are already sitting on that host. The shard reads them there and hands the
|
|
||||||
results over the bridge; nothing is converted on a desktop and nothing is uploaded. See
|
|
||||||
[Client files](/docs/administration/client-files/).
|
|
||||||
</Aside>
|
|
||||||
|
|
||||||
<Aside type="caution" title="Back up before the shard install">
|
<Aside type="caution" title="Back up before the shard install">
|
||||||
The overlay overwrites `Scripts/Scripts.csproj`, a stock file, and the optional patch tier
|
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
|
edits stock sources. A copy of `Scripts/` and `Config/` costs nothing and is the difference
|
||||||
|
|||||||
@@ -86,18 +86,11 @@ So verify each link in the chain, in order. Each check tells you which one to fi
|
|||||||
|
|
||||||
<Aside type="note" title="`runicgateway doctor` answers most of this in one command">
|
<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
|
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`, that the sidecar and overlay
|
hash, the patch tier, the sidecar, its service, `/health`, and that the sidecar and overlay
|
||||||
agree on a protocol, and — on Linux — that the host can decode an image at all. Its output is the first thing anyone helping you will ask for. It
|
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.
|
exits non-zero when a check failed, so a monitoring system can run it too.
|
||||||
</Aside>
|
</Aside>
|
||||||
|
|
||||||
<Aside type="note" title="A bridge can be green and still show no artwork">
|
|
||||||
Creature portraits and item pictures are a separate switch and a separate import, so a
|
|
||||||
perfectly healthy bridge shows a bestiary of text until somebody presses *Update* on
|
|
||||||
**Admin → Client files**. That is the expected first-run state, not a fault — see [Client
|
|
||||||
files](/docs/administration/client-files/).
|
|
||||||
</Aside>
|
|
||||||
|
|
||||||
## What "working" looks like a week later
|
## What "working" looks like a week later
|
||||||
|
|
||||||
- The public shard page shows live status, and the admin dashboard shows events arriving.
|
- The public shard page shows live status, and the admin dashboard shows events arriving.
|
||||||
|
|||||||
@@ -15,32 +15,19 @@ public event stream.
|
|||||||
|
|
||||||
## What the platform is on today
|
## What the platform is on today
|
||||||
|
|
||||||
Two versions are shared by every deployment, whichever game it runs:
|
|
||||||
|
|
||||||
<table>
|
<table>
|
||||||
<tbody>
|
<tbody>
|
||||||
|
<tr><td>Wire protocol</td><td>{platform.protocol}</td></tr>
|
||||||
<tr><td>Module API</td><td>{platform.moduleApi}</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>Installer</td><td>{platform.releases.installer}</td></tr>
|
||||||
|
<tr><td>ServUO (minimum)</td><td>{platform.bundle.servuoMin}</td></tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
Everything else belongs to a game. Each game has its own wire protocol and its own bundle —
|
Every value in that table is read from `src/data/platform.json` and re-checked against its
|
||||||
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.
|
source of truth on each build. None of it is typed into prose — including here.
|
||||||
|
|
||||||
## An install is two installs
|
## An install is two installs
|
||||||
@@ -52,13 +39,12 @@ two independent deployments.
|
|||||||
2. **The shard side** is the installer binary, run on the game server's host. It sets up
|
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.
|
the plugin overlay and the sidecar, and it never contacts the website.
|
||||||
|
|
||||||
They meet at the values the installer prints, pasted into the game module's connection
|
They meet at four values pasted into the module's shard screen, and at protocol
|
||||||
screen, and at the game's wire protocol, which both sides check before they will pair.
|
{platform.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
|
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, moderation and the event
|
community website — news, wiki, pages, Teams, forums, accounts and moderation are all core,
|
||||||
calendar are all core, and none of them knows a game exists. The second install is what
|
and none of them knows a game exists. The second install is what fills the game screens.
|
||||||
fills the game screens, and what lets an event reach into a world.
|
|
||||||
|
|
||||||
## Start here
|
## Start here
|
||||||
|
|
||||||
@@ -73,8 +59,8 @@ you should expect to see before you move on:
|
|||||||
6. [Verify the whole stack](/docs/getting-started/verify-the-whole-stack/) — proving it works, rather than assuming
|
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,
|
Then **Administration** covers running it: configuration, branding, content, users,
|
||||||
authentication, Teams, scheduled events, moderation, notifications, modules, the shard
|
authentication, Teams, moderation, notifications, modules, the shard connection, upgrades,
|
||||||
connection, upgrades, and what to do when something is wrong.
|
and what to do when something is wrong.
|
||||||
|
|
||||||
## Where the truth lives
|
## Where the truth lives
|
||||||
|
|
||||||
|
|||||||
@@ -1,161 +0,0 @@
|
|||||||
---
|
|
||||||
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.
|
|
||||||
@@ -1,122 +0,0 @@
|
|||||||
---
|
|
||||||
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.
|
|
||||||
@@ -1,110 +0,0 @@
|
|||||||
---
|
|
||||||
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.
|
|
||||||
@@ -1,104 +0,0 @@
|
|||||||
---
|
|
||||||
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.
|
|
||||||
@@ -1,109 +0,0 @@
|
|||||||
---
|
|
||||||
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
|
|
||||||
[`Module-Rust`](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 `uo-link` and `servuo-plugins` 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
|
|
||||||
`module-uo`'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
|
|
||||||
```
|
|
||||||
@@ -1,172 +0,0 @@
|
|||||||
---
|
|
||||||
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.
|
|
||||||
@@ -1,117 +0,0 @@
|
|||||||
---
|
|
||||||
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';
|
|
||||||
|
|
||||||
`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
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"id": "uo",
|
|
||||||
"name": "Ultima Online",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"coreApi": "^1.0.0",
|
|
||||||
"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"]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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 `module-uo` declares `admin: ["/shard", "/uo-link"]` while its admin screen
|
|
||||||
lives at `/admin/uo/link`. 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 the **shard
|
|
||||||
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.
|
|
||||||
@@ -1,103 +0,0 @@
|
|||||||
---
|
|
||||||
title: The module system
|
|
||||||
description: What a module is, why the platform is built this way, and the one rule about URLs that catches everybody once.
|
|
||||||
---
|
|
||||||
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
|
||||||
|
|
||||||
Runic Gateway's core knows nothing about any particular game. Everything that makes the
|
|
||||||
site a *Ultima Online* site — the shard status, the atlas, the market, the guild pages —
|
|
||||||
lives in a **module**, installed onto a running deployment.
|
|
||||||
|
|
||||||
This section is the builder's track. If you only want to install one, that is
|
|
||||||
[Install a game module](/docs/getting-started/install-a-game-module/) and
|
|
||||||
[Managing modules](/docs/administration/managing-modules/).
|
|
||||||
|
|
||||||
## What a module is
|
|
||||||
|
|
||||||
One repository producing one bundle, with a server half and a client half that version
|
|
||||||
together — so a route and the screen that calls it can never be mismatched.
|
|
||||||
|
|
||||||
A module owns:
|
|
||||||
|
|
||||||
- **Its routes**, server and client
|
|
||||||
- **Its schema**, as a fragment core replays on boot
|
|
||||||
- **Its navigation entries**, interleaved into core's groups rather than parked in a
|
|
||||||
section of their own
|
|
||||||
- **Its vocabulary** — the words a player of *that* game expects
|
|
||||||
|
|
||||||
Core owns the account, the session, the roles, the posts, the uploads, notifications and
|
|
||||||
Teams. A module reaches all of that through a defined surface, [the module
|
|
||||||
API](/docs/modules/the-module-api/).
|
|
||||||
|
|
||||||
## Why it is built this way
|
|
||||||
|
|
||||||
Three constraints had to hold at the same time, and between them they determined almost
|
|
||||||
everything else:
|
|
||||||
|
|
||||||
1. **Production is a prebuilt, pull-only image.** Operators do not build. There is no
|
|
||||||
compile step anywhere in installing a module.
|
|
||||||
2. **Modules live on a mounted volume**, not inside the image — a bind mount of
|
|
||||||
`./modules`. That is what lets a module be added to an image that knows nothing about
|
|
||||||
it.
|
|
||||||
3. **`script-src 'self'`.** The content-security policy forbids inline script, which rules
|
|
||||||
out an import map and is why core shares React on a global instead. See [Building a
|
|
||||||
module](/docs/modules/building-a-module/).
|
|
||||||
|
|
||||||
Install and uninstall need a **restart** — never a rebuild.
|
|
||||||
|
|
||||||
<Aside type="note" title="One active module per deployment">
|
|
||||||
Multi-module deployments are deliberately out of scope. `module_id` columns exist so the
|
|
||||||
idea stays later-friendly, but nothing exercises them, and no one should design around
|
|
||||||
them today.
|
|
||||||
</Aside>
|
|
||||||
|
|
||||||
## The boundary is not a sandbox
|
|
||||||
|
|
||||||
A module runs **in the same Node process, with full access**. Say that plainly, because
|
|
||||||
the word "module" invites the opposite assumption.
|
|
||||||
|
|
||||||
The boundary is a **code-organisation and distribution boundary, not a security
|
|
||||||
boundary**. For a self-hosted operator installing software they chose, that is the same
|
|
||||||
trust category as running its schema fragment — which they are also doing.
|
|
||||||
|
|
||||||
What the boundary buys is that modules talk to core through a *defined* surface, so a core
|
|
||||||
refactor cannot silently break a module. That rule is enforced mechanically rather than by
|
|
||||||
review: **a module must run with zero `require`/`import` reaching outside its own
|
|
||||||
directory**, and CI checks it. A gap in the surface extends the surface; it is never
|
|
||||||
worked around with a deeper import.
|
|
||||||
|
|
||||||
## The URL rule, and its one exception
|
|
||||||
|
|
||||||
**A module owns one path segment wherever it appears.** For a module with id `uo`:
|
|
||||||
|
|
||||||
| Surface | Path |
|
|
||||||
|---|---|
|
|
||||||
| Public pages | `/uo/shard`, `/uo/atlas`, `/uo/market` |
|
|
||||||
| Admin pages | `/admin/uo/link`, `/admin/uo/visibility` |
|
|
||||||
| Player pages | `/player/uo/…` |
|
|
||||||
|
|
||||||
**API routes are the exception, and keep their exact paths.** The shard admin API is still
|
|
||||||
`/api/v1/admin/shard/*`, not `/api/v1/admin/uo/shard/*`. This is why the Android app and
|
|
||||||
the Discord bot needed no API changes at the cutover.
|
|
||||||
|
|
||||||
<Aside type="caution" title="This distinction has already cost real time">
|
|
||||||
The installer printed `<site>/admin/shard` — the pre-module path — well after the screen
|
|
||||||
had moved to `/admin/uo/link`. It was not caught quickly because **the old path does not
|
|
||||||
404**: the SPA has no route for it, so it redirects to the dashboard and looks like it
|
|
||||||
worked.
|
|
||||||
|
|
||||||
If you are moving an existing surface into a module, the SPA paths change and the API paths
|
|
||||||
do not. Grep for both.
|
|
||||||
</Aside>
|
|
||||||
|
|
||||||
Old paths are **not** redirected. That was a deliberate call — a visible boundary in the URL
|
|
||||||
rather than a hidden one — taken while the platform had no public deployments to break.
|
|
||||||
|
|
||||||
## Where the design of record lives
|
|
||||||
|
|
||||||
This page summarises. The normative document is
|
|
||||||
[`MODULE_SYSTEM.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_SYSTEM.md),
|
|
||||||
and the contract itself is
|
|
||||||
[`MODULE_API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md).
|
|
||||||
Where this site and those documents disagree, they are right and this is a bug.
|
|
||||||
@@ -1,73 +0,0 @@
|
|||||||
---
|
|
||||||
title: Bridge.cfg
|
|
||||||
description: Every key the in-game plugin reads — the connection, the sweep intervals, the feature switches and the caps that keep untrusted game data bounded.
|
|
||||||
---
|
|
||||||
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
|
||||||
import { bridgeCfg } from '../../../../data/reference.mjs';
|
|
||||||
|
|
||||||
`Config/Bridge.cfg` in the ServUO tree configures the plugin — what it connects to, how
|
|
||||||
often it sweeps the world, and which features it publishes.
|
|
||||||
|
|
||||||
[The installer](/docs/reference/installer-cli/) puts it there. Editing it is a shard
|
|
||||||
operator's job, not a builder's.
|
|
||||||
|
|
||||||
## How to read this file
|
|
||||||
|
|
||||||
Three kinds of key, and they carry very different risk:
|
|
||||||
|
|
||||||
- **Connection** — where the sidecar is, and how much the plugin may buffer.
|
|
||||||
- **Sweep intervals** — how often the plugin walks part of the world. **These are the
|
|
||||||
performance dial.** Every sweep runs on the game's core thread, so shortening one costs
|
|
||||||
the game, not the sidecar.
|
|
||||||
- **Caps and switches** — feature toggles, and the bounds on anything a player can
|
|
||||||
influence.
|
|
||||||
|
|
||||||
<Aside type="caution" title="The caps are a security control, not tuning">
|
|
||||||
`TownCrierMaxLineLength`, `NewsMaxBodyLength`, `AccountNameMaxLength` and their siblings
|
|
||||||
bound data that crosses between a public website and a game world in both directions.
|
|
||||||
|
|
||||||
`AdminWriteEnabled` is **off by default**, and it is the switch that decides whether the
|
|
||||||
website may write to the game at all. Turn it on deliberately, having read
|
|
||||||
[`ADMIN_CONTROLS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/ADMIN_CONTROLS.md).
|
|
||||||
</Aside>
|
|
||||||
|
|
||||||
## Every key
|
|
||||||
|
|
||||||
{Object.entries(bridgeCfg).map(([group, keys]) => (
|
|
||||||
<div key={group}>
|
|
||||||
<h3>{group}</h3>
|
|
||||||
<table>
|
|
||||||
<thead><tr><th>Key</th><th>What it is for</th></tr></thead>
|
|
||||||
<tbody>
|
|
||||||
{Object.entries(keys).map(([name, why]) => (
|
|
||||||
<tr key={name}><td><code>{name}</code></td><td>{why}</td></tr>
|
|
||||||
))}
|
|
||||||
</tbody>
|
|
||||||
</table>
|
|
||||||
</div>
|
|
||||||
))}
|
|
||||||
|
|
||||||
This list is checked against the shipped `Bridge.cfg` on every build, so a key added by a
|
|
||||||
protocol change turns this page red rather than going undocumented.
|
|
||||||
|
|
||||||
## Two that deserve their own note
|
|
||||||
|
|
||||||
**`QueueCap`** bounds the drop-oldest queue between the game and the writer thread. When it
|
|
||||||
fills, the **oldest events are discarded** — which is the correct behaviour, because the
|
|
||||||
alternative is a game server that stutters when a sidecar is slow. Raising it buys tolerance
|
|
||||||
for longer sidecar outages at the cost of memory; it never buys correctness.
|
|
||||||
|
|
||||||
**`GuildRosterMembersPerLine`** exists because a roster is the only fat frame this bridge
|
|
||||||
emits — a real 155-member guild measured about 10.8 KB. Rosters are **split** across lines
|
|
||||||
rather than sent oversized. See [The bridge](/docs/architecture/the-bridge/).
|
|
||||||
|
|
||||||
## Canonical documents
|
|
||||||
|
|
||||||
The shipped
|
|
||||||
[`Bridge.cfg`](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/src/branch/main/overlay/Config/Bridge.cfg)
|
|
||||||
is the authority;
|
|
||||||
[`link/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md)
|
|
||||||
§10 documents the config keys and
|
|
||||||
[`SHARD_PREREQS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/SHARD_PREREQS.md)
|
|
||||||
covers what a shard needs before any of this works.
|
|
||||||
@@ -1,74 +0,0 @@
|
|||||||
---
|
|
||||||
title: Canonical documents
|
|
||||||
description: Where the normative specifications live — the documents that win whenever this site disagrees with them.
|
|
||||||
---
|
|
||||||
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
|
||||||
import { canonicalDocs } from '../../../../data/reference.mjs';
|
|
||||||
|
|
||||||
Everything on this site is a **summary**. These are the documents it summarises, and where
|
|
||||||
the two disagree, **they are right and this site has a bug**.
|
|
||||||
|
|
||||||
<Aside type="note" title="Why say that so bluntly">
|
|
||||||
A documentation site that quietly re-specifies a contract becomes a second source of truth,
|
|
||||||
and second sources of truth drift. Every page here links out for exactly this reason, and
|
|
||||||
this page is the index of what it links to.
|
|
||||||
|
|
||||||
If you find a disagreement, it is worth reporting — it means a check is missing.
|
|
||||||
</Aside>
|
|
||||||
|
|
||||||
## The documents
|
|
||||||
|
|
||||||
<table>
|
|
||||||
<thead><tr><th>Document</th><th>Answers</th></tr></thead>
|
|
||||||
<tbody>
|
|
||||||
{Object.entries(canonicalDocs).map(([docPath, why]) => (
|
|
||||||
<tr key={docPath}>
|
|
||||||
<td>
|
|
||||||
<a href={`https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/${docPath}`}>
|
|
||||||
<code>{docPath}</code>
|
|
||||||
</a>
|
|
||||||
</td>
|
|
||||||
<td>{why}</td>
|
|
||||||
</tr>
|
|
||||||
))}
|
|
||||||
</tbody>
|
|
||||||
</table>
|
|
||||||
|
|
||||||
Every path above is checked to still exist on every build, so a document that is renamed or
|
|
||||||
moved turns this page red rather than leaving a dead link.
|
|
||||||
|
|
||||||
## Which document answers which question
|
|
||||||
|
|
||||||
- **"May a module do this?"** → `MODULE_API.md`. It is the contract, and it is the only thing
|
|
||||||
that can answer yes.
|
|
||||||
- **"Why is the module system like this?"** → `MODULE_SYSTEM.md`.
|
|
||||||
- **"What does this API return?"** → your own deployment's `/api/docs`, then
|
|
||||||
`BACKEND_DESIGN.md` §4.
|
|
||||||
- **"What can the shard send?"** → `link/PLAN.md` §5, and `v8.md` for the current
|
|
||||||
protocol — which is also where the asset plane is specified.
|
|
||||||
- **"What may a scheduled event do to the world?"** → `website/EVENTS.md` for the model,
|
|
||||||
`MODULE_API.md` for the verbs a module may declare, and `link/ADMIN_CONTROLS.md` for what
|
|
||||||
the site may ask a game to do at all.
|
|
||||||
- **"Who may see this?"** → `SHARD_VISIBILITY.md` for the administrator's view,
|
|
||||||
`modules/uo/API.md` §4 for the specification.
|
|
||||||
- **"How do I set a shard up?"** → `installer/INSTALL.md`.
|
|
||||||
|
|
||||||
## Where they live
|
|
||||||
|
|
||||||
All of them are in
|
|
||||||
[`RunicGateway/docs`](https://gitea.whitlocktech.com/RunicGateway/docs), which is Markdown
|
|
||||||
only and versioned independently of the code it describes.
|
|
||||||
|
|
||||||
**A code change is not complete until `docs` reflects it.** That is a rule in the
|
|
||||||
project's own contributor guidance, not an aspiration — a change to behaviour, protocol,
|
|
||||||
endpoints, schema, configuration or the deployment model requires a matching edit there.
|
|
||||||
|
|
||||||
## Two things that are not in `docs`
|
|
||||||
|
|
||||||
**The Integration Kit** is its own repository, because its audience is outside this project
|
|
||||||
and it teaches rather than specifies. See [The Integration
|
|
||||||
Kit](/docs/modules/the-integration-kit/).
|
|
||||||
|
|
||||||
**The OpenAPI specification** is generated and committed in `website` itself, because it is
|
|
||||||
derived from the routes rather than written alongside them.
|
|
||||||
@@ -1,66 +0,0 @@
|
|||||||
---
|
|
||||||
title: Environment variables
|
|
||||||
description: Every variable the site reads, what each is for, and the four it refuses to start without.
|
|
||||||
---
|
|
||||||
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
|
||||||
import { envVars } from '../../../../data/reference.mjs';
|
|
||||||
|
|
||||||
Every variable in `website`'s root `.env.example` — **the file a Compose deployment actually
|
|
||||||
reads**, which is not the same file local development copies.
|
|
||||||
|
|
||||||
This list is checked against that file on every build, in both directions: a variable that
|
|
||||||
disappears upstream fails, and a variable added upstream that is missing here fails too.
|
|
||||||
|
|
||||||
<Aside type="caution" title="Four are refused at boot in production">
|
|
||||||
`SECRET_ENC_KEY` and `BOT_INTERNAL_KEY` are required in production and the server **will not
|
|
||||||
start** without them — `BOT_INTERNAL_KEY` even on a deployment running no Discord bot.
|
|
||||||
`JWT_SECRET` and the `DB_*` group are required everywhere.
|
|
||||||
|
|
||||||
The first boot is also when your admin account is written, so `ADMIN_USERNAME` and
|
|
||||||
`ADMIN_PASSWORD` are set-once-before-first-boot values, not fill-in-later ones.
|
|
||||||
</Aside>
|
|
||||||
|
|
||||||
## Every variable
|
|
||||||
|
|
||||||
<table>
|
|
||||||
<thead><tr><th>Variable</th><th>What it is for</th></tr></thead>
|
|
||||||
<tbody>
|
|
||||||
{Object.entries(envVars).map(([name, why]) => (
|
|
||||||
<tr key={name}><td><code>{name}</code></td><td>{why}</td></tr>
|
|
||||||
))}
|
|
||||||
</tbody>
|
|
||||||
</table>
|
|
||||||
|
|
||||||
## The three worth reading twice
|
|
||||||
|
|
||||||
**`SECRET_ENC_KEY`** encrypts secrets at rest — OAuth client secrets, the Discord bot token,
|
|
||||||
the shard's auth token. Changing it 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.
|
|
||||||
|
|
||||||
**`COOKIE_SECURE=auto`** decides `Secure` per request, which is what lets one deployment
|
|
||||||
work both over HTTPS through a proxy and over plain HTTP on a LAN address. Forcing it either
|
|
||||||
way breaks one of those.
|
|
||||||
|
|
||||||
**`TRUST_PROXY`** is required behind a reverse proxy for secure cookies, real client IPs and
|
|
||||||
rate limiting to work at all. Without it, every request appears to come from the proxy — so
|
|
||||||
rate limiting and IP bans apply to your whole user base at once.
|
|
||||||
|
|
||||||
## Where to set them
|
|
||||||
|
|
||||||
A first install is [Install the site](/docs/getting-started/install-the-site/), which prints
|
|
||||||
a complete `.env` alongside its Compose file. Afterwards,
|
|
||||||
[Configuration](/docs/administration/configuration/) covers what is env-configured and what
|
|
||||||
is not.
|
|
||||||
|
|
||||||
**Most settings are not here.** Branding, navigation, theming and the shard connection are
|
|
||||||
**admin-managed and live in the database**, deliberately — so changing them does not mean
|
|
||||||
redeploying a container.
|
|
||||||
|
|
||||||
## Canonical source
|
|
||||||
|
|
||||||
`website`'s
|
|
||||||
[`.env.example`](https://gitea.whitlocktech.com/RunicGateway/website/src/branch/main/.env.example)
|
|
||||||
is the authority, and
|
|
||||||
[`BACKEND_DESIGN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/BACKEND_DESIGN.md)
|
|
||||||
§8 covers deployment.
|
|
||||||
@@ -1,110 +0,0 @@
|
|||||||
---
|
|
||||||
title: Shard event catalog
|
|
||||||
description: What a game server can tell the website, how those events are grouped, and the five-rung ladder that decides who may see each one.
|
|
||||||
---
|
|
||||||
|
|
||||||
import { Aside } from '@astrojs/starlight/components';
|
|
||||||
import { visibilityLadder } from '../../../../data/reference.mjs';
|
|
||||||
|
|
||||||
The events a shard emits, and the mechanism that decides who may see them.
|
|
||||||
|
|
||||||
**Not to be confused with a scheduled event.** This page is about what the game tells the
|
|
||||||
site, unprompted, as things happen in the world. An *event* in the sense of a thing you put
|
|
||||||
on the calendar and run — phases, steps, a boss at eight o'clock — is
|
|
||||||
[Scheduled events](/docs/administration/events/). The two do meet: a kind listed below is
|
|
||||||
exactly what a scheduled event's phase can wait for.
|
|
||||||
|
|
||||||
The exact wire shapes are in the protocol specification and are **not** restated here — a
|
|
||||||
copy of a wire format is a copy that will be wrong after the next bump. This page is the map
|
|
||||||
and the security model.
|
|
||||||
|
|
||||||
## What the shard can say
|
|
||||||
|
|
||||||
Nine groups, from the data catalog:
|
|
||||||
|
|
||||||
| Group | Covers |
|
|
||||||
|---|---|
|
|
||||||
| Session & identity | Logins, logouts, account linking |
|
|
||||||
| Character state | Vitals, stats, skills, position |
|
|
||||||
| Economy & commerce | Gold movement, vendor sales, supply totals |
|
|
||||||
| Housing / IDOC | Decay stages, ownership, coordinates |
|
|
||||||
| Combat, death, PvP | Kills, deaths, notable fights |
|
|
||||||
| Progression & activity | Skill gains, points, leaderboards |
|
|
||||||
| Cheat detection & staff audit | Fastwalk and friends; staff property edits |
|
|
||||||
| Lifecycle | `server.hello`, shutdown, crash |
|
|
||||||
| Known gaps | Things ServUO offers no clean hook for |
|
|
||||||
|
|
||||||
A representative line:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{"t":1752,"kind":"cheat.fastwalk","serial":"0x1A2B","acct":"PerryAdimn"}
|
|
||||||
```
|
|
||||||
|
|
||||||
Note that one. **Cheat and audit events exist, and they are exactly what must never reach a
|
|
||||||
public page.**
|
|
||||||
|
|
||||||
## How events are handled
|
|
||||||
|
|
||||||
Not all alike, and the difference is deliberate:
|
|
||||||
|
|
||||||
- **State-changing kinds** update tables. The current state is what a page renders.
|
|
||||||
- **Notable kinds** additionally append to an events log, because a history is worth
|
|
||||||
keeping.
|
|
||||||
- **High-frequency kinds** only update state. Accumulating history for something that fires
|
|
||||||
constantly buys nothing and costs a table that grows forever.
|
|
||||||
|
|
||||||
## The visibility ladder
|
|
||||||
|
|
||||||
Five rungs, in order, least privileged first:
|
|
||||||
|
|
||||||
<ol>
|
|
||||||
{visibilityLadder.map((rung) => (<li key={rung}><code>{rung}</code></li>))}
|
|
||||||
</ol>
|
|
||||||
|
|
||||||
Every feature declares the rung it is visible from, and individual **fields** can require a
|
|
||||||
higher rung than the feature that carries them — a character's presence may be public while
|
|
||||||
its *location* is staff-only.
|
|
||||||
|
|
||||||
This list and its **order** are checked against the module that enforces it on every build.
|
|
||||||
Order matters as much as membership: reasoning about "staff and above" depends on the rungs
|
|
||||||
being in the right sequence.
|
|
||||||
|
|
||||||
<Aside type="caution" title="This is a security boundary, not a filter">
|
|
||||||
It is applied in **three** places — at routes, at SSE subscribe time, and at the navigation.
|
|
||||||
All three, because a surface filtered in only two of them leaks through the third.
|
|
||||||
|
|
||||||
Defaults **fail closed**: an unresolvable viewer is anonymous, not privileged, and a feature
|
|
||||||
with no configuration is not public by accident.
|
|
||||||
</Aside>
|
|
||||||
|
|
||||||
## Two SSE channels
|
|
||||||
|
|
||||||
Ingested events fan out to browsers over two streams:
|
|
||||||
|
|
||||||
- a **public** stream, carrying only allowlisted kinds;
|
|
||||||
- an **admin** stream, which additionally carries staff audit, cheat detection and login
|
|
||||||
attempts with IP addresses.
|
|
||||||
|
|
||||||
**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 viewer's rung is resolved **once, when the stream opens, and frozen for its life**. A
|
|
||||||
long-lived connection must not silently gain privilege because the session changed
|
|
||||||
underneath it. Configuration changes, by contrast, *do* take effect live.
|
|
||||||
|
|
||||||
## Administering it
|
|
||||||
|
|
||||||
[The shard connection](/docs/administration/the-shard-connection/) covers the admin screens,
|
|
||||||
and the visibility ladder is administrator-configurable per feature and per field.
|
|
||||||
|
|
||||||
## Canonical documents
|
|
||||||
|
|
||||||
[`link/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md)
|
|
||||||
§5 is the data catalog and §7 the wire protocol;
|
|
||||||
[`link/v4.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v4.md)
|
|
||||||
is the current protocol;
|
|
||||||
[`SHARD_VISIBILITY.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/SHARD_VISIBILITY.md)
|
|
||||||
is the administrator's guide to the ladder, and
|
|
||||||
[`modules/uo/API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/uo/API.md)
|
|
||||||
§4 specifies it.
|
|
||||||