Compare commits
53 Commits
feat/phase
...
ec65b2d5aa
| Author | SHA1 | Date | |
|---|---|---|---|
| ec65b2d5aa | |||
| 297cc83db5 | |||
| ecc556d7ac | |||
| fe86fc369d | |||
| 9b28c95305 | |||
| aad3a37c09 | |||
| 75c8ffc07a | |||
| a100195e7b | |||
| 4426d3e339 | |||
| 6046214d71 | |||
| 9938e71e07 | |||
| 2971b84d51 | |||
| b1584043a3 | |||
| c3c347d237 | |||
| 4e1ce2316a | |||
| 73f664c38e | |||
| e91e76bfa9 | |||
| 5f58a4cbf2 | |||
| 82b55e3084 | |||
| a0af01026e | |||
| 5c6735bd1d | |||
| 5e987518c6 | |||
| 3574bba4d5 | |||
| d01fd55f43 | |||
| 83c438885e | |||
| 391a4a131b | |||
| c8a293b8f6 | |||
| 916921551f | |||
| 7709b055a4 | |||
| 92a1a33121 | |||
| 283814dbf2 | |||
| 782e3df7e2 | |||
| e0d491d33b | |||
| ebd6ba8dbf | |||
| 289b6b3a8d | |||
| 5ba91717c0 | |||
| 2da014790e | |||
| 268e1c98fc | |||
| 12c416f5fc | |||
| ce13a44ed7 | |||
| b86f4cabf0 | |||
| e60812fb34 | |||
| 92f00ab20a | |||
| 3b4067fa37 | |||
| 1558111050 | |||
| f2e59a2426 | |||
| 18064062a9 | |||
| de9d25bbe7 | |||
| 58883951a4 | |||
| e71ff4acd4 | |||
| a34c2ce538 | |||
| 8b6efd5c0a | |||
| ebb3f71786 |
42
.dockerignore
Normal file
42
.dockerignore
Normal file
@@ -0,0 +1,42 @@
|
||||
# What must never reach the build context.
|
||||
#
|
||||
# Two entries here are load-bearing rather than housekeeping, and both are about
|
||||
# the bind mounts (PLAN.md §6, §7).
|
||||
#
|
||||
# brand/ is the OPERATOR's override. If a developer's local mount were copied
|
||||
# in, the image would ship somebody's test logo as if it were stock —
|
||||
# and, worse, it would win over brand-default/ on every deployment that
|
||||
# does not mount its own. The mount is the only way brand/ is allowed
|
||||
# to exist inside a container.
|
||||
#
|
||||
# data/ holds beta.sqlite: real addresses, given under a consent notice that
|
||||
# says where they are stored. A published image is world-readable to
|
||||
# anyone who can pull it. This line is the reason that cannot happen by
|
||||
# accident.
|
||||
#
|
||||
# brand-default/ is deliberately NOT here. It is baked in and must always be
|
||||
# complete; §7's whole per-file fallback rests on it.
|
||||
|
||||
node_modules
|
||||
dist
|
||||
.astro
|
||||
.output
|
||||
|
||||
brand
|
||||
data
|
||||
|
||||
.git
|
||||
.gitea
|
||||
.gitignore
|
||||
.dockerignore
|
||||
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
|
||||
# Authoring inputs and working notes, none of which the running site reads.
|
||||
PLAN.md
|
||||
*.log
|
||||
npm-debug.log*
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
70
.env.example
Normal file
70
.env.example
Normal file
@@ -0,0 +1,70 @@
|
||||
# runicgateway.com — production environment.
|
||||
#
|
||||
# Copy to `.env` beside docker-compose.yml on the host and fill in the two
|
||||
# secrets. Everything else has a working default; this file exists so the
|
||||
# defaults are visible rather than discovered.
|
||||
#
|
||||
# cp .env.example .env
|
||||
#
|
||||
# Nothing here is a credential for another service. The site talks to no API,
|
||||
# sends no mail (D7) and has no database server — the only state it keeps is a
|
||||
# SQLite file on the ./data mount.
|
||||
|
||||
# ---------------------------------------------------------------------------------------
|
||||
# Deployment
|
||||
# ---------------------------------------------------------------------------------------
|
||||
|
||||
# Which published build runs. `latest` follows main; pin `sha-<7>` for a
|
||||
# reproducible deploy or to roll back — every merge publishes both tags.
|
||||
IMAGE_TAG=latest
|
||||
|
||||
# Host port the container is published on.
|
||||
SITE_HOST_PORT=4321
|
||||
|
||||
# Which of the host's addresses that port is published on. The default is every
|
||||
# interface, so the site answers on the host's own address — http://<vm-ip>:4321
|
||||
# — which is what a proxy in another container, another machine, or a browser
|
||||
# elsewhere on the network needs.
|
||||
#
|
||||
# Narrow it if this host has a public address and you want only the proxy to
|
||||
# reach the container: 127.0.0.1 for a proxy on this same host, or one interface
|
||||
# address for the LAN but not a public NIC. Nothing else in the site changes.
|
||||
SITE_BIND_ADDR=0.0.0.0
|
||||
|
||||
# ---------------------------------------------------------------------------------------
|
||||
# The closed-beta signup (PLAN.md §8)
|
||||
# ---------------------------------------------------------------------------------------
|
||||
#
|
||||
# THE TWO BELOW ARE THE ONLY VALUES THAT REALLY WANT SETTING. Both default to a
|
||||
# random value generated per process, which is safe but forgetful: every restart
|
||||
# invalidates every rate-limit window and every rendered form. That is the right
|
||||
# default — a hard-coded salt shipped in a public repository would make every
|
||||
# deployment's ip_hash values identical and therefore reversible by anyone who
|
||||
# can read it — but it is not what you want on a host that restarts.
|
||||
#
|
||||
# Generate both once, keep them, and do not rotate them casually: changing the
|
||||
# salt orphans the rate-limit history of everyone already counted.
|
||||
#
|
||||
# openssl rand -hex 32
|
||||
|
||||
# Salts the ip_hash column. The raw IP address is never stored — /privacy says
|
||||
# so, and this is the mechanism that makes it true while still allowing a
|
||||
# per-connection limit.
|
||||
BETA_IP_SALT=
|
||||
|
||||
# Signs the hidden form token, so a script has to fetch the page before it can
|
||||
# post. Rotating this only invalidates forms currently open in a browser.
|
||||
BETA_FORM_KEY=
|
||||
|
||||
# Rows, across all time, above which the form closes and says so on the page.
|
||||
BETA_TOTAL_CAP=500
|
||||
|
||||
# What one connection may do, in a rolling hour and a rolling day.
|
||||
BETA_PER_HOUR=3
|
||||
BETA_PER_DAY=24
|
||||
|
||||
# Seconds between the page rendering and the form posting. Below the minimum is
|
||||
# treated as a script; above the maximum the form is stale and re-rendered.
|
||||
# Twelve hours is the default maximum.
|
||||
BETA_MIN_SECONDS=2
|
||||
BETA_MAX_SECONDS=43200
|
||||
48
.gitea/ISSUE_TEMPLATE/bug_report.md
Normal file
48
.gitea/ISSUE_TEMPLATE/bug_report.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
name: Bug report
|
||||
about: Something on the site is broken, wrong, or behaving unexpectedly
|
||||
title: "[bug] "
|
||||
labels:
|
||||
- bug
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
<!-- A clear, concise description of the problem. -->
|
||||
|
||||
## Where
|
||||
|
||||
<!-- The URL, or the page and the section. If it is a documentation page, the heading. -->
|
||||
|
||||
- Page:
|
||||
- Viewport width, if it is a layout problem:
|
||||
- Browser and version:
|
||||
|
||||
## What happened, and what you expected
|
||||
|
||||
<!--
|
||||
Include exact wording for a factual error, and the console message if there is
|
||||
one. A screenshot helps for anything visual.
|
||||
-->
|
||||
|
||||
## Is it a factual error?
|
||||
|
||||
<!--
|
||||
The most valuable reports this repository gets are claims that are WRONG about
|
||||
the platform — a version, a command, a flag, a capability that no longer works
|
||||
that way. If so, say where the correct answer lives (which repository, which
|
||||
file), because the fix is usually to a data file or a check rather than to the
|
||||
sentence.
|
||||
-->
|
||||
|
||||
## Additional context
|
||||
|
||||
<!-- Anything else that helps. -->
|
||||
|
||||
<!--
|
||||
Security issue? Do NOT file it here — see SECURITY.md for the private route.
|
||||
|
||||
A problem with the PLATFORM rather than with this site (the website, the
|
||||
sidecar, the shard plugin, the installer, the Android app) belongs in that
|
||||
repository's tracker. This one only describes them.
|
||||
-->
|
||||
11
.gitea/ISSUE_TEMPLATE/config.yaml
Normal file
11
.gitea/ISSUE_TEMPLATE/config.yaml
Normal file
@@ -0,0 +1,11 @@
|
||||
blank_issues_enabled: true
|
||||
contact_links:
|
||||
- name: Security vulnerability
|
||||
url: https://gitea.whitlocktech.com/RunicGateway/runicgateway.com/src/branch/main/SECURITY.md
|
||||
about: Please do not open a public issue for security problems — report them privately instead (see SECURITY.md).
|
||||
- name: Questions, help and the Android beta
|
||||
url: https://discord.gg/t2Jav8yT4g
|
||||
about: Discord is the front door — instant, and it needs no account here. Bug reports are welcome there too.
|
||||
- name: A problem with the platform, not the site
|
||||
url: https://gitea.whitlocktech.com/RunicGateway
|
||||
about: The website, the sidecar, the shard plugin, the installer and the Android app each have their own tracker. This repository only describes them.
|
||||
38
.gitea/ISSUE_TEMPLATE/feature_request.md
Normal file
38
.gitea/ISSUE_TEMPLATE/feature_request.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
name: Feature request
|
||||
about: Suggest a page, a section, or a change to how the site explains something
|
||||
title: "[feature] "
|
||||
labels:
|
||||
- enhancement
|
||||
---
|
||||
|
||||
## Problem / motivation
|
||||
|
||||
<!--
|
||||
What were you trying to find out, or do, when the site let you down? A missing
|
||||
page is easier to judge from the question that went unanswered than from the
|
||||
page title.
|
||||
-->
|
||||
|
||||
## Proposed solution
|
||||
|
||||
<!-- What you would like to see. -->
|
||||
|
||||
## Does it belong here?
|
||||
|
||||
<!--
|
||||
Two boundaries this repository holds deliberately (PLAN.md §1):
|
||||
|
||||
- The site TEACHES; `docs/` SPECIFIES. Protocol, module API, backend design and
|
||||
installer behaviour are normative in the docs repository — a page here links
|
||||
out rather than restating them, so that it cannot drift.
|
||||
- Absences are stated as data, not implied. If the request is for something the
|
||||
platform does not do yet, it may belong in src/data/notBuilt.mjs rather than
|
||||
as a page.
|
||||
|
||||
Say which side you think it falls on; being wrong about it is fine.
|
||||
-->
|
||||
|
||||
## Additional context
|
||||
|
||||
<!-- Mockups, links, related issues, the repository the change would describe. -->
|
||||
42
.gitea/PULL_REQUEST_TEMPLATE.md
Normal file
42
.gitea/PULL_REQUEST_TEMPLATE.md
Normal file
@@ -0,0 +1,42 @@
|
||||
<!--
|
||||
Thanks for contributing to Runic Gateway!
|
||||
Please fill out the sections below and check every box before requesting review.
|
||||
|
||||
Merging to main publishes: it builds the image, pushes it to the registry and
|
||||
deploys the site. There is no separate release step. See DEPLOY.md.
|
||||
-->
|
||||
|
||||
## What & why
|
||||
|
||||
<!-- What does this PR change, and why? Link any related issue: "Closes #123". -->
|
||||
|
||||
## How it was tested
|
||||
|
||||
<!--
|
||||
`npm run verify` output is the baseline. If the change touches a page, say what
|
||||
you looked at and at what width; if it touches the container, say whether you
|
||||
built and ran the image.
|
||||
-->
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] I have read [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
- [ ] `npm run verify` passes locally (all eleven checks and both test suites).
|
||||
- [ ] No fact is stated in prose — versions and platform facts come from `src/data/platform.json`.
|
||||
- [ ] `PLAN.md` still describes what this repository does; a decision it records is either
|
||||
unchanged or amended here, with the reasoning.
|
||||
- [ ] My commits are reasonably scoped, with Conventional Commit messages.
|
||||
|
||||
## AI-assisted contributions (required)
|
||||
|
||||
This project **requires disclosure of AI tool usage**. Please pick one:
|
||||
|
||||
- [ ] No AI tools were used to produce this contribution.
|
||||
- [ ] AI tools were used. Tool(s): `___________`. I have reviewed and understand
|
||||
every change, and take responsibility for it. AI-authored commits are
|
||||
marked with a `Co-Authored-By` / `Assisted-By` trailer.
|
||||
|
||||
## License
|
||||
|
||||
- [ ] I agree that my contribution is licensed under this project's license
|
||||
(**GNU GPL v3.0 or later**), and I have the right to contribute it.
|
||||
209
.gitea/workflows/build-image.yml
Normal file
209
.gitea/workflows/build-image.yml
Normal file
@@ -0,0 +1,209 @@
|
||||
# Build the container image, publish it to Gitea's container registry, then roll
|
||||
# the site onto it — on every merge to main.
|
||||
#
|
||||
# Gitea Actions caution, learned elsewhere in this org and repeated from
|
||||
# pr-checks.yml because it costs one comment and has already cost months: never
|
||||
# leave an empty template expression anywhere in a `run:` script, not even inside
|
||||
# a comment. The runner silently SKIPS the whole step without failing the job,
|
||||
# and the problem is invisible in the workflow list.
|
||||
#
|
||||
# Two jobs, in sequence:
|
||||
#
|
||||
# build — builds and pushes the image (on `ubuntu-latest`)
|
||||
# deploy — `needs: build`, so it starts only after a clean build and push, and
|
||||
# pulls + recreates the stack on the host (on `rgcom`)
|
||||
#
|
||||
# Prerequisites, one-time:
|
||||
#
|
||||
# • A runner labelled `ubuntu-latest` whose jobs have the host Docker socket
|
||||
# mounted (/var/run/docker.sock), so `docker build` talks to the host daemon.
|
||||
# This also gives free layer caching between runs. The org already runs one.
|
||||
#
|
||||
# • A runner labelled `rgcom` ON the host that serves the site, able to reach
|
||||
# the Docker daemon and /opt/runicgateway.com — the directory holding the
|
||||
# production docker-compose.yml and .env. DEPLOY.md has the registration
|
||||
# command and the directory layout.
|
||||
#
|
||||
# • Two repository secrets (Settings → Actions → Secrets), both of which
|
||||
# already exist for pr-checks.yml's cross-repository checks:
|
||||
# REGISTRY_USER — the Gitea username owning the token below
|
||||
# REGISTRY_TOKEN — a token with write:package (and read:package)
|
||||
#
|
||||
# Produces, in gitea.whitlocktech.com/runicgateway/ :
|
||||
# runicgateway-site:latest + runicgateway-site:sha-<7>
|
||||
#
|
||||
# and deploys `:latest`, which is what docker-compose.yml defaults IMAGE_TAG to.
|
||||
#
|
||||
# WHY THIS REPOSITORY DEPLOYS AND D6 SAID IT WOULD NOT: D6 was written before
|
||||
# there was a host to deploy to, and read "ship the image, the org lead deploys".
|
||||
# The org lead amended it on 2026-08-25 (D54): a marketing site whose content is
|
||||
# its whole purpose is a bad fit for a manual step between merging a fix and the
|
||||
# fix being visible. What D6 was protecting — that a bad build cannot reach
|
||||
# production — is held by `needs: build` instead, plus every check in
|
||||
# pr-checks.yml having already run on the pull request.
|
||||
|
||||
name: Build and publish the image
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_dispatch: {}
|
||||
|
||||
concurrency:
|
||||
group: image-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
env:
|
||||
REGISTRY: gitea.whitlocktech.com
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Check out the merged commit
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Derive the image ref
|
||||
# The registry path must be lowercase for Docker; the org is `RunicGateway`.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
OWNER="$(echo "${{ github.repository_owner }}" | tr '[:upper:]' '[:lower:]')"
|
||||
SHORT_SHA="${GITHUB_SHA:0:7}"
|
||||
echo "IMAGE=${REGISTRY}/${OWNER}/runicgateway-site" >> "$GITHUB_ENV"
|
||||
echo "TAG=sha-${SHORT_SHA}" >> "$GITHUB_ENV"
|
||||
|
||||
- name: Verify the Docker daemon is reachable
|
||||
# Fails fast with a clear message if the host socket is not mounted into
|
||||
# the job container — the one hard runner prerequisite.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
if ! docker info >/dev/null 2>&1; then
|
||||
echo "::error::Docker daemon not reachable. Mount /var/run/docker.sock into the runner's job containers."
|
||||
exit 1
|
||||
fi
|
||||
echo "Docker daemon OK"
|
||||
|
||||
- name: Log in to the Gitea container registry
|
||||
run: |
|
||||
set -euo pipefail
|
||||
echo "${{ secrets.REGISTRY_TOKEN }}" \
|
||||
| docker login "${REGISTRY}" -u "${{ secrets.REGISTRY_USER }}" --password-stdin
|
||||
|
||||
- name: Build
|
||||
# Two tags from one build: `latest` for the compose default, `sha-<7>` so
|
||||
# a deploy can be pinned or rolled back to an exact commit.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
docker build -f Dockerfile \
|
||||
-t "${IMAGE}:latest" \
|
||||
-t "${IMAGE}:${TAG}" \
|
||||
.
|
||||
|
||||
- name: No layer may exceed the registry's request limit
|
||||
# Gitea is behind Cloudflare, which refuses a request body over 100 MB on
|
||||
# every plan below Enterprise, and `docker push` uploads each layer as one
|
||||
# monolithic PUT. An oversized layer is therefore rejected at the EDGE:
|
||||
# Gitea never sees it, the log says only `413 Payload Too Large` against a
|
||||
# blob digest, and the image is not published at all. That is what happened
|
||||
# on the first merge after phase 12, and the Dockerfile's three-layer
|
||||
# node_modules split is what fixed it.
|
||||
#
|
||||
# A split is a margin, not a guarantee, so this counts the layers before
|
||||
# the push rather than letting the next fat dependency rediscover the 413.
|
||||
# 90 MB, not 100: the cap is on the whole request, and the blob is not the
|
||||
# only thing in it.
|
||||
#
|
||||
# Measured by re-compressing what `docker save` writes, because the daemon
|
||||
# exposes uncompressed sizes only and the limit applies to the compressed
|
||||
# blob. gzip is what the push uses, so the numbers agree to within a per
|
||||
# cent; both archive layouts are handled, since a layer is already gzipped
|
||||
# in one of them and plain in the other.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
LIMIT_MB=90
|
||||
|
||||
docker save "${IMAGE}:${TAG}" -o /tmp/image.tar
|
||||
mkdir -p /tmp/layers
|
||||
tar -xf /tmp/image.tar -C /tmp/layers
|
||||
|
||||
WORST_MB=0
|
||||
WORST_FILE=""
|
||||
# Only files big enough to matter; everything else is metadata.
|
||||
while IFS= read -r f; do
|
||||
if [ "$(head -c 2 "$f" | od -An -tx1 | tr -d ' \n')" = "1f8b" ]; then
|
||||
SIZE=$(stat -c %s "$f") # already compressed
|
||||
else
|
||||
SIZE=$(gzip -c "$f" | wc -c) # compress it the way the push will
|
||||
fi
|
||||
MB=$(( SIZE / 1048576 ))
|
||||
if [ "$MB" -gt "$WORST_MB" ]; then
|
||||
WORST_MB=$MB
|
||||
WORST_FILE=$f
|
||||
fi
|
||||
done < <(find /tmp/layers -type f -size +8M)
|
||||
|
||||
rm -rf /tmp/image.tar /tmp/layers
|
||||
|
||||
echo "Largest layer: ${WORST_MB} MB compressed (limit ${LIMIT_MB} MB)"
|
||||
if [ "$WORST_MB" -gt "$LIMIT_MB" ]; then
|
||||
echo "::error::A layer is ${WORST_MB} MB compressed (${WORST_FILE}). Cloudflare rejects a request body over 100 MB, so this push would fail with 413 Payload Too Large and publish nothing. Split the layer in the Dockerfile — see the COPY block that splits node_modules."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
- name: Push
|
||||
run: |
|
||||
set -euo pipefail
|
||||
docker push "${IMAGE}:latest"
|
||||
docker push "${IMAGE}:${TAG}"
|
||||
|
||||
- name: Log out
|
||||
if: always()
|
||||
run: docker logout "${REGISTRY}" || true
|
||||
|
||||
deploy:
|
||||
# Roll the site onto the image `build` just pushed. `needs: build` makes this
|
||||
# wait for a clean build and push — if the build fails, deploy never fires and
|
||||
# the running container is left alone rather than torn down for nothing.
|
||||
needs: build
|
||||
runs-on: rgcom
|
||||
# Guard against a workflow_dispatch fired from a branch: only main is deployed.
|
||||
if: github.ref == 'refs/heads/main'
|
||||
# Until a runner with this label exists, this job simply QUEUES. That is the
|
||||
# intended behaviour and it breaks nothing: `build` has already published the
|
||||
# image, so `docker compose pull && up -d` by hand is available the whole time,
|
||||
# and the queued job runs the moment the runner registers.
|
||||
|
||||
steps:
|
||||
- name: Pull the fresh image and recreate the container
|
||||
# No `down` first, deliberately. There is one service and no database to
|
||||
# keep still, so `up -d` recreates it in place when the pulled digest
|
||||
# differs — a couple of seconds of connection refused behind the proxy
|
||||
# rather than the whole stack stopped while an image is fetched.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cd /opt/runicgateway.com
|
||||
docker compose pull
|
||||
docker compose up -d --remove-orphans
|
||||
docker compose ps
|
||||
|
||||
- name: Wait for the container to report healthy
|
||||
# The image's healthcheck watches an actual response, and `npm start` runs
|
||||
# the brand rewrite before the server starts — so "running" arrives well
|
||||
# before "serving". Without this the job would go green on a container
|
||||
# that is about to crash-loop on, say, an unwritable ./data.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cd /opt/runicgateway.com
|
||||
for attempt in $(seq 1 30); do
|
||||
STATUS="$(docker compose ps --format '{{.Health}}' site | head -n 1)"
|
||||
echo "attempt ${attempt}: ${STATUS:-unknown}"
|
||||
if [ "$STATUS" = "healthy" ]; then
|
||||
echo "Site is healthy."
|
||||
exit 0
|
||||
fi
|
||||
sleep 5
|
||||
done
|
||||
echo "::error::The site did not become healthy within 150s."
|
||||
docker compose logs --tail 100 site
|
||||
exit 1
|
||||
@@ -78,6 +78,16 @@ jobs:
|
||||
# No token, no network, no build — so it runs early and fails fast.
|
||||
run: npm run check:sidebar
|
||||
|
||||
- name: Game vocabulary
|
||||
# PLAN.md §16, D63/D64 — the twelfth check, phase 14. The site may NAME the games it
|
||||
# supports anywhere, but a game's vocabulary (shard, guild, clan, uo-link, Oxide…)
|
||||
# belongs in that game's own docs group, its sidebar group, or a <GameExample> block
|
||||
# that labels it (D68). Core pages use core's words: a Team, a game server, the
|
||||
# sidecar, the bridge plugin, the game module.
|
||||
#
|
||||
# No token, no network, no build — so it runs early and fails fast.
|
||||
run: npm run check:terms
|
||||
|
||||
- name: Screenshots
|
||||
# PLAN.md §12, phase 9 (D45). src/data/screens.mjs is the one list of what the site
|
||||
# shows of itself: every entry must have a file, at the size the markup declares, and
|
||||
@@ -158,3 +168,45 @@ jobs:
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
|
||||
run: npm run check:reference
|
||||
|
||||
- name: The headers the server actually sends
|
||||
# PLAN.md §6 / D48, phase 10. Every other check reads dist/; this one starts
|
||||
# scripts/serve.mjs and reads the responses, because the defect it exists for
|
||||
# happened after the build was already correct. @astrojs/node matched a request to a
|
||||
# policy with a SUBSTRING test, so /modules/ was served the policy built for
|
||||
# /docs/modules/building-a-module — every file on disk right, the bytes on the wire
|
||||
# wrong, and the page rendered with its own stylesheet refused.
|
||||
#
|
||||
# It needs the build, so it cannot live in the "Unit tests" step above.
|
||||
run: npm run test:served
|
||||
|
||||
- name: Accessibility
|
||||
# PLAN.md §13, phase 10. Seven structural rules over every built page: one <h1> and
|
||||
# no skipped heading level, an alt attribute on every image, a label on every form
|
||||
# control, an accessible name on every link and button, <html lang>, one <main> with
|
||||
# a skip link that reaches it, and no positive tabindex.
|
||||
#
|
||||
# Structural on purpose. A static check cannot measure contrast on a rendered page
|
||||
# or find a focus trap, and a check that pretended to would be trusted for things it
|
||||
# cannot see. What it does catch is the class of defect that is invisible to a
|
||||
# sighted author and permanent once shipped — and it covers Starlight's forty pages
|
||||
# too, so a dependency upgrade that loses a label is a red build rather than a
|
||||
# discovery.
|
||||
#
|
||||
# After the build, because it reads dist/client. No token and no network.
|
||||
run: npm run check:a11y
|
||||
|
||||
- name: Content-Security-Policy
|
||||
# PLAN.md §6 / D48. The policy is a real response header — the Node adapter's
|
||||
# staticHeaders writes dist/_headers.json and the standalone server sends it — so
|
||||
# frame-ancestors applies and the operator's proxy needs no CSP config.
|
||||
#
|
||||
# The check that matters is the second one: every inline script and style must be
|
||||
# covered by a hash in ITS OWN page's policy. Astro does not hash <script is:inline>,
|
||||
# and Starlight ships six of them per documentation page, so the first build with CSP
|
||||
# enabled had a strict, correct header and a dead theme switcher — a failure with no
|
||||
# symptom except a console message. A Starlight upgrade can reintroduce it at any
|
||||
# time, which is why this runs on every PR rather than once.
|
||||
#
|
||||
# After the build, because it reads dist/. No token and no network.
|
||||
run: npm run check:csp
|
||||
|
||||
17
CODE_OF_CONDUCT.md
Normal file
17
CODE_OF_CONDUCT.md
Normal file
@@ -0,0 +1,17 @@
|
||||
# Code of Conduct
|
||||
|
||||
This repository is covered by the Runic Gateway organisation's Code of Conduct — the Contributor
|
||||
Covenant, v2.1 — which applies identically across all ten repositories:
|
||||
|
||||
**[RunicGateway/docs → CODE_OF_CONDUCT.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/CODE_OF_CONDUCT.md)**
|
||||
|
||||
It covers the standards expected of everyone taking part, the scope (project spaces and public
|
||||
spaces where somebody represents the project), the enforcement guidelines, and **how to report
|
||||
unacceptable behaviour privately**.
|
||||
|
||||
Reporting goes to the organisation maintainer. That document carries the address; this file
|
||||
deliberately does not, for the same reason [SECURITY.md](SECURITY.md) does not — **D13** (`PLAN.md`
|
||||
§5) keeps the published contact address in one bind-mounted file so that changing it costs a file
|
||||
copy rather than a commit in ten repositories.
|
||||
|
||||
Reports are handled privately, and the reporter's identity is not shared with the person reported.
|
||||
141
CONTRIBUTING.md
Normal file
141
CONTRIBUTING.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Contributing to runicgateway.com
|
||||
|
||||
Thanks for your interest. This repository is the **public marketing and documentation site** for
|
||||
[Runic Gateway][org] — the platform that puts a private game server's live state on a public website
|
||||
without ever exposing the game to the internet.
|
||||
|
||||
It is a site, not a component. Nothing else in the organisation depends on it, and it depends on
|
||||
everything: almost every sentence here describes something that lives in another repository.
|
||||
|
||||
By participating you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
|
||||
|
||||
## Read the plan first
|
||||
|
||||
**[`PLAN.md`](PLAN.md) is the design of record.** It is not a sketch — it carries the verified
|
||||
platform state, the org lead's fifty-odd decisions, the information architecture, the accuracy
|
||||
machinery and the build phases. A change that contradicts a decision recorded there needs the
|
||||
decision changed first, in the same pull request, with the reasoning written down.
|
||||
|
||||
Two things it records are worth knowing before you write a line:
|
||||
|
||||
- **§1 — the site never re-specifies a contract.** `docs/` is normative for the protocol, the module
|
||||
API, the backend design and the installer. This site teaches, links out, and quotes versions from
|
||||
data rather than prose. A page that restates a contract is a page that will be wrong later, and
|
||||
nothing will notice.
|
||||
- **§12 — the checks are the mechanism, and their failure is the feature.** When the platform moves,
|
||||
this repository goes red so that somebody updates the site. Do not route around a check; if one is
|
||||
wrong, fix the check and say why in the pull request.
|
||||
|
||||
## Ways to contribute
|
||||
|
||||
- **Report a bug** or **request a feature** through the [issue tracker][issues] — templates are
|
||||
provided.
|
||||
- **Improve a page, a check or the build** by opening a pull request.
|
||||
- **Never** report a security vulnerability in a public issue. See [SECURITY.md](SECURITY.md).
|
||||
|
||||
If you spot a claim on the site that is *wrong about the platform* — a version, a capability, a
|
||||
command that no longer exists — that is the most valuable report this repository can receive.
|
||||
|
||||
## Development setup
|
||||
|
||||
**Prerequisites:** Node 22 LTS or newer. Nothing else — no database, no game server, no container
|
||||
runtime for ordinary work.
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev # http://localhost:4321
|
||||
```
|
||||
|
||||
```bash
|
||||
npm run build # → dist/ (prerendered pages + the Node server entry)
|
||||
npm start # serve the built site, exactly as the container does
|
||||
```
|
||||
|
||||
Two directories are **bind mounts at runtime and not in the repository**: `brand/` overrides the
|
||||
stock branding per file, and `data/` holds the beta signup store. Both are optional locally; an
|
||||
absent `brand/` produces exactly the stock site, and `data/` is created on first write.
|
||||
|
||||
## The checks
|
||||
|
||||
There are twelve, plus two test suites. `npm run verify` runs all of them in dependency order, and
|
||||
that is what CI does on every pull request.
|
||||
|
||||
```bash
|
||||
npm run verify
|
||||
```
|
||||
|
||||
Three of them read other repositories over the Gitea API and need a token with access to the
|
||||
organisation, not just this repository:
|
||||
|
||||
```bash
|
||||
GITEA_TOKEN=<token> npm run check:facts # every version agrees with its authority
|
||||
GITEA_TOKEN=<token> npm run check:quickstart # the install page still matches website's own files
|
||||
GITEA_TOKEN=<token> npm run check:reference # every name the Reference lists still exists
|
||||
```
|
||||
|
||||
Without a token they fail rather than skip, deliberately: a check that silently passes when it could
|
||||
not do its job is worse than no check. CI maps the org-level `REGISTRY_TOKEN` secret into
|
||||
`GITEA_TOKEN` for those three steps.
|
||||
|
||||
The README's "The checks, and why they are not optional" section explains what each one guards.
|
||||
Read it before adding a page — several of them constrain how a page may be written, particularly
|
||||
`check:tokens` (no colour literal outside `src/styles/tokens.css`) and `check:links` (no commit
|
||||
permalinks into org repositories).
|
||||
|
||||
## Writing for this site
|
||||
|
||||
- **Understated honesty** (D8). The site reads as finished. Where something is not built, the
|
||||
absence is stated as data in `src/data/notBuilt.mjs` and rendered — never implied by silence and
|
||||
never dressed up as a roadmap.
|
||||
- **No version in prose.** Every externally-sourced fact lives in `src/data/platform.json` and is
|
||||
re-read from its authority by `check:facts`. If you find yourself typing a version number into a
|
||||
sentence, put it in the data file instead.
|
||||
- **No email address in `src/` or `scripts/`** (D13). The published contact is a `brand.json` field
|
||||
so that changing it stays a file copy and a restart. `check:facts` enforces this.
|
||||
- **British spelling**, in common with the rest of the organisation's prose.
|
||||
|
||||
## Branch and pull-request workflow
|
||||
|
||||
1. Branch from `main` with a descriptive name (`feature/…`, `fix/…`, `docs/…`, `chore/…`).
|
||||
2. Keep changes focused; small pull requests are easier to review.
|
||||
3. Run `npm run verify` before opening the pull request.
|
||||
4. Push and open a pull request against `main`. Fill out the template, including the **AI-assisted
|
||||
contributions** disclosure.
|
||||
5. A maintainer will review; address feedback with follow-up commits.
|
||||
|
||||
### Commit messages
|
||||
|
||||
[Conventional Commits](https://www.conventionalcommits.org/) — `type(scope): summary`, in common
|
||||
with every repository in the organisation. For example `fix(docs): correct the installer flag on the
|
||||
quickstart`.
|
||||
|
||||
### What merging does
|
||||
|
||||
Merging to `main` builds a container image, publishes it to the Gitea registry and **deploys it**
|
||||
(`.gitea/workflows/build-image.yml`). There is no separate release step and no manual promotion, so
|
||||
a merge is a publication. [`DEPLOY.md`](DEPLOY.md) describes the whole path, including how to roll
|
||||
back to a previous build.
|
||||
|
||||
## AI-assisted contributions (disclosure required)
|
||||
|
||||
This project is developed openly with AI assistance, and we ask the same transparency of everyone.
|
||||
**If you used an AI tool** (Claude, Copilot, ChatGPT, Cursor, etc.) to help produce a contribution,
|
||||
you must disclose it:
|
||||
|
||||
- Tick the AI-usage box in the pull-request template and name the tool(s).
|
||||
- Mark AI-authored commits with a trailer, e.g. `Co-Authored-By: Claude <noreply@anthropic.com>` or
|
||||
`Assisted-By: <tool>`.
|
||||
- You remain responsible for every line you submit: review it, understand it, and make sure it is
|
||||
correct and that you have the right to contribute it.
|
||||
|
||||
Disclosed AI assistance is welcome. Undisclosed AI-generated contributions are not, and may be
|
||||
closed.
|
||||
|
||||
## Licence
|
||||
|
||||
Runic Gateway is licensed under the **GNU General Public License v3.0 or later** (see
|
||||
[LICENSE](LICENSE)). By submitting a contribution you agree that it is licensed under the same terms
|
||||
(inbound = outbound) and that you have the right to contribute it.
|
||||
|
||||
[org]: https://gitea.whitlocktech.com/RunicGateway
|
||||
[issues]: https://gitea.whitlocktech.com/RunicGateway/runicgateway.com/issues
|
||||
409
DEPLOY.md
Normal file
409
DEPLOY.md
Normal file
@@ -0,0 +1,409 @@
|
||||
# Deploying runicgateway.com
|
||||
|
||||
The operator's guide. `PLAN.md` is the design of record and explains *why* the site is shaped this
|
||||
way; this file is what you follow on the host.
|
||||
|
||||
**What ships:** one container image, published to the Gitea registry, and the
|
||||
[`docker-compose.yml`](docker-compose.yml) in this repository. There is no installer and no
|
||||
`curl | bash`. The image is built and pushed by `.gitea/workflows/build-image.yml` on every merge to
|
||||
`main`, tagged `latest` and `sha-<7>`.
|
||||
|
||||
```
|
||||
gitea.whitlocktech.com/runicgateway/runicgateway-site:latest
|
||||
```
|
||||
|
||||
**What you provide:** a host with Docker, a reverse proxy that terminates TLS, and a DNS record.
|
||||
|
||||
---
|
||||
|
||||
## Contents
|
||||
|
||||
1. [What the site actually needs](#1-what-the-site-actually-needs)
|
||||
2. [First deploy](#2-first-deploy)
|
||||
3. [Putting a proxy in front of it](#3-putting-a-proxy-in-front-of-it)
|
||||
4. [DNS and TLS](#4-dns-and-tls)
|
||||
5. [Branding, without a rebuild](#5-branding-without-a-rebuild)
|
||||
6. [The closed-beta tester list](#6-the-closed-beta-tester-list)
|
||||
7. [Updating, and the automatic deploy](#7-updating-and-the-automatic-deploy)
|
||||
8. [Rolling back](#8-rolling-back)
|
||||
9. [Backups](#9-backups)
|
||||
10. [When something is wrong](#10-when-something-is-wrong)
|
||||
|
||||
---
|
||||
|
||||
## 1. What the site actually needs
|
||||
|
||||
Very little, and that is deliberate (`PLAN.md` §6).
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Runtime** | Docker, with Compose v2 (`docker compose`, not `docker-compose`) |
|
||||
| **CPU / RAM** | One core and 512 MB is comfortable. Every page but two is prerendered HTML |
|
||||
| **Disk** | ~750 MB for the image, plus a SQLite file that will not reach a megabyte |
|
||||
| **Network out** | Only to pull the image. The running site makes no outbound request of any kind |
|
||||
| **Network in** | One HTTP port, reached by your reverse proxy |
|
||||
| **Database** | None. No MariaDB, no Redis, no second service |
|
||||
| **Mail** | None. The site sends no email at all (D7) — there is nothing to configure |
|
||||
|
||||
It does **not** need the platform: no website, no sidecar, no shard. The site describes Runic
|
||||
Gateway; it does not talk to it.
|
||||
|
||||
## 2. First deploy
|
||||
|
||||
### 2.1 Create the directory
|
||||
|
||||
The compose file, the `.env` and both bind mounts live together. The automatic deploy
|
||||
([§7](#7-updating-and-the-automatic-deploy)) expects **`/opt/runicgateway.com`**; if you put it
|
||||
somewhere else, change the `cd` in `.gitea/workflows/build-image.yml`.
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/runicgateway.com
|
||||
sudo chown "$USER" /opt/runicgateway.com
|
||||
cd /opt/runicgateway.com
|
||||
```
|
||||
|
||||
Fetch the two files from this repository — the compose file, and the environment template:
|
||||
|
||||
```bash
|
||||
curl -fsSLO https://gitea.whitlocktech.com/RunicGateway/runicgateway.com/raw/branch/main/docker-compose.yml
|
||||
curl -fsSLO https://gitea.whitlocktech.com/RunicGateway/runicgateway.com/raw/branch/main/.env.example
|
||||
mv .env.example .env
|
||||
```
|
||||
|
||||
### 2.2 Create the two mounts
|
||||
|
||||
```bash
|
||||
mkdir -p brand data
|
||||
```
|
||||
|
||||
**`data/` must be writable by uid 1000**, which is what the container runs as. If you created it as
|
||||
another user:
|
||||
|
||||
```bash
|
||||
sudo chown -R 1000:1000 data
|
||||
```
|
||||
|
||||
Two failure modes this avoids, both of which look like a broken site rather than a permission
|
||||
problem:
|
||||
|
||||
- **A missing directory.** Docker creates a bind-mount source that does not exist, as `root:root`.
|
||||
The container then cannot open the store, and `/beta` renders with the form replaced by "the
|
||||
signup is temporarily unavailable" — correct behaviour, and a confusing thing to debug.
|
||||
- **`brand/` deleted later.** Same mechanism. An empty `brand/` is fine and produces exactly the
|
||||
stock site; a *missing* one gets recreated as root, and since the container only ever reads it,
|
||||
nothing breaks until the day you want to change the logo.
|
||||
|
||||
### 2.3 Fill in the two secrets
|
||||
|
||||
Open `.env`. Everything has a working default except `BETA_IP_SALT` and `BETA_FORM_KEY`, which
|
||||
default to a random value **per process** — safe, but forgotten on every restart, which means every
|
||||
rate-limit window resets and every open form goes stale.
|
||||
|
||||
```bash
|
||||
printf 'BETA_IP_SALT=%s\n' "$(openssl rand -hex 32)" >> .env
|
||||
printf 'BETA_FORM_KEY=%s\n' "$(openssl rand -hex 32)" >> .env
|
||||
```
|
||||
|
||||
(Then delete the two empty declarations the template shipped with, so the file has one of each.)
|
||||
|
||||
Do not rotate the salt casually: it is what makes the stored `ip_hash` values meaningful, so
|
||||
changing it orphans the rate-limit history of everyone already counted. The raw IP address is never
|
||||
stored — `/privacy` says so, and the salt is the mechanism that makes it true.
|
||||
|
||||
### 2.4 Log in to the registry and start
|
||||
|
||||
The image is published to the organisation's Gitea registry. If the package is not public-read, log
|
||||
in once with a token that has `read:package`:
|
||||
|
||||
```bash
|
||||
docker login gitea.whitlocktech.com
|
||||
```
|
||||
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
`ps` should show `site` as `running (healthy)` within about a minute. Health is a real HTTP request
|
||||
rather than a process check, and the delay is expected: `npm start` runs the brand rewrite before
|
||||
the server starts.
|
||||
|
||||
### 2.5 Confirm it from the host
|
||||
|
||||
```bash
|
||||
curl -sI http://127.0.0.1:4321/ | head -n 1
|
||||
curl -sI http://127.0.0.1:4321/ | grep -i content-security-policy | cut -c1-120
|
||||
```
|
||||
|
||||
The port is published on every interface by default ([§3.1](#31-forward-to-the-published-port)), so
|
||||
the same two commands work from any other machine on the network with the host's address in place of
|
||||
`127.0.0.1` — which is the quickest way to look at the site in a real browser before DNS or the
|
||||
proxy exists.
|
||||
|
||||
The second command matters more than the first. The site sends its **own** Content-Security-Policy,
|
||||
per page, built from the hashes of that page's inline scripts and styles. If it is missing, do not
|
||||
add one at the proxy — see below.
|
||||
|
||||
## 3. Putting a proxy in front of it
|
||||
|
||||
The container publishes on **port 4321 of every interface** by default and speaks plain HTTP, so it
|
||||
answers both on `http://127.0.0.1:4321` and on the host's own address — `http://<vm-ip>:4321`. Any
|
||||
reverse proxy will do; the site has no opinion about which. What it does have is four requirements,
|
||||
and the third is the one that is easy to get wrong and quiet when you do.
|
||||
|
||||
### 3.1 Forward to the published port
|
||||
|
||||
Whatever your proxy calls it: forward `runicgateway.com` (and `www.` if you want it) to
|
||||
`http://<host>:4321` — loopback if the proxy runs on this same machine, the host's address if it
|
||||
runs in another container or on another machine. There are no WebSockets, no long-polling, no
|
||||
streaming responses and no upload larger than a form field, so no timeout or buffering setting needs
|
||||
changing.
|
||||
|
||||
A proxy on a shared Docker network can address the service as `site:4321` instead and skip the host
|
||||
port entirely.
|
||||
|
||||
**Narrowing the binding.** `SITE_BIND_ADDR` in `.env` decides which addresses the port answers on,
|
||||
and nothing else in the site changes with it:
|
||||
|
||||
```bash
|
||||
SITE_BIND_ADDR=0.0.0.0 # every interface — the default
|
||||
SITE_BIND_ADDR=192.168.1.10 # one interface: the LAN, but not a public NIC
|
||||
SITE_BIND_ADDR=127.0.0.1 # loopback only: a proxy on THIS host and nothing else
|
||||
```
|
||||
|
||||
**On a host with a public address, the default means port 4321 answers from the internet directly**,
|
||||
beside whatever the proxy serves on 443 — plain HTTP, no TLS, and no proxy in the path to set
|
||||
`X-Forwarded-For` ([§3.2](#32-set-x-forwarded-for)), so signups arriving that way share one
|
||||
rate-limit bucket. There is no login and nothing to steal, so this is untidy rather than dangerous —
|
||||
but on a public host, firewall the port or narrow the binding.
|
||||
|
||||
### 3.2 Set `X-Forwarded-For`
|
||||
|
||||
**This one is load-bearing.** The beta signup rate-limits per client, and it reads the first entry of
|
||||
`X-Forwarded-For`, falling back to the connection's peer address. Behind a proxy that does not set
|
||||
the header, that peer address is *the proxy* — so every visitor on earth shares one bucket, and the
|
||||
third signup of any hour closes the form for everybody.
|
||||
|
||||
It fails toward refusing signups rather than toward accepting abuse, which is the right direction,
|
||||
but it is still a broken page. Most proxies set the header by default; confirm yours does.
|
||||
|
||||
`X-Forwarded-Proto` and `Host` are worth passing through as well, in common with any site behind a
|
||||
proxy.
|
||||
|
||||
### 3.3 Do not add security headers at the proxy
|
||||
|
||||
The container already sends `Content-Security-Policy`, `X-Content-Type-Options`, `Referrer-Policy`,
|
||||
`X-Frame-Options` and a `Permissions-Policy` (`PLAN.md` D48). That is deliberate: the image should be
|
||||
correct on its own, and a proxy somebody else configures is a promise this repository cannot check.
|
||||
|
||||
If your proxy adds its own, you get **two** of each. Browsers resolve a duplicate CSP by enforcing
|
||||
the intersection — that is, the *strictest* combination of both — and since this site's policy is a
|
||||
list of per-page hashes, a second generic policy from a proxy will forbid the page's own stylesheet
|
||||
and inline scripts. The site renders unstyled, the documentation theme switcher stops working, and
|
||||
the only symptom is a console message.
|
||||
|
||||
So: strip a global CSP for this host if your proxy adds one. The one header worth adding at the
|
||||
proxy is HSTS, which the container cannot sensibly set because it does not know whether it is behind
|
||||
TLS.
|
||||
|
||||
### 3.4 Give it a real hostname
|
||||
|
||||
Two absolute URLs are generated at build time — the sitemap and the OpenGraph `og:url` — so the site
|
||||
expects to be served at its own name rather than under a path. Serving it at `example.com/site/` will
|
||||
work visually and produce wrong metadata.
|
||||
|
||||
## 4. DNS and TLS
|
||||
|
||||
The domain is registered through **Cloudflare**, with DNS on Cloudflare (`PLAN.md` §14, N1).
|
||||
|
||||
1. In the Cloudflare dashboard, add an `A` record for `runicgateway.com` pointing at the host's
|
||||
public IP (and `AAAA` if it has a v6 address). Add `www` as a `CNAME` to the apex if you want it.
|
||||
2. Let your proxy obtain the certificate — Let's Encrypt over HTTP-01 works once the record
|
||||
resolves.
|
||||
|
||||
**If you leave Cloudflare's proxy on (the orange cloud)**, three of its features rewrite HTML and
|
||||
will break the hash-based CSP. Check them before assuming the site is at fault:
|
||||
|
||||
- **Rocket Loader** — injects a script into every page. Not covered by any hash. Turn it off.
|
||||
- **Auto Minify / HTML minification** — changes the bytes of inline `<style>` and `<script>`
|
||||
elements, so their hashes no longer match what the header declares. Turn it off.
|
||||
- **Email address obfuscation** — injects a script *and* rewrites the contact address into an
|
||||
obfuscated span. Turn it off; the address on this site is published deliberately (D13).
|
||||
|
||||
Everything else — caching, Brotli, HTTP/3, Always Use HTTPS — is fine. If you would rather not think
|
||||
about it, DNS-only (the grey cloud) works and the site loses nothing, since it uses no third-party
|
||||
resource at all.
|
||||
|
||||
## 5. Branding, without a rebuild
|
||||
|
||||
`brand/` is the override; the image's `brand-default/` is the stock. **Every file resolves against
|
||||
the mount first and the defaults second, per file**, so a directory holding only `theme.css`
|
||||
recolours the site and leaves every logo alone. `PLAN.md` §7 is the full account.
|
||||
|
||||
```
|
||||
brand/
|
||||
brand.json Site name, tagline, contact address, Discord invite, Gitea org,
|
||||
demo URL, Play opt-in URL
|
||||
logo.png ONE raster. Every size the site asks for — header at three pixel
|
||||
ratios, install icons, apple-touch, favicons, a real .ico — is
|
||||
derived from it on demand
|
||||
theme.css Redefines the custom properties in tokens.css. It wins by cascade
|
||||
layer, so it does not need to be loaded last
|
||||
```
|
||||
|
||||
```bash
|
||||
# edit or drop in a file, then:
|
||||
docker compose restart site
|
||||
```
|
||||
|
||||
The restart is what rewrites the brand text into the prerendered HTML and re-indexes search — a
|
||||
mounted site name has to reach forty-nine pages that were rendered before the file existed.
|
||||
|
||||
**One field needs no restart:** `betaOptInUrl`. `/beta` renders per request and reads it live, so the
|
||||
day the Play closed test opens, pasting the URL into `brand/brand.json` puts a working link on the
|
||||
confirmation screen on the very next request.
|
||||
|
||||
To see which source answered a given asset:
|
||||
|
||||
```bash
|
||||
curl -sI http://127.0.0.1:4321/brand/logo.png | grep -i x-brand-source
|
||||
```
|
||||
|
||||
`mount`, `default`, or `derived:mount` / `derived:default` when the size was generated on demand
|
||||
from whichever `logo.png` is in force.
|
||||
|
||||
## 6. The closed-beta tester list
|
||||
|
||||
There is no admin page, by design (`PLAN.md` §8) — the site has no authenticated surface at all. The
|
||||
list is managed from a shell against the mount.
|
||||
|
||||
```bash
|
||||
cd /opt/runicgateway.com
|
||||
|
||||
docker compose exec site node scripts/beta.mjs stats
|
||||
docker compose exec site node scripts/beta.mjs export # marks the rows exported
|
||||
docker compose exec site node scripts/beta.mjs export --all # everything, again
|
||||
docker compose exec site node scripts/beta.mjs remove someone@example.com
|
||||
```
|
||||
|
||||
`export` writes two files into `data/exports/` — a CSV record, and a `.txt` of one address per line,
|
||||
which is the format Google Play's tester list accepts. They are on the bind mount, so they are on the
|
||||
host at `./data/exports/` and can be copied off with `scp` like any other file.
|
||||
|
||||
`remove` is a deletion request, and it **overwrites** the address, the IP hash and the user agent
|
||||
rather than flagging the row. That is what `/privacy` promises; the row survives only as an anonymous
|
||||
record that a signup happened.
|
||||
|
||||
## 7. Updating, and the automatic deploy
|
||||
|
||||
Merging to `main` builds the image, pushes it, and **deploys it** (D54). No manual step, no release
|
||||
tag. What protects production is that every one of the eleven checks and both test suites have
|
||||
already run on the pull request, and the deploy job is `needs: build`, so a failed build never
|
||||
reaches the host.
|
||||
|
||||
That requires a Gitea Actions runner **on this host**, labelled `rgcom`, running jobs directly on
|
||||
the host rather than inside a container — it needs the host's Docker daemon and
|
||||
`/opt/runicgateway.com`.
|
||||
|
||||
```bash
|
||||
# On the host, once. Get the registration token from
|
||||
# Gitea → the repository → Settings → Actions → Runners → Create new runner
|
||||
act_runner register \
|
||||
--no-interactive \
|
||||
--instance https://gitea.whitlocktech.com \
|
||||
--token <REGISTRATION_TOKEN> \
|
||||
--name runicgateway-com-host \
|
||||
--labels rgcom:host
|
||||
```
|
||||
|
||||
`rgcom:host` — the `:host` suffix is what makes jobs run on the machine rather than in a job
|
||||
container. Without it the job starts in a container with no Docker socket and no
|
||||
`/opt/runicgateway.com`, and fails on the `cd`.
|
||||
|
||||
Make sure the user the runner runs as can talk to Docker (`docker ps` succeeds) and can read and
|
||||
write `/opt/runicgateway.com`.
|
||||
|
||||
**Until that runner exists, the deploy job just queues**, and nothing is harmed: the image has
|
||||
already been built and pushed by the time it would run, so the manual update below works throughout,
|
||||
and the queued job goes as soon as the runner registers.
|
||||
|
||||
**One way the automatic deploy can fail before it starts.** The registry is behind Cloudflare, which
|
||||
refuses a request body over 100 MB, and `docker push` uploads each image layer as a single request —
|
||||
so a layer that grows past that is rejected at the edge with `413 Payload Too Large`, publishing
|
||||
nothing. `needs: build` then keeps the deploy from running at all, which means the container you are
|
||||
already serving is left alone; the site is simply not updated. The workflow checks layer sizes before
|
||||
it pushes and fails with a message naming the layer, so this should announce itself rather than
|
||||
arriving as a `413`. Either way it is fixed in the `Dockerfile` (see the `COPY` block that splits
|
||||
`node_modules`) and nothing needs doing on the host.
|
||||
|
||||
**To update by hand instead** — always available, and what you do if the runner is down:
|
||||
|
||||
```bash
|
||||
cd /opt/runicgateway.com
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
The compose file has no `build:` at all, so a production host can only ever pull.
|
||||
|
||||
## 8. Rolling back
|
||||
|
||||
Every merge publishes two tags: `latest` and `sha-<7>` of the commit. To pin:
|
||||
|
||||
```bash
|
||||
cd /opt/runicgateway.com
|
||||
sed -i 's/^IMAGE_TAG=.*/IMAGE_TAG=sha-1806406/' .env
|
||||
docker compose pull && docker compose up -d
|
||||
```
|
||||
|
||||
Set it back to `latest` to resume following `main`. Note that while it is pinned, the automatic
|
||||
deploy still runs and still pulls — but Compose recreates the container on the *pinned* tag, so the
|
||||
site stays where you put it. That is the intended behaviour: a pin is a decision, and a merge should
|
||||
not quietly undo it.
|
||||
|
||||
The tags are listed under **Packages** on the organisation's Gitea page.
|
||||
|
||||
## 9. Backups
|
||||
|
||||
One file matters: `data/beta.sqlite`. The rest of the site is in the image and in git.
|
||||
|
||||
It is a live SQLite database in WAL mode, so **do not just `cp` it** — a copy taken mid-write can
|
||||
miss committed rows sitting in the `-wal` file. Either use SQLite's own backup, which is safe against
|
||||
a running writer:
|
||||
|
||||
```bash
|
||||
cd /opt/runicgateway.com
|
||||
docker compose exec site node -e "const db=require('better-sqlite3')(process.env.DATA_DIR+'/beta.sqlite');db.exec(\"VACUUM INTO '/app/data/beta-backup.sqlite'\");db.close()"
|
||||
mv data/beta-backup.sqlite /somewhere/safe/beta-$(date +%F).sqlite
|
||||
```
|
||||
|
||||
or stop the container first and copy all three files (`beta.sqlite`, `-wal`, `-shm`) together.
|
||||
|
||||
`brand/` is worth keeping too, if you have customised it — it is the one part of a running
|
||||
deployment that exists nowhere else.
|
||||
|
||||
## 10. When something is wrong
|
||||
|
||||
```bash
|
||||
cd /opt/runicgateway.com
|
||||
docker compose logs --tail 200 site
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
| Symptom | Cause worth checking first |
|
||||
|---|---|
|
||||
| Container restarts, or never becomes healthy | `data/` not writable by uid 1000 — `sudo chown -R 1000:1000 data` |
|
||||
| `/beta` says the signup is unavailable | Same. The rest of the site is unaffected, which is by design |
|
||||
| Every visitor hits the rate limit | The proxy is not setting `X-Forwarded-For` — [§3.2](#32-set-x-forwarded-for) |
|
||||
| Rate limits reset on every restart | `BETA_IP_SALT` is unset in `.env` — [§2.3](#23-fill-in-the-two-secrets) |
|
||||
| Pages render unstyled; console says `Refused to apply inline style` | A second CSP from the proxy or from Cloudflare Rocket Loader / minification — [§3.3](#33-do-not-add-security-headers-at-the-proxy), [§4](#4-dns-and-tls) |
|
||||
| A new logo or site name has not appeared | The mount needs a `docker compose restart site`, not just a file edit — [§5](#5-branding-without-a-rebuild) |
|
||||
| Search finds the old site name | Same restart; the boot rewrite re-indexes |
|
||||
| The site is stock despite files in `brand/` | Check the mount actually landed: `docker compose exec site ls /app/brand` |
|
||||
| A merge did not deploy, and the build job is red | If it failed on the layer check or on a `413`, a layer grew past Cloudflare's 100 MB request limit — [§7](#7-updating-and-the-automatic-deploy). The running container is untouched; the fix is in the Dockerfile, not on the host |
|
||||
|
||||
Everything the container writes goes to stdout, so `docker compose logs` is the whole log. The
|
||||
reverse proxy's access log is the only traffic data that exists — there are no analytics anywhere on
|
||||
the site (D9).
|
||||
132
Dockerfile
Normal file
132
Dockerfile
Normal file
@@ -0,0 +1,132 @@
|
||||
# runicgateway.com — the one container (PLAN.md §6).
|
||||
#
|
||||
# Two stages. The first has the whole toolchain and produces `dist/`; the second
|
||||
# carries the built site, the pruned runtime dependencies and nothing else.
|
||||
#
|
||||
# Debian slim rather than Alpine, deliberately. Two of the runtime dependencies
|
||||
# are native — `better-sqlite3` (the beta store, §8) and `sharp` (the brand
|
||||
# derivations, §7) — and both publish prebuilt binaries for glibc. On musl they
|
||||
# are compiled from source instead, which means a C++ toolchain, libvips headers
|
||||
# and several minutes in the image build, to save about sixty megabytes on a
|
||||
# thing that is pulled a few times a year. A third, `pagefind`, ships a platform
|
||||
# binary and is needed at RUN time, not just build time: the boot rewrite
|
||||
# re-indexes the site after the brand strings change.
|
||||
|
||||
# ---------------------------------------------------------------------------------------
|
||||
# Stage 1 — build
|
||||
# ---------------------------------------------------------------------------------------
|
||||
FROM node:22-bookworm-slim AS build
|
||||
|
||||
WORKDIR /build
|
||||
|
||||
# Dependencies first, so an edit to a page does not re-resolve the tree.
|
||||
COPY package.json package-lock.json ./
|
||||
RUN npm ci
|
||||
|
||||
# Then the source. .dockerignore keeps node_modules, dist and BOTH bind mounts out.
|
||||
COPY . .
|
||||
|
||||
# Prerenders every marketing, legal and documentation page, builds the Node
|
||||
# server entry for the two routes that run per request, and writes the per-route
|
||||
# Content-Security-Policy into dist/_headers.json (D48).
|
||||
#
|
||||
# No token and no network: everything the build reads is in this context. The
|
||||
# checks that DO need the Gitea API — facts, quickstart, reference — run in CI
|
||||
# against the pull request, which is the right place for them. An image build
|
||||
# that could fail because another repository's server was slow would be an image
|
||||
# build people learn to retry rather than read.
|
||||
RUN npm run build
|
||||
|
||||
# Drop the devDependencies from the tree the runtime stage inherits. Pruning
|
||||
# here rather than running a second `npm ci --omit=dev` below keeps the native
|
||||
# modules exactly as they were resolved and built once.
|
||||
RUN npm prune --omit=dev
|
||||
|
||||
# Set the two largest packages aside so the runtime stage can copy them as their
|
||||
# own layers. See the COPY block below for why a single node_modules layer could
|
||||
# not be pushed at all. Moving them rather than copying them twice is what keeps
|
||||
# the three layers disjoint: whatever is left in node_modules is exactly the
|
||||
# remainder, and a dependency added later lands in it automatically.
|
||||
RUN mkdir -p /split \
|
||||
&& mv node_modules/@pagefind /split/ \
|
||||
&& mv node_modules/@img /split/
|
||||
|
||||
# ---------------------------------------------------------------------------------------
|
||||
# Stage 2 — runtime
|
||||
# ---------------------------------------------------------------------------------------
|
||||
FROM node:22-bookworm-slim AS runtime
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
ENV NODE_ENV=production \
|
||||
HOST=0.0.0.0 \
|
||||
PORT=4321
|
||||
|
||||
# Both bind mounts, named here so the code's own `process.cwd()` defaults are
|
||||
# never what a container relies on. See docker-compose.yml.
|
||||
ENV BRAND_DIR=/app/brand \
|
||||
DATA_DIR=/app/data
|
||||
|
||||
# The stock brand, baked in and always complete (§7). Every /brand/* URL resolves
|
||||
# against the mount first and this second, per file.
|
||||
ENV BRAND_DEFAULT_DIR=/app/brand-default
|
||||
|
||||
# `dist/` is owned by `node` because the boot rewrite WRITES to it: applyBrand.mjs
|
||||
# rewrites the prerendered HTML from what it last applied to what the mount now
|
||||
# says, records that in dist/.brand-applied.json, and re-indexes dist/client/pagefind
|
||||
# so search finds the mounted site name. A read-only dist would make §7's promise
|
||||
# — recolour and rename by copying a file — fail at boot with a permission error.
|
||||
# node_modules arrives in THREE layers, not one, and the reason is the registry
|
||||
# rather than anything about the site.
|
||||
#
|
||||
# Gitea sits behind Cloudflare, which refuses a request body over 100 MB on every
|
||||
# plan below Enterprise, and `docker push` uploads each layer as one monolithic
|
||||
# PUT. A single `COPY node_modules` measured **108.8 MB compressed** — nine over —
|
||||
# so the first merge to `main` after phase 12 failed with `413 Payload Too Large`
|
||||
# on that one blob, from the edge, with Gitea never seeing the request. Nothing
|
||||
# was published, and `needs: build` meant nothing was deployed either.
|
||||
#
|
||||
# `@pagefind` (the search index binaries) and `@img` (sharp's libvips) are the two
|
||||
# packages that make it fat and both are needed at RUN time — the boot rewrite
|
||||
# re-indexes the site and re-derives the brand images — so the fix is where they
|
||||
# land, not whether they ship. Split, they measure 54.7 + 50.6 + 12.1 MB, the
|
||||
# largest with about 45 MB of headroom.
|
||||
#
|
||||
# That headroom is why the workflow counts layers before it pushes: this is a
|
||||
# margin, not a guarantee, and a dependency that grows past it would otherwise
|
||||
# come back as the same unreadable 413. See `.gitea/workflows/build-image.yml`.
|
||||
COPY --from=build --chown=node:node /build/node_modules ./node_modules
|
||||
COPY --from=build --chown=node:node /split/@pagefind ./node_modules/@pagefind
|
||||
COPY --from=build --chown=node:node /split/@img ./node_modules/@img
|
||||
COPY --from=build --chown=node:node /build/dist ./dist
|
||||
COPY --from=build --chown=node:node /build/brand-default ./brand-default
|
||||
COPY --from=build --chown=node:node /build/scripts ./scripts
|
||||
COPY --from=build --chown=node:node /build/package.json ./package.json
|
||||
|
||||
# `src/` is here for one reason: the tester-list CLI. §8 has no admin page by
|
||||
# design, so managing the closed beta is `docker compose exec site node
|
||||
# scripts/beta.mjs …`, and that reaches into src/lib/betaStore.mjs. Nothing
|
||||
# serving a request reads it — the pages were prerendered in stage 1.
|
||||
COPY --from=build --chown=node:node /build/src ./src
|
||||
|
||||
# Both mount points exist in the image, owned by the runtime user. An operator
|
||||
# who forgets a mount then gets a working stock site and an empty store rather
|
||||
# than a container that will not start; and `data/` being writable by uid 1000
|
||||
# BEFORE Docker creates it is what stops the store failing to open. If the host
|
||||
# directory is owned by someone else, `chown 1000:1000 ./data` on the host.
|
||||
RUN mkdir -p /app/brand /app/data && chown -R node:node /app/brand /app/data
|
||||
|
||||
USER node
|
||||
|
||||
EXPOSE 4321
|
||||
|
||||
# Cheap, and it tests the thing that actually breaks: `npm start` runs the brand
|
||||
# rewrite BEFORE the server, so a container can sit alive for a long moment with
|
||||
# nothing listening. A healthcheck that only watched the process would call that
|
||||
# healthy.
|
||||
HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
|
||||
CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT || 4321) + '/').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
|
||||
|
||||
# applyBrand.mjs, then serve.mjs. Not dist/server/entry.mjs directly — see the
|
||||
# header comment in scripts/serve.mjs for the adapter bug that wrapper exists for.
|
||||
CMD ["npm", "start"]
|
||||
911
PLAN.md
911
PLAN.md
@@ -1,8 +1,8 @@
|
||||
# runicgateway.com — design of record
|
||||
|
||||
**Status:** decisions taken by the org lead on 2026-08-19 and recorded in §5. **Phase 0 is
|
||||
complete**; Phase 1 is the next build step.
|
||||
**Date:** 2026-08-19 (revision 3)
|
||||
**Status:** phases 0–14 are built (13 and 14 as part of revision 4). **Revision 4 (2026-10-22) plans phases 13–18** —
|
||||
the second game, RunicNPC, and taking game vocabulary out of the site at large — in §16.
|
||||
**Date:** 2026-08-19 (revision 3) · 2026-10-22 (revision 4)
|
||||
**Repo:** `RunicGateway/runicgateway.com`
|
||||
**AI-assisted:** yes — drafted by Claude, per the org's AI-usage disclosure policy.
|
||||
|
||||
@@ -35,6 +35,7 @@ existing one rather than delay the beta.
|
||||
13. [Build phases](#13-build-phases)
|
||||
14. [Still needed from the org lead](#14-still-needed-from-the-org-lead)
|
||||
15. [Planned, not in scope: the demo instance](#15-planned-not-in-scope-the-demo-instance)
|
||||
16. [A second game: Rust, RunicNPC, and a vocabulary rule](#16-a-second-game-rust-runicnpc-and-a-vocabulary-rule)
|
||||
|
||||
---
|
||||
|
||||
@@ -225,7 +226,7 @@ Taken by the org lead (Colby Whitlock) on 2026-08-19. Recorded so they are not r
|
||||
| **D3** | **All ten documentation conflicts are fixed**, not just the operator-facing five. | §4. |
|
||||
| **D4** | **Real web screenshots**, captured from the local review stack, not placeholders. | §13 phase 6. Needs seeded, presentable demo content. |
|
||||
| **D5** | **Claude drafts `/privacy` and `/terms`** from what the code actually collects; the org lead reviews before ship. | §9. |
|
||||
| **D6** | **Ship the image and compose file; the org lead deploys.** DNS and TLS terminate at their existing reverse proxy. | §13 phase 9. This repo never touches the production host. |
|
||||
| **D6** | **Ship the image and compose file; the org lead deploys.** DNS and TLS terminate at their existing reverse proxy. | §13 phase 9. **Amended by D54 (2026-08-25):** a merge to `main` now builds, publishes and deploys. What D6 protected is held by `needs: build` and by every check having run on the pull request. |
|
||||
| **D7** | **The site sends no email at all.** No SMTP, no notifications, no mailbox behind the domain yet. | §8 designs the signup so it works anyway — see "The opt-in link removes the need for email". A contact address is still required; D13 supplies it. |
|
||||
| **D8** | **Understated honesty.** The site reads as finished; factual badges appear only where they save a reader wasted effort. **The Integration Kit stays marked draft until a second module is successfully built against it.** | §11, §10. A status with an exit criterion, not a mood. |
|
||||
| **D9** | **No analytics.** No tracking scripts, no third-party requests, no cookie banner. | Reverse-proxy access logs are the only traffic data. |
|
||||
@@ -236,7 +237,7 @@ Taken by the org lead (Colby Whitlock) on 2026-08-19. Recorded so they are not r
|
||||
|
||||
**Decisions after D13 are recorded where they were taken**, in the section describing the phase that
|
||||
raised them, rather than appended here — a decision is only re-litigated when its reasoning is
|
||||
somewhere other than the thing it decided. The count of record is **forty-six**:
|
||||
somewhere other than the thing it decided. The count of record is **seventy-four**:
|
||||
|
||||
| # | Where | What it settled |
|
||||
|---|---|---|
|
||||
@@ -248,6 +249,17 @@ somewhere other than the thing it decided. The count of record is **forty-six**:
|
||||
| D34–D37 | §10, "How phase 7 built the documentation journey" | One PR for all twenty pages, a self-contained install quickstart with a drift check, every admin screen walked before it was described, a thirteenth Administration page for content |
|
||||
| D38–D41 | §10, "How phase 8 built the builder and reference docs" | One PR for all twenty pages again, Reference enumerates names and checks every one of them, the docs section links to the drawn diagrams rather than importing them, `plannedSidebar` becomes a checked invariant |
|
||||
| D42–D46 | §10, "How phase 9 took the screenshots" | The full rig behind the imagery, a neutral demo brand, the captures beside the claims, a committed and checked capture pipeline, the world dressed in the plugin repo's scaffolding |
|
||||
| D47–D50 | §6, "How phase 10 polished it" | Search reaches the marketing pages, the CSP is a real response header from the container, `robots.txt` allows everything and names the sitemap, two blocks of structured data and no more |
|
||||
| D51–D53 | §6, "How phase 11 validated it" | The chrome and the head follow the brand mount while the consent sentence does not, the documentation half gets phase 10's skip-link fix, and no twelfth check |
|
||||
| D54–D57 | §6, "How phase 12 delivered it" | A merge deploys (amending D6), the proxy is documented by its requirements rather than by an example, the container trusts the forwarded headers with nothing to configure, and the operator note is its own file while the two policy files are pointers |
|
||||
| D58 | §6, "How phase 12 delivered it" | `node_modules` ships in three layers because Cloudflare refuses a request body over 100 MB, and the workflow counts layers before it pushes |
|
||||
| D59 | §6, "How phase 12 delivered it" | The container publishes on every interface (amending D55), with `SITE_BIND_ADDR` to narrow it |
|
||||
| D60–D65 | §16, "The six decisions" | Per-game sidebar groups, RunicNPC inside Rust with its own page, the RunicNPC API carried in full with a drift check, game names allowed but game vocabulary confined, a twelfth check that enforces it (amending D53), Rust screenshots last and from the rigs |
|
||||
| D66 | §16, "How phase 13 built it" | The hero and footer show the Module API only; a protocol and a bundle belong to a game |
|
||||
| D67 | §16, "One rule the phases need" | A screenshot belongs to its game: a capture tagged with a game may carry its words, beside the game's name |
|
||||
| D68–D69 | §16, "How phase 14 built it" | A game's real example on a core page is a tagged, labelled block; *Verify the whole stack* stays in Getting started, game-neutral (amending D60) |
|
||||
| D70–D71 | §16, "How phase 15 built it" | The Rust group is fifteen pages, one per admin screen where it can be; the Rust event kinds are checked against the module's own classification |
|
||||
| D72–D74 | §16, "How phase 16 built it" | The RunicNPC subgroup is eight pages with a shared profile-field reference; the API check compares signatures and every data shape's field names; the site's API page carries the current API only, with no decision numbers and no version history |
|
||||
|
||||
---
|
||||
|
||||
@@ -295,6 +307,403 @@ inside the org's existing tooling family. Node 22 LTS.
|
||||
- **No authenticated surface exists on the site at all.** The CSV export is a CLI run against the
|
||||
bind mount, not an HTTP route — see §8.
|
||||
|
||||
### How phase 10 polished it
|
||||
|
||||
Four decisions, D47–D50, taken 2026-08-25. Three of them were straightforward; the fourth turned
|
||||
into the phase's real work, because the thing that was supposed to be a configuration flag was
|
||||
broken in a dependency and broken *silently*.
|
||||
|
||||
**D47 — search reaches the marketing pages, and the marketing header gets a box.** The
|
||||
documentation had search from phase 1: Starlight builds a Pagefind index at the end of every build.
|
||||
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. `Base.astro` now marks its
|
||||
`<main>` as a Pagefind body, which puts all ten in the index the docs already query, and a
|
||||
`Search.astro` in the header opens the same index in a `<dialog>`.
|
||||
|
||||
Three things about the build are worth keeping. **Nothing is fetched until the dialog is opened** —
|
||||
Pagefind's UI bundle is 120 kB before the index and the WASM, and these pages otherwise ship almost
|
||||
no JavaScript, so the button is inert markup and the first open injects the script. **`<dialog>`
|
||||
rather than a hand-built overlay**, because the browser supplies the focus trap, the inert
|
||||
background, Escape-to-close and the top layer, and every one of those is something an accessibility
|
||||
pass would otherwise find missing. And **the index needed an explicit title**: Pagefind titles a
|
||||
result from the first `<h1>`, and these pages have editorial ones — `/app/`'s is "The app for a
|
||||
deployment you already use", `/terms/`'s is "Short, and only about what we run". Correct on the page
|
||||
under an eyebrow that names the section; unscannable as four rows in a result list, which is exactly
|
||||
what the first walk of the finished search produced. `data-pagefind-meta` now carries the page's
|
||||
short name, the one already in the nav and the browser tab.
|
||||
|
||||
**Two things about styling somebody else's widget.** Pagefind's UI takes a `resetStyles`
|
||||
option; setting it to `false` — on the reasoning that the site's own type and colour should
|
||||
show through — is wrong, because that reset is what styles Pagefind's 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 an `outset` border. The palette is bound through
|
||||
Pagefind's custom properties instead. And the match highlight needed one extra class in the
|
||||
selector: the reset declares `.pagefind-ui--reset mark { all: revert }`, same specificity as a
|
||||
plain descendant rule and injected after our stylesheet, so it won on order and put the
|
||||
user-agent yellow back on every result.
|
||||
|
||||
It also closed a note phase 2 left here. Pagefind indexes at build time, so the boot rewrite
|
||||
(§7, D15) reached the pages and not the search results: a site renamed through the mount would
|
||||
answer a search for its own name with the stock one. `applyBrand.mjs` now re-indexes after a rewrite
|
||||
— only when it actually rewrote something, so a stock deployment still pays nothing.
|
||||
|
||||
**D48 — the CSP is a real response header, sent by the container.** The alternatives were a
|
||||
`<meta http-equiv>`, which is what Astro emits by default and which silently ignores
|
||||
`frame-ancestors` — the one directive that stops the site being framed — and writing the headers
|
||||
into an operator's reverse-proxy configuration, which puts the strictest promise in §6 outside the
|
||||
artifact this repository builds and tests. Neither is good enough for a security boundary, so the
|
||||
Node adapter's `staticHeaders` is on: the build writes one policy per prerendered route into
|
||||
`dist/_headers.json` and the server sends it.
|
||||
|
||||
**Three things fought this, and each is the same shape: correct build, broken page, no error.**
|
||||
|
||||
1. **Astro does not hash `<script is:inline>`.** It hashes what it processes; an inline script is
|
||||
the author's own text, which it never parses. Starlight ships six per documentation page — the
|
||||
theme provider, the theme-picker sync, the mobile menu, the sidebar scroll restore. The first
|
||||
build with CSP enabled produced a strict, correct header and a documentation site whose theme
|
||||
switch and mobile sidebar did nothing, with the explanation only in a console. `'unsafe-inline'`
|
||||
would have fixed all six and given up the single directive CSP exists to enforce, so instead the
|
||||
hashes are enumerated in a generated `src/config/cspHashes.mjs` and `scripts/checkCsp.mjs`
|
||||
verifies, per page, that every inline block is covered by *that page's own* policy. A Starlight
|
||||
upgrade that edits one byte turns the build red; `npm run csp:hashes` re-harvests it.
|
||||
|
||||
2. **Expressive Code cannot be hashed at all.** Around 3,700 inline `style` **attributes** across
|
||||
the documentation carry every syntax colour, and CSP hashes cover `<style>` elements, never
|
||||
attributes — Astro's own documentation records Shiki as incompatible with CSP for this reason.
|
||||
The policy therefore carries `style-src-attr 'unsafe-inline'`, scoped to that directive: a style
|
||||
attribute cannot execute script, so `script-src` is untouched. The marketing pages emit none.
|
||||
|
||||
3. **`@astrojs/node` served the wrong page's policy.** Its per-request lookup is
|
||||
`headersMap.find((h) => h.pathname.includes(baselessPathname))` — a substring test taking the
|
||||
first match. `/modules/` was served the policy built for `/docs/modules/building-a-module`;
|
||||
`/architecture/` got a docs page's; and `/`, a substring of every path in the file, got whichever
|
||||
record came first, which was `/404`. Since each policy is a list of per-page hashes, the browser
|
||||
refused each page's own stylesheet: `/modules/` and `/architecture/` were rendering unstyled,
|
||||
and the homepage looked perfect only because it happened to share a hash with the 404 page.
|
||||
`scripts/serve.mjs` — a thin wrapper `npm start` now runs instead of the adapter's entry — keeps
|
||||
the same `_headers.json` and matches by equality. It is small on purpose so it can be deleted
|
||||
whole when upstream is fixed, and it is where the non-CSP security headers live too.
|
||||
|
||||
**This is why `test/headers.test.mjs` exists.** Every other check in this repository reads
|
||||
`dist/`, and every file on disk was right — the bytes on the wire were not. It starts the server
|
||||
and reads the responses, and reverting the wrapper to the substring lookup fails it.
|
||||
|
||||
**D49 — `robots.txt` allows everything and names the sitemap.** The sitemap has covered all fifty
|
||||
URLs since phase 1 (Starlight bundles `@astrojs/sitemap`) and nothing pointed at it; a crawler finds
|
||||
one either from this file or from a search console, and D9's posture extends to not having an
|
||||
account with anyone. Nothing is disallowed: there is no authenticated surface (§6), `/brand/*` is
|
||||
derived images with no text, and `/beta/` is a page a person is meant to find. The 404 is kept out
|
||||
of the *search index* instead, with `data-pagefind-ignore`, which is the right layer for it.
|
||||
|
||||
**D50 — two blocks of structured data, and no more.** `Organization` so the project's name resolves
|
||||
to an entity rather than to whichever page ranks, and `SoftwareApplication` because what the site
|
||||
describes is software someone installs. No ratings, no counts, no invented `aggregateRating` — §11's
|
||||
understated honesty applies to markup a reader never sees, and inventing a rating is what gets
|
||||
structured data ignored. Breadcrumb and `Article` markup on the forty documentation pages was
|
||||
rejected: Starlight already renders breadcrumbs a reader can see, and it would be forty more places
|
||||
for a fact to go stale. Every value is read from `brand.json` or `platform.json`, so `checkFacts.mjs`
|
||||
already guards them.
|
||||
|
||||
It is a `<script type="application/ld+json">`, which is a data block: no browser executes it and no
|
||||
CSP hash covers it. **Both `checkCsp.mjs` and `applyBrand.mjs` had to be taught that explicitly** —
|
||||
the first would have demanded a hash for text that changes whenever a fact does, and the second
|
||||
would have refused to rewrite the homepage at all, which is §7 failing on the page that matters
|
||||
most.
|
||||
|
||||
**What the walk found.** Ten marketing pages and a documentation sample, at 390, 768 and 1280 in
|
||||
real Chrome. No horizontal overflow at any width, on any page — the responsive work of phases 3 and
|
||||
4 held, including with a search button added to the header. The CSP violations above. The consent
|
||||
checkbox on `/beta` measured 17×17 against WCAG 2.2 SC 2.5.8's 24px minimum, and is now 24 — the one
|
||||
control on the site a person must hit precisely, on the page a phone is most likely to arrive at.
|
||||
And following the skip link moved the scroll but not the focus, because a `<main>` is not focusable;
|
||||
Chrome papers over that and not every browser does, so it now carries `tabindex="-1"`.
|
||||
|
||||
**`checkA11y.mjs` is the eleventh check**, and the eighth in CI. Seven structural rules over every
|
||||
built page, ours and Starlight's forty. 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. Its own first run reported every marketing page as having two `<main>`
|
||||
landmarks — this repository comments its markup heavily, and one of those comments quotes the tag it
|
||||
is explaining, so comments are stripped before anything is counted. It was then verified by breaking
|
||||
each of its rules in turn.
|
||||
|
||||
### How phase 11 validated it
|
||||
|
||||
Three decisions, D51–D53, taken 2026-08-25. The phase's list in §13 is a list of things to run, and
|
||||
running them was the easy half: `npm run verify` was green on `main` before this phase started and
|
||||
is green now. The half that mattered was the part no script does — a real browser, at three widths,
|
||||
across every page, and a signup and a brand mount walked end to end against the built server.
|
||||
|
||||
That found three things, two of which are fixed here. All three are recorded, including the one that
|
||||
was left, because a defect nobody wrote down is one the next phase re-discovers.
|
||||
|
||||
**What was run.** Fourteen steps: `astro check`, the production build, all eleven checks (sidebar,
|
||||
screens, tokens, brand, data safety, links, facts, quickstart, reference, a11y, CSP) and both test
|
||||
suites — 36 tests offline and 5 against a running server. Then, outside CI: fifty pages at 390, 768
|
||||
and 1280 in the installed Chrome; the signup's whole decision path against a scratch store; the
|
||||
export CLI including a deletion; a full brand mount, applied and restarted; and every off-site link
|
||||
the built site publishes.
|
||||
|
||||
**The browser walk came back clean on everything phase 10 had claimed.** No horizontal overflow at
|
||||
any width on any page. No CSP violation anywhere — the wrapper in `scripts/serve.mjs` holds for all
|
||||
fifty policies. No failed request, no image without an `alt`, no image that failed to decode, and no
|
||||
console error other than the 404 page's own 404. Search opens, reaches both chromes, and closes on
|
||||
Escape at both widths; the documentation theme switcher and mobile sidebar work, which is the thing
|
||||
a wrong CSP breaks first and silently; twelve tab stops on the homepage all draw a focus ring and
|
||||
follow the visual order.
|
||||
|
||||
**D51 — the chrome and the head follow the mount; the consent sentence does not.** The brand walk
|
||||
mounted a complete `brand.json` — a different site name, tagline, contact address, Discord invite,
|
||||
Gitea org, demo URL and Play opt-in URL — restarted, and asked every page whether any stock string
|
||||
survived. Forty-nine came back clean. `/beta` did not.
|
||||
|
||||
The reason is structural and was written down in `brand.mjs` before it was true: `applyBrand.mjs`
|
||||
rewrites files in `dist/client`, and `/beta` renders per request, so its HTML never exists as a file
|
||||
to rewrite. `liveBrand()` was added in phase 5 for exactly this, and `/beta` used it — for
|
||||
`betaOptInUrl`, and nothing else. Everything *around* the form came from the shared chrome, and the
|
||||
shared chrome was baked: the page's `<title>`, its `og:site_name`, `og:title` and `og:image:alt`,
|
||||
the header lockup, and the footer's Source and Discord links. On a mounted deployment the one page
|
||||
that asks a person for their address under a stated identity was the one page still stating the
|
||||
wrong one.
|
||||
|
||||
Both accessors were right for a page that renders one way. The chrome is neither, so
|
||||
`renderBrand(Astro)` picks by `Astro.isPrerendered` — the stock value where the boot rewrite will
|
||||
reach it, the mount where it will not — and `Base.astro`, `Header.astro` and `Footer.astro` call it.
|
||||
Doing it by discriminator rather than by calling `liveBrand()` everywhere matters: unconditional
|
||||
live reads would also change the forty-nine, where a build machine that happened to have a mount
|
||||
would bake mounted text into HTML the boot rewrite then has nothing to replace.
|
||||
|
||||
**`CONSENT_TEXT` is deliberately excluded.** It names the operator of the list inside a sentence a
|
||||
person agrees to, and it is stored verbatim in their row — so making it follow a mounted name would
|
||||
change the recorded text of a consent already given. It stays a constant and moves only with a
|
||||
consent-version bump, which `test/legal.test.mjs` already enforces.
|
||||
|
||||
Two strings on `/beta` are knowingly left as they are: "A Runic Gateway deployment to connect to"
|
||||
and "If you already run a Runic Gateway deployment". Both name the *platform the app connects to*
|
||||
rather than the operator of this site, which is the one thing on the page a rebrand does not change.
|
||||
|
||||
**D52 — the documentation half gets phase 10's skip-link fix.** Phase 10 found that following the
|
||||
skip link moved the viewport but not the keyboard focus, because a `<main>` is not focusable, and
|
||||
fixed it on the marketing chrome. The walk found the identical defect standing on the other forty
|
||||
pages: Starlight's skip link targets the page `<h1>`, and an `<h1>` is no more focusable than a
|
||||
`<main>`. A `PageTitle` override adds `tabindex="-1"` and suppresses the ring on an element that is
|
||||
reachable by exactly one deliberate route and is never in the tab sequence. It is Starlight's own
|
||||
implementation with one attribute added, because the override mechanism replaces a component rather
|
||||
than decorating it; the drift risk that creates is named in the file.
|
||||
|
||||
**The heading anchor links were checked and left.** Starlight's ¶ links measure 23.98×34.8 beside an
|
||||
`h2` and 19.86×28.8 beside an `h3` at 390px, under WCAG 2.2 SC 2.5.8's 24px. They are exempt under
|
||||
that criterion's *Equivalent* clause: the mobile table of contents on the same page offers a
|
||||
388×34.5 link to every one of the same anchors. Recorded rather than fixed, so the next walk does
|
||||
not re-raise it.
|
||||
|
||||
**D53 — no twelfth check.** Two of the phase's rigs were good enough to be tempting. An external
|
||||
link sweep found 73 of 74 destinations alive (the 74th, gnu.org's licence text, is unreachable from
|
||||
this network rather than gone), and a brand-mount walk would have caught D51 and would guard it. Both
|
||||
were left as throwaway scripts. A link check makes the build depend on other people's uptime, and a
|
||||
browser walk needs Chrome on the runner — CI would gain two ways to be red for reasons that are not
|
||||
about this repository. The eleven checks stand, and what the rigs found is written down here instead.
|
||||
|
||||
**What the signup walk proved.** Every branch of the decision path, each against the store rather
|
||||
than against the page it renders: an address is added and its consent text stored verbatim; the same
|
||||
address again is a duplicate and not a second row; a filled honeypot stores nothing and is
|
||||
indistinguishable from success; a malformed address and an unticked consent box are both refused on
|
||||
the server with the browser's validation disabled; an unsigned form token stores nothing; and a
|
||||
burst is stopped at `perHour` with a message that says the count is attempts rather than signups.
|
||||
The `minSeconds` gate is real enough to be worth knowing about — the first pass of the walk recorded
|
||||
four `too-fast` rows and nothing else, because a script fills a form faster than a person can.
|
||||
|
||||
The export CLI writes both files Play needs, marks the rows exported, refuses to re-export without
|
||||
`--all`, and `remove` overwrites the address, the IP hash and the user agent rather than flagging
|
||||
the row — which is what `/privacy` promises.
|
||||
|
||||
**And the mount itself.** The rewrite reached 51 files and re-indexed all 50 pages for search, so
|
||||
results agree with the pages. `/brand/*` served the mounted `theme.css` and fell back per key to the
|
||||
default `wordmark.svg`. Three path-traversal shapes were refused. The demo slot opened and twelve
|
||||
per-capability deep links pointed into the mounted demo. And an opt-in URL pasted into the mounted
|
||||
file reached the confirmation screen on the next request, with no restart — which is the one part of
|
||||
§7 that has to be true on the day the closed test opens.
|
||||
|
||||
### How phase 12 delivered it
|
||||
|
||||
The last phase, and the one that turns a repository into a deployment: a two-stage `Dockerfile`, a
|
||||
pull-only `docker-compose.yml` carrying both bind mounts, `.env.example`, the publishing workflow,
|
||||
`CONTRIBUTING.md` with the AI-disclosure requirement, the community-health files this repository was
|
||||
the only one in the organisation to lack, and `DEPLOY.md`. Four decisions, **D54–D57**, taking the
|
||||
count of record to **fifty-seven** — plus **D58**, added when the merge that shipped the phase could
|
||||
not publish its own image, and **D59**, which amends D55's loopback binding. **Fifty-nine.**
|
||||
|
||||
It also found a defect that would have made the closed beta impossible, and it is the only phase
|
||||
that could have found it. Everything before this ran the site the way a developer runs it: one
|
||||
process, plain HTTP, an origin the browser and the server agree about by construction. The site does
|
||||
not run that way. Standing a real container behind a real proxy is a different question, and it had
|
||||
a different answer.
|
||||
|
||||
#### D54 — a merge deploys, which amends D6
|
||||
|
||||
D6 said "ship the image and the compose file; the org lead deploys", and it was written before there
|
||||
was a host to deploy to. The org lead amended it on 2026-08-25: `.gitea/workflows/build-image.yml`
|
||||
builds, pushes `runicgateway-site:latest` and `:sha-<7>`, and then rolls the container over on a
|
||||
runner labelled **`rgcom`** on the site's own host, out of **`/opt/runicgateway.com`**. There is no
|
||||
release step and no promotion, so **a merge is a publication**.
|
||||
|
||||
What D6 was protecting is held by something else now. Every one of the eleven checks and both test
|
||||
suites have already run on the pull request; the deploy job is `needs: build`, so a failed build
|
||||
never reaches the host at all; and the job then waits for the container's own healthcheck rather
|
||||
than for `up -d` to return, because `npm start` runs the brand rewrite *before* the server starts and
|
||||
"running" therefore arrives well before "serving". A pinned `IMAGE_TAG` survives an automatic
|
||||
deploy — Compose recreates on the pinned tag — because a pin is a decision and a merge should not
|
||||
quietly undo it.
|
||||
|
||||
The runner registers with the label `rgcom:host`. The `:host` suffix is what makes jobs run on the
|
||||
machine rather than inside a job container; without it the deploy fails on the `cd`, having no
|
||||
Docker socket and no compose directory.
|
||||
|
||||
#### D55 — a generic proxy, documented by its requirements rather than by an example
|
||||
|
||||
The site runs on its own host, behind whatever reverse proxy the org lead puts there. So
|
||||
`DEPLOY.md` does not carry a worked Caddyfile or nginx block that would be wrong for three readers
|
||||
out of four; it states the four things the proxy must do. The container originally bound to
|
||||
`127.0.0.1` by default so that the safe configuration was the default one; **amended by D59
|
||||
(2026-08-26)** — it publishes on every interface, and which interfaces is a variable.
|
||||
|
||||
Two of the four are worth repeating here because they are silent when wrong:
|
||||
|
||||
- **`X-Forwarded-For` is load-bearing.** The signup rate-limits per client from the first entry of
|
||||
that header, falling back to the connection's peer address. Behind a proxy that does not set it,
|
||||
the 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 and still a broken page.
|
||||
- **A second Content-Security-Policy from the proxy breaks every page.** Browsers enforce the
|
||||
intersection of duplicate policies, and this site's is a list of per-page hashes, so a generic
|
||||
policy added at the proxy forbids the page's own stylesheet. The container already sends CSP,
|
||||
`X-Content-Type-Options`, `Referrer-Policy`, `X-Frame-Options` and `Permissions-Policy` (D48), so
|
||||
the proxy's job is to add none of them. The same paragraph names the three Cloudflare features
|
||||
that rewrite HTML — Rocket Loader, HTML minification and email obfuscation — because each of them
|
||||
breaks the hashes in exactly the same way, from a dashboard rather than from a config file.
|
||||
|
||||
#### D56 — the container trusts the forwarded headers, with nothing to configure
|
||||
|
||||
**The defect.** `@astrojs/node` builds the URL of every request from the connection and the `Host`
|
||||
header alone. In `astro/app/node`'s `createRequestFromNodeRequest`:
|
||||
|
||||
```js
|
||||
const isEncrypted = "encrypted" in req.socket && req.socket.encrypted;
|
||||
const protocol = isEncrypted ? "https" : "http";
|
||||
```
|
||||
|
||||
`x-forwarded-proto` is never consulted on that path — and `security.allowedDomains`, which sounds
|
||||
like the answer, is not: on this code path it gates only whether `Astro.clientAddress` may come from
|
||||
`x-forwarded-for`. Behind a proxy that terminates TLS, the browser sends `Origin:
|
||||
https://runicgateway.com` and the container computes `http://runicgateway.com`, because its own
|
||||
socket is plaintext. Astro's CSRF middleware then compares the two for equality:
|
||||
|
||||
```js
|
||||
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`** — on the one route that accepts a POST, on the site whose nearest real deadline is a
|
||||
closed test that cannot start without it. No proxy configuration fixes it; a proxy cannot make the
|
||||
container's socket encrypted. Fifty pages look perfectly healthy while the form silently refuses
|
||||
everyone.
|
||||
|
||||
`scripts/serve.mjs` already exists to wrap this adapter's mistakes (D48), so the fix went there:
|
||||
`x-forwarded-proto: https` marks the socket encrypted, and `x-forwarded-host` replaces `Host` for
|
||||
the proxies that rewrite it to the upstream address instead of passing it through.
|
||||
|
||||
**Both are trusted unconditionally, with no flag to set** — the org lead's call, and the right one.
|
||||
The image is meant to be deployed and work; an operator who has to discover a `TRUST_PROXY` variable
|
||||
to make the signup work is an operator who ships a dead form, and the broken configuration would be
|
||||
the default. It costs nothing: 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. Two assertions in `test/headers.test.mjs` hold
|
||||
both halves — a proxy-shaped POST is accepted, and a genuinely cross-origin one is still refused.
|
||||
|
||||
#### D57 — the operator note is its own file, and two policies are pointers
|
||||
|
||||
`DEPLOY.md` rather than a README section: the README is for someone working *on* the site and was
|
||||
already long, and deployment is a different task for a different sitting — it is also the file that
|
||||
gets opened on the host. It carries what the site needs, first deploy, the proxy, DNS and TLS,
|
||||
branding without a rebuild, the tester-list CLI, updating, rolling back, backups, and a symptoms
|
||||
table.
|
||||
|
||||
This repository was also the only one of the ten with no `CONTRIBUTING.md`, no
|
||||
`CODE_OF_CONDUCT.md`, no `SECURITY.md` and no issue or pull-request templates, so phase 12 added
|
||||
them. **The two policy files are pointers to the organisation's copies in `docs`, not copies** —
|
||||
because a copy would hard-code the contact address in a tenth place, and D13's whole promise is that
|
||||
the address lives only in `brand.json` and moves for the cost of a file copy. `checkFacts.mjs` scans
|
||||
`src/` and `scripts/`; these files honour the same rule voluntarily, and say so, so that the next
|
||||
person does not "fix" the missing address.
|
||||
|
||||
`SECURITY.md` is not only a pointer, though. It names what is actually worth reporting *here* —
|
||||
the signup's store, rate limit and signed form token; path traversal out of the branding mount; and
|
||||
a page served no policy or another page's — and states plainly that there is no authenticated
|
||||
surface to attack.
|
||||
|
||||
**No twelfth check.** D53 was re-tested against this phase's new drift risk — the environment
|
||||
variables the code reads, `.env.example` declares and the README tabulates — and the org lead held
|
||||
the line. Eleven checks stand.
|
||||
|
||||
#### D58 — the image ships in three layers, because of the registry rather than the site
|
||||
|
||||
The merge that landed phase 12 could not publish the image it had just built. `docker push` answered
|
||||
**`413 Payload Too Large`** on one blob and stopped; nothing reached the registry, and `needs: build`
|
||||
meant nothing reached the host either. The site was merged and undeployed, and the log said only that
|
||||
a digest was too large.
|
||||
|
||||
**The limit is Cloudflare's, not Gitea's.** `gitea.whitlocktech.com` is proxied, and Cloudflare
|
||||
refuses a request body over **100 MB** on every plan below Enterprise — a plan limit, not a setting.
|
||||
`docker push` uploads each layer as a single monolithic `PUT`, so the ceiling applies per layer, and
|
||||
the rejection happens at the edge with Gitea never seeing the request. It is invisible from the
|
||||
Gitea side and unfixable from it.
|
||||
|
||||
Measured on the merge commit, one layer was over and only just: **`COPY node_modules` at 108.8 MB
|
||||
compressed**, against a 188.6 MB image whose next largest layer was the 47.6 MB Node base. Two
|
||||
packages account for it, `@pagefind` (the search binaries) and `@img` (sharp's libvips), and both are
|
||||
needed at **run** time — the boot rewrite re-indexes the site and re-derives the brand images — so
|
||||
what could move was where they land, not whether they ship.
|
||||
|
||||
The build stage now moves those two aside after `npm prune`, and the runtime stage copies them as
|
||||
their own layers: **46.8 + 50.5 + 11.5 MB** in place of 108.8, largest layer 50.5, and the image
|
||||
**exactly the same total size**, because the same bytes are simply divided differently. Moving rather
|
||||
than copying twice is what keeps the three disjoint — whatever remains in `node_modules` is the
|
||||
remainder by construction, so a dependency added later needs no maintenance here.
|
||||
|
||||
**The workflow now counts layers before it pushes**, because a split is a margin and not a
|
||||
guarantee: `docker save`, re-compress anything over 8 MB the way the push would, and fail at **90 MB**
|
||||
— not 100, since the blob is not the only thing in the request — naming the layer and what would
|
||||
have happened. It was tested in both directions, against the fixed image and the broken one, and the
|
||||
number it reports for the broken layer (108 MB) agrees with what the registry recorded.
|
||||
|
||||
This is a workflow step and not a twelfth check script: it needs a built image rather than a source
|
||||
tree, which is the one thing the eleven never have. D53 holds.
|
||||
|
||||
#### D59 — the container publishes on every interface, which amends D55
|
||||
|
||||
D55 bound the published port to `127.0.0.1`, reasoning that TLS terminates at a proxy on the same
|
||||
host and nothing else has business reaching the container. That is the right default for the host
|
||||
this eventually runs on, and the wrong one for every step before it: a loopback binding cannot be
|
||||
opened from a browser on another machine, which is exactly what an operator wants to do first —
|
||||
look at the thing on the VM's own address, before DNS exists, before the proxy exists, from a
|
||||
desktop or a phone that is not the VM.
|
||||
|
||||
The org lead settled it on 2026-08-26: **publish on all interfaces**, the way a normal bridge
|
||||
publish behaves. `docker-compose.yml` now reads
|
||||
`"${SITE_BIND_ADDR:-0.0.0.0}:${SITE_HOST_PORT:-4321}:4321"`, so the site answers on
|
||||
`http://<vm-ip>:4321` out of the box.
|
||||
|
||||
**Which addresses it answers on is a variable, not an edit.** `SITE_BIND_ADDR` in `.env` narrows it
|
||||
to one interface or back to loopback without touching a file that `docker compose pull` replaces,
|
||||
which also removes the "change the port line" instruction D55 had to give proxies running in another
|
||||
container or on another machine.
|
||||
|
||||
What is honestly given up: on a host with a public address, port 4321 answers from the internet
|
||||
directly — plain HTTP beside the proxy's 443, and with no proxy in the path to set `X-Forwarded-For`,
|
||||
so signups arriving that way share one rate-limit bucket. The site has no login and no secret behind
|
||||
it, so this is untidy rather than dangerous, and `DEPLOY.md` §3.1 says so and gives both remedies
|
||||
(firewall the port, or narrow the binding).
|
||||
|
||||
---
|
||||
|
||||
## 7. Branding is bind-mounted data
|
||||
@@ -549,7 +958,8 @@ that omitted sideloading would read, to somebody who knows the APK exists, as a
|
||||
rewrites files in `dist/client`; an on-demand route's HTML never was a file, so `/beta` reading
|
||||
`brand` would show stock values forever. It reads the mounted `brand.json` itself, guarded by an
|
||||
mtime check. That is strictly better where it applies — pasting the opt-in URL into the mount
|
||||
takes effect on the **next request**, with no restart.
|
||||
takes effect on the **next request**, with no restart. *Phase 11 found it had been applied to one
|
||||
field and not to the chrome around it, and added `renderBrand()` — see D51.*
|
||||
- **`checkLinks.mjs` learned what an on-demand route is.** `/beta` is the first on-demand *page*,
|
||||
and rule 1 resolves links against the build, where it has no file. The fix is not a
|
||||
`PLANNED_ROUTES` entry — that list's reverse check fires when a route has been *built*, and an
|
||||
@@ -1204,11 +1614,12 @@ a mechanism rather than diligence:
|
||||
|
||||
| Fact | Authority |
|
||||
|---|---|
|
||||
| Protocol version | `link` `main:sidecar/src/main.rs` → `PROTOCOL_VERSION` |
|
||||
| Overlay protocol | `servuo-plugins` `main:overlay.toml` → `protocol` |
|
||||
| Protocol version, per game | the game's sidecar repo (`link`, `Rust-Link`) `main:sidecar/src/main.rs` → `PROTOCOL_VERSION` |
|
||||
| Plugin protocol, per game | the game's plugin repo (`servuo-plugins`, `Rust-Plugins`) `main:overlay.toml` → `protocol` |
|
||||
| Module API | `website` `main:server/src/modules/version.js` → `MODULE_API_VERSION` |
|
||||
| Module capability list | `Module-uo` `main:module.json` → `capabilities` (added in phase 3) |
|
||||
| Bundle + component pins | `installer` branch `bundles`, **root** `current.json` |
|
||||
| Module capabilities + `coreApi`, per game | `Module-uo` / `Module-Rust` `main:module.json` (capabilities added in phase 3, both games and `coreApi` in phase 13) |
|
||||
| Bundle + component pins, per game | `installer` branch `bundles`, **`v2/servuo/current.json`** and **`v2/rust/current.json`** (phase 13; the root `current.json` is the frozen schema-1 manifest) |
|
||||
| RunicNPC API, floors, required plugins | `runicnpc-rust` `main:plugin.toml`, and the Rust bundle's `npc` block (phase 13) |
|
||||
| Release versions | Gitea releases API per repo |
|
||||
|
||||
Same mechanism and the same intent as the Integration Kit's `checkCoreApi.js`: when the platform
|
||||
@@ -1219,6 +1630,17 @@ a mechanism rather than diligence:
|
||||
replaceable by a file copy, and that promise survives exactly as long as nobody types the address
|
||||
into a paragraph. Same argument as `checkTokens.mjs` and colour literals — the check is the
|
||||
mechanism, diligence is not.
|
||||
|
||||
**All three network checks read a file through Gitea's `contents` endpoint, never `raw`** —
|
||||
`checkFacts.mjs`, `checkQuickstart.mjs`, `checkReference.mjs`. Phase 12b found the reason.
|
||||
`raw` answers with `Cache-Control: public, max-age=21600`, so the CDN in front of Gitea keeps
|
||||
a copy for six hours: on cutover day this check read `website`'s `version.js` from a fortnight
|
||||
earlier and failed the site for saying Module API 1.9.0 when `main` said 1.6.0 — except that
|
||||
`main` said 1.9.0, and nothing anyone could edit here would have made it pass. `contents`
|
||||
answers `private, must-revalidate` and is not cached, at the cost of a base64 decode. Same
|
||||
argument as `checkLinks.mjs` fetching nothing: a check that goes red on someone else's
|
||||
infrastructure is a check people learn to ignore, and one that goes red on a stale copy is
|
||||
worse — it is indistinguishable from the failure it exists to report.
|
||||
- **`scripts/checkLinks.mjs`** — every internal link resolves; every outbound link into a
|
||||
`RunicGateway` repo points at a branch path, not a commit permalink. **Built in phase 4** (D23),
|
||||
and it reads `dist/client` rather than `src/`: half the links these pages carry are assembled from
|
||||
@@ -1251,6 +1673,10 @@ a mechanism rather than diligence:
|
||||
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.
|
||||
- **`scripts/checkTokens.mjs`** — no colour literal outside the token file (§7).
|
||||
- **`scripts/checkTerms.mjs`** — added in phase 14 for D63 and D64, the twelfth check. No game's
|
||||
vocabulary outside that game's section: its docs group, its sidebar group, or a
|
||||
`<GameExample>` block (D68). Reads the docs and both sidebar trees; phase 17 widens it to all of
|
||||
`src/`.
|
||||
- `astro check` plus a production build, in CI on every PR.
|
||||
|
||||
---
|
||||
@@ -1269,13 +1695,35 @@ a mechanism rather than diligence:
|
||||
| **7** | Docs — the journey: Getting started (7) + Administration (**13**, per D37) — twenty pages in one PR (D34), with the install page self-contained and drift-checked (D35) and every admin screen walked before it was described (D36). **The installation path is the priority of the whole project** |
|
||||
| **8** | Docs — builder and reference: Modules (8) + Architecture (5) + Reference (7) — twenty pages in one PR (D38), with Reference enumerating names and **checking every one of them** against its source (D39), and `plannedSidebar` becoming a checked invariant (D41) |
|
||||
| **9** | Screenshots (D4): stand up the local review stack, seed presentable content, capture the admin panel, Teams, forums, marketplace, spawn atlas and shard console; build the screenshot components. **Plus an emulator pass against the same seeded stack** to fill `/app/`'s reserved slot (D26) |
|
||||
| **10** | Polish: responsive, accessibility, SEO/OpenGraph/sitemap/robots, full-text search, CSP headers |
|
||||
| **11** | Validation: `astro check`, production build, **all nine check scripts** (tokens, brand, links, facts, quickstart, data safety, reference, sidebar, screens), mobile layout verified in a real browser, a signup walked end to end |
|
||||
| **12** | Delivery: Dockerfile, `docker-compose.yml` with both bind mounts documented, Gitea Actions workflow publishing to the registry, README, CONTRIBUTING with the AI-disclosure requirement, and an operator note covering DNS, TLS and the reverse proxy (D6) |
|
||||
| **10** | Polish: responsive, accessibility, SEO/OpenGraph/sitemap/robots, full-text search, CSP headers. See D47–D50 — the CSP was the work, because `@astrojs/node` served every page another page's policy |
|
||||
| **11** | Validation: `astro check`, production build, **all eleven check scripts** (tokens, brand, links, facts, quickstart, data safety, reference, sidebar, screens, a11y, CSP) plus both test suites, mobile layout verified in a real browser, a signup walked end to end. See D51–D53 — the scripts were green before the phase started; the browser walk and a real brand mount are what found the three defects |
|
||||
| **12** | Delivery: two-stage Dockerfile, pull-only `docker-compose.yml` with both bind mounts, `.env.example`, the Gitea Actions workflow that publishes **and deploys** (D54), README, CONTRIBUTING, the community-health files this repo alone lacked, and `DEPLOY.md` (D55, D57). It found the one defect that only a container behind a proxy can find — see D56 |
|
||||
|
||||
Phases 5 and 6 are deliberately adjacent and early: the beta cannot start without `/privacy`, and
|
||||
the closed test is the nearest real deadline.
|
||||
|
||||
**All twelve are built, as of 2026-08-25.** The `rgcom` runner was registered on the host the next
|
||||
day, in host mode as §7 of `DEPLOY.md` requires. What is left is not a phase: point the DNS record at
|
||||
the host (§14, N1), and — when the demo VM exists (§15) and the Play track is open — put two URLs
|
||||
into the mounted `brand.json`. Neither is a code change, which was the point.
|
||||
|
||||
**One thing did need a code change.** The merge that landed phase 12 built its image and then could
|
||||
not publish it: Cloudflare rejected the largest layer with `413 Payload Too Large`, so the registry
|
||||
stayed empty and the deploy never ran. See **D58** — the layer is split, and the workflow now counts
|
||||
layers before it pushes.
|
||||
|
||||
**Revision 4 adds six more** (§16), one pull request each, with a pause for the org lead between
|
||||
them:
|
||||
|
||||
| Phase | Deliverable |
|
||||
|---|---|
|
||||
| **13** | Facts: `platform.json` per game, `checkFacts.mjs` reading the per-game bundles, the two values already red on `main`, and the absences the second game resolves |
|
||||
| **14** | Vocabulary: game-neutral core docs, an **Ultima Online** docs group, redirects for every moved page, and `checkTerms.mjs` (D64) over the docs |
|
||||
| **15** | The **Rust** docs group |
|
||||
| **16** | **RunicNPC**: its docs subgroup inside Rust and the full API reference with its drift check (D62) |
|
||||
| **17** | Marketing: per-game pages, `/runicnpc/`, the homepage, `/features/`, `/modules/`, `/app/`, the architecture drawings, and `checkTerms.mjs` widened to all of `src/` |
|
||||
| **18** | Rust screenshots from the rigs (D65) |
|
||||
|
||||
---
|
||||
|
||||
## 14. Still needed from the org lead
|
||||
@@ -1283,7 +1731,9 @@ the closed test is the nearest real deadline.
|
||||
None of these block starting Phase 0 or Phase 1.
|
||||
|
||||
**N1 — Resolved.** `runicgateway.com` is registered through **Cloudflare**, with DNS on Cloudflare.
|
||||
The domain does not resolve to anything yet; the record is pointed at the host in phase 12.
|
||||
The domain does not resolve to anything yet. Phase 12 shipped everything needed to point it: the
|
||||
`A` record, the proxy requirements and the three Cloudflare features that break a hash-based CSP are
|
||||
in `DEPLOY.md` §4. Creating the record is the org lead's, on the day the host is up.
|
||||
|
||||
**N2 — Settled by D13, and no longer blocking anything.** As of 2026-08-19 no mailbox exists at the
|
||||
domain and the org lead chose not to wait for one. **`whitlocktech@gmail.com` is the published
|
||||
@@ -1381,6 +1831,439 @@ line in a bind-mounted file — no rebuild, consistent with §7.
|
||||
|
||||
---
|
||||
|
||||
## 16. A second game: Rust, RunicNPC, and a vocabulary rule
|
||||
|
||||
Revision 4, 2026-10-22. The org lead's brief, in their words: *update the site for the Rust module,
|
||||
include RunicNPC documentation, and keep terms like shard or clan — the game-specific terms — in
|
||||
that module only, not on the site at large.*
|
||||
|
||||
### What changed since the site was built
|
||||
|
||||
All values below were read on 2026-10-22 from `origin/main`, the Gitea API, and the installer's
|
||||
`bundles` branch. The site was last fact-checked on 2026-09-15.
|
||||
|
||||
| | Now | The site says |
|
||||
|---|---|---|
|
||||
| Module API | **1.17.0** (`website` `main:server/src/modules/version.js`) | 1.10.0, so `checkFacts` is **already red on `main`** |
|
||||
| Installer | **v0.8.0** | v0.2.0, also red |
|
||||
| `Module-Rust` | **v0.5.0**: id `rust`, `coreApi ^1.17.0`, capabilities `rust servers killfeed leaderboard presence wipes identity map` | nothing |
|
||||
| Rust bundle | **`v2/rust/current.json`**, bundle **2026.10.22**, protocol **14**: Rust-Link v0.3.0, Rust-Plugins v0.3.0, Oxide ≥ 2.0.7585, Carbon ≥ 2.0.259, requires Kits + ZoneManager, plus RunicNPC v1.0.0 | nothing |
|
||||
| UO bundle | **`v2/servuo/current.json`**. The root `current.json` is the schema-1 manifest, still at 2026.09.15 | read from the root |
|
||||
| RunicNPC | **v1.0.0**: an Oxide/Carbon plugin with its own API (`docs/runicnpc/API.md`), `/rnpc` commands, and standalone use without Runic Gateway | nothing |
|
||||
| Second module | **Exists and is released**. Core now *refuses* a second game module at boot | "a paper dry-run, deliberately unimplemented" |
|
||||
|
||||
Two of the §2 absences are therefore now false. **`second-module` is resolved**, and its own
|
||||
`resolvedBy` names exactly this event. **`multi-module` needs its wording changed**: it is no longer
|
||||
"nothing exercises the columns" but "core refuses to boot a second game module". The
|
||||
**Integration Kit's draft banner stays**: the kit still says it is a draft, and its condition is
|
||||
someone *outside this project* building a module from it. D8 mirrors the kit and does not
|
||||
overrule it.
|
||||
|
||||
### The vocabulary problem, measured
|
||||
|
||||
"Shard" appears **227 times in 45 files**. It is not only in the UO material: the whole
|
||||
*Getting started* path is a ServUO walkthrough (`connect-a-game-server` alone uses the word 14
|
||||
times). The homepage diagram's box reads "ServUO today", and the Reference group has a "Shard event
|
||||
catalog". The product never had this problem: core's client contains no "Shard" label at all, and
|
||||
"Admin → Shard (uo-link)" is a menu item **module-uo** registers. So the site is less accurate
|
||||
than the product here, and the fix is a correction rather than a rebrand.
|
||||
|
||||
### The six decisions
|
||||
|
||||
Taken by the org lead on 2026-10-22, each from a concrete example.
|
||||
|
||||
**D60 — per-game sidebar groups.** *Getting started* becomes game-neutral and ends in "Connect your
|
||||
game server", which sends the reader to their game. Two new groups sit after *Reference*:
|
||||
|
||||
- **Ultima Online** takes everything that is UO today: connecting a ServUO shard, the shard
|
||||
connection, client files, `Bridge.cfg`, uo-link's `sidecar.toml`, and the shard event catalog.
|
||||
- **Rust** covers installing the bridge (installer, Pterodactyl egg, by hand), connecting the site,
|
||||
linking Steam accounts, permissions and groups, mod config from the site, events, zones and
|
||||
rewards, the live map, and troubleshooting.
|
||||
|
||||
*Administration*, *Modules*, *Architecture* and *Reference* keep only core material, described in
|
||||
core's own words. Every page that moves gets a redirect from its old URL. The alternative, a
|
||||
separate sidebar per game under `/docs/uo/` and `/docs/rust/`, was not taken.
|
||||
|
||||
**D61 — RunicNPC lives inside Rust and also has its own page.** Its docs are a subgroup of the Rust
|
||||
group: overview, install (with and without Runic Gateway), the `/rnpc` commands, managing NPCs from
|
||||
the site's profile and placement screens, and the API. Marketing gets a RunicNPC card on the Rust
|
||||
module page and a short standalone `/runicnpc/` page. The plugin works on a Rust server that runs no
|
||||
Runic Gateway at all, and that server's owner should be able to find it without first learning what
|
||||
the platform is.
|
||||
|
||||
**D62 — the RunicNPC API is carried in full, with a drift check.** This is a **deliberate exception
|
||||
to §1**, which links contracts rather than copying them. The site renders every call, every hook it
|
||||
raises, and every data shape. A drift check, landing as a section of `checkReference.mjs`, reads
|
||||
`docs` `main:runicnpc/API.md` through the `contents` endpoint (§12) and fails if the two disagree: a call, a hook, or a signature that exists on one side
|
||||
only, or a signature that differs. It is two-directional like `checkQuickstart.mjs`.
|
||||
`docs/runicnpc/API.md` stays normative, and the site page says so at the top. The reason for the
|
||||
exception: the API's readers are plugin authors outside this project, and a page they can search and
|
||||
read in the site's own docs is the difference between using the plugin and not.
|
||||
|
||||
**D63 — game names yes, game vocabulary no.** Outside the game sections the site may name the games
|
||||
it supports, as product names. It may not use their vocabulary. Concretely:
|
||||
|
||||
- The homepage diagram's box reads "Game server · opens no inbound port". A **"Supported games:
|
||||
Ultima Online · Rust"** strip on the homepage, `/features/` and `/modules/` links to each game's
|
||||
page.
|
||||
- Words such as *shard, guild, clan, wipe, ServUO, uo-link, Bridge.cfg, cliloc, Oxide, Carbon,
|
||||
uMod, rust-link* appear only in the Ultima Online and Rust sections, their per-game marketing
|
||||
pages, and data files that belong to one game.
|
||||
- Core concepts keep core's names: a **Team** (never a guild or clan), a **game server** (never a
|
||||
shard), **the sidecar** and **the bridge plugin** (never uo-link or rust-link), **the game
|
||||
module** (never module-uo). Steam is not on the list: Steam sign-in is a core identity provider
|
||||
(`website` `server/src/auth/identityHooks.js`), even though Rust is its first user.
|
||||
|
||||
**D64 — a twelfth check enforces D63, amending D53.** D53 declined a twelfth check because nothing
|
||||
then needed one. This does, for the same reason `checkTokens.mjs` exists: a convention that holds
|
||||
only while everyone remembers it does not hold. `scripts/checkTerms.mjs` keeps a list of game words,
|
||||
each tagged with its game. It fails the build, naming the file, line and word, when one appears
|
||||
outside that game's allowed paths. The allowlist is short and justified line by line. Its first
|
||||
known entry is Discord's own term: the Discord bot settings really do ask for a *guild ID*, and
|
||||
that is Discord's word, not a game's. Phase 14 runs the check over the docs; phase 17 widens it to
|
||||
all of `src/` once the marketing pages have somewhere to move their game content.
|
||||
|
||||
**D65 — Rust screenshots come last, from the rigs.** D4 still holds: real captures only. Every Rust
|
||||
page is written first, without screenshot slots and never with placeholders. Phase 18 then brings the
|
||||
rigs up to date (Rust, Oxide and Carbon, as the rig rule requires before any rig work), points the
|
||||
walk site at them, and captures through `scripts/captureScreens.mjs`, the same pipeline as phase 9
|
||||
(D45). Candidates: the server list, the live map, the kill feed, the leaderboard, the permissions
|
||||
screen and the NPC profile editor.
|
||||
|
||||
### One rule the phases need, recorded so review can object
|
||||
|
||||
Adopted by the org lead on 2026-10-22 as **D67**.
|
||||
|
||||
**D67 — A screenshot belongs to its game.** Phase 9's UO captures carry the word "Shard" in the pixels and
|
||||
in their alt text. Alt text has to describe the image honestly, so a capture tagged with a game in
|
||||
`screens.mjs` may use that game's words in its caption and alt. The page showing it must name the
|
||||
game next to it. `checkTerms.mjs` reads the tag. The homepage's "What it looks like" therefore either
|
||||
shows a core screen, or shows a game screen labelled with its game. Phase 17 picks one and says which.
|
||||
|
||||
### The phases
|
||||
|
||||
Each phase is one pull request into `main`, with a pause for the org lead before the next.
|
||||
|
||||
**Phase 13 — facts.** `platform.json` grows a `games` object, with `uo` and `rust` each holding
|
||||
their bundle tag, protocol, component pins, framework minimums, module release and capability list,
|
||||
and a `runicnpc` entry holding its release. `checkFacts.mjs` reads `v2/servuo/current.json` and
|
||||
`v2/rust/current.json` instead of the root manifest. It re-reads `Module-Rust` `main:module.json`
|
||||
the same way it reads module-uo's, and checks the RunicNPC release. Module API and installer go to
|
||||
their current values, and every page quoting them is re-read (§1). `notBuilt.mjs` drops
|
||||
`second-module` and rewords `multi-module`. `capabilities.mjs`'s coverage assertion gains its Rust
|
||||
half, so a capability Module-Rust adds turns the site red the same way a UO one does. **This is the
|
||||
phase that turns `main` green again.**
|
||||
|
||||
**Phase 14 — vocabulary and the Ultima Online group.** Getting started is rewritten game-neutral,
|
||||
and its "connect" step becomes a short page that hands off to each game. The UO pages move into the
|
||||
new group, each with a redirect from its old URL. Every remaining core page is swept to core's
|
||||
words. `checkSidebar.mjs`'s `plannedSidebar` gains the new group. `checkTerms.mjs` lands, scoped to
|
||||
`src/content/docs` and `src/config/sidebar.mjs`. `checkReference.mjs`'s entries for `Bridge.cfg`,
|
||||
`sidecar.toml` and the event catalog follow their pages.
|
||||
|
||||
**Phase 15 — the Rust group.** Journey pages written from `docs/rust-link/INSTALL.md`,
|
||||
`INTEGRATION.md`, `docs/modules/rust/PLAN.md` and its redesign and fix plans, and `OPERATING.md`.
|
||||
They teach and link out (§1). The Rust reference pages (rust-link's `sidecar.toml`, the bridge
|
||||
plugin's config, and the protocol-14 event list) are enumerated and checked against their sources
|
||||
the way D39 does for UO, extending `checkReference.mjs` rather than adding a check. Every admin
|
||||
screen described is walked on the walk site first (D36).
|
||||
|
||||
**Phase 16 — RunicNPC.** The subgroup: overview, install, commands, managing NPCs from the site, and
|
||||
the API reference (D62), with its drift check. That check is the one D62 adds; the count stays at
|
||||
twelve because it lands as a section of `checkReference.mjs`, which already reads `docs` through
|
||||
`contents`.
|
||||
|
||||
**Phase 17 — marketing.** `/modules/uo/` and `/modules/rust/` carry each game's own feature list,
|
||||
written in that game's words. `/runicnpc/` is the standalone page (D61). `/modules/` gains Rust
|
||||
beside UO. `/features/`'s module-supplied group becomes "what a game module adds", linking to both.
|
||||
The homepage diagram and caption, `/architecture/`'s two drawings, `/app/` (the Android app has
|
||||
Rust screens too), `/community/`'s "there is one module" passage and the supported-games strip
|
||||
(D63) are updated. `collection.mjs` and the Play Data Safety notes are re-read against what the Rust
|
||||
module collects, Steam ids first, before anything is claimed there. `checkTerms.mjs` widens to all of
|
||||
`src/`.
|
||||
|
||||
**Phase 18 — screenshots** (D65), plus the emulator pass for `/app/`'s Rust screens. This is the only
|
||||
phase that needs the rigs.
|
||||
|
||||
### How phase 13 built it
|
||||
|
||||
One decision, **D66**, taken 2026-10-22 when the restructure reached the homepage. The count of
|
||||
record is now **sixty-six**.
|
||||
|
||||
**D66 — the hero and the footer show the Module API only.** Both used to read "Protocol 8 · Bundle
|
||||
2026.09.15", which was a description of the platform while there was one game. There are now two
|
||||
protocols and two bundles, and neither belongs on the front door. The hero and footer show **Module
|
||||
API**, the one version every deployment shares. The structured data's `softwareVersion` reads the
|
||||
same value. Each game's protocol and bundle are on that game's pages, and the docs landing page
|
||||
splits its table in two: shared versions, then one column per game. The alternative was per-game
|
||||
chips on the hero ("Ultima Online: protocol 8, bundle … · Rust: protocol 14, bundle …"). It was
|
||||
declined as busier and as putting game facts on the front door.
|
||||
|
||||
**`platform.json` is per game.** `protocol`, `bundle` and `moduleUoCapabilities` are gone. In their
|
||||
place is a `games` object (`uo` and `rust`, each with its protocol, its sidecar and plugin repos, its
|
||||
module's capabilities and `coreApi`, and its bundle pins), plus a `runicnpc` block for the plugin's
|
||||
API version, framework floors and required plugins. `releases` stays flat, so every repository's
|
||||
release is read the same way. **41 facts** are now checked, up from 19. Checks 1, 2, 4 and 5 loop
|
||||
over the games, and the bundle reads `v2/<game>/current.json` and refuses anything but schema 2.
|
||||
|
||||
**What the re-read found** (§1 obliges a re-read of every page that quotes a changed value):
|
||||
|
||||
- **Three hard-coded Module API versions in prose**, all saying 1.6.0, on *The module API* and *The
|
||||
module manifest*. §12 has forbidden that since phase 1. Nothing caught it because `checkFacts`
|
||||
guards `platform.json` and not the prose. All three now read `platform.json`. The manifest page's
|
||||
worked example of a caret range now quotes the two modules' real `coreApi` ranges, which are
|
||||
checked facts as of this phase.
|
||||
- ***Module lifecycle* said modules load alphabetically.** That stopped being the whole truth on
|
||||
2026-09-23, when the installer began refusing a second module, and stopped being true at all on
|
||||
2026-10-22, when the loader began refusing one (W19). The page now says what the loader does. *Installing
|
||||
modules* and *Managing modules* had never mentioned the one-module rule at all, and now do.
|
||||
- **"There is one module" was false in five places.** Those were the `/architecture/` seam drawing and its
|
||||
"what this does not yet prove", `/community/`, the `/features/` lede, the Game intelligence
|
||||
summary, and the homepage's list of absences. Each now says two modules exist, both built inside
|
||||
this project, and that the Integration Kit keeps its draft banner until someone outside does it.
|
||||
- **The homepage diagram's sub-labels** said "ServUO today" and "uo-link". They became false the day
|
||||
Rust shipped, so they changed here rather than waiting for phase 17. They now carry D63's wording.
|
||||
The caption names both games.
|
||||
|
||||
**One planned item moved to phase 17.** §16 put the Rust half of `capabilities.mjs`'s *page* coverage
|
||||
assertion in this phase. But a coverage assertion needs a list of Rust capabilities on a page to
|
||||
cover, and phase 17 is the phase that writes that list. Phase 13 does the half that has something to
|
||||
check: `checkFacts` now holds Module-Rust's declared capabilities against `platform.json`, so a
|
||||
capability the module adds turns this repo red today. The page-side assertion lands with the page.
|
||||
|
||||
### How phase 14 built it
|
||||
|
||||
Three decisions, taken on 2026-10-22 when the restructure reached pages D60 had not placed. The
|
||||
count of record is now **sixty-nine**. D67 is the screenshot rule above, adopted that day.
|
||||
|
||||
**D68 — a game's real example on a core page is a tagged, labelled block.** Some core pages need
|
||||
a real example rather than an invented one: *The module manifest* shows a manifest, *Scheduled
|
||||
events* names a module's budget dimensions, and the *Installer CLI* has to print
|
||||
`--game <servuo|rust>`, because that is the flag. §1 prefers the real thing, since an invented
|
||||
example is checked by nothing. So the example keeps its game's words and says whose they are:
|
||||
`src/components/GameExample.astro` prints the game's name above the block, read from
|
||||
`platform.json` so the label cannot disagree with the attribute, and `checkTerms.mjs` allows that
|
||||
game's words, and only that game's, between the tags. It is D67's bargain applied to text: a
|
||||
game's words are honest on a core page when the game is named right beside them. The
|
||||
alternatives were an invented neutral example (the Integration Kit's template could not serve: it
|
||||
mounts `/clans`) and prose only, which would have left the core pages less concrete.
|
||||
|
||||
**D69 — *Verify the whole stack* stays in Getting started, game-neutral.** This amends D60, which
|
||||
had Getting started end on the hand-off page. The core page now teaches the four links in the
|
||||
chain — the plugin loaded, the game server reached the sidecar, the sidecar is healthy, the site
|
||||
is ingesting — which are the same for both games, and sends the reader to their game for the
|
||||
commands. The Ultima Online commands became that group's *Verify the bridge*. The Ultima Online
|
||||
host requirements moved onto *Connect a ServUO shard*, and the Ultima Online rows of
|
||||
*Troubleshooting* became the group's own *Troubleshooting* page.
|
||||
|
||||
**What moved, and what stayed.** The Ultima Online group has nine pages: an overview (*The Ultima
|
||||
Online module*, which took *Install a game module*'s "what the `uo` module adds"), *Connect a
|
||||
ServUO shard*, *Verify the bridge*, *The shard connection*, *Client files*, *Troubleshooting*,
|
||||
*Bridge.cfg*, *sidecar.toml* and the *Shard event catalog*. Five pages changed URL, and each old
|
||||
URL answers with a real `301` from the server: `src/config/redirects.mjs`, asserted by
|
||||
`test/headers.test.mjs`. *Connect a game server* did **not** move. Its URL is now the
|
||||
game-neutral hand-off page (*Connect your game server*), which is a better landing for an old link
|
||||
than a redirect into one game. Until phase 15, its Rust row links to `docs`
|
||||
`main:rust-link/INSTALL.md`.
|
||||
|
||||
**The core pages use core's words** (D63): a Team, a game server, the sidecar, the bridge plugin,
|
||||
the game module. Detail that was really one game's moved into that game's pages rather than being
|
||||
dropped. *The bridge*'s guild-roster passage, for example, is now a general rule about Team rosters,
|
||||
with the Ultima Online specifics in its event catalog. Three passages were checked against Rust before they were
|
||||
generalised: both bridges dial loopback newline-delimited JSON with one writer thread, both
|
||||
sidecars answer `/health` with *plugin connected*, both plugins ship `EventsEnabled` off, and
|
||||
both modules encrypt their sidecar token with core's key. `canonicalDocs` is now grouped by
|
||||
game, and the Rust group carries four documents. Discord's *guild* became *Discord server*
|
||||
everywhere except the one label core's Discord Bot screen really prints, *Guild (server) ID*,
|
||||
which is the check's only allowlist entry, as D64 predicted.
|
||||
|
||||
**`checkTerms.mjs` is the twelfth check.** It reads every docs page, frontmatter included, and
|
||||
both sidebar trees as data. It knows 16 words, each tagged with its game. Link targets, bare URLs,
|
||||
imports and `{…}` expressions are not read, because an address is not prose and an expression
|
||||
renders a value from `src/data/`, which phase 17 brings into scope. Fenced code is read. An
|
||||
allowlist entry that stops matching fails the check, so the list cannot rot. Before it was
|
||||
trusted it was run against a planted page: five violations (a word in prose, in a title, in link
|
||||
text, in a code fence, and inside another game's block) all failed, and a URL and an expression
|
||||
carrying the same words both passed.
|
||||
|
||||
**Two findings outside this repository**, reported rather than fixed (they belong to other
|
||||
repositories):
|
||||
|
||||
- **Core's own Teams panel says "shard".** `website` `client/src/lib/teamAdmin.js` tells an
|
||||
administrator the list "is not a confirmed empty shard". The docs page now paraphrases it
|
||||
rather than quoting it.
|
||||
- **The installer's `--help` says "Which game's shard side"** for `--game`, and `--site-url` names
|
||||
"Admin → Shard (uo-link)" for both games.
|
||||
|
||||
### How phase 15 built it
|
||||
|
||||
Two decisions, taken by the org lead on 2026-10-22 before any page was written. The count of
|
||||
record is now **seventy-one**.
|
||||
|
||||
**D70 — the Rust group is fifteen pages.** D60 named the topics and not the pages. The group
|
||||
follows the Ultima Online group's shape: an overview, then the journey (*Install the bridge*,
|
||||
*Connect the site*, *Verify the bridge*), then one page per admin screen where there is one
|
||||
(*Permissions and groups*, *Mod config from the site*, *Who sees who is online*, *Events, zones
|
||||
and rewards*), then *Linking Steam accounts*, *Optional plugins*, *The live map* and
|
||||
*Troubleshooting*, and three reference pages (*sidecar.toml*, *RunicGateway.json*, *Event
|
||||
kinds*). *Who sees who is online* and *Optional plugins* got pages of their own rather than
|
||||
being folded into the overview and the events page, because each has a screen or a trap of its
|
||||
own — RaidableBases must be restarted, never reloaded. The alternative was ten longer pages. The
|
||||
question put to the org lead called this option "14 pages" while listing fifteen; the list is
|
||||
what was chosen. RunicNPC's subgroup is phase 16's.
|
||||
|
||||
**D71 — the Rust event kinds are checked against the module's classification.** The plan said the
|
||||
protocol-14 event list would be checked "against its sources". There were two candidates:
|
||||
`PROTOCOL.md`, whose kinds are spread across tables from §8.4 to §20.12, and `Module-Rust`
|
||||
`server/catalogue.js`, which holds three lists in code — public, staff, and the presence subset
|
||||
of public. The second was chosen, for D39's reason: the visibility ladder is checked against the
|
||||
module that enforces it, and so is this. The module's own test already holds its lists to
|
||||
`PROTOCOL.md`, so the chain reaches the spec without this repo parsing prose tables. The page
|
||||
shows three classes, and each is compared separately, so a kind moving from staff to public
|
||||
upstream fails here twice.
|
||||
|
||||
**`checkReference.mjs` gained three Rust sections**, as the plan said, rather than a new check:
|
||||
rust-link's `sidecar.toml` (parsed from its serde structs by the same function as uo-link's, now
|
||||
shared) and the six `RUSTLINK_…` variables that override it; the bridge plugin's
|
||||
`RunicGateway.json`, read from the public fields of `PluginConfig` in `RunicGateway.cs`; and the
|
||||
event kinds (D71). The canonical documents gained `OPERATING.md` and `CARBON.md` under Rust.
|
||||
|
||||
**Every admin screen was walked on the walk site first** (D36), signed in as the walk admin:
|
||||
Rust servers (Test, Edit, Chat titles, Optional mods), Rust permissions (a player, a group's four
|
||||
tabs), Rust mod config (the tree and `RunicGateway.json`'s read-only keys), Rust visibility, Rust
|
||||
zone presets, the event editor's action list, a user's Rust section, and the public server page's
|
||||
feed, map and leaderboard. Nothing was saved. The NPC screens are phase 16's. Writing from the
|
||||
walk and the source corrected three of my own drafts before they shipped: a reward does **not**
|
||||
need a linked account (rewards go to Steam ids), the bundle ships **three** helpers, not two, and
|
||||
the Test button prints the raw status (`protocol-mismatch`), not a phrase.
|
||||
|
||||
**What the re-read found in this repository**, fixed here:
|
||||
|
||||
- ***Verify the bridge* (Ultima Online) showed `"protocol":4`** in its `/health` sample, a
|
||||
hard-coded version four protocols stale. Both games' samples now render the protocol from
|
||||
`platform.json` through Starlight's `<Code>`, which is how a version gets into a code block
|
||||
without being typed.
|
||||
- ***Authentication* said "four tabs"** and never mentioned Steam, which core shipped with Module
|
||||
API 1.17.0. It now has five, and a *Steam* section the Rust pages link to.
|
||||
- ***Scheduled events* and *Events architecture* said the site cannot reach `EventsEnabled`.**
|
||||
True for Ultima Online, false for Rust: an administrator can edit `RunicGateway.json`, that switch
|
||||
included, from Admin → Rust mod config. Both pages now say so, the first as two tagged examples
|
||||
(D68).
|
||||
|
||||
**`checkFacts` went red mid-phase, as designed.** Installer v0.8.1 shipped on 2026-10-22 — the
|
||||
game-neutral `--help` that phase 14 reported, fixed in `installer` #43 alongside `website` #221 for
|
||||
the Teams panel — so `platform.json` moved to it. Its only change is that help text, which no page
|
||||
quotes.
|
||||
|
||||
**Findings in other repositories.** Reported in the PR, and then fixed at the org lead's ask the
|
||||
same day, each in its own repository's PR into `edge`:
|
||||
|
||||
- **`Module-Rust` admin copy showed decision numbers.** A group's *Servers* tab read "unless it is
|
||||
shared (D189)", and the *not imported yet* chip's tooltip ended "(D198)". A search of every
|
||||
non-comment line found **24** such strings an administrator reads — the event editor's step and
|
||||
budget descriptions and five NPC validation errors among them. All went in `Module-Rust` #59; the
|
||||
developer-facing swagger descriptions keep theirs.
|
||||
- **`Module-Rust`'s servers page read "Last pushed: 1 player hold one."** Also `Module-Rust` #59.
|
||||
- **`Rust-Plugins`' `PluginConfig.EventsEnabled` comment said it "gates taking a lease only"**,
|
||||
which stopped being true at protocol 9. It now lists everything the switch gates, read from every
|
||||
check in the file: `Rust-Plugins` #45.
|
||||
- **`docs` `rust-link/INTEGRATION.md` predates the installer**: it says there is no installer
|
||||
support for Rust and shows protocol-1 samples. **`rust-link/INSTALL.md`'s by-hand step names two
|
||||
helpers**; the bundle ships three. The org lead approved a separate `docs` PR for these:
|
||||
`docs` #370.
|
||||
|
||||
### How phase 16 built it
|
||||
|
||||
Three decisions, taken by the org lead on 2026-10-22 before any page was written. The count of
|
||||
record is now **seventy-four**.
|
||||
|
||||
**D72 — the RunicNPC subgroup is eight pages, one of them a shared profile-field reference.** D61
|
||||
named five topics. The subgroup sits at the end of the Rust group, nested, at
|
||||
`/docs/rust/runicnpc/`: *RunicNPC* (the overview), *Install RunicNPC*, *Commands*, *NPC profiles*,
|
||||
*NPC placements*, *Cost and caps*, *Profile fields* and *The API*. The site's two NPC screens get a
|
||||
page each, as the Rust group's screens do, and the cost warning and caps get their own page rather
|
||||
than a section of *Install*. ***Profile fields* is the one page every way of writing a profile
|
||||
links to**: the site's editor (whose sections it follows, with each field's label), `rnpc.profile
|
||||
set` (which takes the same JSON paths), the data file, and the API. So the API page shows calls,
|
||||
hooks, placements and routes, and links there for a profile's shape rather than repeating it. The
|
||||
alternatives were D61's five pages, and seven without the shared reference.
|
||||
|
||||
**D73 — the API check compares signatures and field names.** D62 named calls, hooks and
|
||||
signatures. The check also compares the field names of every data shape `API.md` gives: a
|
||||
profile's fields, `RunicNpc_List`'s keys, a placement's keys, a route's keys, and the owners. A
|
||||
field added to the profile upstream turns this site red the same way a new call does. The
|
||||
alternative, calls and hooks only, would have let the largest and most-changed shape drift
|
||||
unnoticed.
|
||||
|
||||
**D74 — the site's API page carries the current API only.** `API.md` explains itself with decision
|
||||
numbers (*D258, D269*) and plan stages, and tags each call with the API version that added it. The
|
||||
site page drops both. Decision numbers mean nothing to a plugin author outside this project — the
|
||||
reason `Module-Rust` #59 removed them from the admin screens — and the version history is
|
||||
`API.md`'s to keep. The page states the current API version, read from `platform.json`, and shows
|
||||
how to check it before calling. The alternatives were keeping the "since API n" tags, and copying
|
||||
`API.md` faithfully, decision numbers included.
|
||||
|
||||
**The drift check is two sections of `checkReference.mjs`**, so the count of checks stays at
|
||||
twelve, as the plan said:
|
||||
|
||||
- **Against `docs` `main:runicnpc/API.md`**, through the `contents` endpoint: the API version
|
||||
against `platform.json`; all 24 calls by whole signature, parsed from their headings; all 10
|
||||
hooks by signature, from their table; and the field names of the five shapes (D73). A profile
|
||||
field cell that names two fields (`hurtByPlayers`, `hurtsPlayers`), or a bare name after a dotted
|
||||
one (`phases[].damageDealt`, `aimCone`), is read the way a person reads it. And the page itself:
|
||||
every call must have exactly one `<Signature call="…" />` on `api.mdx`, so "carried in full" is
|
||||
held by the build, not by whoever last edited the page.
|
||||
- **Against `runicnpc-rust` `main:plugin/RunicNPC.cs`**: the console verbs it registers, the
|
||||
permissions it registers (and that every command's permission is one of them), the `key=`
|
||||
options `ParseOptions` accepts, and the JSON keys of its config classes. These are names on the
|
||||
*Commands* and *Cost and caps* pages, and §12 has checked every name the Reference pages write
|
||||
since phase 8. D62 did not ask for this half; it is the phase-15 precedent (the bridge plugin's
|
||||
`RunicGateway.json` is read from its source the same way) applied to the two new pages that list
|
||||
names.
|
||||
|
||||
Signatures print from `src/data/runicnpc.mjs` through `src/components/Signature.astro`, which
|
||||
renders them with Starlight's `<Code>`, so the signature a reader copies is the one the check
|
||||
compared. Descriptions live beside them as short strings, written in the site's words, and
|
||||
`src/components/Ticks.astro` renders their backticks, bold and links — never HTML. Before the check
|
||||
was trusted, six drifts were planted: a parameter added to a call, a hook renamed, a `RunicNpc_List`
|
||||
key renamed, a profile field renamed, a command verb renamed, and one call's `<Signature>` removed
|
||||
from the page. All six failed, each naming the side it broke.
|
||||
|
||||
**The sidebar check learned nested groups.** `checkSidebar.mjs` and `checkTerms.mjs` read both
|
||||
trees through `flatLabels()` in `sidebar.mjs`, which writes a nested page as `RunicNPC › Commands`.
|
||||
The plan's order, and its vocabulary, are held for a subgroup exactly as for a group.
|
||||
|
||||
**Every admin screen was walked first** (D36), signed in as the walk admin on the walk site against
|
||||
both rigs: *Rust NPC profiles* (the servers with their RunicNPC version, API and last push; the
|
||||
profile list; the faction table; the editor opened on a new profile, through every section) and
|
||||
*Rust NPC placements* (the server picker, the map with its layers, a waiting placement whose
|
||||
profile had gone, and the cost warning above the list). Nothing was saved. Two claims were then
|
||||
checked in `Module-Rust`'s server before they were written: the push tick is 30 s with a
|
||||
quarter-hourly audit (`npcSync.js`), and saving a profile asks every covered server that answers
|
||||
for its kits.
|
||||
|
||||
**What else changed.** The Rust overview's staff table links the two NPC screens to their pages,
|
||||
and its "In this group" table gains the subgroup. *Events, zones and rewards* links its *Place
|
||||
NPCs* step to the profiles page. The canonical documents gain `runicnpc/API.md`, `COMMANDS.md`,
|
||||
`INSTALL.md` and `PLAN.md` under Rust, and that page now names the API page as the one deliberate
|
||||
exception to "every page links out".
|
||||
|
||||
**Two findings outside this repository**, reported in the PR:
|
||||
|
||||
- **The Rust bundle's Oxide floor is lower than RunicNPC's — and that is intended.**
|
||||
`v2/rust/current.json` says Oxide 2.0.7585, the bridge plugin's floor, while RunicNPC's own
|
||||
`plugin.toml` says 2.0.7726. The org lead ruled on 2026-10-22 that **2.0.7585 is the original
|
||||
compatible version and stays**. It moves only when the CI staging drill reports an issue, and then
|
||||
as part of the update that fixes it. The site states each number where it belongs (the Rust
|
||||
overview quotes the bundle's, the RunicNPC pages RunicNPC's) and claims nothing about the gap.
|
||||
- **`API.md`'s profile table broke in two places.** The `boss` rows and the `loot` rows each
|
||||
followed a blank line with no header row, so Gitea rendered them as plain text full of pipes.
|
||||
The check parses them line by line and was not affected. Fixed at the org lead's ask in `docs`
|
||||
#371, which removes the two blank lines and changes nothing else.
|
||||
|
||||
---
|
||||
|
||||
[api]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md
|
||||
[system]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_SYSTEM.md
|
||||
[int]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md
|
||||
|
||||
@@ -32,6 +32,7 @@ Where the console offers free text about security practices, two things are wort
|
||||
| App info and performance | Other app data | No | No | Not collected by us. Stored on the device only. |
|
||||
| Messages | Other in-app messages | No | No | Not collected by us. Declare the relay hop in the console’s free-text security section if it asks. |
|
||||
| Messages | Other user-generated content | No | No | Not collected by us. |
|
||||
| Messages | Other in-app messages | No | No | Not collected by us. Stored on the device only. |
|
||||
| Device or other IDs | Device or other IDs | No | No | Not collected. |
|
||||
|
||||
## Each answer, and why it is the truthful one
|
||||
@@ -83,12 +84,23 @@ Push is off until you enable it. When you do, the app mints a random, unguessabl
|
||||
|
||||
**Messages → Other user-generated content.** Not collected by us.
|
||||
|
||||
Forum posts, Team activity, character and shard information, notification preferences: all of it is a live read or write against the deployment. Nothing is cached for offline use and nothing is duplicated anywhere else — the app with no signal is an app with no content, which is a limitation and also an accurate description of where the data lives.
|
||||
Forum posts, Team activity, character and shard information, notification preferences: all of it is a live read or write against the deployment. Apart from the notification snapshot described in the next entry, nothing is cached for offline use and nothing is duplicated anywhere else — the app with no signal is an app with almost no content, which is a limitation and also an accurate description of where the data lives.
|
||||
|
||||
- **Why that answer:** Content is written to the community’s own installation. We have no copy, no access and no way to obtain one.
|
||||
- **Retention:** Held by the deployment, under its operator’s policy
|
||||
- **Read from:** `PLAN.md §9 section 2`
|
||||
|
||||
### A snapshot of your notifications, so the inbox opens without a signal
|
||||
|
||||
**Messages → Other in-app messages.** Not collected by us. Stored on the device only.
|
||||
|
||||
The app keeps the most recent notifications it has already fetched — at most thirty, and only the first page — on the device, so opening the inbox shows you what you had rather than a spinner. It is a copy of what the deployment already sent you and it is refreshed from there; nothing is written here that was not read from your own account. It is scoped to the account that fetched it, so a second person signing in on the same phone is never shown the first one’s messages.
|
||||
|
||||
- **Why that answer:** The snapshot is written on the phone from data the deployment had already delivered. It is not uploaded anywhere, and no server we operate is on either end of it.
|
||||
- **Retention:** Until you sign out, or the thirty are pushed out by newer ones
|
||||
- **In detail:** Signing out deletes the snapshot outright. It lives in the app’s ordinary preference store rather than the encrypted one — sign-in tokens are the thing that store is for — which is worth stating plainly: on a device where someone has root, these are readable, and they are notification bodies rather than credentials.
|
||||
- **Read from:** `core/inbox/DataStoreInboxCache.kt, data/repository/AuthRepository.kt`
|
||||
|
||||
### No analytics, no crash reporting, no advertising
|
||||
|
||||
**Device or other IDs → Device or other IDs.** Not collected.
|
||||
@@ -116,4 +128,4 @@ Not part of the Data Safety form — that form is about the app — but a review
|
||||
- **Your browser’s user-agent string, truncated** — With the row; blanked on removal.
|
||||
- **The web server’s access log** — Short-term operational retention, then rotated away.
|
||||
|
||||
Last generated from data dated 2026-08-24. Regenerate with `npm run play:datasafety` after any change to what the app stores.
|
||||
Last generated from data dated 2026-09-01. Regenerate with `npm run play:datasafety` after any change to what the app stores.
|
||||
|
||||
108
README.md
108
README.md
@@ -11,11 +11,12 @@ closed beta: **players**, who want the app.
|
||||
platform state, the org lead's decisions, the information architecture, and the build phases. Read
|
||||
it before changing anything here.
|
||||
|
||||
**Status: phase 5 of 12 — the app and the beta.** The foundation, the branding pipeline, the
|
||||
homepage and the five marketing pages are built, and `/app/` and `/beta/` now join them: a signed
|
||||
APK beside the closed-test signup, backed by a SQLite store on a bind mount and an export CLI. Next
|
||||
are the legal pages (phase 6) and then the documentation — the installation path, which is the
|
||||
priority of the whole project — in phases 7 and 8.
|
||||
**Status: phase 12 of 12 — delivery. The site is built.** Fifty pages: ten marketing, legal and
|
||||
app pages and forty of documentation, with real screenshots of the product, full-text search, a
|
||||
per-page Content-Security-Policy, twelve checks that fail the build when the platform moves out from
|
||||
under a claim, and a closed-beta signup backed by SQLite on a bind mount. This phase is the part
|
||||
that makes it a deployment rather than a repository — the container image, the compose file, the
|
||||
publishing workflow and [`DEPLOY.md`](DEPLOY.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -31,21 +32,44 @@ npm run build # → dist/ (prerendered pages + the Node server entry)
|
||||
npm start # serve the built site
|
||||
```
|
||||
|
||||
Node 22 LTS or newer.
|
||||
Node 22 LTS or newer. Nothing else — no database, no game server, no container runtime.
|
||||
|
||||
## Running it in production
|
||||
|
||||
One container, pulled from the Gitea registry, with two bind mounts and a reverse proxy in front.
|
||||
**[`DEPLOY.md`](DEPLOY.md) is the operator's guide**: first deploy, what the proxy must and must not
|
||||
do, DNS and TLS, branding without a rebuild, managing the tester list, rolling back, and the
|
||||
symptoms table.
|
||||
|
||||
```bash
|
||||
docker compose pull && docker compose up -d
|
||||
```
|
||||
|
||||
Merging to `main` builds the image, publishes it as `runicgateway-site:latest` and `:sha-<7>`, and
|
||||
deploys it — `.gitea/workflows/build-image.yml`. There is no separate release step, so **a merge is
|
||||
a publication**.
|
||||
|
||||
## The checks, and why they are not optional
|
||||
|
||||
Two of them, both from `PLAN.md` §12. Neither is a linter; each one enforces a promise the site
|
||||
makes that would otherwise decay quietly.
|
||||
Twelve of them, from `PLAN.md` §12. None is a linter; each one enforces a promise the site makes
|
||||
that would otherwise decay quietly.
|
||||
|
||||
```bash
|
||||
npm run check:sidebar # the rendered docs tree still matches the planned one
|
||||
npm run check:terms # no game's vocabulary outside that game's section
|
||||
npm run check:screens # every screenshot has an entry, at the size declared
|
||||
npm run check:tokens # no colour literal outside the token file
|
||||
npm run check:brand # the branding pipeline's two quiet failures
|
||||
npm run check:datasafety # the Play declaration still matches /privacy
|
||||
npm run check # astro check
|
||||
npm test # the beta signup's decision path, and the policy data
|
||||
npm run build && npm run check:links # every internal link resolves (reads the build)
|
||||
npm run build # everything below reads the build
|
||||
npm run check:links # every internal link resolves
|
||||
GITEA_TOKEN=<token> npm run check:facts # every version agrees with its authority
|
||||
GITEA_TOKEN=<token> npm run check:quickstart # the install page still matches website's own files
|
||||
GITEA_TOKEN=<token> npm run check:reference # every name the Reference lists still exists
|
||||
npm run check:a11y # seven structural accessibility rules, every page
|
||||
npm run check:csp # every inline script and style is hashed in its policy
|
||||
npm run verify # all of the above, in that order
|
||||
```
|
||||
|
||||
@@ -81,6 +105,22 @@ carry are assembled from data files and template literals and a source scan sees
|
||||
also refuses a commit permalink into any org repository — those stop tracking the document they name
|
||||
without ever 404ing, which is the failure a link checker would otherwise call healthy.
|
||||
|
||||
**`checkA11y.mjs`** applies seven structural rules to every built page — one `<h1>` and no skipped
|
||||
heading level, an `alt` on every image, a label on every form control, an accessible name on every
|
||||
link and button, `<html lang>`, one `<main>` with a skip link that reaches it, and no positive
|
||||
`tabindex`. Structural on purpose: a static check cannot measure contrast on a rendered page or find
|
||||
a focus trap, and one that pretended to would be trusted for things it cannot see. It covers
|
||||
Starlight's forty pages as well as our ten, so a dependency upgrade that loses a label turns the
|
||||
build red rather than becoming a discovery.
|
||||
|
||||
**`checkCsp.mjs`** verifies that every route has a policy and that **every inline script and style is
|
||||
covered by a hash in its own page's policy**. That second rule is the one that earns its keep: Astro
|
||||
does not hash `<script is:inline>`, and Starlight ships six of them per documentation page, so the
|
||||
first build with CSP enabled had a strict, correct header and a dead theme switcher — a failure whose
|
||||
only symptom is a console message. When Starlight is upgraded and a hash stops matching,
|
||||
`npm run csp:hashes` rebuilds, re-harvests `src/config/cspHashes.mjs` and rebuilds again; read the
|
||||
diff before committing it, because that file is a list of scripts allowed to run.
|
||||
|
||||
**`npm test`** is the one check that reads none of the above. Everything else inspects built output,
|
||||
and the beta signup's logic does not appear there: a honeypot can stop working entirely and produce
|
||||
a build identical to one where it works. It covers the honeypot, the signed form token, the timing
|
||||
@@ -147,6 +187,40 @@ Regenerating the stock assets is a separate, manual step — `npm run brand:asse
|
||||
the emblem and the Cinzel outlines from the sibling checkouts in the workspace. Its output is
|
||||
committed so that CI never needs either.
|
||||
|
||||
## Security headers, and the one workaround in the server
|
||||
|
||||
`npm start` runs `scripts/applyBrand.mjs` and then `scripts/serve.mjs` — not
|
||||
`dist/server/entry.mjs` directly. `serve.mjs` is a thin wrapper around the adapter's own handler,
|
||||
and it exists for two reasons.
|
||||
|
||||
The first is a bug in `@astrojs/node`. Its `staticHeaders` option writes one Content-Security-Policy
|
||||
per prerendered route into `dist/_headers.json`, then looks the right one up per request with
|
||||
`headersMap.find((h) => h.pathname.includes(baselessPathname))` — a **substring** test taking the
|
||||
first match. So `/modules/` was served the policy built for `/docs/modules/building-a-module`,
|
||||
`/architecture/` got a docs page's, and `/`, being a substring of every path in the file, got
|
||||
whichever record came first. Because each policy is a list of per-page hashes, that is not a
|
||||
cosmetic mismatch: the browser refused the page's own stylesheet, and `/modules/` and
|
||||
`/architecture/` rendered unstyled with `Refused to apply inline style` in a console. The wrapper
|
||||
keeps the same `_headers.json` and matches by **equality**. It is deliberately small so it can be
|
||||
deleted whole once the upstream `find` is fixed; the test for that is whether `/modules/` and
|
||||
`/docs/modules/building-a-module` are served different policies.
|
||||
|
||||
The second is the handful of headers that have nothing to do with Astro: `X-Content-Type-Options`,
|
||||
`Referrer-Policy`, `X-Frame-Options` and a `Permissions-Policy` that turns off hardware this site has
|
||||
no reason to ask for. They are set in the container rather than written into an operator's
|
||||
reverse-proxy configuration, because the image should be correct on its own and a proxy somebody
|
||||
else configures is a promise this repository cannot check. The two routes that render per request —
|
||||
`/beta` and `/brand/*` — have no prerendered policy, so they get `frame-ancestors 'none'` on its own:
|
||||
the one directive a `<meta>` CSP cannot express, and therefore the one thing Astro's per-page meta
|
||||
tag leaves them missing.
|
||||
|
||||
`style-src-attr 'unsafe-inline'` is the single relaxation in the policy, and it is scoped to that
|
||||
directive. Starlight and Expressive Code write around 3,700 inline `style` attributes into the
|
||||
documentation — icon sizes, the theme select's width, and every syntax colour — which cannot be
|
||||
hashed, because CSP hashes cover `<style>` elements and never attributes. A style attribute cannot
|
||||
execute script, so this leaves `script-src`, the directive CSP exists for, untouched. The marketing
|
||||
pages emit no inline style attributes at all.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
@@ -170,12 +244,17 @@ src/
|
||||
lib/betaSignup.mjs Everything between a POST body and a row. Never throws.
|
||||
lib/tokens.mjs Reads tokens.css at build time, for the few values that leave CSS.
|
||||
config/sidebar.mjs The documentation journey, and the planned tree behind it.
|
||||
config/cspHashes.mjs GENERATED. Starlight's inline scripts, which Astro does not hash.
|
||||
brand-default/ The stock brand, baked into the image and always complete.
|
||||
scripts/ The build-time checks, plus applyBrand (boot), brand:assets (manual)
|
||||
and beta.mjs (the tester-list CLI).
|
||||
scripts/ The build-time checks, plus applyBrand and serve (boot),
|
||||
brand:assets (manual) and beta.mjs (the tester-list CLI).
|
||||
test/ node --test. The logic the other checks cannot see.
|
||||
PLAY_DATA_SAFETY.md GENERATED. The answers to Google Play's Data Safety form, from
|
||||
src/data/collection.mjs. Edit the data, run npm run play:datasafety.
|
||||
Dockerfile Two stages. Build with the toolchain, run with the pruned tree.
|
||||
docker-compose.yml Production. Pull-only, one service, both bind mounts.
|
||||
.env.example The two secrets worth setting, and every default made visible.
|
||||
DEPLOY.md The operator's guide: proxy, DNS, TLS, branding, backups.
|
||||
```
|
||||
|
||||
Two directories are bind mounts at runtime and are **not** in the repository: `brand/` overrides
|
||||
@@ -186,13 +265,18 @@ and §7.
|
||||
|
||||
Branch from `main` (`feature/…`, `fix/…`, `docs/…`, `chore/…`) and use
|
||||
[Conventional Commits](https://www.conventionalcommits.org/). Run `npm run verify` before opening a
|
||||
pull request.
|
||||
pull request. **[CONTRIBUTING.md](CONTRIBUTING.md)** has the rest, including the two rules from
|
||||
`PLAN.md` that constrain how a page may be written at all: the site never re-specifies a contract,
|
||||
and no fact is stated in prose.
|
||||
|
||||
**AI-assisted contributions must be disclosed**, per org policy: tick the box in the pull request
|
||||
template naming the tool, and mark AI-authored commits with a trailer such as
|
||||
`Co-Authored-By: Claude <noreply@anthropic.com>`. Undisclosed AI-generated contributions may be
|
||||
closed.
|
||||
|
||||
Security problems go to [SECURITY.md](SECURITY.md), never to a public issue. Everyone taking part is
|
||||
covered by the [Code of Conduct](CODE_OF_CONDUCT.md).
|
||||
|
||||
## Licence
|
||||
|
||||
GPL-3.0-or-later, in common with every repository in the organisation. See [LICENSE](LICENSE).
|
||||
|
||||
43
SECURITY.md
Normal file
43
SECURITY.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Security Policy
|
||||
|
||||
**Please do not report security vulnerabilities through public issues, pull requests or the wiki.**
|
||||
A public report tips off attackers before a fix is available.
|
||||
|
||||
Report privately, using the contact route in the organisation's security policy:
|
||||
|
||||
**[RunicGateway/docs → SECURITY.md](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/SECURITY.md)**
|
||||
|
||||
That document is the single copy for all ten repositories, and it carries the address, what to
|
||||
include in a report and what to expect back.
|
||||
|
||||
## Why this file is a pointer rather than a copy
|
||||
|
||||
Every other repository in the organisation states the reporting address inline. This one does not,
|
||||
and the reason is a decision of record rather than an oversight: **D13** (`PLAN.md` §5) confines the
|
||||
published contact address to `brand.json`, a bind-mounted file, so that changing it is a file copy
|
||||
and a container restart rather than a commit. `scripts/checkFacts.mjs` fails the build if an address
|
||||
appears anywhere in `src/` or `scripts/`, and this file honours the same rule voluntarily — a
|
||||
hard-coded address in the repository root would be one more place to forget when the address moves.
|
||||
|
||||
## What is worth reporting here
|
||||
|
||||
This site holds one thing of value and has one writing endpoint.
|
||||
|
||||
- **The closed-beta signup** (`/beta`, `PLAN.md` §8) is the only route that writes. It stores an
|
||||
email address, a consent record and a **salted hash of the IP address** — never the address
|
||||
itself. Anything that lets a caller read rows, bypass the rate limit or the total cap, forge the
|
||||
signed form token, or recover an IP from a hash is in scope and worth reporting.
|
||||
- **The branding mount** (`GET /brand/*`, §7) reads files from a directory an operator controls.
|
||||
Path traversal out of that directory, or reaching a file type outside the route's allowlist, is in
|
||||
scope.
|
||||
- **The Content-Security-Policy** is a real response header written by `scripts/serve.mjs`. A page
|
||||
that is served no policy, or another page's policy, is a defect worth reporting — that exact bug
|
||||
has happened here once already (`PLAN.md` D48).
|
||||
|
||||
The site has **no authenticated surface at all**, by design: the tester list is managed from a shell
|
||||
against the bind mount, not from an admin page. There is no session, no cookie and no login to
|
||||
attack.
|
||||
|
||||
Vulnerabilities in the **platform itself** — the website, the sidecar, the shard plugin, the
|
||||
installer or the Android app — belong in the organisation's policy linked above, not here. This
|
||||
repository only describes them.
|
||||
@@ -3,6 +3,8 @@ import { defineConfig } from 'astro/config';
|
||||
import node from '@astrojs/node';
|
||||
import starlight from '@astrojs/starlight';
|
||||
|
||||
import { inlineScriptHashes, inlineStyleHashes } from './src/config/cspHashes.mjs';
|
||||
import { docsRedirects } from './src/config/redirects.mjs';
|
||||
import { docsSidebar } from './src/config/sidebar.mjs';
|
||||
|
||||
/**
|
||||
@@ -20,13 +22,76 @@ import { docsSidebar } from './src/config/sidebar.mjs';
|
||||
export default defineConfig({
|
||||
site: 'https://runicgateway.com',
|
||||
output: 'static',
|
||||
adapter: node({ mode: 'standalone' }),
|
||||
// `staticHeaders` is what turns §6's CSP from a promise into a response header (D48).
|
||||
// Without it the policy ships as a `<meta http-equiv>`, and a meta CSP silently ignores
|
||||
// `frame-ancestors` — the one directive that stops the site being framed. With it, the
|
||||
// build writes `_headers.json` next to the server entry and the standalone server sends
|
||||
// the policy as a real header on every prerendered route, so the operator's reverse proxy
|
||||
// needs no CSP configuration at all and cannot get it wrong.
|
||||
adapter: node({ mode: 'standalone', staticHeaders: true }),
|
||||
|
||||
build: {
|
||||
// Directory-style URLs, so every link in prose can end in a slash and mean it.
|
||||
format: 'directory',
|
||||
},
|
||||
|
||||
// Pages that moved into a game's own sidebar group (PLAN.md §16, D60). See the file.
|
||||
redirects: docsRedirects,
|
||||
|
||||
|
||||
security: {
|
||||
csp: {
|
||||
directives: [
|
||||
// The whole posture in one line: nothing loads from anywhere but this origin.
|
||||
// §6 could promise this without exceptions because the fonts are self-hosted and
|
||||
// D9 rules out analytics — there is no CDN to whitelist and no beacon to allow.
|
||||
"default-src 'self'",
|
||||
// Not covered by `default-src`, and each one closes a specific door: no injected
|
||||
// `<base>` can re-point every relative URL on the page, the signup form can only
|
||||
// post to us, no plugin content at all, and the site cannot be framed. The last
|
||||
// of those is the reason `staticHeaders` is on.
|
||||
"base-uri 'self'",
|
||||
"form-action 'self'",
|
||||
"object-src 'none'",
|
||||
"frame-ancestors 'none'",
|
||||
// One `url(data:image/svg+xml)` survives bundling into the stylesheet. Data URLs
|
||||
// are a real (if small) exfiltration-free risk surface, so this is the only
|
||||
// relaxation of `default-src` on the image directive and it is scoped to images.
|
||||
"img-src 'self' data:",
|
||||
],
|
||||
scriptDirective: {
|
||||
resources: [
|
||||
"'self'",
|
||||
// Pagefind (D47) compiles its index with `WebAssembly.instantiate`, which a
|
||||
// strict `script-src` blocks outright — search silently returns nothing. This
|
||||
// permits WASM compilation *only*; it does not restore `eval`.
|
||||
"'wasm-unsafe-eval'",
|
||||
],
|
||||
// Starlight's own `is:inline` scripts, which Astro does not hash because it never
|
||||
// parses them. Generated — see src/config/cspHashes.mjs and `npm run check:csp`.
|
||||
hashes: inlineScriptHashes,
|
||||
},
|
||||
styleDirective: {
|
||||
// No `'self'` here, though `style-src` needs it and gets it: Astro's default
|
||||
// already supplies it, and naming it alongside an `attribute`-kind resource makes
|
||||
// the build warn — browsers do not fall back from `style-src-attr` to `style-src`,
|
||||
// so a `'self'` written here would apply to neither scope the author meant.
|
||||
resources: [
|
||||
// Starlight and Expressive Code write ~3,700 inline `style` attributes into the
|
||||
// documentation — icon sizing, the theme select's width, and every syntax
|
||||
// colour, which Expressive Code emits as custom properties on the element. They
|
||||
// cannot be hashed (CSP hashes cover `<style>` elements, never attributes), and
|
||||
// Astro's own docs record Shiki as incompatible with CSP for exactly this
|
||||
// reason. Scoped to `style-src-attr` deliberately: a style attribute cannot
|
||||
// execute script, so this leaves the directive CSP exists for — `script-src` —
|
||||
// untouched. The marketing pages emit zero inline style attributes.
|
||||
{ resource: "'unsafe-inline'", kind: 'attribute' },
|
||||
],
|
||||
hashes: inlineStyleHashes,
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'Runic Gateway',
|
||||
@@ -49,6 +114,9 @@ export default defineConfig({
|
||||
// Starlight builds its own head, so the docs otherwise miss the brand stylesheet,
|
||||
// the manifest and the OG card entirely. See the component.
|
||||
Head: './src/components/DocsHead.astro',
|
||||
// One attribute, for one reason: Starlight's skip link targets the `<h1>`, and an
|
||||
// `<h1>` is not focusable. See the component (phase 11).
|
||||
PageTitle: './src/components/DocsPageTitle.astro',
|
||||
},
|
||||
credits: false,
|
||||
sidebar: docsSidebar,
|
||||
|
||||
104
docker-compose.yml
Normal file
104
docker-compose.yml
Normal file
@@ -0,0 +1,104 @@
|
||||
# runicgateway.com — production.
|
||||
#
|
||||
# Pull-only, in common with the rest of the org: `image:` and no `build:`, so a
|
||||
# production host can never accidentally build. The image is published to the
|
||||
# Gitea registry by .gitea/workflows/build-image.yml on every merge to main.
|
||||
#
|
||||
# Full operator guide, including DNS, TLS and the reverse proxy: DEPLOY.md.
|
||||
#
|
||||
# docker compose pull && docker compose up -d
|
||||
#
|
||||
# One service. §6 records why there is no second one: the dynamic surface is two
|
||||
# routes, and one container is one thing to deploy, one thing to patch and one
|
||||
# log to read.
|
||||
|
||||
services:
|
||||
site:
|
||||
# IMAGE_TAG defaults to `latest`. Pin a build for a reproducible deploy or a
|
||||
# rollback — e.g. IMAGE_TAG=sha-1806406 in .env; every merge publishes both.
|
||||
image: gitea.whitlocktech.com/runicgateway/runicgateway-site:${IMAGE_TAG:-latest}
|
||||
restart: unless-stopped
|
||||
|
||||
# Secrets and tuning for the beta signup (§8). The file is optional in the
|
||||
# sense that the site starts without it — but read the note in .env.example
|
||||
# about BETA_IP_SALT and BETA_FORM_KEY before deciding to skip it: their
|
||||
# defaults are random PER PROCESS, so leaving them unset means every restart
|
||||
# forgets who has been rate-limited.
|
||||
env_file: .env
|
||||
|
||||
volumes:
|
||||
# ---------------------------------------------------------------------------
|
||||
# The branding mount (§7). Read-only: nothing in the container ever writes
|
||||
# here, and the whole point of the directory is that a human puts files in
|
||||
# it from the host.
|
||||
#
|
||||
# May be empty, partial or complete. Every file resolves against this mount
|
||||
# first and the image's brand-default/ second, PER FILE — so a directory
|
||||
# holding only theme.css recolours the site and leaves every logo stock,
|
||||
# and an empty directory produces exactly the stock site.
|
||||
#
|
||||
# Changing a file here takes a RESTART, not a rebuild: `docker compose
|
||||
# restart site` re-runs the boot rewrite, which is what puts a new site
|
||||
# name into forty-nine prerendered pages. The exception is brand.json's
|
||||
# betaOptInUrl, which /beta reads live on every request — so the closed
|
||||
# test can be opened by editing one file, with no restart at all.
|
||||
- ./brand:/app/brand:ro
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# The beta signup store (§8): beta.sqlite and exports/. Read-WRITE, and the
|
||||
# only thing this site persists.
|
||||
#
|
||||
# A bind mount rather than a named volume because the tester list has to be
|
||||
# reachable from the host — `sqlite3 ./data/beta.sqlite`, a backup by `cp`,
|
||||
# and the CSV the export CLI writes into ./data/exports/ for pasting into
|
||||
# Play. A named volume would put all three behind `docker cp`.
|
||||
#
|
||||
# The container runs as uid 1000. Docker creates a MISSING bind-mount source
|
||||
# as root:root, and the store then fails to open — so create the directory
|
||||
# yourself and, if it is owned by someone else, `chown 1000:1000 ./data`.
|
||||
# DEPLOY.md has the two commands.
|
||||
- ./data:/app/data
|
||||
|
||||
# Published on ALL interfaces by default, so the site answers on the host's
|
||||
# own address — `http://<vm-ip>:4321` — and not only on its loopback. That is
|
||||
# what makes it reachable from the rest of the network: a proxy in another
|
||||
# container or on another machine, a browser on the LAN, a phone on the same
|
||||
# wifi checking the mobile layout.
|
||||
#
|
||||
# It is deliberately a variable rather than a fixed address, because the safe
|
||||
# binding depends on where this host sits. Set SITE_BIND_ADDR in .env to
|
||||
# narrow it without touching this file:
|
||||
#
|
||||
# SITE_BIND_ADDR=127.0.0.1 loopback only — a proxy on THIS host, nothing else
|
||||
# SITE_BIND_ADDR=192.168.1.10 one interface — the LAN, but not a public NIC
|
||||
# SITE_BIND_ADDR=0.0.0.0 every interface (the default)
|
||||
#
|
||||
# On a host with a public address, `0.0.0.0` means port 4321 answers from the
|
||||
# internet directly, beside whatever the proxy serves on 443 — plain HTTP, no
|
||||
# TLS. Firewall the port, or narrow the binding. DEPLOY.md, "Putting a proxy
|
||||
# in front of it".
|
||||
ports:
|
||||
- "${SITE_BIND_ADDR:-0.0.0.0}:${SITE_HOST_PORT:-4321}:4321"
|
||||
|
||||
# Repeats the image's own HEALTHCHECK so `docker compose ps` reports it even
|
||||
# when the image is pinned to an older tag that predates it. It watches an
|
||||
# actual response rather than the process, because `npm start` runs the brand
|
||||
# rewrite before the server: there is a real window where the container is up
|
||||
# and nothing is listening.
|
||||
#
|
||||
# The command is a QUOTED flow sequence, which is not a style choice: written as a
|
||||
# block sequence, YAML reads the `: ` inside `r.ok ? 0 : 1` as a key/value separator
|
||||
# and `docker compose config` refuses the file with "healthcheck.test.3 must be a
|
||||
# string". Keep the quotes.
|
||||
healthcheck:
|
||||
test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:4321/').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
start_period: 40s
|
||||
retries: 3
|
||||
|
||||
logging:
|
||||
driver: json-file
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
1
package-lock.json
generated
1
package-lock.json
generated
@@ -15,6 +15,7 @@
|
||||
"@fontsource-variable/inter": "^5.3.0",
|
||||
"astro": "^7.2.4",
|
||||
"better-sqlite3": "^12.11.1",
|
||||
"pagefind": "^1.5.2",
|
||||
"sharp": "^0.35.3"
|
||||
},
|
||||
"devDependencies": {
|
||||
|
||||
12
package.json
12
package.json
@@ -12,7 +12,7 @@
|
||||
"dev": "astro dev",
|
||||
"build": "astro build",
|
||||
"preview": "astro preview",
|
||||
"start": "node scripts/applyBrand.mjs && node ./dist/server/entry.mjs",
|
||||
"start": "node scripts/applyBrand.mjs && node scripts/serve.mjs",
|
||||
"check": "astro check",
|
||||
"check:facts": "node scripts/checkFacts.mjs",
|
||||
"check:tokens": "node scripts/checkTokens.mjs",
|
||||
@@ -22,13 +22,18 @@
|
||||
"check:quickstart": "node scripts/checkQuickstart.mjs",
|
||||
"check:reference": "node scripts/checkReference.mjs",
|
||||
"check:sidebar": "node scripts/checkSidebar.mjs",
|
||||
"check:terms": "node scripts/checkTerms.mjs",
|
||||
"check:screens": "node scripts/checkScreens.mjs",
|
||||
"check:a11y": "node scripts/checkA11y.mjs",
|
||||
"check:csp": "node scripts/checkCsp.mjs",
|
||||
"play:datasafety": "node scripts/playDataSafety.mjs",
|
||||
"beta": "node scripts/beta.mjs",
|
||||
"test": "node --test test/beta.test.mjs test/legal.test.mjs",
|
||||
"test": "node --test test/beta.test.mjs test/legal.test.mjs test/footer.test.mjs",
|
||||
"brand:assets": "node scripts/buildBrandAssets.mjs",
|
||||
"screens:capture": "node scripts/captureScreens.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"
|
||||
"csp:hashes": "node scripts/checkCsp.mjs --reset && astro build && node scripts/checkCsp.mjs --write && astro build && node scripts/checkCsp.mjs",
|
||||
"verify": "npm run check:sidebar && npm run check:terms && npm run check:screens && npm run check:tokens && npm run check:brand && npm run check:datasafety && npm run check && npm test && npm run build && npm run check:links && npm run check:facts && npm run check:quickstart && npm run check:reference && npm run test:served && npm run check:a11y && npm run check:csp",
|
||||
"test:served": "node --test test/headers.test.mjs"
|
||||
},
|
||||
"dependencies": {
|
||||
"@astrojs/node": "^11.1.4",
|
||||
@@ -37,6 +42,7 @@
|
||||
"@fontsource-variable/inter": "^5.3.0",
|
||||
"astro": "^7.2.4",
|
||||
"better-sqlite3": "^12.11.1",
|
||||
"pagefind": "^1.5.2",
|
||||
"sharp": "^0.35.3"
|
||||
},
|
||||
"devDependencies": {
|
||||
|
||||
BIN
public/screens/admin-client-files.webp
Normal file
BIN
public/screens/admin-client-files.webp
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 114 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 53 KiB After Width: | Height: | Size: 55 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 67 KiB |
@@ -229,10 +229,71 @@ const counts = new Map(replacements.map((r) => [r.field, 0]));
|
||||
counts.set('demoDeep', 0);
|
||||
let filesTouched = 0;
|
||||
|
||||
/**
|
||||
* The CSP (§6, D48) hashes every inline `<script>` and `<style>` in the build. This script
|
||||
* runs after that hashing and rewrites the same files, so a brand value that happened to
|
||||
* sit inside an inline block would change its bytes, invalidate its hash and get the block
|
||||
* refused by the browser — with no error anywhere except a console nobody has open. The
|
||||
* page would render perfectly and the script simply would not run.
|
||||
*
|
||||
* Nothing puts brand text in an inline script today, and the replacements are guarded by
|
||||
* MIN_REWRITABLE_LENGTH so they are unlikely to collide by accident. "Unlikely" is not the
|
||||
* standard for a failure this quiet, so the collision is checked rather than reasoned
|
||||
* about: if a rewrite ever lands inside an inline block, this refuses to write that file
|
||||
* and says so, and the page keeps its stock text instead of losing its behaviour.
|
||||
*/
|
||||
const INLINE_BLOCK = /<(script|style)(?![^>]*\bsrc\s*=)([^>]*)>([\s\S]*?)<\/\1>/g;
|
||||
|
||||
/**
|
||||
* The structured-data block (D50) is a `<script>` that no browser executes and no CSP hash
|
||||
* covers, so it is not one of the blocks this guard protects — and it MUST NOT be, because
|
||||
* it contains the site's name. Treating it as a script would make the guard refuse to
|
||||
* rewrite the homepage, which is §7 failing on the one page that matters most.
|
||||
*/
|
||||
const DATA_BLOCK = /type\s*=\s*["']application\/(ld\+json|json)["']/i;
|
||||
|
||||
const inlineRanges = (html) => {
|
||||
const ranges = [];
|
||||
INLINE_BLOCK.lastIndex = 0;
|
||||
let match;
|
||||
while ((match = INLINE_BLOCK.exec(html))) {
|
||||
if (match[1] === 'script' && DATA_BLOCK.test(match[2])) continue;
|
||||
// Where the block's CONTENT starts — measured back from the end of the whole match, so
|
||||
// the opening tag's attributes cannot throw the offset off: `</script>` is the tag name
|
||||
// plus three characters.
|
||||
const closing = match[1].length + 3;
|
||||
const start = match.index + match[0].length - closing - match[3].length;
|
||||
ranges.push([start, start + match[3].length]);
|
||||
}
|
||||
return ranges;
|
||||
};
|
||||
const hitsInlineBlock = (html, needle) => {
|
||||
if (!needle || !html.includes(needle)) return false;
|
||||
const ranges = inlineRanges(html);
|
||||
if (ranges.length === 0) return false;
|
||||
for (let at = html.indexOf(needle); at !== -1; at = html.indexOf(needle, at + 1)) {
|
||||
const end = at + needle.length;
|
||||
if (ranges.some(([from, to]) => at < to && end > from)) return true;
|
||||
}
|
||||
return false;
|
||||
};
|
||||
const inlineCollisions = [];
|
||||
|
||||
for (const file of walk(CLIENT)) {
|
||||
const before = readFileSync(file, 'utf8');
|
||||
let after = before;
|
||||
|
||||
if (path.extname(file) === '.html') {
|
||||
const colliding = replacements.filter(({ from }) => hitsInlineBlock(before, from));
|
||||
if (colliding.length) {
|
||||
inlineCollisions.push({
|
||||
file: path.relative(CLIENT, file),
|
||||
fields: [...new Set(colliding.map((c) => c.field))],
|
||||
});
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
for (const { field, from, to } of replacements) {
|
||||
if (!after.includes(from)) continue;
|
||||
counts.set(field, counts.get(field) + after.split(from).length - 1);
|
||||
@@ -270,6 +331,47 @@ if (counts.get('demoDeep')) {
|
||||
);
|
||||
}
|
||||
|
||||
// Pagefind builds its search index from the HTML at BUILD time (phase 10), so a rename
|
||||
// applied here reaches the pages but not the search results. Worth fixing when search
|
||||
// lands; recorded here rather than in a plan section nobody will re-read.
|
||||
if (inlineCollisions.length) {
|
||||
console.error(
|
||||
`\n[brand] ${inlineCollisions.length} file(s) were LEFT UNCHANGED: a brand value occurs ` +
|
||||
`inside an inline <script> or <style>, and rewriting it would break that block's CSP ` +
|
||||
`hash (§6, D48) — the page would render and the script would silently not run.\n`
|
||||
);
|
||||
for (const { file, fields } of inlineCollisions) {
|
||||
console.error(` ! ${file} (${fields.join(', ')})`);
|
||||
}
|
||||
console.error(
|
||||
`\n Those pages keep the stock text. Fix it by taking the brand value out of the inline\n` +
|
||||
` block — move it into markup the CSP does not hash, or into /brand/theme.css.\n`
|
||||
);
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------------------------------
|
||||
Search
|
||||
--------------------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Pagefind builds its index from the built HTML at BUILD time, so everything above reaches
|
||||
* the pages and none of it reaches the search results: a site renamed through the mount
|
||||
* would answer a search for its own name with the stock one, and every result title would
|
||||
* still carry the old suffix. Phase 2 recorded that and left it for this phase, when
|
||||
* search became site-wide (D47).
|
||||
*
|
||||
* The fix is to re-index, which is cheap and needs nothing the container does not already
|
||||
* have — Pagefind is what Starlight ran at build. It only runs when a rewrite actually
|
||||
* happened, so the stock deployment, which is the common case, still pays nothing.
|
||||
*/
|
||||
if (filesTouched > 0) {
|
||||
const pagefind = await import('pagefind');
|
||||
try {
|
||||
const { index } = await pagefind.createIndex();
|
||||
const { page_count } = await index.addDirectory({ path: CLIENT });
|
||||
await index.writeFiles({ outputPath: path.join(CLIENT, 'pagefind') });
|
||||
console.log(`[brand] re-indexed ${page_count} page(s) for search so results agree with it.`);
|
||||
} catch (error) {
|
||||
// Search degrading to stale titles is not a reason to refuse to serve the site.
|
||||
console.error(`[brand] could not rebuild the search index; it keeps the built one: ${error.message}`);
|
||||
} finally {
|
||||
await pagefind.close();
|
||||
}
|
||||
}
|
||||
|
||||
278
scripts/checkA11y.mjs
Normal file
278
scripts/checkA11y.mjs
Normal file
@@ -0,0 +1,278 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* checkA11y.mjs — PLAN.md §13 phase 10.
|
||||
*
|
||||
* Every other rule this repository cares about is enforced by a script — the facts, the
|
||||
* links, the tokens, the sidebar, the screenshots, the CSP. Accessibility was the exception:
|
||||
* it was a thing someone checked once, by hand, on the pages they happened to open. This
|
||||
* makes it the eleventh check so a regression fails a build instead of waiting for a reader
|
||||
* who cannot use the page and will not file an issue.
|
||||
*
|
||||
* node scripts/checkA11y.mjs
|
||||
*
|
||||
* ── What it checks, and why each one ────────────────────────────────────────
|
||||
* A static check cannot measure contrast against a rendered page or find a focus trap, and
|
||||
* pretending otherwise would be worse than not checking. What it CAN do is catch the class
|
||||
* of defect that is invisible to a sighted author and permanent once shipped:
|
||||
*
|
||||
* 1. **One `<h1>` per page, and no skipped heading level.** The heading tree is the
|
||||
* document outline a screen-reader user navigates by. Two `<h1>`s or an `<h2>` under
|
||||
* nothing reads as a page with no structure at all.
|
||||
* 2. **Every `<img>` has an `alt`.** Not "a non-empty alt": `alt=""` is correct and
|
||||
* deliberate for the header mark, which sits inside a link that already says the
|
||||
* product's name. A MISSING attribute is what makes a screen reader read the filename.
|
||||
* 3. **Every form control has a label.** `<label for>`, a wrapping `<label>`,
|
||||
* `aria-label` or `aria-labelledby`. The signup form is the only place on this site
|
||||
* where a person is asked to type something, so it is the one place this must hold.
|
||||
* 4. **Every link and button has an accessible name.** An icon-only control with no text
|
||||
* and no `aria-label` is announced as "link", which is no name at all. The search
|
||||
* button is icon-only under 46rem, which is exactly this hazard.
|
||||
* 5. **`<html lang>` is set**, or a screen reader reads English prose with whatever voice
|
||||
* the reader last used.
|
||||
* 6. **One `<main>` per page and a skip link that points at it.** The site's header is a
|
||||
* lockup, four links and a search box in front of every page; without a working skip
|
||||
* link a keyboard user walks all six on every navigation.
|
||||
* 7. **No positive `tabindex`.** It reorders the tab sequence away from the visual one
|
||||
* and is almost never what the author meant.
|
||||
*
|
||||
* Both chromes are checked — the marketing pages and Starlight's forty. Starlight is
|
||||
* generally careful, so the docs half is a regression alarm on a dependency rather than a
|
||||
* review of our own markup, and it has already earned its place once: it is what would have
|
||||
* caught the `<h2>`-without-`<h1>` shape if a docs page had ever lost its title.
|
||||
*
|
||||
* No token and no network: everything read here is in `dist/`.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
||||
const clientDir = path.join(root, 'dist', 'client');
|
||||
|
||||
if (!fs.existsSync(clientDir)) {
|
||||
console.error('\ncheckA11y: dist/client does not exist. Run `npm run build` first.\n');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const failures = [];
|
||||
const fail = (page, what, detail) => failures.push({ page, what, detail });
|
||||
|
||||
const pages = [];
|
||||
const walk = (dir) => {
|
||||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) walk(full);
|
||||
else if (entry.name.endsWith('.html')) pages.push(full);
|
||||
}
|
||||
};
|
||||
walk(clientDir);
|
||||
|
||||
/* ---------------------------------------------------------------------------------------
|
||||
A very small amount of HTML reading
|
||||
|
||||
Not a parser. Everything below is a tag-level question — does this element carry this
|
||||
attribute, what text sits between these two tags — and a regex answers those on
|
||||
generated, well-formed output. A DOM parser would be a dependency, and this repository's
|
||||
checks are dependency-free on purpose (§12): the reader runs them the same way CI does.
|
||||
--------------------------------------------------------------------------------------- */
|
||||
|
||||
/** Takes the ATTRIBUTE STRING — what is between the tag name and the `>` — not the tag. */
|
||||
const attrs = (attrString) => {
|
||||
const found = new Map();
|
||||
const re = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
|
||||
let m;
|
||||
while ((m = re.exec(attrString))) {
|
||||
found.set(m[1].toLowerCase(), m[2] ?? m[3] ?? m[4] ?? '');
|
||||
}
|
||||
return found;
|
||||
};
|
||||
|
||||
/** Text a screen reader would announce: markup and comments stripped, entities loosened. */
|
||||
const textOf = (html) =>
|
||||
html
|
||||
.replace(/<!--[\s\S]*?-->/g, '')
|
||||
.replace(/<[^>]*>/g, ' ')
|
||||
.replace(/&[a-zA-Z#0-9]+;/g, ' ')
|
||||
.replace(/\s+/g, ' ')
|
||||
.trim();
|
||||
|
||||
/** An element's own accessible name, near enough for "is there one at all". */
|
||||
const named = (tag, inner) => {
|
||||
const a = attrs(tag);
|
||||
if (a.get('aria-label')?.trim()) return true;
|
||||
if (a.get('aria-labelledby')?.trim()) return true;
|
||||
if (a.get('title')?.trim()) return true;
|
||||
if (textOf(inner)) return true;
|
||||
// An image child with alt text names the control.
|
||||
for (const img of inner.matchAll(/<img\b([^>]*)>/gi)) {
|
||||
if (attrs(img[1]).get('alt')?.trim()) return true;
|
||||
}
|
||||
// An SVG with a title element does too.
|
||||
if (/<svg\b[^>]*>[\s\S]*?<title\b[^>]*>[^<]+<\/title>/i.test(inner)) return true;
|
||||
return false;
|
||||
};
|
||||
|
||||
for (const file of pages) {
|
||||
const page = '/' + path.relative(clientDir, file).replace(/\\/g, '/');
|
||||
|
||||
/**
|
||||
* Comments are stripped before anything is counted, and that is not a nicety: this
|
||||
* repository comments its markup heavily, and several of those comments quote the tags
|
||||
* they are explaining. `Base.astro`'s note about `data-pagefind-body` contains the text
|
||||
* "<main>", and the first run of this check reported every marketing page as having two
|
||||
* `<main>` landmarks because of it. Stripping once, up front, also keeps every offset
|
||||
* below measured against the same string.
|
||||
*/
|
||||
const html = fs.readFileSync(file, 'utf8').replace(/<!--[\s\S]*?-->/g, '');
|
||||
|
||||
// ── 5. lang ───────────────────────────────────────────────────────────────
|
||||
const htmlTag = /<html\b([^>]*)>/i.exec(html);
|
||||
if (!htmlTag) fail(page, '<html>', 'has no <html> element');
|
||||
else if (!attrs(htmlTag[1]).get('lang')?.trim()) fail(page, '<html>', 'has no lang attribute');
|
||||
|
||||
// ── 1. headings ───────────────────────────────────────────────────────────
|
||||
const headings = [...html.matchAll(/<h([1-6])\b([^>]*)>([\s\S]*?)<\/h\1>/gi)]
|
||||
// `aria-hidden` headings are decorative and out of the outline by definition.
|
||||
.filter((m) => attrs(m[2]).get('aria-hidden') !== 'true')
|
||||
.map((m) => ({ level: Number(m[1]), text: textOf(m[3]) }));
|
||||
|
||||
const h1s = headings.filter((h) => h.level === 1);
|
||||
if (h1s.length === 0) fail(page, 'headings', 'has no <h1>');
|
||||
if (h1s.length > 1) {
|
||||
fail(page, 'headings', `has ${h1s.length} <h1>s: ${h1s.map((h) => JSON.stringify(h.text)).join(', ')}`);
|
||||
}
|
||||
|
||||
let previous = 0;
|
||||
for (const heading of headings) {
|
||||
if (previous && heading.level > previous + 1) {
|
||||
fail(
|
||||
page,
|
||||
'headings',
|
||||
`jumps from h${previous} to h${heading.level} at ${JSON.stringify(heading.text.slice(0, 50))}`,
|
||||
);
|
||||
}
|
||||
previous = heading.level;
|
||||
}
|
||||
|
||||
// ── 2. images ─────────────────────────────────────────────────────────────
|
||||
for (const img of html.matchAll(/<img\b([^>]*)>/gi)) {
|
||||
const a = attrs(img[1]);
|
||||
if (!a.has('alt')) {
|
||||
fail(page, '<img>', `has no alt attribute: src=${a.get('src') ?? '(none)'}`);
|
||||
}
|
||||
}
|
||||
|
||||
// ── 3. form controls ──────────────────────────────────────────────────────
|
||||
const labelledIds = new Set(
|
||||
[...html.matchAll(/<label\b([^>]*)>/gi)]
|
||||
.map((m) => attrs(m[1]).get('for'))
|
||||
.filter(Boolean),
|
||||
);
|
||||
/**
|
||||
* A control wrapped in its own `<label>` needs no `for` and — this is the part that took
|
||||
* a wrong answer to find — needs no `id` either, so it cannot be recorded by id. Starlight
|
||||
* labels its theme and language selects exactly this way. What is recorded instead is the
|
||||
* character offset of each wrapped control, which identifies it uniquely without
|
||||
* requiring it to have any attributes at all.
|
||||
*/
|
||||
const wrappedAt = new Set();
|
||||
for (const label of html.matchAll(/<label\b[^>]*>([\s\S]*?)<\/label>/gi)) {
|
||||
const base = label.index + label[0].indexOf(label[1]);
|
||||
for (const control of label[1].matchAll(/<(input|select|textarea)\b[^>]*>/gi)) {
|
||||
wrappedAt.add(base + control.index);
|
||||
}
|
||||
}
|
||||
|
||||
for (const control of html.matchAll(/<(input|select|textarea)\b([^>]*)>/gi)) {
|
||||
const a = attrs(control[2]);
|
||||
const type = (a.get('type') ?? 'text').toLowerCase();
|
||||
// These are not things a person types into and are named by other means.
|
||||
if (['hidden', 'submit', 'button', 'reset', 'image'].includes(type)) continue;
|
||||
|
||||
const id = a.get('id');
|
||||
const hasLabel =
|
||||
wrappedAt.has(control.index) ||
|
||||
(id && labelledIds.has(id)) ||
|
||||
a.get('aria-label')?.trim() ||
|
||||
a.get('aria-labelledby')?.trim() ||
|
||||
a.get('title')?.trim();
|
||||
|
||||
if (!hasLabel) {
|
||||
fail(
|
||||
page,
|
||||
`<${control[1]}>`,
|
||||
`has no label: ${id ? `id="${id}"` : `name="${a.get('name') ?? '(none)'}"`} — ` +
|
||||
'a placeholder is not a label',
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ── 4. link and button names ──────────────────────────────────────────────
|
||||
for (const [, tag, attrString, inner] of html.matchAll(/<(a|button)\b([^>]*)>([\s\S]*?)<\/\1>/gi)) {
|
||||
const a = attrs(attrString);
|
||||
if (a.get('aria-hidden') === 'true') continue;
|
||||
// An <a> with no href is not a link; it is a target for one.
|
||||
if (tag.toLowerCase() === 'a' && !a.has('href')) continue;
|
||||
if (named(attrString, inner)) continue;
|
||||
|
||||
fail(
|
||||
page,
|
||||
`<${tag}>`,
|
||||
`has no accessible name: ${a.get('href') ? `href="${a.get('href')}"` : `class="${a.get('class') ?? ''}"`}`,
|
||||
);
|
||||
}
|
||||
|
||||
// ── 6. main and the skip link ─────────────────────────────────────────────
|
||||
const mains = [...html.matchAll(/<main\b([^>]*)>/gi)];
|
||||
if (mains.length === 0) fail(page, '<main>', 'has no <main> landmark');
|
||||
if (mains.length > 1) fail(page, '<main>', `has ${mains.length} <main> elements`);
|
||||
|
||||
const skip = /<a\b([^>]*class="[^"]*skip-link[^"]*"[^>]*)>/i.exec(html);
|
||||
if (skip) {
|
||||
const target = attrs(skip[1]).get('href') ?? '';
|
||||
if (!target.startsWith('#')) {
|
||||
fail(page, 'skip link', `points at ${JSON.stringify(target)}, which is not an in-page anchor`);
|
||||
} else {
|
||||
const id = target.slice(1);
|
||||
if (!new RegExp(`\\bid=["']${id}["']`).test(html)) {
|
||||
fail(page, 'skip link', `points at #${id}, and nothing on the page has that id`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ── 7. positive tabindex ──────────────────────────────────────────────────
|
||||
for (const m of html.matchAll(/\btabindex\s*=\s*["']?(-?\d+)/gi)) {
|
||||
if (Number(m[1]) > 0) {
|
||||
fail(page, 'tabindex', `is ${m[1]} — a positive tabindex reorders the tab sequence`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------------------------------
|
||||
Report
|
||||
--------------------------------------------------------------------------------------- */
|
||||
|
||||
if (failures.length === 0) {
|
||||
console.log(`checkA11y: ${pages.length} built pages pass all seven structural checks.`);
|
||||
} else {
|
||||
// Grouped by page: a shared component's defect otherwise prints fifty times and buries
|
||||
// the one page that has a real problem of its own.
|
||||
const byPage = new Map();
|
||||
for (const f of failures) {
|
||||
if (!byPage.has(f.page)) byPage.set(f.page, []);
|
||||
byPage.get(f.page).push(f);
|
||||
}
|
||||
|
||||
console.error(`\ncheckA11y: ${failures.length} problem(s) across ${byPage.size} page(s):\n`);
|
||||
for (const [page, items] of byPage) {
|
||||
console.error(` ${page}`);
|
||||
for (const item of items) console.error(` ✗ ${item.what}: ${item.detail}`);
|
||||
}
|
||||
console.error(`
|
||||
These are structural, so they are the same in every browser and for every reader. A defect
|
||||
repeated across many pages is usually one shared component — fix it there rather than on
|
||||
each page.
|
||||
`);
|
||||
process.exit(1);
|
||||
}
|
||||
263
scripts/checkCsp.mjs
Normal file
263
scripts/checkCsp.mjs
Normal file
@@ -0,0 +1,263 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* checkCsp.mjs — PLAN.md §6 and D48, added in phase 10.
|
||||
*
|
||||
* §6 promises "a strict CSP with no external origins". D48 decided that promise should be
|
||||
* a real response header sent by the container itself, not a `<meta>` (which ignores
|
||||
* `frame-ancestors`) and not advice in an operator's proxy config (which lives outside the
|
||||
* artifact we ship and test). `astro.config.mjs` sets it up; this checks it arrived.
|
||||
*
|
||||
* node scripts/checkCsp.mjs # verify the built output
|
||||
* node scripts/checkCsp.mjs --write # rewrite src/config/cspHashes.mjs from the build
|
||||
* node scripts/checkCsp.mjs --reset # empty it, so the next harvest starts from nothing
|
||||
*
|
||||
* Three things are checked, and each one has already been wrong once:
|
||||
*
|
||||
* 1. **Every built route has a policy.** `staticHeaders` writes `dist/_headers.json`; a
|
||||
* route missing from it is a page served with no CSP at all, which is the failure mode
|
||||
* nobody notices because the page looks perfect.
|
||||
*
|
||||
* 2. **Every inline script and style is covered by its page's own policy.** This is the
|
||||
* real check. Astro does not hash `<script is:inline>`, and Starlight ships six of
|
||||
* them per documentation page — so the first build with CSP on had a strict, correct
|
||||
* header and a dead theme switcher. Hashing is verified per page against that page's
|
||||
* header, not against a global list, because that is what the browser does.
|
||||
*
|
||||
* 3. **The directives §6 actually promised are present.** A policy that lost
|
||||
* `frame-ancestors` in a refactor still passes checks 1 and 2 while no longer stopping
|
||||
* anything.
|
||||
*
|
||||
* `--write` harvests the hashes from check 2 into `src/config/cspHashes.mjs`, which
|
||||
* `astro.config.mjs` feeds back into the next build. So the sequence is reset → build →
|
||||
* write → build → verify, which is what `npm run csp:hashes` runs. It resets first because
|
||||
* harvesting only ever collects what the build did NOT cover — see `--reset` below.
|
||||
*
|
||||
* No token and no network: everything read here is in `dist/`.
|
||||
*/
|
||||
|
||||
import { createHash } from 'node:crypto';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
||||
const headersFile = path.join(root, 'dist', '_headers.json');
|
||||
const clientDir = path.join(root, 'dist', 'client');
|
||||
const hashesFile = path.join(root, 'src', 'config', 'cspHashes.mjs');
|
||||
|
||||
const write = process.argv.includes('--write');
|
||||
const reset = process.argv.includes('--reset');
|
||||
|
||||
const failures = [];
|
||||
const fail = (what, detail) => failures.push({ what, detail });
|
||||
|
||||
/**
|
||||
* Rewrites the two exported arrays in `src/config/cspHashes.mjs`, leaving every comment and
|
||||
* the JSDoc types above them untouched.
|
||||
*/
|
||||
const writeHashes = (script, style) => {
|
||||
const source = fs.readFileSync(hashesFile, 'utf8');
|
||||
const list = (hashes) =>
|
||||
hashes.size === 0 ? '[]' : `[\n${[...hashes].sort().map((h) => ` '${h}',`).join('\n')}\n]`;
|
||||
|
||||
fs.writeFileSync(
|
||||
hashesFile,
|
||||
source
|
||||
.replace(
|
||||
/export const inlineScriptHashes = [\s\S]*?;\n/,
|
||||
`export const inlineScriptHashes = ${list(script)};\n`,
|
||||
)
|
||||
.replace(
|
||||
/export const inlineStyleHashes = [\s\S]*?;\n/,
|
||||
`export const inlineStyleHashes = ${list(style)};\n`,
|
||||
),
|
||||
);
|
||||
};
|
||||
|
||||
/**
|
||||
* `--reset` empties the generated file, and `npm run csp:hashes` runs it FIRST.
|
||||
*
|
||||
* Without it the regeneration is not idempotent, and its failure mode is the worst
|
||||
* available: harvesting collects the blocks the build did not cover, so running it against
|
||||
* a build that is already correct finds nothing, writes two empty arrays and produces a
|
||||
* build with no hashes at all. Emptying first means the harvest always sees the same thing
|
||||
* — every inline block Astro does not hash on its own — whatever state the file was in.
|
||||
*/
|
||||
if (reset) {
|
||||
writeHashes(new Set(), new Set());
|
||||
console.log('checkCsp --reset: src/config/cspHashes.mjs emptied, ready to re-harvest.');
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// ── The build has to be there ───────────────────────────────────────────────
|
||||
if (!fs.existsSync(headersFile)) {
|
||||
console.error(`
|
||||
checkCsp: dist/_headers.json does not exist.
|
||||
|
||||
That file is written by the Node adapter's \`staticHeaders\` option, so either the build
|
||||
has not run (\`npm run build\`) or \`staticHeaders\` was turned off in astro.config.mjs —
|
||||
in which case the CSP is a <meta> tag and \`frame-ancestors\` is being ignored (D48).
|
||||
`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
/**
|
||||
* `_headers.json` is keyed by an internal route id, so the pathname lives in the record.
|
||||
* Normalised without a trailing slash: the file says `/docs/first-run`, the built page is
|
||||
* at `docs/first-run/index.html`, and `build.format: 'directory'` serves it at
|
||||
* `/docs/first-run/`.
|
||||
*/
|
||||
const byPath = new Map();
|
||||
for (const record of Object.values(JSON.parse(fs.readFileSync(headersFile, 'utf8')))) {
|
||||
const csp = record.headers?.find((h) => h.key.toLowerCase() === 'content-security-policy');
|
||||
byPath.set(record.pathname.replace(/\/$/, '') || '/', csp?.value ?? null);
|
||||
}
|
||||
|
||||
// ── Walk the built HTML ─────────────────────────────────────────────────────
|
||||
const pages = [];
|
||||
const walk = (dir) => {
|
||||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) walk(full);
|
||||
else if (entry.name === 'index.html' || entry.name.endsWith('.html')) pages.push(full);
|
||||
}
|
||||
};
|
||||
walk(clientDir);
|
||||
|
||||
/**
|
||||
* Inline only: anything with a `src` is a fetched file and is covered by `'self'`.
|
||||
* The body is hashed exactly as written, because that is what the browser hashes — one
|
||||
* byte of whitespace either side changes the digest.
|
||||
*/
|
||||
const INLINE_SCRIPT = /<script(?![^>]*\bsrc\s*=)([^>]*)>([\s\S]*?)<\/script>/g;
|
||||
const INLINE_STYLE = /<style([^>]*)>([\s\S]*?)<\/style>/g;
|
||||
|
||||
/**
|
||||
* `<script type="application/ld+json">` (D50) is a data block, not code: the browser never
|
||||
* executes it, and CSP's script-src is not enforced against it. Demanding a hash for one
|
||||
* would be wrong twice over — it would add the structured data's own text to the list of
|
||||
* scripts allowed to run, and that text changes whenever a fact or the brand name does, so
|
||||
* the generated hash file would churn on edits that cannot affect security.
|
||||
*/
|
||||
const DATA_BLOCK = /type\s*=\s*["']application\/(ld\+json|json)["']/i;
|
||||
|
||||
const sha256 = (body) => `sha256-${createHash('sha256').update(body, 'utf8').digest('base64')}`;
|
||||
|
||||
const harvested = { script: new Set(), style: new Set() };
|
||||
let inlineScripts = 0;
|
||||
let inlineStyles = 0;
|
||||
let uncovered = 0;
|
||||
|
||||
for (const file of pages) {
|
||||
const rel = path.relative(clientDir, file).replace(/\\/g, '/');
|
||||
const pathname = '/' + rel.replace(/index\.html$/, '').replace(/\.html$/, '').replace(/\/$/, '');
|
||||
const csp = byPath.get(pathname === '/' ? '/' : pathname.replace(/\/$/, ''));
|
||||
|
||||
if (csp === undefined) {
|
||||
fail(pathname, 'is a built page with no entry in dist/_headers.json — it ships with no CSP');
|
||||
continue;
|
||||
}
|
||||
if (csp === null) {
|
||||
fail(pathname, 'has an entry in dist/_headers.json but no Content-Security-Policy header');
|
||||
continue;
|
||||
}
|
||||
|
||||
const html = fs.readFileSync(file, 'utf8');
|
||||
|
||||
for (const [kind, re, counter] of [
|
||||
['script', INLINE_SCRIPT, 'inlineScripts'],
|
||||
['style', INLINE_STYLE, 'inlineStyles'],
|
||||
]) {
|
||||
re.lastIndex = 0;
|
||||
let match;
|
||||
while ((match = re.exec(html))) {
|
||||
const [, attrs, body] = match;
|
||||
if (kind === 'script' && DATA_BLOCK.test(attrs)) continue;
|
||||
// An empty inline block needs no hash; browsers do not enforce one.
|
||||
if (body.trim() === '') continue;
|
||||
if (counter === 'inlineScripts') inlineScripts++;
|
||||
else inlineStyles++;
|
||||
|
||||
const hash = sha256(body);
|
||||
if (csp.includes(hash)) continue;
|
||||
|
||||
uncovered++;
|
||||
harvested[kind].add(hash);
|
||||
if (!write) {
|
||||
fail(
|
||||
`${pathname} (inline <${kind}>)`,
|
||||
`${hash} is not in that page's policy — ${JSON.stringify(body.trim().slice(0, 60))}…`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ── The directives §6 promised, on a page that has to have them ─────────────
|
||||
const REQUIRED = [
|
||||
"default-src 'self'",
|
||||
"base-uri 'self'",
|
||||
"form-action 'self'",
|
||||
"object-src 'none'",
|
||||
"frame-ancestors 'none'",
|
||||
];
|
||||
const home = byPath.get('/');
|
||||
if (!home) {
|
||||
fail('/', 'the homepage has no CSP header at all');
|
||||
} else {
|
||||
for (const directive of REQUIRED) {
|
||||
if (!home.includes(directive)) fail('/ policy', `is missing "${directive}" (PLAN.md §6)`);
|
||||
}
|
||||
// The point of the whole exercise: a hash and 'unsafe-inline' in the same script
|
||||
// directive means browsers ignore 'unsafe-inline' — but if the hashes ever went away it
|
||||
// would quietly start applying.
|
||||
const scriptSrc = /script-src ([^;]*)/.exec(home)?.[1] ?? '';
|
||||
if (scriptSrc.includes("'unsafe-inline'")) {
|
||||
fail('/ policy', "script-src contains 'unsafe-inline' — D48 says the hashes carry this");
|
||||
}
|
||||
if (scriptSrc.includes("'unsafe-eval'")) {
|
||||
fail('/ policy', "script-src contains 'unsafe-eval' ('wasm-unsafe-eval' is the intended one)");
|
||||
}
|
||||
}
|
||||
|
||||
// ── --write: regenerate the hash file ───────────────────────────────────────
|
||||
if (write) {
|
||||
writeHashes(harvested.script, harvested.style);
|
||||
console.log(
|
||||
`checkCsp --write: harvested ${harvested.script.size} script and ${harvested.style.size} ` +
|
||||
`style hash(es) from ${pages.length} pages into src/config/cspHashes.mjs.`,
|
||||
);
|
||||
if (failures.length) {
|
||||
console.error('\ncheckCsp --write: the build is still wrong in ways hashes cannot fix:\n');
|
||||
for (const f of failures) console.error(` ✗ ${f.what}\n ${f.detail}`);
|
||||
process.exit(1);
|
||||
}
|
||||
console.log('Now rebuild so the next build embeds them (npm run csp:hashes does both).');
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// ── Report ──────────────────────────────────────────────────────────────────
|
||||
if (failures.length === 0) {
|
||||
console.log(
|
||||
`checkCsp: ${pages.length} pages carry a policy; ` +
|
||||
`${inlineScripts} inline script(s) and ${inlineStyles} inline style(s) are all hashed.`,
|
||||
);
|
||||
} else {
|
||||
console.error(`\ncheckCsp: ${failures.length} problem(s) with the Content-Security-Policy:\n`);
|
||||
for (const f of failures) console.error(` ✗ ${f.what}\n ${f.detail}`);
|
||||
if (uncovered) {
|
||||
console.error(`
|
||||
${uncovered} inline block(s) are not covered by a hash. In a browser this is silent: the
|
||||
page renders and the script simply never runs — Starlight's theme switch and mobile
|
||||
sidebar are inline scripts, so this is how the documentation loses them.
|
||||
|
||||
If the inline block is legitimate (usually: Starlight was upgraded), run
|
||||
|
||||
npm run csp:hashes
|
||||
|
||||
which rebuilds, harvests the hashes into src/config/cspHashes.mjs and rebuilds again.
|
||||
Read what changed before committing it — that file is a list of scripts allowed to run.
|
||||
`);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
@@ -60,8 +60,28 @@ async function api(pathname) {
|
||||
return res;
|
||||
}
|
||||
|
||||
const raw = async (repo, filePath, ref) =>
|
||||
(await api(`${repo}/raw/${filePath}?ref=${encodeURIComponent(ref)}`)).text();
|
||||
/**
|
||||
* A file's bytes, read through the `contents` endpoint rather than `raw`.
|
||||
*
|
||||
* `raw` answers with `Cache-Control: public, max-age=21600`, so the CDN in front of Gitea
|
||||
* serves a copy for six hours and this check can read a blob most of a working day old.
|
||||
* That is not theoretical: on the day of the engagement cutover it reported website's
|
||||
* MODULE_API_VERSION as 1.6.0 -- the value from two weeks earlier -- and failed a site
|
||||
* whose number was right. A check that goes red on stale data is a check people learn to
|
||||
* ignore, which is the one failure mode this file exists to avoid.
|
||||
*
|
||||
* `contents` answers `private, must-revalidate`, which the CDN does not cache, so it is
|
||||
* always the ref's current blob. The cost is a JSON parse and a base64 decode.
|
||||
*/
|
||||
async function raw(repo, filePath, ref) {
|
||||
const meta = await json(`${repo}/contents/${filePath}?ref=${encodeURIComponent(ref)}`);
|
||||
if (meta.encoding !== 'base64' || typeof meta.content !== 'string') {
|
||||
throw new Error(
|
||||
`${repo}:${filePath}@${ref} did not come back as a base64 file (encoding ${meta.encoding}).`
|
||||
);
|
||||
}
|
||||
return Buffer.from(meta.content, 'base64').toString('utf8');
|
||||
}
|
||||
|
||||
const json = async (pathname) => (await api(pathname)).json();
|
||||
|
||||
@@ -72,33 +92,42 @@ function extract(text, re, what, authority) {
|
||||
return m[1];
|
||||
}
|
||||
|
||||
// Every game the site quotes facts for (PLAN.md §16). Checks 1, 2, 4 and 5 run once per
|
||||
// game, and a row's label carries the game's key so a failure names which one moved.
|
||||
const GAMES = Object.entries(platform.games);
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 1. The wire protocol, from the sidecar itself
|
||||
// 1. Each game's wire protocol, from its sidecar
|
||||
// ---------------------------------------------------------------------------
|
||||
async function checkProtocol() {
|
||||
const authority = 'link main:sidecar/src/main.rs';
|
||||
const src = await raw('link', 'sidecar/src/main.rs', 'main');
|
||||
const value = extract(
|
||||
src,
|
||||
/pub const PROTOCOL_VERSION:\s*u32\s*=\s*(\d+)\s*;/,
|
||||
'PROTOCOL_VERSION',
|
||||
authority
|
||||
);
|
||||
record('protocol (sidecar)', platform.protocol, Number(value), authority);
|
||||
for (const [key, game] of GAMES) {
|
||||
const authority = `${game.sidecarRepo} main:sidecar/src/main.rs`;
|
||||
const src = await raw(game.sidecarRepo, 'sidecar/src/main.rs', 'main');
|
||||
const value = extract(
|
||||
src,
|
||||
/pub const PROTOCOL_VERSION:\s*u32\s*=\s*(\d+)\s*;/,
|
||||
'PROTOCOL_VERSION',
|
||||
authority
|
||||
);
|
||||
record(`${key} protocol (sidecar)`, game.protocol, Number(value), authority);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 2. The overlay's declared protocol — the third declaration site
|
||||
// 2. Each game plugin's declared protocol — the third declaration site
|
||||
//
|
||||
// CLAUDE.md: a protocol bump has to land in overlay.toml in the same PR as the emitters,
|
||||
// or the installer refuses to pair the sidecar with the overlay. If these two ever
|
||||
// disagree, the site must not print either number.
|
||||
// or the installer refuses to pair the sidecar with the plugin. If these two ever
|
||||
// disagree, the site must not print either number. Both games keep the file under the
|
||||
// same name at the root of their plugin repository.
|
||||
// ---------------------------------------------------------------------------
|
||||
async function checkOverlayProtocol() {
|
||||
const authority = 'servuo-plugins main:overlay.toml';
|
||||
const toml = await raw('servuo-plugins', 'overlay.toml', 'main');
|
||||
const value = extract(toml, /^\s*protocol\s*=\s*(\d+)\s*$/m, 'protocol', authority);
|
||||
record('protocol (overlay)', platform.protocol, Number(value), authority);
|
||||
for (const [key, game] of GAMES) {
|
||||
const authority = `${game.pluginRepo} main:overlay.toml`;
|
||||
const toml = await raw(game.pluginRepo, 'overlay.toml', 'main');
|
||||
const value = extract(toml, /^\s*protocol\s*=\s*(\d+)\s*$/m, 'protocol', authority);
|
||||
record(`${key} protocol (plugin)`, game.protocol, Number(value), authority);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -117,7 +146,7 @@ async function checkModuleApi() {
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 4. The capabilities the installed module actually declares
|
||||
// 4. The capabilities each game's module actually declares
|
||||
//
|
||||
// §12 names "module-uo's capability list" as one of the facts platform.json holds, and it
|
||||
// was the one fact nothing re-read. That mattered from phase 3 onwards, because the
|
||||
@@ -130,36 +159,109 @@ async function checkModuleApi() {
|
||||
// array is not a changed capability set. A slug appearing or disappearing is.
|
||||
// ---------------------------------------------------------------------------
|
||||
async function checkModuleCapabilities() {
|
||||
const authority = 'Module-uo main:module.json';
|
||||
const manifest = JSON.parse(await raw('Module-uo', 'module.json', 'main'));
|
||||
const declared = [...(manifest.capabilities || [])].sort();
|
||||
const expected = [...platform.moduleUoCapabilities].sort();
|
||||
for (const [key, game] of GAMES) {
|
||||
const authority = `${game.module.repo} main:module.json`;
|
||||
const manifest = JSON.parse(await raw(game.module.repo, 'module.json', 'main'));
|
||||
const declared = [...(manifest.capabilities || [])].sort();
|
||||
const expected = [...game.module.capabilities].sort();
|
||||
|
||||
record('moduleUoCapabilities', expected.join(' '), declared.join(' '), authority);
|
||||
record(`${key} module capabilities`, expected.join(' '), declared.join(' '), authority);
|
||||
// The range the module declares against core. The manifest docs use it as the worked
|
||||
// example of a caret range resolving across minor bumps, so it is a quoted fact.
|
||||
record(`${key} module coreApi`, game.module.coreApi, manifest.coreApi, authority);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 5. The current bundle
|
||||
// 5. Each game's current bundle
|
||||
//
|
||||
// The manifests live at the ROOT of the `bundles` branch — `current.json`,
|
||||
// `bundle-<tag>.json` — not under `bundles/`. Fetching the directory 404s.
|
||||
// One manifest per game on the installer's `bundles` branch, at
|
||||
// `v2/<game>/current.json` (schema 2). The ROOT `current.json` is the schema-1 manifest
|
||||
// from before the installer learned a second game; it is frozen and no longer read here,
|
||||
// because a check against a file that stopped moving passes forever.
|
||||
//
|
||||
// Each bundle is protocol-checked by CI when it is published, so its protocol is a third
|
||||
// independent read of the same number rather than a duplicate of checks 1 and 2.
|
||||
// ---------------------------------------------------------------------------
|
||||
async function checkBundle() {
|
||||
const authority = 'installer bundles:current.json';
|
||||
const current = JSON.parse(await raw('installer', 'current.json', 'bundles'));
|
||||
async function readBundle(game) {
|
||||
const file = `v2/${game.bundleGame}/current.json`;
|
||||
const authority = `installer bundles:${file}`;
|
||||
const current = JSON.parse(await raw('installer', file, 'bundles'));
|
||||
if (current.schema !== 2) {
|
||||
throw new Error(`${authority} is schema ${current.schema}, and this check reads schema 2.`);
|
||||
}
|
||||
return { current, authority };
|
||||
}
|
||||
|
||||
record('bundle.tag', platform.bundle.tag, current.bundle, authority);
|
||||
record('bundle.sidecar', platform.bundle.sidecar, current.link?.tag, authority);
|
||||
record('bundle.overlay', platform.bundle.overlay, current.overlay?.tag, authority);
|
||||
async function checkBundle() {
|
||||
const { uo, rust } = platform.games;
|
||||
|
||||
{
|
||||
const { current, authority } = await readBundle(uo);
|
||||
record('uo bundle.tag', uo.bundle.tag, current.bundle, authority);
|
||||
record('uo bundle.sidecar', uo.bundle.sidecar, current.sidecar?.tag, authority);
|
||||
record('uo bundle.overlay', uo.bundle.overlay, current.payload?.tag, authority);
|
||||
record('uo bundle.servuoMin', uo.bundle.servuoMin, current.payload?.compat?.min_version, authority);
|
||||
record('uo protocol (bundle)', uo.protocol, current.protocol, authority);
|
||||
}
|
||||
|
||||
{
|
||||
const { current, authority } = await readBundle(rust);
|
||||
const compat = current.payload?.compat ?? {};
|
||||
record('rust bundle.tag', rust.bundle.tag, current.bundle, authority);
|
||||
record('rust bundle.sidecar', rust.bundle.sidecar, current.sidecar?.tag, authority);
|
||||
record('rust bundle.plugin', rust.bundle.plugin, current.payload?.tag, authority);
|
||||
record('rust bundle.oxideMin', rust.bundle.oxideMin, compat.frameworks?.oxide?.min_version, authority);
|
||||
record('rust bundle.carbonMin', rust.bundle.carbonMin, compat.frameworks?.carbon?.min_version, authority);
|
||||
record(
|
||||
'rust bundle.requiresPlugins',
|
||||
[...rust.bundle.requiresPlugins].sort().join(' '),
|
||||
[...(compat.requires_plugins ?? [])].sort().join(' '),
|
||||
authority
|
||||
);
|
||||
record('rust bundle.runicnpc', rust.bundle.runicnpc, current.npc?.tag, authority);
|
||||
record('rust protocol (bundle)', rust.protocol, current.protocol, authority);
|
||||
// The bundle carries RunicNPC's API too; check 5b reads it from the plugin's own repo.
|
||||
record('runicnpc api (bundle)', platform.runicnpc.api, current.npc?.api, authority);
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 5b. RunicNPC's own declarations
|
||||
//
|
||||
// RunicNPC stands alone as well as shipping in the Rust bundle (D61), so its facts are
|
||||
// read from its own `plugin.toml` too — the file its release workflow folds into the
|
||||
// manifest the installer and the egg read. The API version is the number a plugin author
|
||||
// calling `RunicNpc_*` relies on, and the site quotes it beside the API reference (D62).
|
||||
// ---------------------------------------------------------------------------
|
||||
async function checkRunicNpc() {
|
||||
const authority = 'runicnpc-rust main:plugin.toml';
|
||||
const toml = await raw('runicnpc-rust', 'plugin.toml', 'main');
|
||||
const npc = platform.runicnpc;
|
||||
|
||||
record('runicnpc api', npc.api, Number(extract(toml, /^\s*api\s*=\s*(\d+)\s*$/m, 'api', authority)), authority);
|
||||
record(
|
||||
'bundle.servuoMin',
|
||||
platform.bundle.servuoMin,
|
||||
current.overlay?.servuo?.min_version,
|
||||
'runicnpc oxideMin',
|
||||
npc.oxideMin,
|
||||
extract(toml, /^\s*min_oxide_version\s*=\s*"([^"]+)"/m, 'min_oxide_version', authority),
|
||||
authority
|
||||
);
|
||||
record(
|
||||
'runicnpc carbonMin',
|
||||
npc.carbonMin,
|
||||
extract(toml, /^\s*min_carbon_version\s*=\s*"([^"]+)"/m, 'min_carbon_version', authority),
|
||||
authority
|
||||
);
|
||||
const required = extract(toml, /^\s*requires_plugins\s*=\s*\[([^\]]*)\]/m, 'requires_plugins', authority)
|
||||
.split(',')
|
||||
.map((name) => name.trim().replace(/^"|"$/g, ''))
|
||||
.filter(Boolean);
|
||||
record(
|
||||
'runicnpc requiresPlugins',
|
||||
[...npc.requiresPlugins].sort().join(' '),
|
||||
required.sort().join(' '),
|
||||
authority
|
||||
);
|
||||
// The bundle is protocol-checked by CI when it is published, so this is a third
|
||||
// independent read of the same number rather than a duplicate of check 1.
|
||||
record('protocol (bundle)', platform.protocol, current.protocol, authority);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -329,6 +431,7 @@ async function main() {
|
||||
checkModuleApi,
|
||||
checkModuleCapabilities,
|
||||
checkBundle,
|
||||
checkRunicNpc,
|
||||
checkReleases,
|
||||
checkWebsiteHasNoReleases,
|
||||
checkAndroidApk,
|
||||
|
||||
@@ -55,12 +55,18 @@ const checked = [];
|
||||
const ok = (what) => checked.push(what);
|
||||
const fail = (what, detail) => failures.push({ what, detail });
|
||||
|
||||
/** Same raw-file accessor checkFacts.mjs uses, and for the same reason. */
|
||||
/** Same file accessor checkFacts.mjs uses, and for the same reason -- including the CDN one. */
|
||||
async function raw(repo, filePath, ref) {
|
||||
const url = `${BASE}/api/v1/repos/${ORG}/${repo}/raw/${filePath}?ref=${encodeURIComponent(ref)}`;
|
||||
const url = `${BASE}/api/v1/repos/${ORG}/${repo}/contents/${filePath}?ref=${encodeURIComponent(ref)}`;
|
||||
const res = await fetch(url, { headers: { Authorization: `token ${TOKEN}` } });
|
||||
if (!res.ok) throw new Error(`${res.status} ${res.statusText} for ${url}`);
|
||||
return res.text();
|
||||
const meta = await res.json();
|
||||
if (meta.encoding !== 'base64' || typeof meta.content !== 'string') {
|
||||
throw new Error(
|
||||
`${repo}:${filePath}@${ref} did not come back as a base64 file (encoding ${meta.encoding}).`
|
||||
);
|
||||
}
|
||||
return Buffer.from(meta.content, 'base64').toString('utf8');
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -7,6 +7,10 @@
|
||||
* this is the machinery that makes writing the NAMES down safe anyway — the same bargain
|
||||
* checkQuickstart.mjs struck for the quickstart, applied to six more sources.
|
||||
*
|
||||
* Phase 15 (PLAN.md §16) added the Rust group's three: rust-link's `sidecar.toml` and its
|
||||
* environment overrides, the bridge plugin's `RunicGateway.json`, and the event kinds with the
|
||||
* class each is served under (D71).
|
||||
*
|
||||
* Each enumeration in `src/data/reference.mjs` is compared against its authority, read from
|
||||
* the repository that owns it over the Gitea API — never from a working tree, per §1's
|
||||
* process rule. Every comparison is a SET comparison in both directions:
|
||||
@@ -39,7 +43,24 @@ import {
|
||||
bridgeCfg,
|
||||
visibilityLadder,
|
||||
canonicalDocs,
|
||||
rustSidecarConfig,
|
||||
rustSidecarEnv,
|
||||
rustPluginConfig,
|
||||
rustEventKinds,
|
||||
} from '../src/data/reference.mjs';
|
||||
import {
|
||||
runicnpcOwners,
|
||||
runicnpcCalls,
|
||||
runicnpcHooks,
|
||||
runicnpcListKeys,
|
||||
runicnpcPlacementKeys,
|
||||
runicnpcRouteKeys,
|
||||
runicnpcProfileFields,
|
||||
runicnpcCommands,
|
||||
runicnpcPermissions,
|
||||
runicnpcPlaceOptions,
|
||||
runicnpcConfig,
|
||||
} from '../src/data/runicnpc.mjs';
|
||||
|
||||
const ROOT = fileURLToPath(new URL('..', import.meta.url));
|
||||
const platform = JSON.parse(readFileSync(path.join(ROOT, 'src/data/platform.json'), 'utf8'));
|
||||
@@ -53,12 +74,18 @@ const checked = [];
|
||||
const ok = (what) => checked.push(what);
|
||||
const fail = (what, detail) => failures.push({ what, detail });
|
||||
|
||||
/** Same raw-file accessor checkFacts.mjs and checkQuickstart.mjs use. */
|
||||
/** 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}/raw/${filePath}?ref=${encodeURIComponent(ref)}`;
|
||||
const url = `${BASE}/api/v1/repos/${ORG}/${repo}/contents/${filePath}?ref=${encodeURIComponent(ref)}`;
|
||||
const res = await fetch(url, { headers: { Authorization: `token ${TOKEN}` } });
|
||||
if (!res.ok) throw new Error(`${res.status} ${res.statusText} for ${url}`);
|
||||
return res.text();
|
||||
const meta = await res.json();
|
||||
if (meta.encoding !== 'base64' || typeof meta.content !== 'string') {
|
||||
throw new Error(
|
||||
`${repo}:${filePath}@${ref} did not come back as a base64 file (encoding ${meta.encoding}).`
|
||||
);
|
||||
}
|
||||
return Buffer.from(meta.content, 'base64').toString('utf8');
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -97,6 +124,235 @@ const cfgKeysOf = (text) =>
|
||||
.filter(Boolean)
|
||||
.map((m) => m[1]);
|
||||
|
||||
/**
|
||||
* A sidecar's TOML keys, parsed from its serde structs rather than from a sample file,
|
||||
* because the sample is GENERATED by the binary on first run and no committed copy is
|
||||
* authoritative. Each `pub name: T` inside a `struct XCfg` is one key, and the struct name
|
||||
* gives the section. Both sidecars are written this way, so one parser serves both.
|
||||
*/
|
||||
function tomlKeysOf(configRs) {
|
||||
const keys = [];
|
||||
for (const m of configRs.matchAll(/struct\s+(\w+)Cfg\s*\{([\s\S]*?)\n\}/g)) {
|
||||
const section = m[1].toLowerCase();
|
||||
for (const f of m[2].matchAll(/pub\s+(\w+)\s*:/g)) keys.push(`${section}.${f[1]}`);
|
||||
}
|
||||
return keys;
|
||||
}
|
||||
|
||||
/** The body of a C# class, by brace counting from its opening brace. */
|
||||
function classBody(source, name) {
|
||||
const start = source.search(new RegExp(`class\\s+${name}\\b`));
|
||||
if (start < 0) return null;
|
||||
const open = source.indexOf('{', start);
|
||||
let depth = 0;
|
||||
for (let i = open; i < source.length; i++) {
|
||||
if (source[i] === '{') depth++;
|
||||
else if (source[i] === '}' && --depth === 0) return source.slice(open + 1, i);
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* The quoted strings inside `const NAME = Object.freeze([ … ])`, comments removed first —
|
||||
* the module's comments are prose, and prose has apostrophes.
|
||||
*/
|
||||
function frozenListOf(source, name) {
|
||||
const m = source.match(new RegExp(`const\\s+${name}\\s*=\\s*Object\\.freeze\\(\\[([\\s\\S]*?)\\]\\)`));
|
||||
if (!m) return null;
|
||||
const code = m[1].replace(/\/\/.*$/gm, '');
|
||||
return [...code.matchAll(/'([^'\n]+)'/g)].map((x) => x[1]);
|
||||
}
|
||||
|
||||
/**
|
||||
* One section of a Markdown document: from the line starting with `heading` to the next
|
||||
* heading of the same or a higher level. Null when there is no such heading, which every
|
||||
* caller reports — a section that silently vanished must not read as an empty one.
|
||||
*/
|
||||
function mdSection(md, heading) {
|
||||
const lines = md.split(/\r?\n/);
|
||||
const start = lines.findIndex((l) => l.startsWith(heading));
|
||||
if (start < 0) return null;
|
||||
const level = heading.match(/^#+/)[0].length;
|
||||
const stop = new RegExp(`^#{1,${level}} `);
|
||||
let end = lines.length;
|
||||
for (let i = start + 1; i < lines.length; i++) {
|
||||
if (stop.test(lines[i])) {
|
||||
end = i;
|
||||
break;
|
||||
}
|
||||
}
|
||||
return lines.slice(start + 1, end).join('\n');
|
||||
}
|
||||
|
||||
/** The backticked names in the first cell of every table row of a section. */
|
||||
function firstCellNames(section) {
|
||||
return section
|
||||
.split('\n')
|
||||
.filter((l) => l.startsWith('| `'))
|
||||
.map((l) => [...l.split('|')[1].matchAll(/`([^`]+)`/g)].map((m) => m[1]));
|
||||
}
|
||||
|
||||
const collapse = (s) => s.replace(/\s+/g, ' ').trim();
|
||||
|
||||
/** The top-level keys of the first ```json block in a section. */
|
||||
function jsonKeysOf(section) {
|
||||
const m = section?.match(/```json\s*\n([\s\S]*?)\n```/);
|
||||
if (!m) return null;
|
||||
try {
|
||||
return Object.keys(JSON.parse(m[1]));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
async function checkRunicNpcApi(md) {
|
||||
const hint = 'docs main:runicnpc/API.md';
|
||||
|
||||
// The version the specification describes, against the one platform.json quotes (and
|
||||
// checkFacts holds to the plugin's own plugin.toml). Together they close the loop.
|
||||
const version = Number(md.match(/\*\*API version (\d+)\*\*/)?.[1]);
|
||||
if (version !== platform.runicnpc.api) {
|
||||
fail('RunicNPC API version', `${hint} describes API ${version || '(none found)'}; platform.json says ${platform.runicnpc.api}`);
|
||||
} else ok(`RunicNPC API version (${version})`);
|
||||
|
||||
// Calls: `### \`RunicNpc_X(params)\` → \`returns\`` headings, compared by whole signature.
|
||||
const theirCalls = new Map(
|
||||
[...md.matchAll(/^### `(RunicNpc_\w+)\(([^)]*)\)` → `([^`]+)`\s*$/gm)].map((m) => [m[1], collapse(`(${m[2]}) → ${m[3]}`)]),
|
||||
);
|
||||
const myCalls = new Map(Object.entries(runicnpcCalls).map(([n, c]) => [n, collapse(`(${c.params}) → ${c.returns}`)]));
|
||||
compareSignatures('RunicNPC call', myCalls, theirCalls, hint);
|
||||
|
||||
// Hooks: the first cell of each row of "Hooks it raises".
|
||||
const hooksSection = mdSection(md, '## Hooks it raises');
|
||||
if (!hooksSection) fail('RunicNPC hooks', `no "## Hooks it raises" section in ${hint}`);
|
||||
else {
|
||||
const theirHooks = new Map(
|
||||
[...hooksSection.matchAll(/^\| `(OnRunicNpc\w+)\(([^)]*)\)` \|/gm)].map((m) => [m[1], collapse(`(${m[2]})`)]),
|
||||
);
|
||||
const myHooks = new Map(Object.entries(runicnpcHooks).map(([n, h]) => [n, collapse(`(${h.params})`)]));
|
||||
compareSignatures('RunicNPC hook', myHooks, theirHooks, hint);
|
||||
}
|
||||
|
||||
// The data shapes, by field name (D73).
|
||||
const shape = (label, heading, mine, read) => {
|
||||
const section = mdSection(md, heading);
|
||||
const theirs = section && read(section);
|
||||
if (!theirs || theirs.length === 0) fail(label, `could not read the "${heading}" section of ${hint}`);
|
||||
else compareSets(label, mine, theirs, `${hint} "${heading.replace(/^#+ /, '')}"`);
|
||||
};
|
||||
|
||||
shape('RunicNPC owner', '## Owners', Object.keys(runicnpcOwners), (s) => firstCellNames(s).flat());
|
||||
shape('RunicNpc_List key', '### `RunicNpc_List', Object.keys(runicnpcListKeys), (s) => firstCellNames(s).flat());
|
||||
|
||||
// A profile's fields. A cell may name several (`hurtByPlayers`, `hurtsPlayers`), and a bare
|
||||
// name after a dotted one shares its prefix (`phases[].damageDealt`, `aimCone`).
|
||||
shape(
|
||||
'RunicNPC profile field',
|
||||
'### A profile',
|
||||
Object.values(runicnpcProfileFields).flatMap((group) => Object.keys(group)),
|
||||
(s) =>
|
||||
firstCellNames(s).flatMap(([first, ...rest]) => {
|
||||
const prefix = first.includes('.') ? first.slice(0, first.lastIndexOf('.') + 1) : '';
|
||||
return [first, ...rest.map((n) => (n.includes('.') ? n : prefix + n))];
|
||||
}),
|
||||
);
|
||||
|
||||
// A placement's keys: the example's, plus the optional ones its bullets introduce.
|
||||
shape('RunicNPC placement key', '### A placement', Object.keys(runicnpcPlacementKeys), (s) => {
|
||||
const keys = jsonKeysOf(s);
|
||||
return keys && [...new Set([...keys, ...[...s.matchAll(/^- `(\w+)`/gm)].map((m) => m[1])])];
|
||||
});
|
||||
shape('RunicNPC route key', '### A route', Object.keys(runicnpcRouteKeys), jsonKeysOf);
|
||||
|
||||
// The page itself: every call has exactly one <Signature call="…" />, so "in full" is held
|
||||
// by the build and not by whoever last edited api.mdx.
|
||||
const page = readFileSync(path.join(ROOT, 'src/content/docs/docs/rust/runicnpc/api.mdx'), 'utf8');
|
||||
const onPage = [...page.matchAll(/<Signature\s+call="(\w+)"/g)].map((m) => m[1]);
|
||||
let covered = true;
|
||||
for (const call of Object.keys(runicnpcCalls)) {
|
||||
const n = onPage.filter((c) => c === call).length;
|
||||
if (n !== 1) {
|
||||
covered = false;
|
||||
fail(`RunicNPC API page: ${call}`, `has ${n} <Signature call="${call}" /> on api.mdx — every call needs exactly one, with its prose`);
|
||||
}
|
||||
}
|
||||
if (covered) ok(`RunicNPC API page covers every call (${onPage.length})`);
|
||||
}
|
||||
|
||||
/** Compare name → signature maps: both directions by name, then each shared name by signature. */
|
||||
function compareSignatures(label, mine, theirs, hint) {
|
||||
compareSets(label, [...mine.keys()], [...theirs.keys()], hint);
|
||||
let same = true;
|
||||
for (const [name, sig] of mine) {
|
||||
if (theirs.has(name) && theirs.get(name) !== sig) {
|
||||
same = false;
|
||||
fail(`${label} ${name}`, `signature differs — here "${sig}", ${hint} "${theirs.get(name)}"`);
|
||||
}
|
||||
}
|
||||
if (same) ok(`${label} signatures (${mine.size})`);
|
||||
}
|
||||
|
||||
/** The text of a C# method, by brace counting from the first brace after its name. */
|
||||
function methodBody(source, name) {
|
||||
const start = source.search(new RegExp(`\\b${name}\\s*\\(`));
|
||||
if (start < 0) return null;
|
||||
const open = source.indexOf('{', start);
|
||||
let depth = 0;
|
||||
for (let i = open; i < source.length; i++) {
|
||||
if (source[i] === '{') depth++;
|
||||
else if (source[i] === '}' && --depth === 0) return source.slice(open + 1, i);
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function checkRunicNpcSource(cs) {
|
||||
const hint = 'runicnpc-rust main:plugin/RunicNPC.cs';
|
||||
|
||||
// The verbs: every `rnpc.<verb>` console command. The chat command answers the same verbs.
|
||||
compareSets(
|
||||
'RunicNPC command',
|
||||
[...new Set(Object.values(runicnpcCommands).flatMap((s) => Object.keys(s)).map((usage) => usage.split(' ')[0]))],
|
||||
[...cs.matchAll(/\[ConsoleCommand\("rnpc\.(\w+)"\)\]/g)].map((m) => m[1]),
|
||||
`${hint} [ConsoleCommand]`,
|
||||
);
|
||||
|
||||
// A command's permission must be one the plugin registers.
|
||||
const perms = [...cs.matchAll(/const\s+string\s+Perm\w+\s*=\s*"(runicnpc\.\w+)"/g)].map((m) => m[1]);
|
||||
compareSets('RunicNPC permission', Object.keys(runicnpcPermissions), perms, `${hint} Perm constants`);
|
||||
for (const [section, commands] of Object.entries(runicnpcCommands)) {
|
||||
for (const [usage, c] of Object.entries(commands)) {
|
||||
if (c.perm.startsWith('runicnpc.') && !perms.includes(c.perm)) {
|
||||
fail(`RunicNPC command ${usage}`, `(${section}) needs "${c.perm}", which the plugin does not register`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const options = methodBody(cs, 'ParseOptions');
|
||||
if (!options) fail('RunicNPC place option', `could not find ParseOptions in ${hint}`);
|
||||
else {
|
||||
compareSets(
|
||||
'RunicNPC place option',
|
||||
Object.keys(runicnpcPlaceOptions),
|
||||
[...options.matchAll(/case\s+"(\w+)":/g)].map((m) => m[1]),
|
||||
`${hint} ParseOptions`,
|
||||
);
|
||||
}
|
||||
|
||||
// The config: `[JsonProperty("name")] public Type Field`, and a field whose type is another
|
||||
// config class is a section, its keys written `section.key`.
|
||||
const jsonKeys = (className, prefix = '') => {
|
||||
const body = classBody(cs, className);
|
||||
if (!body) return null;
|
||||
return [...body.matchAll(/\[JsonProperty\("(\w+)"\)\]\s*public\s+(\w+)\s+\w+/g)].flatMap(([, key, type]) => {
|
||||
const nested = /Config$/.test(type) ? jsonKeys(type, `${prefix}${key}.`) : null;
|
||||
return nested ?? [`${prefix}${key}`];
|
||||
});
|
||||
};
|
||||
const configKeys = jsonKeys('PluginConfig');
|
||||
if (!configKeys) fail('RunicNPC.json', `could not find class PluginConfig in ${hint}`);
|
||||
else compareSets('RunicNPC.json', Object.keys(runicnpcConfig), configKeys, `${hint} PluginConfig`);
|
||||
}
|
||||
|
||||
async function run() {
|
||||
if (!TOKEN) {
|
||||
console.error('checkReference: GITEA_TOKEN is not set. This check cannot run anonymously.');
|
||||
@@ -116,13 +372,12 @@ async function run() {
|
||||
// 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');
|
||||
compareSets(
|
||||
'sidecar.toml',
|
||||
Object.keys(sidecarConfig),
|
||||
tomlKeysOf(await raw('link', 'sidecar/src/config.rs')),
|
||||
'link main:sidecar/src/config.rs',
|
||||
);
|
||||
|
||||
// ── 3. Installer commands ─────────────────────────────────────────────────
|
||||
const cliRs = await raw('installer', 'src/cli.rs');
|
||||
@@ -162,13 +417,94 @@ async function run() {
|
||||
//
|
||||
// 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)) {
|
||||
for (const docPath of Object.values(canonicalDocs).flatMap((group) => Object.keys(group))) {
|
||||
const url = `${BASE}/api/v1/repos/${ORG}/docs/contents/${docPath}?ref=main`;
|
||||
const res = await fetch(url, { headers: { Authorization: `token ${TOKEN}` } });
|
||||
if (res.ok) ok(`canonical doc ${docPath}`);
|
||||
else fail(`canonical doc ${docPath}`, `not found in docs main (HTTP ${res.status})`);
|
||||
}
|
||||
|
||||
// ── 7. Rust: rust-link's sidecar.toml, and the variables that override it ──
|
||||
//
|
||||
// PLAN.md §16, phase 15. The same parser as uo-link's — both sidecars declare their file
|
||||
// as serde structs — plus the environment overrides, which a Pterodactyl egg sets and an
|
||||
// operator meets on the panel before they ever see the file.
|
||||
const rustConfigRs = await raw('Rust-Link', 'sidecar/src/config.rs');
|
||||
compareSets(
|
||||
'rust-link sidecar.toml',
|
||||
Object.keys(rustSidecarConfig),
|
||||
tomlKeysOf(rustConfigRs),
|
||||
'Rust-Link main:sidecar/src/config.rs',
|
||||
);
|
||||
compareSets(
|
||||
'rust-link environment variable',
|
||||
Object.keys(rustSidecarEnv),
|
||||
[...rustConfigRs.matchAll(/get\("(RUSTLINK_[A-Z_]+)"\)/g)].map((m) => m[1]),
|
||||
'Rust-Link main:sidecar/src/config.rs',
|
||||
);
|
||||
for (const [envName, key] of Object.entries(rustSidecarEnv)) {
|
||||
if (!(key in rustSidecarConfig)) fail(`rust-link environment variable ${envName}`, `says it overrides "${key}", which is not a key listed here`);
|
||||
}
|
||||
|
||||
// ── 8. Rust: the bridge plugin's RunicGateway.json ────────────────────────
|
||||
//
|
||||
// The public fields of `PluginConfig`, which the framework serialises as the file.
|
||||
const pluginCs = await raw('Rust-Plugins', 'overlay/oxide/plugins/RunicGateway.cs');
|
||||
const pluginBody = classBody(pluginCs, 'PluginConfig');
|
||||
if (!pluginBody) {
|
||||
fail('RunicGateway.json', 'could not find class PluginConfig in Rust-Plugins main:overlay/oxide/plugins/RunicGateway.cs');
|
||||
} else {
|
||||
compareSets(
|
||||
'RunicGateway.json',
|
||||
Object.values(rustPluginConfig).flatMap((group) => Object.keys(group)),
|
||||
[...pluginBody.matchAll(/public\s+[\w<>[\],]+\s+(\w+)\s*=/g)].map((m) => m[1]),
|
||||
'Rust-Plugins main:overlay/oxide/plugins/RunicGateway.cs PluginConfig',
|
||||
);
|
||||
}
|
||||
|
||||
// ── 9. Rust: the event kinds, and who may see each ────────────────────────
|
||||
//
|
||||
// D71: checked against the module's own catalogue, because the module is what enforces
|
||||
// the boundary (the same reasoning as check 5). Three comparisons, each a security
|
||||
// statement: a kind listed public here must be public there, a presence kind must be one
|
||||
// of the module's presence kinds, and a staff kind must be staff there. A kind moved from
|
||||
// staff to public upstream fails this check twice over, which is the point.
|
||||
const catalogue = await raw('Module-Rust', 'server/catalogue.js');
|
||||
const upPublic = frozenListOf(catalogue, 'PUBLIC_KINDS');
|
||||
const upStaff = frozenListOf(catalogue, 'STAFF_KINDS');
|
||||
const upPresence = frozenListOf(catalogue, 'PRESENCE_KINDS');
|
||||
if (!upPublic || !upStaff || !upPresence) {
|
||||
fail('Rust event kinds', 'could not find PUBLIC_KINDS, STAFF_KINDS and PRESENCE_KINDS in Module-Rust main:server/catalogue.js');
|
||||
} else {
|
||||
const hint = 'Module-Rust main:server/catalogue.js';
|
||||
compareSets('Rust presence kind', Object.keys(rustEventKinds.presence), upPresence, `${hint} PRESENCE_KINDS`);
|
||||
compareSets(
|
||||
'Rust public kind',
|
||||
Object.keys(rustEventKinds.public),
|
||||
upPublic.filter((k) => !upPresence.includes(k)),
|
||||
`${hint} PUBLIC_KINDS (less its presence kinds)`,
|
||||
);
|
||||
compareSets('Rust staff kind', Object.keys(rustEventKinds.staff), upStaff, `${hint} STAFF_KINDS`);
|
||||
for (const k of upPresence) {
|
||||
if (!upPublic.includes(k)) fail(`Rust presence kind ${k}`, 'is a presence kind upstream but not a public one — the page explains presence as a narrowing of public, so re-read it');
|
||||
}
|
||||
}
|
||||
|
||||
// ── 10. RunicNPC: the API, against its specification ──────────────────────
|
||||
//
|
||||
// PLAN.md §16, D62 and D73. The one place this site carries a contract in full rather than
|
||||
// linking to it, so the one place it must be held to the contract most tightly: every call
|
||||
// and hook by its whole signature, and every field name of every data shape, both ways.
|
||||
// `docs` `main:runicnpc/API.md` is normative, so it is the authority, not the plugin source.
|
||||
await checkRunicNpcApi(await raw('docs', 'runicnpc/API.md'));
|
||||
|
||||
// ── 11. RunicNPC: the commands, permissions, options and config ───────────
|
||||
//
|
||||
// Names, checked against the plugin's own source the way RunicGateway.json is (check 8):
|
||||
// the console verbs it registers, the permissions it registers, the `key=` options
|
||||
// `place` and `here` parse, and the JSON keys of its config classes.
|
||||
checkRunicNpcSource(await raw('runicnpc-rust', 'plugin/RunicNPC.cs'));
|
||||
|
||||
// ── Report ────────────────────────────────────────────────────────────────
|
||||
if (failures.length === 0) {
|
||||
console.log(`checkReference: ${checked.length} enumeration check(s) passed against their sources.`);
|
||||
|
||||
@@ -22,13 +22,15 @@
|
||||
* No token and no network: both trees are in this repository.
|
||||
*/
|
||||
|
||||
import { docsSidebar, plannedSidebar } from '../src/config/sidebar.mjs';
|
||||
import { docsSidebar, plannedSidebar, flatLabels } 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));
|
||||
// A nested group (RunicNPC inside Rust, phase 16) flattens to `Group › Page` labels, so its
|
||||
// pages and their order are held to the plan exactly as a top-level group's are.
|
||||
const live = new Map(docsSidebar.map((g) => [g.label, flatLabels(g.items)]));
|
||||
const planned = new Map(Object.entries(plannedSidebar).map(([label, items]) => [label, flatLabels(items)]));
|
||||
|
||||
// ── Groups ──────────────────────────────────────────────────────────────────
|
||||
for (const label of live.keys()) {
|
||||
|
||||
271
scripts/checkTerms.mjs
Normal file
271
scripts/checkTerms.mjs
Normal file
@@ -0,0 +1,271 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* checkTerms.mjs — PLAN.md §16, D63 and D64. The twelfth check, added in phase 14.
|
||||
*
|
||||
* D63: outside a game's own section, the site may NAME the games it supports, but it may not
|
||||
* use their VOCABULARY. Core concepts keep core's names — a Team, a game server, the sidecar,
|
||||
* the bridge plugin, the game module — because that is what core itself calls them, and a
|
||||
* site that says "shard" on a core page is describing one game's deployment as though it were
|
||||
* the platform.
|
||||
*
|
||||
* D64: a convention that holds only while everyone remembers it does not hold. This is the
|
||||
* same argument `checkTokens.mjs` makes for colours, applied to words. The vocabulary problem
|
||||
* was measured before this check existed — "shard" 227 times in 45 files — and none of that
|
||||
* was anybody's decision; it was the residue of a site written while there was one game.
|
||||
*
|
||||
* What it reads, as of phase 14:
|
||||
*
|
||||
* - every page under `src/content/docs`, frontmatter included (a title and a description
|
||||
* are what a reader sees first, in the sidebar and in search results);
|
||||
* - `src/config/sidebar.mjs`, as DATA rather than as text: every group label and every
|
||||
* page label, in both trees. Its comments are not scanned, because a comment is not
|
||||
* something a reader of the site ever sees.
|
||||
*
|
||||
* Phase 17 widens it to all of `src/`, once the marketing pages have a game page to move
|
||||
* their game content to. That is also when it learns D67's screenshot tag.
|
||||
*
|
||||
* Where a game's words are allowed:
|
||||
*
|
||||
* - in that game's own docs directory (`GAME_DIRS`), and its own sidebar group — a group
|
||||
* whose label is the game's `name` in `platform.json`;
|
||||
* - between `<GameExample game="…">` tags on a core page (D68). The component prints the
|
||||
* game's name above the block, so the words arrive already labelled.
|
||||
*
|
||||
* What is NOT read, deliberately:
|
||||
*
|
||||
* - link targets and bare URLs. A repository is called what it is called, and an address is
|
||||
* not prose. The LINK TEXT is read, so `[Module-uo](…)` fails and `[releases](…)` passes;
|
||||
* - `import` lines and `{…}` expressions. They are code, and what an expression renders is
|
||||
* a value from `platform.json` or `src/data/`, which phase 17 brings into scope.
|
||||
*
|
||||
* node scripts/checkTerms.mjs
|
||||
*
|
||||
* No token and no network: everything it reads is in this repository.
|
||||
*/
|
||||
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { readdir } from 'node:fs/promises';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import path from 'node:path';
|
||||
|
||||
import { docsSidebar, plannedSidebar, flatLabels } from '../src/config/sidebar.mjs';
|
||||
|
||||
const ROOT = fileURLToPath(new URL('..', import.meta.url));
|
||||
const platform = JSON.parse(readFileSync(path.join(ROOT, 'src/data/platform.json'), 'utf8'));
|
||||
|
||||
/**
|
||||
* The words, each tagged with the game it belongs to. Matching is case-insensitive and on
|
||||
* word boundaries, so "shard" does not match `SHARD_VISIBILITY` and "wipe" does not match
|
||||
* "wiped" unless it is listed.
|
||||
*
|
||||
* A word is on this list because it is a game's name for something core has its own name for
|
||||
* (shard → game server, guild and clan → Team), or because it names one game's component
|
||||
* (uo-link → the sidecar, ServUO → the game server). Game NAMES — Ultima Online, UO, Rust —
|
||||
* are not on it: D63 allows them everywhere. Steam is not on it either: Steam sign-in is a
|
||||
* core identity provider, even though Rust was its first user.
|
||||
*/
|
||||
const TERMS = [
|
||||
{ game: 'uo', word: 'shard', re: /\bshards?\b/gi },
|
||||
{ game: 'uo', word: 'ServUO', re: /\bservuo\b/gi },
|
||||
{ game: 'uo', word: 'uo-link', re: /\buo-?link\b/gi },
|
||||
{ game: 'uo', word: 'Module-uo', re: /\bmodule-uo\b/gi },
|
||||
{ game: 'uo', word: 'Bridge.cfg', re: /\bbridge\.cfg\b/gi },
|
||||
{ game: 'uo', word: 'cliloc', re: /\bclilocs?\b/gi },
|
||||
{ game: 'uo', word: 'guild', re: /\bguilds?\b/gi },
|
||||
{ game: 'uo', word: 'IDOC', re: /\bidocs?\b/gi },
|
||||
{ game: 'rust', word: 'rust-link', re: /\brust-?link\b/gi },
|
||||
{ game: 'rust', word: 'Rust-Plugins', re: /\brust-plugins\b/gi },
|
||||
{ game: 'rust', word: 'Module-Rust', re: /\bmodule-rust\b/gi },
|
||||
{ game: 'rust', word: 'Oxide', re: /\boxide\b/gi },
|
||||
{ game: 'rust', word: 'Carbon', re: /\bcarbon\b/gi },
|
||||
{ game: 'rust', word: 'uMod', re: /\bumod\b/gi },
|
||||
{ game: 'rust', word: 'clan', re: /\bclans?\b/gi },
|
||||
{ game: 'rust', word: 'wipe', re: /\bwipes?\b/gi },
|
||||
];
|
||||
|
||||
/** Each game's own docs directory. A page under one may use that game's words. */
|
||||
const GAME_DIRS = {
|
||||
uo: 'src/content/docs/docs/ultima-online/',
|
||||
rust: 'src/content/docs/docs/rust/',
|
||||
};
|
||||
|
||||
/**
|
||||
* The allowlist: an exact phrase in one file that may use a word the rule would otherwise
|
||||
* refuse. Short on purpose, and every entry says why. An entry that no longer matches its
|
||||
* file fails the check too, so the list cannot rot into a set of permanent exemptions.
|
||||
*/
|
||||
const ALLOW = [
|
||||
{
|
||||
file: 'src/content/docs/docs/administration/notifications-and-email.mdx',
|
||||
text: 'Guild (server) ID',
|
||||
why: "Discord's own word, not a game's: it is the label on core's Discord Bot screen.",
|
||||
},
|
||||
];
|
||||
|
||||
for (const game of Object.keys(GAME_DIRS)) {
|
||||
if (!platform.games[game]) throw new Error(`checkTerms: GAME_DIRS names "${game}", which platform.json does not.`);
|
||||
}
|
||||
for (const t of TERMS) {
|
||||
if (!platform.games[t.game]) throw new Error(`checkTerms: "${t.word}" is tagged "${t.game}", which platform.json does not know.`);
|
||||
}
|
||||
|
||||
const failures = [];
|
||||
const fail = (where, detail) => failures.push({ where, detail });
|
||||
|
||||
/** Replace a span with spaces, keeping newlines, so later line numbers stay true. */
|
||||
const blank = (text) => text.replace(/[^\n]/g, ' ');
|
||||
|
||||
/** The game whose directory holds this file, or null for a core page. */
|
||||
function gameOfPath(relative) {
|
||||
const posix = relative.split(path.sep).join('/');
|
||||
for (const [game, dir] of Object.entries(GAME_DIRS)) if (posix.startsWith(dir)) return game;
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Turn an MDX source into the text a reader would actually see, with everything that is not
|
||||
* prose blanked out. Returns that text plus the GameExample regions, as offsets into it.
|
||||
*/
|
||||
function proseOf(source, relative) {
|
||||
let text = source;
|
||||
|
||||
// GameExample regions first, while the tags are still intact. Recorded, then the tags
|
||||
// themselves are blanked so the attribute does not read as prose.
|
||||
const regions = [];
|
||||
for (const m of text.matchAll(/<GameExample\s+game="([^"]*)"\s*>([\s\S]*?)<\/GameExample>/g)) {
|
||||
const game = m[1];
|
||||
if (!platform.games[game]) {
|
||||
fail(`${relative}:${lineOf(source, m.index)}`, `<GameExample game="${game}"> names a game platform.json does not have`);
|
||||
}
|
||||
regions.push({ game, start: m.index, end: m.index + m[0].length });
|
||||
}
|
||||
text = text.replace(/<\/?GameExample\b[^>]*>/g, blank);
|
||||
|
||||
text = text.replace(/<!--[\s\S]*?-->/g, blank); // HTML comments
|
||||
text = text.replace(/^import\s.*$/gm, blank); // MDX imports
|
||||
text = text.replace(/\]\([^)\s]*\)/g, (m) => '] ' + blank(m.slice(2))); // link targets, not their text
|
||||
text = text.replace(/\b(?:href|src)=(?:"[^"]*"|\{`[^`]*`\})/g, blank); // JSX/HTML link targets
|
||||
text = text.replace(/\bhttps?:\/\/[^\s)>"'`]+/g, blank); // bare URLs
|
||||
|
||||
// `{…}` expressions, outside code fences only — a fenced JSON example's braces are prose.
|
||||
// Innermost first, repeatedly, so nested and multi-line expressions both go.
|
||||
const parts = text.split(/(^```[\s\S]*?^```)/m);
|
||||
for (let i = 0; i < parts.length; i += 2) {
|
||||
let prev;
|
||||
do {
|
||||
prev = parts[i];
|
||||
parts[i] = parts[i].replace(/\{[^{}]*\}/g, blank);
|
||||
} while (parts[i] !== prev);
|
||||
}
|
||||
text = parts.join('');
|
||||
|
||||
return { text, regions };
|
||||
}
|
||||
|
||||
function lineOf(source, index) {
|
||||
return source.slice(0, index).split('\n').length;
|
||||
}
|
||||
|
||||
/** Hits for every term the given context may not use. */
|
||||
function scan(text, allowedGame) {
|
||||
const hits = [];
|
||||
for (const t of TERMS) {
|
||||
if (t.game === allowedGame) continue;
|
||||
t.re.lastIndex = 0;
|
||||
for (const m of text.matchAll(t.re)) hits.push({ term: t, value: m[0], index: m.index });
|
||||
}
|
||||
return hits;
|
||||
}
|
||||
|
||||
async function* walk(dir) {
|
||||
let entries;
|
||||
try {
|
||||
entries = await readdir(dir, { withFileTypes: true });
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
for (const entry of entries) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) yield* walk(full);
|
||||
else if (/\.mdx?$/.test(entry.name)) yield full;
|
||||
}
|
||||
}
|
||||
|
||||
// ── 1. The documentation pages ──────────────────────────────────────────────
|
||||
let files = 0;
|
||||
const allowUsed = new Set();
|
||||
|
||||
for await (const file of walk(path.join(ROOT, 'src', 'content', 'docs'))) {
|
||||
const relative = path.relative(ROOT, file).split(path.sep).join('/');
|
||||
const posix = relative;
|
||||
const source = readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
|
||||
files++;
|
||||
|
||||
let { text, regions } = proseOf(source, relative);
|
||||
|
||||
for (const [i, entry] of ALLOW.entries()) {
|
||||
if (entry.file !== posix) continue;
|
||||
if (text.includes(entry.text)) {
|
||||
allowUsed.add(i);
|
||||
text = text.split(entry.text).join(blank(entry.text));
|
||||
}
|
||||
}
|
||||
|
||||
const pageGame = gameOfPath(relative);
|
||||
for (const hit of scan(text, pageGame)) {
|
||||
const region = regions.find((r) => hit.index >= r.start && hit.index < r.end);
|
||||
if (region && region.game === hit.term.game) continue;
|
||||
const where = region ? `inside <GameExample game="${region.game}">` : pageGame ? `in the ${platform.games[pageGame].name} group` : 'on a core page';
|
||||
fail(
|
||||
`${relative}:${lineOf(source, hit.index)}`,
|
||||
`"${hit.value}" is ${platform.games[hit.term.game].name} vocabulary, ${where}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
for (const [i, entry] of ALLOW.entries()) {
|
||||
if (!allowUsed.has(i)) {
|
||||
fail(`allowlist: ${entry.file}`, `"${entry.text}" no longer appears there — remove the entry`);
|
||||
}
|
||||
}
|
||||
|
||||
// ── 2. The sidebar, as data ─────────────────────────────────────────────────
|
||||
const gameByName = new Map(Object.entries(platform.games).map(([key, g]) => [g.name, key]));
|
||||
const trees = [
|
||||
['docsSidebar', docsSidebar.map((g) => [g.label, flatLabels(g.items)])],
|
||||
['plannedSidebar', Object.entries(plannedSidebar).map(([label, items]) => [label, flatLabels(items)])],
|
||||
];
|
||||
let labels = 0;
|
||||
for (const [treeName, groups] of trees) {
|
||||
for (const [groupLabel, items] of groups) {
|
||||
const game = gameByName.get(groupLabel) ?? null;
|
||||
for (const label of [groupLabel, ...items]) {
|
||||
labels++;
|
||||
for (const hit of scan(label, game)) {
|
||||
fail(
|
||||
`src/config/sidebar.mjs ${treeName} → ${groupLabel}`,
|
||||
`"${label}" uses "${hit.value}", ${platform.games[hit.term.game].name} vocabulary, ${game ? `in the ${platform.games[game].name} group` : 'in a core group'}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ── Report ──────────────────────────────────────────────────────────────────
|
||||
if (failures.length === 0) {
|
||||
console.log(
|
||||
`checkTerms: ${files} docs pages and ${labels} sidebar labels use only their own game's words ` +
|
||||
`(${TERMS.length} terms, ${ALLOW.length} allowlisted phrase${ALLOW.length === 1 ? '' : 's'}).`,
|
||||
);
|
||||
} else {
|
||||
console.error(`\ncheckTerms: ${failures.length} game word(s) outside their game's section:\n`);
|
||||
for (const f of failures) console.error(` ✗ ${f.where}\n ${f.detail}`);
|
||||
console.error(`
|
||||
PLAN.md §16, D63: name the games anywhere, but keep their vocabulary in their own section.
|
||||
Use core's word instead — a Team, a game server, the sidecar, the bridge plugin, the game
|
||||
module. If a core page genuinely needs a game's real example, wrap it in
|
||||
<GameExample game="…"> (D68), which labels it with the game's name. Add to the allowlist
|
||||
in this script only for a word that is not a game's at all, and say why.
|
||||
`);
|
||||
process.exit(1);
|
||||
}
|
||||
@@ -14,7 +14,7 @@
|
||||
* 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 4 wire protocol to pin — see the note below
|
||||
* UOLINK_PROTOCOL (platform.json) wire protocol to pin — see the note below
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* WHY THE SEED DRIVES THE API AND NEVER THE DATABASE
|
||||
@@ -45,6 +45,8 @@
|
||||
|
||||
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';
|
||||
@@ -53,16 +55,21 @@ 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 has to be STATED, not left to the module's default.
|
||||
// The pinned wire protocol, read from `platform.json` rather than written down here.
|
||||
//
|
||||
// `module-uo`'s schema fragment still carries `protocol INT NOT NULL DEFAULT 3`, from the
|
||||
// protocol-3 cutover; the sidecar on `link` `main` speaks 4. The module handles protocol 4's
|
||||
// frames — `guild.roster` and `guild.leave` ingest landed with the Teams cutover — but a
|
||||
// FRESH install pins 3, and the sidecar answers a 3 with `409 protocol version mismatch` on
|
||||
// every REST call. So a new deployment reads nothing from its shard until somebody edits the
|
||||
// number in Admin → Shard. Raised with the org lead rather than patched from here: the fix
|
||||
// belongs in `module-uo`, not in this repo's screenshot rig (PLAN.md §13 phase 9).
|
||||
const UOLINK_PROTOCOL = Number(process.env.UOLINK_PROTOCOL || 4);
|
||||
// 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');
|
||||
|
||||
|
||||
204
scripts/serve.mjs
Normal file
204
scripts/serve.mjs
Normal file
@@ -0,0 +1,204 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* serve.mjs — the production entry point (PLAN.md §6, D48, D56).
|
||||
*
|
||||
* `npm start` runs `applyBrand.mjs` and then this, instead of `dist/server/entry.mjs`
|
||||
* directly. It is a thin wrapper around the adapter's own handler and exists for three
|
||||
* reasons, two of them things `@astrojs/node` gets wrong.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* 1. THE ADAPTER SERVES THE WRONG PAGE'S CONTENT-SECURITY-POLICY
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* `@astrojs/node`'s `staticHeaders` writes one policy per prerendered route into
|
||||
* `dist/_headers.json` and looks the right one up per request. The lookup, in
|
||||
* `dist/serve-static.js`, is:
|
||||
*
|
||||
* headersMap.find((header) => header.pathname.includes(baselessPathname))
|
||||
*
|
||||
* `String.includes` — a SUBSTRING test, not equality, taking the first match. So:
|
||||
*
|
||||
* - `/modules/` matches the record for `/docs/modules/building-a-module`,
|
||||
* - `/architecture/` matches `/docs/architecture/...`,
|
||||
* - and `/`, which is a substring of every path in the file, matches whichever record
|
||||
* happens to be first — here `/404`.
|
||||
*
|
||||
* Every prerendered page was therefore served some other page's policy. Because the
|
||||
* policies are per-page hash lists, that is not a cosmetic mismatch: the browser refused
|
||||
* the page's own stylesheet. `/modules/` and `/architecture/` rendered unstyled sections
|
||||
* with `Refused to apply inline style` in a console, and the homepage only looked fine
|
||||
* because it happens to share a hash with the 404 page.
|
||||
*
|
||||
* Astro's static-header machinery is otherwise exactly what §6 wants, so this replaces the
|
||||
* lookup rather than the mechanism: the same `_headers.json`, matched by pathname
|
||||
* EQUALITY. The workaround is deliberately small and obvious so it can be deleted whole
|
||||
* when the upstream `find` is fixed — the check for that is whether `/modules/` and
|
||||
* `/docs/modules/building-a-module` are served different policies.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* 2. THE HEADERS THAT ARE NOT CSP
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* A few security headers have nothing to do with Astro and no other place to live. They
|
||||
* are set here rather than written into an operator's reverse-proxy configuration (D48,
|
||||
* again): the container should be correct on its own, and a proxy someone else configures
|
||||
* is a promise this repository cannot check.
|
||||
*
|
||||
* The two routes that render per request — `/beta` and `/brand/*` — have no entry in
|
||||
* `_headers.json`, because nothing prerendered them. They get `frame-ancestors 'none'` on
|
||||
* its own, which is the one directive a `<meta>` CSP cannot express and therefore the one
|
||||
* thing Astro's per-page meta tag leaves them missing.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import http from 'node:http';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath, pathToFileURL } from 'node:url';
|
||||
|
||||
const here = path.dirname(fileURLToPath(import.meta.url));
|
||||
const root = path.join(here, '..');
|
||||
|
||||
const port = Number(process.env.PORT ?? 4321);
|
||||
const host = process.env.HOST ?? '0.0.0.0';
|
||||
|
||||
/* ---------------------------------------------------------------------------------------
|
||||
The policies, matched exactly
|
||||
--------------------------------------------------------------------------------------- */
|
||||
|
||||
const normalise = (pathname) => {
|
||||
const clean = pathname.split('?')[0].split('#')[0];
|
||||
const trimmed = clean.replace(/\/+$/, '');
|
||||
return trimmed === '' ? '/' : trimmed;
|
||||
};
|
||||
|
||||
const policies = new Map();
|
||||
const headersFile = path.join(root, 'dist', '_headers.json');
|
||||
|
||||
if (fs.existsSync(headersFile)) {
|
||||
for (const record of Object.values(JSON.parse(fs.readFileSync(headersFile, 'utf8')))) {
|
||||
const csp = record.headers?.find((h) => h.key.toLowerCase() === 'content-security-policy');
|
||||
if (csp) policies.set(normalise(record.pathname), csp.value);
|
||||
}
|
||||
} else {
|
||||
// Not fatal: the site still serves, with the per-page <meta> policy Astro also emits.
|
||||
// Loud, because a deployment silently losing its response-header CSP is exactly what §6
|
||||
// is trying to prevent.
|
||||
console.error(
|
||||
'[serve] dist/_headers.json is missing — pages will be served without a CSP response\n' +
|
||||
' header. Check that astro.config.mjs still sets `staticHeaders: true`.'
|
||||
);
|
||||
}
|
||||
|
||||
const FRAME_ONLY = "frame-ancestors 'none'";
|
||||
|
||||
/**
|
||||
* Headers with no page-by-page component. Each is the browser default made explicit, and
|
||||
* each closes something the CSP does not:
|
||||
*
|
||||
* - `X-Content-Type-Options` stops a browser guessing that a .txt is HTML.
|
||||
* - `Referrer-Policy` keeps the path of the page a reader came from out of requests to
|
||||
* other origins — there are none today (D9), and this is what keeps that true if a
|
||||
* link is ever followed off-site.
|
||||
* - `X-Frame-Options` says again, for anything too old to honour `frame-ancestors`.
|
||||
* - `Permissions-Policy` turns off hardware this site has no reason to ask for. A
|
||||
* marketing page requesting a camera should be impossible, not merely unlikely.
|
||||
*/
|
||||
const STATIC_HEADERS = {
|
||||
'X-Content-Type-Options': 'nosniff',
|
||||
'Referrer-Policy': 'strict-origin-when-cross-origin',
|
||||
'X-Frame-Options': 'DENY',
|
||||
'Permissions-Policy': 'camera=(), microphone=(), geolocation=(), payment=(), usb=()',
|
||||
};
|
||||
|
||||
/* ---------------------------------------------------------------------------------------
|
||||
The server
|
||||
--------------------------------------------------------------------------------------- */
|
||||
|
||||
// The adapter's entry starts its own listener on import unless this is set.
|
||||
process.env.ASTRO_NODE_AUTOSTART = 'disabled';
|
||||
|
||||
// `pathToFileURL`, not the bare path: on Windows an absolute path starts with a drive
|
||||
// letter, and Node's ESM loader reads `c:` as an unsupported URL scheme.
|
||||
const { handler } = await import(pathToFileURL(path.join(root, 'dist', 'server', 'entry.mjs')).href);
|
||||
|
||||
/* ---------------------------------------------------------------------------------------
|
||||
3. THE FORWARDED HEADERS THE ADAPTER DOES NOT READ
|
||||
--------------------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Make the request look, to the adapter, like what the browser actually sent.
|
||||
*
|
||||
* `@astrojs/node` builds the URL of every request from the connection and the `Host`
|
||||
* header alone — `astro/app/node`'s `createRequestFromNodeRequest`:
|
||||
*
|
||||
* const isEncrypted = "encrypted" in req.socket && req.socket.encrypted;
|
||||
* const protocol = isEncrypted ? "https" : "http";
|
||||
*
|
||||
* `x-forwarded-proto` is never consulted on this path. (`security.allowedDomains` does not
|
||||
* help: on this code path it gates only whether `Astro.clientAddress` may come from
|
||||
* `x-forwarded-for`.)
|
||||
*
|
||||
* Behind a proxy that terminates TLS — which is how this site is deployed, and the only
|
||||
* way it is deployed — that is fatal to the one route that accepts a POST. The browser
|
||||
* sends `Origin: https://runicgateway.com`; the container computes `http://runicgateway.com`
|
||||
* because its own socket is plaintext; and Astro's CSRF middleware compares the two for
|
||||
* EQUALITY:
|
||||
*
|
||||
* const isSameOrigin = request.headers.get("origin") === url.origin;
|
||||
*
|
||||
* So every beta signup, from every visitor, is answered `403 Cross-site POST form
|
||||
* submissions are forbidden`. No proxy configuration can fix it — a proxy cannot make this
|
||||
* container's socket encrypted — and nothing else on the site changes, so the symptom is a
|
||||
* form that silently refuses everyone while fifty pages look perfectly healthy.
|
||||
*
|
||||
* Both headers are trusted unconditionally, with no flag to set. The image is meant to be
|
||||
* deployed and work: it publishes on loopback for a proxy to reach, and an operator who has
|
||||
* to discover a `TRUST_PROXY` variable to make the signup work is an operator who ships a
|
||||
* dead form. Trusting them costs nothing here — a cross-site form submission cannot make a
|
||||
* victim's browser send `x-forwarded-proto`, so the CSRF check is exactly as strong as it
|
||||
* was, and the site has no cookie, session or credential to protect in the first place.
|
||||
*
|
||||
* `x-forwarded-host` is handled for the same reason at one remove: most proxies pass `Host`
|
||||
* through untouched, but some rewrite it to the upstream address and put the real name here
|
||||
* instead, which produces the identical mismatch.
|
||||
*/
|
||||
const firstForwarded = (value) => value?.toString().split(',')[0].trim();
|
||||
|
||||
const applyForwardedHeaders = (req) => {
|
||||
const proto = firstForwarded(req.headers['x-forwarded-proto']);
|
||||
if (proto === 'https' && !req.socket.encrypted) {
|
||||
// What `"encrypted" in req.socket` reads. Defined on the socket rather than passed
|
||||
// along, because the adapter is given the raw request and looks there itself.
|
||||
Object.defineProperty(req.socket, 'encrypted', { value: true, configurable: true });
|
||||
}
|
||||
|
||||
const forwardedHost = firstForwarded(req.headers['x-forwarded-host']);
|
||||
if (forwardedHost && !/[/\\]/.test(forwardedHost)) {
|
||||
req.headers.host = forwardedHost;
|
||||
}
|
||||
};
|
||||
|
||||
const server = http.createServer((req, res) => {
|
||||
applyForwardedHeaders(req);
|
||||
|
||||
const policy = policies.get(normalise(req.url ?? '/'));
|
||||
|
||||
for (const [key, value] of Object.entries(STATIC_HEADERS)) res.setHeader(key, value);
|
||||
res.setHeader('Content-Security-Policy', policy ?? FRAME_ONLY);
|
||||
|
||||
/**
|
||||
* The adapter will set its own (wrong) `Content-Security-Policy` from inside the static
|
||||
* handler, overwriting what was just set. Rather than race it, every later attempt to
|
||||
* set that one header is ignored — the correct value is already on the response, and
|
||||
* this request's policy cannot change halfway through serving it.
|
||||
*/
|
||||
const setHeader = res.setHeader.bind(res);
|
||||
res.setHeader = (name, value) => {
|
||||
if (String(name).toLowerCase() === 'content-security-policy') return res;
|
||||
return setHeader(name, value);
|
||||
};
|
||||
|
||||
handler(req, res);
|
||||
});
|
||||
|
||||
server.listen(port, host, () => {
|
||||
console.log(`[serve] listening on http://${host}:${port} — ${policies.size} prerendered policies`);
|
||||
});
|
||||
53
src/components/DocsPageTitle.astro
Normal file
53
src/components/DocsPageTitle.astro
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
/**
|
||||
* Overrides Starlight's `PageTitle` for one attribute: `tabindex="-1"` on the heading.
|
||||
*
|
||||
* Phase 10 found and fixed this on the marketing chrome — following a skip link moves the
|
||||
* viewport but not the keyboard focus, because the target of the link is not focusable.
|
||||
* Chrome papers over it; not every browser does, and a reader who lands past the header
|
||||
* only to find Tab returning them to the top of the nav has not been skipped anywhere.
|
||||
* `Base.astro`'s `<main>` gained `tabindex="-1"` then.
|
||||
*
|
||||
* Phase 11's browser walk found the same defect still standing on the other forty pages.
|
||||
* Starlight's skip link points at the page's `<h1>` rather than at a landmark, and an
|
||||
* `<h1>` is no more focusable than a `<main>`, so the docs half of the site had the fix
|
||||
* that the marketing half had.
|
||||
*
|
||||
* The rest of this file is Starlight's own implementation, copied because the override
|
||||
* mechanism replaces a component rather than decorating it. That is a small drift risk —
|
||||
* if Starlight restyles its `h1`, this copy will not follow — so it is deliberately kept
|
||||
* to exactly what upstream has, with nothing of ours added beyond the attribute. The
|
||||
* check for drift is visual: a documentation title that stops matching the marketing
|
||||
* chrome's.
|
||||
*
|
||||
* The id is Starlight's `PAGE_TITLE_ID`, written out rather than imported: `./constants`
|
||||
* is not one of the subpaths the package exports, so importing it reaches past the
|
||||
* package's own boundary. It is what `SkipLink.astro` puts in its `href`, so the two must
|
||||
* agree; if a Starlight upgrade ever renames it, the skip link stops resolving at all and
|
||||
* the first Tab on a documentation page lands somewhere obviously wrong.
|
||||
*/
|
||||
const PAGE_TITLE_ID = '_top';
|
||||
---
|
||||
|
||||
<h1 id={PAGE_TITLE_ID} tabindex="-1">{Astro.locals.starlightRoute.entry.data.title}</h1>
|
||||
|
||||
<style>
|
||||
@layer starlight.core {
|
||||
h1 {
|
||||
margin-top: 1rem;
|
||||
font-size: var(--sl-text-h1);
|
||||
line-height: var(--sl-line-height-headings);
|
||||
font-weight: 600;
|
||||
color: var(--sl-color-white);
|
||||
}
|
||||
|
||||
/* Ours, and the only line that is: the heading is focusable now, so it can be
|
||||
focused, and a focus ring drawn around a page title reads as an error rather than
|
||||
as a destination. Removing it is safe only because this element is reachable by
|
||||
exactly one route — the skip link, which the reader took deliberately. It is never
|
||||
in the tab sequence. */
|
||||
h1:focus {
|
||||
outline: none;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
import { brand } from '../lib/brand.mjs';
|
||||
import { renderBrand } from '../lib/brand.mjs';
|
||||
import { legal } from '../data/legal.mjs';
|
||||
import { footerColumns } from '../data/footer.mjs';
|
||||
import platform from '../data/platform.json';
|
||||
|
||||
/**
|
||||
@@ -13,35 +14,15 @@ import platform from '../data/platform.json';
|
||||
* reader browses to alongside Features, it is a thing they go looking for, and the line
|
||||
* that already carries the licence and the copyright is where people look.
|
||||
*/
|
||||
// `/beta` renders per request, so the footer it gets must read the mount rather than the
|
||||
// value baked at build time. See `renderBrand` in src/lib/brand.mjs (phase 11).
|
||||
const brand = renderBrand(Astro);
|
||||
|
||||
const year = new Date().getFullYear();
|
||||
|
||||
const columns = [
|
||||
{
|
||||
heading: 'Product',
|
||||
links: [
|
||||
{ href: '/features/', label: 'Features' },
|
||||
{ href: '/architecture/', label: 'Architecture' },
|
||||
{ href: '/modules/', label: 'Modules' },
|
||||
{ href: '/app/', label: 'Android app' },
|
||||
],
|
||||
},
|
||||
{
|
||||
heading: 'Documentation',
|
||||
links: [
|
||||
{ href: '/docs/', label: 'Getting started' },
|
||||
{ href: '/docs/', label: 'Administration' },
|
||||
{ href: '/docs/', label: 'Building a module' },
|
||||
],
|
||||
},
|
||||
{
|
||||
heading: 'Project',
|
||||
links: [
|
||||
{ href: brand.giteaOrg, label: 'Source' },
|
||||
{ href: brand.discordInvite, label: 'Discord' },
|
||||
{ href: '/community/', label: 'Community' },
|
||||
],
|
||||
},
|
||||
];
|
||||
// The columns live in src/data/footer.mjs so a test can read them — see the note there,
|
||||
// and test/footer.test.mjs. The two Project links come from the mounted brand (§7).
|
||||
const columns = footerColumns(brand);
|
||||
|
||||
const isExternal = (href: string) => href.startsWith('http');
|
||||
---
|
||||
@@ -81,8 +62,9 @@ const isExternal = (href: string) => href.startsWith('http');
|
||||
</span>
|
||||
</p>
|
||||
<p class="site-footer__meta">
|
||||
<span class="chip chip--version">Protocol {platform.protocol}</span>
|
||||
<span class="chip chip--version">Bundle {platform.bundle.tag}</span>
|
||||
{/* D66, as on the hero: the shared version only. Each game's protocol and bundle
|
||||
are on that game's pages. */}
|
||||
<span class="chip chip--version">Module API {platform.moduleApi}</span>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
37
src/components/GameExample.astro
Normal file
37
src/components/GameExample.astro
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
import platform from '../data/platform.json';
|
||||
|
||||
/**
|
||||
* A worked example that belongs to one game, quoted on a core page (PLAN.md §16, D68).
|
||||
*
|
||||
* D63 keeps a game's vocabulary inside that game's section, but a core page sometimes needs a
|
||||
* real example rather than an invented one: a module manifest, an event dimension, the flag
|
||||
* that tells the installer which game it is setting up. §1 prefers the real thing, because an
|
||||
* invented example is checked by nothing and goes stale without anybody noticing.
|
||||
*
|
||||
* So the example keeps its game's words and says whose they are. This prints the game's name
|
||||
* above the block — the same bargain D67 strikes for a screenshot: a game's words are honest
|
||||
* on a core page when the game is named right beside them. `scripts/checkTerms.mjs` reads the
|
||||
* `game` attribute and allows that game's words, and only that game's, between the tags.
|
||||
*
|
||||
* The name comes from `platform.json` rather than from the caller, so the label cannot say
|
||||
* one game while the attribute that the check reads says another.
|
||||
*/
|
||||
interface Props {
|
||||
/** A key of `platform.json`'s `games`: `uo` or `rust`. */
|
||||
game: keyof typeof platform.games;
|
||||
}
|
||||
|
||||
const { game } = Astro.props;
|
||||
const entry = platform.games[game];
|
||||
if (!entry) {
|
||||
throw new Error(
|
||||
`GameExample: unknown game "${game}". Use a key of platform.json's games: ${Object.keys(platform.games).join(', ')}.`,
|
||||
);
|
||||
}
|
||||
---
|
||||
|
||||
<figure class="game-example" data-game={game}>
|
||||
<figcaption class="game-example__label">{entry.name}</figcaption>
|
||||
<div class="game-example__body"><slot /></div>
|
||||
</figure>
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
import { brand } from '../lib/brand.mjs';
|
||||
import Search from './Search.astro';
|
||||
import { renderBrand } from '../lib/brand.mjs';
|
||||
|
||||
/**
|
||||
* The marketing header. The docs get Starlight's own header, themed to match in
|
||||
@@ -20,6 +21,10 @@ import { brand } from '../lib/brand.mjs';
|
||||
*/
|
||||
const { pathname } = Astro.url;
|
||||
|
||||
// `/beta` renders per request, so the lockup name it gets must read the mount rather than
|
||||
// the value baked at build time. See `renderBrand` in src/lib/brand.mjs (phase 11).
|
||||
const brand = renderBrand(Astro);
|
||||
|
||||
const links = [
|
||||
{ href: '/features/', label: 'Features' },
|
||||
{ href: '/docs/', label: 'Docs' },
|
||||
@@ -55,6 +60,8 @@ const isCurrent = (href: string) =>
|
||||
))
|
||||
}
|
||||
</nav>
|
||||
|
||||
<Search />
|
||||
</div>
|
||||
</header>
|
||||
|
||||
|
||||
279
src/components/Search.astro
Normal file
279
src/components/Search.astro
Normal file
@@ -0,0 +1,279 @@
|
||||
---
|
||||
/**
|
||||
* Site search for the marketing pages (D47).
|
||||
*
|
||||
* The documentation has had search since phase 1 — Starlight builds a Pagefind index at the
|
||||
* end of every build and puts a box in its own header. The marketing pages were outside it
|
||||
* twice over: not indexed, so a reader searching "Teams" in the docs found the architecture
|
||||
* page and never the feature page; and with no box, so a reader who arrived on the homepage
|
||||
* had a four-item nav and no way to ask a question.
|
||||
*
|
||||
* D47 closed both. `Base.astro` marks its `<main>` as a Pagefind body, which puts the ten
|
||||
* marketing pages in the same index the docs already query, and this is the box.
|
||||
*
|
||||
* ── Why it is built this way ────────────────────────────────────────────────
|
||||
* The marketing pages ship almost no JavaScript, and Pagefind's own UI bundle is 120 kB
|
||||
* before the index and the WASM. Loading that on a homepage so that some visitors can
|
||||
* search would be a poor trade, so **nothing is fetched until the dialog is opened** —
|
||||
* the button is inert markup, and the first open injects the stylesheet and the script.
|
||||
* Opening search a second time costs nothing more.
|
||||
*
|
||||
* `<dialog>` rather than a hand-built overlay: the browser gives us the focus trap, the
|
||||
* inert background, Escape-to-close and the top layer for free, and every one of those is
|
||||
* a thing an accessibility pass would otherwise have to find missing.
|
||||
*
|
||||
* In `astro dev` there is no `/pagefind/` — the index is written by the build. Rather than
|
||||
* fail silently, the dialog says so.
|
||||
*/
|
||||
---
|
||||
|
||||
<div class="site-search">
|
||||
<button type="button" class="site-search__open" data-search-open aria-haspopup="dialog">
|
||||
<svg aria-hidden="true" focusable="false" viewBox="0 0 20 20" width="16" height="16">
|
||||
<circle cx="9" cy="9" r="6" fill="none" stroke="currentColor" stroke-width="2"></circle>
|
||||
<line x1="13.5" y1="13.5" x2="18" y2="18" stroke="currentColor" stroke-width="2" stroke-linecap="round"></line>
|
||||
</svg>
|
||||
<span>Search</span>
|
||||
<kbd aria-hidden="true">/</kbd>
|
||||
</button>
|
||||
|
||||
<dialog class="site-search__dialog" data-search-dialog aria-label="Search this site">
|
||||
<div class="site-search__panel">
|
||||
<div class="site-search__head">
|
||||
<h2 class="site-search__title">Search</h2>
|
||||
<button type="button" class="site-search__close" data-search-close>Close</button>
|
||||
</div>
|
||||
<div data-search-mount></div>
|
||||
<p class="site-search__note" data-search-note hidden>
|
||||
Search is built with the site, so it is not available in the dev server. Run
|
||||
<code>npm run build && npm start</code> to try it.
|
||||
</p>
|
||||
</div>
|
||||
</dialog>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
const dialog = document.querySelector<HTMLDialogElement>('[data-search-dialog]');
|
||||
const mount = document.querySelector<HTMLElement>('[data-search-mount]');
|
||||
const note = document.querySelector<HTMLElement>('[data-search-note]');
|
||||
|
||||
if (dialog && mount) {
|
||||
let loaded: Promise<void> | null = null;
|
||||
|
||||
/**
|
||||
* Pagefind's UI bundle is an IIFE that hangs `PagefindUI` off `window`, so it is a
|
||||
* `<script src>` and not a dynamic `import()`. Both are covered by `script-src 'self'`
|
||||
* (D48); the WASM the index needs is why that directive also carries
|
||||
* `'wasm-unsafe-eval'`.
|
||||
*/
|
||||
const load = () =>
|
||||
(loaded ??= new Promise<void>((resolve, reject) => {
|
||||
const css = document.createElement('link');
|
||||
css.rel = 'stylesheet';
|
||||
css.href = '/pagefind/pagefind-ui.css';
|
||||
document.head.append(css);
|
||||
|
||||
const js = document.createElement('script');
|
||||
js.src = '/pagefind/pagefind-ui.js';
|
||||
js.onload = () => {
|
||||
new (window as any).PagefindUI({
|
||||
element: mount,
|
||||
showSubResults: true,
|
||||
showImages: false,
|
||||
// `resetStyles: false` was tried and is wrong here. Pagefind's reset is what
|
||||
// styles its own input and buttons; without it they fall back to user-agent
|
||||
// defaults, which on this ground meant black text typed into a dark field and
|
||||
// a Clear button with a 1990s `outset` border. The palette is bound to our
|
||||
// tokens below instead, which is the supported way round.
|
||||
translations: {
|
||||
placeholder: 'Search the site and documentation',
|
||||
zero_results: 'Nothing found for [SEARCH_TERM]',
|
||||
},
|
||||
});
|
||||
resolve();
|
||||
};
|
||||
js.onerror = () => reject(new Error('pagefind-ui.js did not load'));
|
||||
document.head.append(js);
|
||||
}).catch((error) => {
|
||||
// A dev server, or a build served without its index. Say which.
|
||||
if (note) note.hidden = false;
|
||||
loaded = null;
|
||||
throw error;
|
||||
}));
|
||||
|
||||
const open = () => {
|
||||
// Deliberately not awaited: the dialog should appear at once and fill in, rather
|
||||
// than the button seeming dead for as long as the bundle takes.
|
||||
load().catch(() => {});
|
||||
if (!dialog.open) dialog.showModal();
|
||||
window.setTimeout(() => {
|
||||
dialog.querySelector<HTMLInputElement>('input[type="text"]')?.focus();
|
||||
}, 50);
|
||||
};
|
||||
|
||||
document
|
||||
.querySelectorAll<HTMLButtonElement>('[data-search-open]')
|
||||
.forEach((button) => button.addEventListener('click', open));
|
||||
|
||||
document
|
||||
.querySelectorAll<HTMLButtonElement>('[data-search-close]')
|
||||
.forEach((button) => button.addEventListener('click', () => dialog.close()));
|
||||
|
||||
// Clicking the backdrop closes it. `<dialog>` reports backdrop clicks as clicks on the
|
||||
// dialog itself, so the test is whether the click landed outside the panel's box.
|
||||
dialog.addEventListener('click', (event) => {
|
||||
if (event.target !== dialog) return;
|
||||
const box = dialog.getBoundingClientRect();
|
||||
const outside =
|
||||
event.clientX < box.left ||
|
||||
event.clientX > box.right ||
|
||||
event.clientY < box.top ||
|
||||
event.clientY > box.bottom;
|
||||
if (outside) dialog.close();
|
||||
});
|
||||
|
||||
/**
|
||||
* `/` and Ctrl/⌘-K, the two the documentation already answers to — the shortcut a
|
||||
* reader learns in the docs should work on the way back out.
|
||||
*/
|
||||
document.addEventListener('keydown', (event) => {
|
||||
if (dialog.open) return;
|
||||
const target = event.target as HTMLElement | null;
|
||||
const typing =
|
||||
target?.isContentEditable ||
|
||||
['INPUT', 'TEXTAREA', 'SELECT'].includes(target?.tagName ?? '');
|
||||
if (typing) return;
|
||||
|
||||
if (event.key === '/' || ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k')) {
|
||||
event.preventDefault();
|
||||
open();
|
||||
}
|
||||
});
|
||||
}
|
||||
</script>
|
||||
|
||||
<style>
|
||||
.site-search__open {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 0.5rem;
|
||||
padding: 0.4rem 0.7rem;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: var(--radius-pill);
|
||||
background: transparent;
|
||||
color: var(--muted);
|
||||
font: inherit;
|
||||
font-size: 0.92rem;
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
.site-search__open:hover {
|
||||
color: var(--ink);
|
||||
border-color: var(--gold);
|
||||
}
|
||||
|
||||
.site-search__open kbd {
|
||||
padding: 0 0.35rem;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 4px;
|
||||
font: inherit;
|
||||
font-size: 0.78rem;
|
||||
line-height: 1.4;
|
||||
}
|
||||
|
||||
/* Narrow viewports get the icon alone: the header has a lockup and four links to fit,
|
||||
and "Search" beside a magnifier is the word the icon already says. */
|
||||
@media (max-width: 46rem) {
|
||||
.site-search__open span,
|
||||
.site-search__open kbd {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.site-search__open {
|
||||
padding: 0.45rem;
|
||||
}
|
||||
}
|
||||
|
||||
.site-search__dialog {
|
||||
width: min(46rem, calc(100vw - 2rem));
|
||||
margin-inline: auto;
|
||||
margin-block-start: min(12vh, 6rem);
|
||||
padding: 0;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: var(--radius-panel);
|
||||
background: var(--panel-flat);
|
||||
color: var(--ink);
|
||||
}
|
||||
|
||||
.site-search__dialog::backdrop {
|
||||
background: var(--scrim);
|
||||
}
|
||||
|
||||
.site-search__panel {
|
||||
padding: 1.1rem 1.25rem 1.4rem;
|
||||
}
|
||||
|
||||
.site-search__head {
|
||||
display: flex;
|
||||
align-items: baseline;
|
||||
justify-content: space-between;
|
||||
gap: 1rem;
|
||||
margin-bottom: 0.85rem;
|
||||
}
|
||||
|
||||
.site-search__title {
|
||||
margin: 0;
|
||||
font-size: 1.05rem;
|
||||
letter-spacing: 0.02em;
|
||||
}
|
||||
|
||||
.site-search__close {
|
||||
border: 0;
|
||||
background: transparent;
|
||||
color: var(--muted);
|
||||
font: inherit;
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
.site-search__close:hover {
|
||||
color: var(--ink);
|
||||
}
|
||||
|
||||
.site-search__note {
|
||||
margin: 0.75rem 0 0;
|
||||
color: var(--muted);
|
||||
font-size: 0.92rem;
|
||||
}
|
||||
|
||||
/* Pagefind ships its own palette; these bind it to the site's tokens so the dialog is
|
||||
not a differently-coloured window sitting on the page. */
|
||||
.site-search__panel :global(.pagefind-ui) {
|
||||
--pagefind-ui-primary: var(--ink);
|
||||
--pagefind-ui-text: var(--ink);
|
||||
--pagefind-ui-background: var(--panel-flat);
|
||||
--pagefind-ui-border: var(--line);
|
||||
--pagefind-ui-tag: var(--bg);
|
||||
--pagefind-ui-border-width: 1px;
|
||||
--pagefind-ui-border-radius: var(--radius-input);
|
||||
--pagefind-ui-font: inherit;
|
||||
}
|
||||
|
||||
.site-search__panel :global(.pagefind-ui__result-link) {
|
||||
color: var(--gold);
|
||||
}
|
||||
|
||||
/* The match highlight. Pagefind marks matched terms with <mark>, and the user-agent
|
||||
default for that is black on pure yellow — legible, and a hole punched through the
|
||||
palette on every result. Gold at low opacity reads as a highlight against this ground
|
||||
without becoming the loudest thing on the page.
|
||||
|
||||
`.pagefind-ui--reset` is in the selector because Pagefind's reset declares
|
||||
`.pagefind-ui--reset mark { all: revert }`, which is the same specificity as a plain
|
||||
descendant rule and is injected after this stylesheet — so it won on order and put the
|
||||
yellow back. One more class is enough; `!important` is not needed and would be a worse
|
||||
way to say the same thing. */
|
||||
.site-search__panel :global(.pagefind-ui--reset mark) {
|
||||
background: color-mix(in srgb, var(--gold) 26%, transparent);
|
||||
color: var(--ink);
|
||||
}
|
||||
</style>
|
||||
21
src/components/Signature.astro
Normal file
21
src/components/Signature.astro
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
import { Code } from '@astrojs/starlight/components';
|
||||
import { runicnpcCalls } from '../data/runicnpc.mjs';
|
||||
|
||||
/**
|
||||
* One RunicNPC call's signature, printed from `src/data/runicnpc.mjs` (PLAN.md §16, D62).
|
||||
*
|
||||
* The API page writes each call's prose by hand and prints its signature through this, so the
|
||||
* signature a reader copies is the one `scripts/checkReference.mjs` holds against
|
||||
* `docs` `main:runicnpc/API.md`. The check also requires exactly one of these per call.
|
||||
*/
|
||||
interface Props {
|
||||
call: keyof typeof runicnpcCalls;
|
||||
}
|
||||
|
||||
const { call } = Astro.props;
|
||||
const sig = runicnpcCalls[call];
|
||||
if (!sig) throw new Error(`Signature: "${call}" is not in runicnpcCalls (src/data/runicnpc.mjs).`);
|
||||
---
|
||||
|
||||
<Code lang="csharp" code={`${sig.returns} ${call}(${sig.params})`} />
|
||||
75
src/components/StructuredData.astro
Normal file
75
src/components/StructuredData.astro
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
import platform from '../data/platform.json';
|
||||
import { brand } from '../lib/brand.mjs';
|
||||
|
||||
/**
|
||||
* Structured data for the homepage (D50, phase 10).
|
||||
*
|
||||
* Two blocks and no more. `Organization` so the project's name resolves to an entity with a
|
||||
* mark and a support channel rather than to whichever page happens to rank; and
|
||||
* `SoftwareApplication` because what the site describes is software someone installs, and
|
||||
* the licence and platform are facts a search result can usefully carry.
|
||||
*
|
||||
* ── What this deliberately is not ───────────────────────────────────────────
|
||||
* It carries no ratings, no counts, no price, no `aggregateRating` — the vocabulary is
|
||||
* full of fields that turn a result into an advert, and every one of them here would be
|
||||
* invented. §11's "understated honesty" applies to markup a reader never sees as much as to
|
||||
* the prose, and inventing a rating is the exact thing that gets structured data ignored.
|
||||
*
|
||||
* Breadcrumb and Article markup for the forty documentation pages was considered and
|
||||
* rejected: Starlight already renders breadcrumbs a reader can see, and forty more blocks
|
||||
* would be forty more places for a fact to go stale.
|
||||
*
|
||||
* ── Where the values come from ──────────────────────────────────────────────
|
||||
* Every one is read — `brand.mjs` for text, `platform.json` for the platform's facts —
|
||||
* so `checkFacts.mjs` already guards them and the mount already reaches them. Nothing here
|
||||
* is typed twice. It is a data block, not code: no browser executes it, no CSP hash covers
|
||||
* it, and `applyBrand.mjs` is free to rewrite the name inside it at boot (both scripts know
|
||||
* about `application/ld+json` explicitly, because both would otherwise get it wrong).
|
||||
*/
|
||||
const site = Astro.site!;
|
||||
const url = (p: string) => new URL(p, site).href;
|
||||
|
||||
const organization = {
|
||||
'@type': 'Organization',
|
||||
'@id': url('/#organization'),
|
||||
name: brand.siteName,
|
||||
url: url('/'),
|
||||
logo: url('/brand/icon-512.png'),
|
||||
description: brand.tagline,
|
||||
// The support front door (D10). The Gitea org is where the code is; Discord is where a
|
||||
// person gets an answer, so both are listed and neither is described as the other.
|
||||
sameAs: [brand.giteaOrg, brand.discordInvite].filter(Boolean),
|
||||
};
|
||||
|
||||
const application = {
|
||||
'@type': 'SoftwareApplication',
|
||||
'@id': url('/#software'),
|
||||
name: brand.siteName,
|
||||
url: url('/'),
|
||||
description: brand.tagline,
|
||||
applicationCategory: 'WebApplication',
|
||||
// What an operator actually runs it on: a container on their own host, and an Android
|
||||
// client. Not "Windows" — the installer runs there, the platform does not require it.
|
||||
operatingSystem: 'Linux, Windows, Android',
|
||||
license: 'https://www.gnu.org/licenses/gpl-3.0.html',
|
||||
// D66: the Module API is the one version every deployment shares. Each game has its own
|
||||
// bundle, so no single bundle tag describes the platform any more.
|
||||
softwareVersion: platform.moduleApi,
|
||||
publisher: { '@id': url('/#organization') },
|
||||
// Self-hosted and free, and `offers` is the only way the vocabulary can say so. Omitting
|
||||
// it reads as "price unknown"; stating zero is simply true.
|
||||
offers: {
|
||||
'@type': 'Offer',
|
||||
price: '0',
|
||||
priceCurrency: 'USD',
|
||||
},
|
||||
};
|
||||
|
||||
const graph = {
|
||||
'@context': 'https://schema.org',
|
||||
'@graph': [organization, application],
|
||||
};
|
||||
---
|
||||
|
||||
<script type="application/ld+json" set:html={JSON.stringify(graph)} is:inline />
|
||||
35
src/components/Ticks.astro
Normal file
35
src/components/Ticks.astro
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
/**
|
||||
* A short description from a data file, rendered inline (PLAN.md §16, phase 16).
|
||||
*
|
||||
* Reference data in `src/data/` is plain strings, because a check reads the same file. Three
|
||||
* inline marks are understood, and nothing else: `code`, **bold**, and [a link](/path/). The
|
||||
* text is never parsed as HTML, so a description cannot inject markup.
|
||||
*/
|
||||
interface Props {
|
||||
text: string;
|
||||
}
|
||||
|
||||
const { text } = Astro.props;
|
||||
|
||||
type Token = { kind: 'text' | 'code' | 'strong'; value: string } | { kind: 'link'; value: string; href: string };
|
||||
|
||||
const tokens: Token[] = [];
|
||||
const pattern = /`([^`]+)`|\*\*([^*]+)\*\*|\[([^\]]+)\]\(([^)\s]+)\)/g;
|
||||
let last = 0;
|
||||
for (const m of String(text ?? '').matchAll(pattern)) {
|
||||
if (m.index > last) tokens.push({ kind: 'text', value: text.slice(last, m.index) });
|
||||
if (m[1] !== undefined) tokens.push({ kind: 'code', value: m[1] });
|
||||
else if (m[2] !== undefined) tokens.push({ kind: 'strong', value: m[2] });
|
||||
else tokens.push({ kind: 'link', value: m[3], href: m[4] });
|
||||
last = m.index + m[0].length;
|
||||
}
|
||||
if (last < text.length) tokens.push({ kind: 'text', value: text.slice(last) });
|
||||
---
|
||||
|
||||
{tokens.map((t) =>
|
||||
t.kind === 'code' ? <code>{t.value}</code>
|
||||
: t.kind === 'strong' ? <strong>{t.value}</strong>
|
||||
: t.kind === 'link' ? <a href={t.href}>{t.value}</a>
|
||||
: t.value
|
||||
)}
|
||||
@@ -8,9 +8,11 @@ import platform from '../../data/platform.json';
|
||||
* The other two draw runtime shapes. This one draws a code boundary, and it is here because
|
||||
* it is the claim the whole project rests on: that a community platform can be built once
|
||||
* and pointed at any game. An evaluator has every reason to read that as marketing, so the
|
||||
* page draws the seam and then says plainly what does and does not prove it — one module
|
||||
* exists, the second is a paper exercise, and the exit criterion for calling the contract
|
||||
* proven is written down (§2, and the entries `/modules/` renders from `notBuilt.mjs`).
|
||||
* page draws the seam and then says plainly what does and does not prove it — two modules
|
||||
* exist, both built inside this project, and the exit criterion for calling the contract
|
||||
* proven by an outsider is written down (§2, §16, and the entries `/modules/` renders from
|
||||
* `notBuilt.mjs`). Until phase 13 this said one module and a paper exercise; Module-Rust's
|
||||
* release made that false.
|
||||
*
|
||||
* The Module API version is read from `platform.json` like every other number on this site
|
||||
* (§12). It is the one place a version genuinely belongs in this diagram: the seam is
|
||||
@@ -73,7 +75,7 @@ import platform from '../../data/platform.json';
|
||||
<!-- The module: everything that knows a game exists. -->
|
||||
<rect class="host" x="8" y="306" width="364" height="186" rx="14" />
|
||||
<text class="host-title" x="28" y="340">Game module</text>
|
||||
<text class="host-sub" x="28" y="360">one per deployment; UO today</text>
|
||||
<text class="host-sub" x="28" y="360">one per deployment; UO or Rust today</text>
|
||||
|
||||
<rect class="node" x="28" y="378" width="156" height="46" rx="10" />
|
||||
<text class="node-title" x="46" y="406">Routes</text>
|
||||
@@ -130,11 +132,12 @@ import platform from '../../data/platform.json';
|
||||
<section>
|
||||
<h3>What this does not yet prove</h3>
|
||||
<p>
|
||||
One module exists and it is Ultima Online. A second, for a different game, is a
|
||||
written dry-run that was deliberately never implemented — it exists to test whether
|
||||
the contract generalises on paper. Until somebody builds the second one, the seam is
|
||||
a well-argued design rather than a demonstrated one, and this site says so wherever
|
||||
it comes up.
|
||||
Two modules exist: Ultima Online, and Rust, which this project built second, from
|
||||
the Integration Kit. Where the Rust module needed something the contract did not
|
||||
yet offer, the gap was closed in core, for every module, rather than in a fork — so
|
||||
the seam now has two games on its far side instead of one. What two modules built
|
||||
inside this project cannot prove is that somebody outside it can do the same, and
|
||||
that is why the Integration Kit still says draft.
|
||||
</p>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
@@ -17,7 +17,7 @@ import { capabilityGroups, assertCapabilityCoverage } from '../../data/capabilit
|
||||
* what exists while quietly omitting the well-known things that do not is the exact failure
|
||||
* §1 is written to prevent.
|
||||
*/
|
||||
assertCapabilityCoverage(platform.moduleUoCapabilities);
|
||||
assertCapabilityCoverage(platform.games.uo.module.capabilities);
|
||||
---
|
||||
|
||||
<section class="page section caps">
|
||||
@@ -52,7 +52,7 @@ assertCapabilityCoverage(platform.moduleUoCapabilities);
|
||||
|
||||
<p class="caps__foot prose">
|
||||
Some things people reasonably expect are <strong>deliberately not built</strong> — a Matrix
|
||||
integration, more than one game module active at once, a second game module. They are
|
||||
integration, more than one game module active at once, a finished Integration Kit. They are
|
||||
listed rather than left out, on <a href="/features/">features</a> and{' '}
|
||||
<a href="/integrations/">integrations</a>.
|
||||
</p>
|
||||
|
||||
@@ -1,12 +1,10 @@
|
||||
---
|
||||
import platform from '../../data/platform.json';
|
||||
|
||||
/**
|
||||
* The data path (PLAN.md §13 phase 3), drawn as inline SVG per §11's motif rule — hand-drawn
|
||||
* geometry, used where it explains something, and no raster anywhere.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* THE LABELS ARE GENERIC, WITH UO AS THE CAPTION
|
||||
* THE LABELS ARE GENERIC; THE CAPTION NAMES THE GAMES
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* The org lead settled this before the diagram was drawn. The nodes say "your game server"
|
||||
* and "sidecar", not "ServUO shard" and "uo-link", because §10's rule is that a reader
|
||||
@@ -14,10 +12,12 @@ import platform from '../../data/platform.json';
|
||||
* repositories in order to connect a game server — and because the tagline promises a
|
||||
* platform, not a UO product.
|
||||
*
|
||||
* It does NOT hide what actually ships. The sub-labels and the caption name ServUO and
|
||||
* uo-link outright, because §1 says the technical truth wins and today there is exactly one
|
||||
* implementation of this shape. An operator running a shard has to see themselves in the
|
||||
* picture on the first screen.
|
||||
* It does NOT hide what actually ships: the caption names the games that ship on this shape,
|
||||
* because §1 says the technical truth wins and an operator has to see their game in the
|
||||
* picture on the first screen. Until phase 13 the sub-labels named ServUO and uo-link, which
|
||||
* was true while there was exactly one implementation. With two, naming one would mislead,
|
||||
* and D63 (PLAN.md §16) keeps each game's vocabulary on that game's own pages — so the
|
||||
* caption names the games and the diagram names nothing else.
|
||||
*
|
||||
* ---------------------------------------------------------------------------------------
|
||||
* WHY THE SVG IS aria-hidden
|
||||
@@ -74,11 +74,11 @@ import platform from '../../data/platform.json';
|
||||
|
||||
<rect class="node" x="20" y="16" width="340" height="76" rx="12" />
|
||||
<text class="node-title" x="42" y="50">Your game server</text>
|
||||
<text class="node-sub" x="42" y="72">ServUO today · opens no inbound port</text>
|
||||
<text class="node-sub" x="42" y="72">opens no inbound port</text>
|
||||
|
||||
<rect class="node" x="20" y="148" width="340" height="76" rx="12" />
|
||||
<text class="node-title" x="42" y="182">Sidecar</text>
|
||||
<text class="node-sub" x="42" y="204">uo-link · the only network-facing part</text>
|
||||
<text class="node-sub" x="42" y="204">the only network-facing part</text>
|
||||
|
||||
<rect class="node node--self" x="20" y="280" width="340" height="76" rx="12" />
|
||||
<text class="node-title" x="42" y="314">Runic Gateway</text>
|
||||
@@ -90,8 +90,9 @@ import platform from '../../data/platform.json';
|
||||
</svg>
|
||||
|
||||
<p class="datapath__caption">
|
||||
Today that game server is a ServUO shard and that sidecar is uo-link. The shape is the
|
||||
contract; the implementations are what plug into it.
|
||||
Two games ship on this shape today, Ultima Online and Rust, each with its own plugin
|
||||
and its own sidecar. The shape is the contract; the implementations are what plug
|
||||
into it.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
@@ -109,8 +110,8 @@ import platform from '../../data/platform.json';
|
||||
<h3>The sidecar</h3>
|
||||
<p>
|
||||
A small service beside the game, and the only piece of the bridge anything else can
|
||||
reach. It speaks a versioned wire protocol — protocol {platform.protocol} today — so
|
||||
a mismatched pair is refused rather than misread, and it answers only your website's
|
||||
reach. It speaks a versioned wire protocol — each game pins its own — so a
|
||||
mismatched pair is refused rather than misread, and it answers only your website's
|
||||
backend, over an authenticated WebSocket and REST.
|
||||
</p>
|
||||
</li>
|
||||
|
||||
@@ -55,9 +55,9 @@ import platform from '../../data/platform.json';
|
||||
</div>
|
||||
|
||||
<div class="chips">
|
||||
<span class="chip chip--version">Protocol {platform.protocol}</span>
|
||||
{/* D66: only the version every deployment shares. A protocol and a bundle belong
|
||||
to a game, so they live on that game's pages rather than on the front door. */}
|
||||
<span class="chip chip--version">Module API {platform.moduleApi}</span>
|
||||
<span class="chip chip--version">Bundle {platform.bundle.tag}</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
41
src/config/cspHashes.mjs
Normal file
41
src/config/cspHashes.mjs
Normal file
@@ -0,0 +1,41 @@
|
||||
/**
|
||||
* cspHashes.mjs — GENERATED. Do not edit by hand.
|
||||
*
|
||||
* Regenerate with `npm run csp:hashes` (which builds, harvests and rebuilds).
|
||||
* `npm run check:csp` fails if this file no longer covers what the build emits.
|
||||
*
|
||||
* ── Why this file exists ────────────────────────────────────────────────────
|
||||
* Astro's `security.csp` (D48) hashes the scripts and styles it processes itself. It does
|
||||
* not hash `<script is:inline>` — by design, because an inline script is the author's own
|
||||
* text and Astro never parses it. Starlight ships six of them on every documentation page:
|
||||
* the theme provider, the theme-picker sync, the mobile menu, the sidebar scroll restore.
|
||||
*
|
||||
* That combination fails in the worst way available. The build succeeds, the header is
|
||||
* strict and correct, every page renders — and the theme switch, the mobile sidebar and
|
||||
* the sidebar's scroll position are dead, with the explanation only in a browser console
|
||||
* nobody opens. `'unsafe-inline'` would fix all six and give up the single directive CSP
|
||||
* exists to enforce, so instead the hashes are enumerated here and checked.
|
||||
*
|
||||
* These are Starlight's, not ours: a Starlight upgrade that edits one byte of one of those
|
||||
* scripts invalidates a hash. `check:csp` is what turns that from a silent breakage into a
|
||||
* red build, and regenerating this file is the acknowledgement that the upgrade was read.
|
||||
*/
|
||||
|
||||
/**
|
||||
* SHA-256 hashes of inline `<script>` bodies Astro does not hash for us.
|
||||
*
|
||||
* The template-literal type is not decoration: Astro types this option as `CspHashEntry[]`,
|
||||
* so a plain `string[]` fails `astro check`.
|
||||
*
|
||||
* @type {`sha256-${string}`[]}
|
||||
*/
|
||||
export const inlineScriptHashes = [
|
||||
'sha256-7eCV4jtsr4t4knb3c4FCRPeu7GGZeOUGE3XvWix0XOQ=',
|
||||
'sha256-GkZBRnvSuhtx/cvzvukVkX2JJZW+DdPlVr7BX8Tefqo=',
|
||||
'sha256-VWo5Wp4aqSj6nSgMpeAp9cKieaoIfwFUAunAVugI5gA=',
|
||||
'sha256-f/zAUE74ucc3JYp4r4QQvkJofoQdkOIhHYK+jeZ6eko=',
|
||||
'sha256-wX2yOADeV+NMngflD5uYi3vl50SHC4sfM1EmylVjlX4=',
|
||||
];
|
||||
|
||||
/** @type {`sha256-${string}`[]} SHA-256 hashes of inline `<style>` bodies Astro does not hash. */
|
||||
export const inlineStyleHashes = [];
|
||||
22
src/config/redirects.mjs
Normal file
22
src/config/redirects.mjs
Normal file
@@ -0,0 +1,22 @@
|
||||
/**
|
||||
* Docs pages that moved, and where they went — PLAN.md §16, D60.
|
||||
*
|
||||
* Every page that moves keeps its old URL working, because the old URL is in somebody's
|
||||
* bookmarks, in an installer's output and in search results. With the Node adapter these are
|
||||
* not files in `dist/client`: the server answers each one with a real `301`.
|
||||
*
|
||||
* Its own file, rather than inline in `astro.config.mjs`, so that `test/headers.test.mjs` can
|
||||
* read the same list and assert every entry against the running server — the config cannot be
|
||||
* imported by plain Node, because Starlight ships TypeScript.
|
||||
*
|
||||
* Phase 14 moved the Ultima Online pages into their own group. `connect-a-game-server` did
|
||||
* NOT move: its URL is now the game-neutral hand-off page, which is a better landing for an
|
||||
* old link than a redirect into one game would be.
|
||||
*/
|
||||
export const docsRedirects = {
|
||||
'/docs/administration/the-shard-connection': '/docs/ultima-online/the-shard-connection/',
|
||||
'/docs/administration/client-files': '/docs/ultima-online/client-files/',
|
||||
'/docs/reference/bridge-cfg': '/docs/ultima-online/bridge-cfg/',
|
||||
'/docs/reference/sidecar-toml': '/docs/ultima-online/sidecar-toml/',
|
||||
'/docs/reference/event-catalog': '/docs/ultima-online/event-catalog/',
|
||||
};
|
||||
@@ -1,5 +1,6 @@
|
||||
/**
|
||||
* The documentation sidebar — PLAN.md §10 "Documentation", five groups, ~37 pages.
|
||||
* The documentation sidebar — PLAN.md §10 "Documentation": five core groups, then one group
|
||||
* per game after them (§16, D60).
|
||||
*
|
||||
* The pages themselves land in phases 7 and 8. This file exists in phase 1 because the
|
||||
* shape of the journey is a design decision that is already made, and because a sidebar
|
||||
@@ -22,7 +23,7 @@ export const docsSidebar = [
|
||||
{ label: 'Install the site', slug: 'docs/getting-started/install-the-site' },
|
||||
{ label: 'First run', slug: 'docs/getting-started/first-run' },
|
||||
{ label: 'Install a game module', slug: 'docs/getting-started/install-a-game-module' },
|
||||
{ label: 'Connect a game server', slug: 'docs/getting-started/connect-a-game-server' },
|
||||
{ label: 'Connect your game server', slug: 'docs/getting-started/connect-a-game-server' },
|
||||
{ label: 'Verify the whole stack', slug: 'docs/getting-started/verify-the-whole-stack' },
|
||||
],
|
||||
},
|
||||
@@ -36,10 +37,12 @@ export const docsSidebar = [
|
||||
{ label: 'Users and roles', slug: 'docs/administration/users-and-roles' },
|
||||
{ label: 'Authentication', slug: 'docs/administration/authentication' },
|
||||
{ label: 'Teams', slug: 'docs/administration/teams' },
|
||||
{ label: 'Scheduled events', slug: 'docs/administration/events' },
|
||||
{ label: 'Moderation', slug: 'docs/administration/moderation' },
|
||||
{ label: 'Notifications and email', slug: 'docs/administration/notifications-and-email' },
|
||||
{ label: 'Engagement rules', slug: 'docs/administration/engagement-rules' },
|
||||
{ label: 'Message templates', slug: 'docs/administration/message-templates' },
|
||||
{ label: 'Managing modules', slug: 'docs/administration/managing-modules' },
|
||||
{ label: 'The shard connection', slug: 'docs/administration/the-shard-connection' },
|
||||
{ label: 'Maintenance and upgrades', slug: 'docs/administration/maintenance-and-upgrades' },
|
||||
{ label: 'Troubleshooting', slug: 'docs/administration/troubleshooting' },
|
||||
],
|
||||
@@ -64,6 +67,7 @@ export const docsSidebar = [
|
||||
{ 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' },
|
||||
],
|
||||
},
|
||||
@@ -72,13 +76,62 @@ export const docsSidebar = [
|
||||
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: 'Event catalog', slug: 'docs/reference/event-catalog' },
|
||||
{ label: 'Canonical documents', slug: 'docs/reference/canonical-documents' },
|
||||
],
|
||||
},
|
||||
// One group per game, after Reference (PLAN.md §16, D60). Everything above this line is
|
||||
// core and is held to core's words by checkTerms.mjs (D63, D64). A group whose label is a
|
||||
// game's `name` in platform.json is that game's group, and may use that game's words — so
|
||||
// the label is load-bearing: renaming it here without renaming the game turns it core.
|
||||
{
|
||||
label: 'Ultima Online',
|
||||
items: [
|
||||
{ label: 'The Ultima Online module', slug: 'docs/ultima-online' },
|
||||
{ label: 'Connect a ServUO shard', slug: 'docs/ultima-online/connect-a-servuo-shard' },
|
||||
{ label: 'Verify the bridge', slug: 'docs/ultima-online/verify-the-bridge' },
|
||||
{ label: 'The shard connection', slug: 'docs/ultima-online/the-shard-connection' },
|
||||
{ label: 'Client files', slug: 'docs/ultima-online/client-files' },
|
||||
{ label: 'Troubleshooting', slug: 'docs/ultima-online/troubleshooting' },
|
||||
{ label: 'Bridge.cfg', slug: 'docs/ultima-online/bridge-cfg' },
|
||||
{ label: 'sidecar.toml', slug: 'docs/ultima-online/sidecar-toml' },
|
||||
{ label: 'Shard event catalog', slug: 'docs/ultima-online/event-catalog' },
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Rust',
|
||||
items: [
|
||||
{ label: 'The Rust module', slug: 'docs/rust' },
|
||||
{ label: 'Install the bridge', slug: 'docs/rust/install-the-bridge' },
|
||||
{ label: 'Connect the site', slug: 'docs/rust/connect-the-site' },
|
||||
{ label: 'Verify the bridge', slug: 'docs/rust/verify-the-bridge' },
|
||||
{ label: 'Linking Steam accounts', slug: 'docs/rust/linking-steam-accounts' },
|
||||
{ label: 'Permissions and groups', slug: 'docs/rust/permissions-and-groups' },
|
||||
{ label: 'Mod config from the site', slug: 'docs/rust/mod-config' },
|
||||
{ label: 'Who sees who is online', slug: 'docs/rust/who-sees-who-is-online' },
|
||||
{ label: 'Events, zones and rewards', slug: 'docs/rust/events-zones-and-rewards' },
|
||||
{ label: 'Optional plugins', slug: 'docs/rust/optional-plugins' },
|
||||
{ label: 'The live map', slug: 'docs/rust/the-live-map' },
|
||||
{ label: 'Troubleshooting', slug: 'docs/rust/troubleshooting' },
|
||||
{ label: 'sidecar.toml', slug: 'docs/rust/sidecar-toml' },
|
||||
{ label: 'RunicGateway.json', slug: 'docs/rust/runicgateway-json' },
|
||||
{ label: 'Event kinds', slug: 'docs/rust/event-kinds' },
|
||||
// §16, D61/D72: RunicNPC is a subgroup of Rust, nested so it reads as part of the game.
|
||||
{
|
||||
label: 'RunicNPC',
|
||||
items: [
|
||||
{ label: 'RunicNPC', slug: 'docs/rust/runicnpc' },
|
||||
{ label: 'Install RunicNPC', slug: 'docs/rust/runicnpc/install' },
|
||||
{ label: 'Commands', slug: 'docs/rust/runicnpc/commands' },
|
||||
{ label: 'NPC profiles', slug: 'docs/rust/runicnpc/npc-profiles' },
|
||||
{ label: 'NPC placements', slug: 'docs/rust/runicnpc/npc-placements' },
|
||||
{ label: 'Cost and caps', slug: 'docs/rust/runicnpc/cost-and-caps' },
|
||||
{ label: 'Profile fields', slug: 'docs/rust/runicnpc/profile-fields' },
|
||||
{ label: 'The API', slug: 'docs/rust/runicnpc/api' },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
/**
|
||||
@@ -100,7 +153,7 @@ export const plannedSidebar = {
|
||||
'Install the site',
|
||||
'First run',
|
||||
'Install a game module',
|
||||
'Connect a game server',
|
||||
'Connect your game server',
|
||||
'Verify the whole stack',
|
||||
],
|
||||
Administration: [
|
||||
@@ -111,10 +164,12 @@ export const plannedSidebar = {
|
||||
'Users and roles',
|
||||
'Authentication',
|
||||
'Teams',
|
||||
'Scheduled events',
|
||||
'Moderation',
|
||||
'Notifications and email',
|
||||
'Engagement rules',
|
||||
'Message templates',
|
||||
'Managing modules',
|
||||
'The shard connection',
|
||||
'Maintenance and upgrades',
|
||||
'Troubleshooting',
|
||||
],
|
||||
@@ -133,15 +188,71 @@ export const plannedSidebar = {
|
||||
'The bridge',
|
||||
'Authentication architecture',
|
||||
'Teams architecture',
|
||||
'Events architecture',
|
||||
'Protocol versions',
|
||||
],
|
||||
Reference: [
|
||||
'Environment variables',
|
||||
'Installer CLI',
|
||||
'sidecar.toml',
|
||||
'Bridge.cfg',
|
||||
'HTTP API',
|
||||
'Event catalog',
|
||||
'Canonical documents',
|
||||
],
|
||||
'Ultima Online': [
|
||||
'The Ultima Online module',
|
||||
'Connect a ServUO shard',
|
||||
'Verify the bridge',
|
||||
'The shard connection',
|
||||
'Client files',
|
||||
'Troubleshooting',
|
||||
'Bridge.cfg',
|
||||
'sidecar.toml',
|
||||
'Shard event catalog',
|
||||
],
|
||||
// PLAN.md §16, D70 (phase 15). RunicNPC's subgroup lands in phase 16 (D61).
|
||||
Rust: [
|
||||
'The Rust module',
|
||||
'Install the bridge',
|
||||
'Connect the site',
|
||||
'Verify the bridge',
|
||||
'Linking Steam accounts',
|
||||
'Permissions and groups',
|
||||
'Mod config from the site',
|
||||
'Who sees who is online',
|
||||
'Events, zones and rewards',
|
||||
'Optional plugins',
|
||||
'The live map',
|
||||
'Troubleshooting',
|
||||
'sidecar.toml',
|
||||
'RunicGateway.json',
|
||||
'Event kinds',
|
||||
{
|
||||
RunicNPC: [
|
||||
'RunicNPC',
|
||||
'Install RunicNPC',
|
||||
'Commands',
|
||||
'NPC profiles',
|
||||
'NPC placements',
|
||||
'Cost and caps',
|
||||
'Profile fields',
|
||||
'The API',
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
/**
|
||||
* A group's items as flat labels, a nested group's pages written `Group › Page` after the
|
||||
* group's own label. Both trees go through this, so `checkSidebar.mjs` compares nested
|
||||
* groups as strictly as top-level ones, and `checkTerms.mjs` reads every label.
|
||||
*
|
||||
* In `docsSidebar` a nested group is `{ label, items }`; in `plannedSidebar` it is
|
||||
* `{ Label: [pages] }`.
|
||||
*/
|
||||
export function flatLabels(items) {
|
||||
return items.flatMap((item) => {
|
||||
if (typeof item === 'string') return [item];
|
||||
if (Array.isArray(item.items)) return [item.label, ...flatLabels(item.items).map((l) => `${item.label} › ${l}`)];
|
||||
if ('label' in item) return [item.label];
|
||||
return Object.entries(item).flatMap(([label, pages]) => [label, ...flatLabels(pages).map((l) => `${label} › ${l}`)]);
|
||||
});
|
||||
}
|
||||
|
||||
@@ -5,7 +5,7 @@ description: Local accounts and two-factor, SSO providers and the link-only poli
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
**Admin → Authentication** has four tabs: Local Accounts, Google, Discord and Custom
|
||||
**Admin → Authentication** has five tabs: Local Accounts, Google, Discord, Steam and Custom
|
||||
Providers. One session model sits behind all of them — a web cookie, a mobile bearer token
|
||||
and an SSO sign-in all produce the same session.
|
||||
|
||||
@@ -35,6 +35,19 @@ account is still a stranger.
|
||||
Configuring Google here also unlocks **email delivery**, which reuses the same OAuth client
|
||||
— see [Notifications and email](/docs/administration/notifications-and-email/).
|
||||
|
||||
### Steam
|
||||
|
||||
Steam signs people in with OpenID rather than OAuth, so it needs no client ID or secret — but
|
||||
it does need a **Steam Web API key**, for the name and avatar Steam's sign-in does not carry,
|
||||
and saving Steam as enabled without one is refused. It follows the same link-only policy, more
|
||||
strictly: **Steam never creates an account**, whatever registration allows. A person may link
|
||||
several Steam accounts, and each is listed on their account screen with its name, avatar and
|
||||
Steam ID.
|
||||
|
||||
A game module can also be told which Steam accounts a signed-in person has proved are theirs,
|
||||
which is how a game that knows its players by Steam account can recognise a member. The Rust
|
||||
module uses it — see [Linking Steam accounts](/docs/rust/linking-steam-accounts/).
|
||||
|
||||
## Trusted devices
|
||||
|
||||
A second factor that asks on every sign-in on the same laptop trains people to click
|
||||
|
||||
@@ -16,7 +16,7 @@ Two places hold configuration, and the line between them is not arbitrary.
|
||||
|
||||
The rule behind the split: **anything that needs a restart or a shell is environment;
|
||||
anything an administrator should be able to change without either is in the panel.** That
|
||||
is why the Discord bot token, the OAuth client secrets and the shard's auth token are *not*
|
||||
is why the Discord bot token, the OAuth client secrets and the game module's sidecar token are *not*
|
||||
environment variables — they are entered in the panel and stored encrypted.
|
||||
|
||||
## Settings
|
||||
@@ -59,9 +59,10 @@ per-Team settings:
|
||||
## Email
|
||||
|
||||
Configured on the same screen and covered in
|
||||
[Notifications and email](/docs/administration/notifications-and-email/): it is Gmail over
|
||||
OAuth2, it reuses the Google authentication client, and it must be set up on the
|
||||
[Authentication](/docs/administration/authentication/) page first.
|
||||
[Notifications and email](/docs/administration/notifications-and-email/): pick a mail
|
||||
transport, enter its host, port and credentials, and send a test. It depends on nothing
|
||||
else on the site — a relay is the recommended posture, a mailbox provider over SMTP the
|
||||
simplest, and your own MTA needs no credentials at all.
|
||||
|
||||
<Aside type="note" title="Until email is connected, the contact form is a mailto: link">
|
||||
That is a deliberate fallback rather than a failure — but it does mean the *Contact email*
|
||||
|
||||
@@ -27,7 +27,7 @@ glance.
|
||||
|
||||
<Aside type="caution" title="Publishing a news post announces it">
|
||||
Publishing is what triggers the announcement pipeline — the Discord `#news` leg, and any leg
|
||||
an installed module adds, such as the `uo` module's in-game town crier. It fires on
|
||||
an installed module adds, such as the Ultima Online module's in-game town crier. It fires on
|
||||
publication, so an accidental publish is an accidental announcement. See
|
||||
[Notifications and email](/docs/administration/notifications-and-email/).
|
||||
</Aside>
|
||||
|
||||
175
src/content/docs/docs/administration/engagement-rules.mdx
Normal file
175
src/content/docs/docs/administration/engagement-rules.mdx
Normal file
@@ -0,0 +1,175 @@
|
||||
---
|
||||
title: Engagement rules
|
||||
description: Decide what your site mails and shows people — the rule editor, saved audiences, the trigger catalog and the send log that answers "did they actually get it".
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
[Notifications and email](/docs/administration/notifications-and-email/) is about where a
|
||||
message goes. [Message templates](/docs/administration/message-templates/) is about what it
|
||||
says. This page is the part in between: **what makes one get sent at all.**
|
||||
|
||||
A **rule** is four decisions — *when* (a trigger), *to whom* (an audience), *by what*
|
||||
(channels), and *how often* (timing). **Admin → Engagement → Rules.**
|
||||
|
||||
## Nothing sends until you turn it on
|
||||
|
||||
Every rule arrives switched **off**. That is true of the ones you make, and it is true of
|
||||
the ones your modules ship with them: install a game module and you get a shelf of ready
|
||||
rules, all dark, none of them mailing anybody. Turning one on is a deliberate, separate
|
||||
act.
|
||||
|
||||
The same caution runs through the rest of the screen. Every rule carries a **hard ceiling
|
||||
on sends per hour** — you cannot save one without a number — because the failure mode of an
|
||||
automated mailer is not a wrong message, it is ten thousand of them at four in the morning.
|
||||
|
||||
<Aside type="caution" title="Upgrading? Your Team emails are here now">
|
||||
Team notification email used to be its own pipeline. It is engagement rules now, and — like
|
||||
every other seeded rule — those four rules arrive **disabled**. If your members were getting
|
||||
Team mail before an upgrade, it stops until you turn them on. The admin dashboard says so
|
||||
while it is true.
|
||||
</Aside>
|
||||
|
||||
## What a rule is made of
|
||||
|
||||
**The trigger** is the event that fires it: a house falling into disrepair, a post being
|
||||
published, a login failing. Pick it from what is registered — see
|
||||
[the catalog](#the-trigger-catalog) below. A rule's trigger is **fixed once the rule
|
||||
exists**: its cooldowns, its pending messages and its whole send history are about one
|
||||
event, so changing it would silently be a different rule wearing the same name. Make a new
|
||||
one instead.
|
||||
|
||||
**The audience** is who hears about it. Some are built in — the person the event is about,
|
||||
everyone subscribed to it, staff. Others come from your modules and are named in their own
|
||||
vocabulary. You can also point a rule at a **saved audience** you composed yourself; see
|
||||
[Audiences](#audiences).
|
||||
|
||||
**The channels** are how it reaches them: on the site, by email, by push. A rule can name
|
||||
more than one, and each channel picks its own template — the same event can be a sentence
|
||||
in the inbox and a properly laid-out letter in the mail.
|
||||
|
||||
**The timing** is the part worth reading twice.
|
||||
|
||||
- A **delay** holds the message before it goes, so a situation that resolves itself never
|
||||
produces a message at all.
|
||||
- **Cancel on** names the events that call it back. A warning that a house is about to
|
||||
collapse waits fifteen minutes and is cancelled outright if the owner turns up and
|
||||
repairs it — nobody is told their house was in danger after it stopped being in danger.
|
||||
- A **cooldown** is the "not again for a while" limit, counted **per person, per subject
|
||||
and per channel**. Per subject, so a cooldown about one house says nothing about another.
|
||||
Per channel, so "one a day about this house" means one email *and* one inbox item, which
|
||||
is what an operator setting that limit means.
|
||||
|
||||
## Audiences
|
||||
|
||||
**Admin → Engagement → Audiences** is where you build a named set of people out of the ones
|
||||
your modules declare — *members of this Team*, *the sitting governors* — and combine them:
|
||||
all of these, any of these, none of these.
|
||||
|
||||
One rule governs the whole screen: **composition narrows and never widens.**
|
||||
|
||||
- The ceiling of a saved audience is **derived** from the tightest thing in it, never
|
||||
chosen. That is true of "any of" too, where the intuitive answer — the widest of the two —
|
||||
is the wrong one. A ceiling says what an expression is *allowed* to reach, not what it
|
||||
happens to resolve to today.
|
||||
- **"None of" is only offered inside an "all of" group.** Alone it would have to mean
|
||||
"everybody except these", which is a broadcast built out of a short list, and it is not
|
||||
offered anywhere it would mean that.
|
||||
- Two audiences with no relationship between them — staff and "the person this is about",
|
||||
say — have no honest combined ceiling, so the save is refused rather than guessing which
|
||||
side to take.
|
||||
|
||||
Before you save a rule, the editor shows you a **reach preview**: a number, never a list of
|
||||
names. It will also tell you when a number is a floor rather than an answer, and when an
|
||||
audience resolves to nobody at all and why.
|
||||
|
||||
## The ceiling, and why a rule will not offer the audience you expected
|
||||
|
||||
Every trigger declares the **widest audience a rule may ever give it**. It is the security
|
||||
boundary of the whole system, and it is set in code by whoever declared the event, not in
|
||||
the admin panel. Staff-only events cannot be widened into public ones by anybody, including
|
||||
you.
|
||||
|
||||
Seven values, and they are a **tree, not a ladder**:
|
||||
|
||||
| Ceiling | Who that is |
|
||||
| --- | --- |
|
||||
| `everyone` | Everyone, including signed-out visitors |
|
||||
| `authenticated` | Any signed-in user |
|
||||
| `subscribers` | Signed-in users subscribed to this event |
|
||||
| `members` | Members of a module-declared list |
|
||||
| `staff` | Staff only — admins, editors and moderators |
|
||||
| `admin` | Administrators only |
|
||||
| `owner` | Only the user the event is about |
|
||||
|
||||
<Aside type="note" title="Fewer people is not less exposure">
|
||||
The tempting reading is a ladder — that a staff-only event could obviously also go to just
|
||||
one person. It cannot, and the example is the whole argument: cheat detection is a
|
||||
staff-only event, and "just one person" would be *the player it was detected on*. The
|
||||
question a ceiling answers is never how many, it is **which**.
|
||||
</Aside>
|
||||
|
||||
So `staff` does not permit `owner`, `members` does not permit `subscribers`, and the editor
|
||||
simply does not offer you the audiences the trigger forbids. The one exception proves the
|
||||
rule: `admin` sits under `staff`, because every administrator really is staff.
|
||||
|
||||
## The trigger catalog
|
||||
|
||||
**Admin → Engagement → Triggers** lists every event a rule can be built on, and it is
|
||||
read-only on purpose — **there is no table behind it**. A trigger is declared in code, by
|
||||
the site or by an installed module, so what you are looking at is whatever registered on
|
||||
this boot. Uninstall a module and its triggers stop appearing; nothing was deleted.
|
||||
|
||||
Two things it shows that are invisible everywhere else:
|
||||
|
||||
- **The variables** each event carries, with an example of each. This is the list a template
|
||||
is allowed to reference — when a message comes out with a hole in it, this is the screen
|
||||
that says why.
|
||||
- **The ceiling**, so when the rule editor offers you a narrower set of audiences than you
|
||||
expected, you can see the number it is obeying.
|
||||
|
||||
### Dormant rules
|
||||
|
||||
A rule can be switched on and still be unable to fire — most often because the module that
|
||||
declared its trigger, or the audience it points at, is no longer installed. Those are
|
||||
badged **dormant** in the list, with the reason, because "this rule cannot fire" is a
|
||||
different fact from "this rule is off" and you need both. The on/off switch keeps working
|
||||
on a dormant rule, deliberately: a rule whose module has gone is exactly the rule you most
|
||||
want to be able to stop.
|
||||
|
||||
## The send log
|
||||
|
||||
**Admin → Engagement → Send Log** answers one question: *did that person get that message,
|
||||
and if not, why not?* Every attempt is a row — when, what fired it, which user, which
|
||||
channel, and the result. Filter by result to go straight to what failed.
|
||||
|
||||
| Result | What it means |
|
||||
| --- | --- |
|
||||
| **Sent** | Handed to the channel successfully |
|
||||
| **Failed** | The attempt errored — the reason is on the row, not hidden in a tooltip |
|
||||
| **Not sent** | Suppressed before it was attempted: unsubscribed, unverified, or on the [suppression list](/docs/administration/troubleshooting/) |
|
||||
| **Bounced** | The receiving server rejected it after the fact |
|
||||
| **Marked as spam** | The recipient reported it |
|
||||
|
||||
Test sends from the template editor land here too, labelled as such, so you can confirm
|
||||
your own test arrived before turning a rule on for real.
|
||||
|
||||
<Aside type="tip" title="Two things it will not show you, on purpose">
|
||||
**The email address.** The log stores a one-way hash of it — enough to tie a bounce back to
|
||||
a delivery, not enough to become a second address book.
|
||||
|
||||
**A name.** It holds the user id, and that is deliberate: joining the account list in would
|
||||
quietly turn a delivery log into a staff-readable directory. Paste the id into Moderation,
|
||||
which is where a person's record belongs.
|
||||
</Aside>
|
||||
|
||||
## What a game module brings
|
||||
|
||||
A module declares its own triggers and its own audiences, in its own vocabulary, and it may
|
||||
ship rules and message bodies to go with them. The Ultima Online module ships a large family
|
||||
of them — houses falling to ruin, vendors running out of gold, a governor being seated, a
|
||||
Team's fortunes — written in the voice of an in-world office rather than a system alert.
|
||||
|
||||
All of them arrive **disabled**, like every other seeded rule. Read the list in
|
||||
**Admin → Engagement → Triggers**, turn on the ones your site should send, and check the
|
||||
send log the first time each one fires.
|
||||
209
src/content/docs/docs/administration/events.mdx
Normal file
209
src/content/docs/docs/administration/events.mdx
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
title: Scheduled events
|
||||
description: Author an event as phases and steps, price it against this deployment's caps before it runs, and let it change a live game world unattended — with a ledger that makes the undo automatic.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import GameExample from '../../../../components/GameExample.astro';
|
||||
|
||||
An **event** is a scheduled, bounded, audited change to a live game world. You write it once
|
||||
as a sequence of phases, publish a version of it, put it on the calendar, and it runs — at
|
||||
four in the morning if that is when you scheduled it, with nobody watching.
|
||||
|
||||
That last clause is the whole reason this feature is shaped the way it is. Everything below
|
||||
that looks like extra ceremony — the switchboard, the caps, the dry run, the ledger — is
|
||||
there because the thing being automated is somebody's game world, and the person who
|
||||
authored the change is asleep when it happens.
|
||||
|
||||
**Core owns the engine; the installed module owns the meaning.** Core decides whether an
|
||||
action is permitted, when it runs, in what order, how many times, within what budget, what
|
||||
it created and who is told. The module says which verbs exist and performs them. Core never
|
||||
learns a game word: every label you see in the step editor came from the module that
|
||||
registered it.
|
||||
|
||||
## Where it is
|
||||
|
||||
**Admin → Events**, its own group in the sidebar:
|
||||
|
||||
| Row | Who sees it |
|
||||
|---|---|
|
||||
| **Events** — the definitions, and their runs | Admin, editor, moderator |
|
||||
| **Calendar** — month and list view, with series | Admin, editor, moderator |
|
||||
| **Actions** — what this deployment permits, and the caps | **Admin only** |
|
||||
| **My participation** — your own attendance | Everyone |
|
||||
|
||||
Reading is staff-wide on purpose. A moderator's power over this feature is the **run
|
||||
console** — the screen you open when an event is doing something wrong at two in the
|
||||
morning — and hiding it from the one role that exists for incident response would be a
|
||||
strange way to build an incident tool. The narrower gates are on the actions, not the rows:
|
||||
authoring is admin and editor, publishing a version and starting a run are admin only, and
|
||||
all of it is enforced on the server rather than by hiding a button.
|
||||
|
||||
## Authoring
|
||||
|
||||
A **definition** is the thing that gets listed, searched, scheduled and audited: a title, a
|
||||
slug, a storyline, a schedule, and an ordered list of **phases**. Each phase holds **steps**,
|
||||
and a step is one action with its parameters.
|
||||
|
||||
A phase advances on a condition — after a duration, or when something happens in the game a
|
||||
given number of times. The vocabulary of "something that happens" is the trigger catalog the
|
||||
installed module already ships, so a module gains phase conditions by declaring one more
|
||||
entry in a list it already had.
|
||||
|
||||
<Aside type="note" title="A timeline, not a node graph">
|
||||
The phase editor is a vertical list, deliberately. The condition grammar has no branching —
|
||||
it is `and` / `or` / `not` over comparisons and nothing else — and a canvas would advertise
|
||||
power the engine does not have. Phases in order, each with its steps, its advance condition,
|
||||
its budget draw and its failure policy, is exactly what it can do.
|
||||
</Aside>
|
||||
|
||||
### Versions are immutable, and a run pins one
|
||||
|
||||
Publishing takes a snapshot. The run that starts on Saturday holds the version that was
|
||||
published, not the one you edited on Friday — which is what makes a run reproducible and an
|
||||
audit answerable after a change. **A running event cannot be edited**; you edit the
|
||||
definition, publish a new version, and the next run picks it up.
|
||||
|
||||
## Nothing is enabled until you enable it
|
||||
|
||||
**Admin → Events → Actions** lists every action the installed modules registered, and
|
||||
**everything above a notification arrives switched off.** Installing a module must never
|
||||
start doing things to your world.
|
||||
|
||||
Each row has two controls: whether the action is permitted on this deployment at all, and its
|
||||
**per-run caps** — how much of a budget dimension one run may consume. Dimensions are
|
||||
declared by the module, and consumption is counted in the database with a conditional
|
||||
update, not checked in application code.
|
||||
|
||||
<GameExample game="uo">
|
||||
The Ultima Online module declares `uo.creatures`, `uo.bosses`, `uo.rewards` and others —
|
||||
one per kind of thing an event can spend.
|
||||
</GameExample>
|
||||
|
||||
That distinction matters more than it sounds. A stolen admin session has already passed every
|
||||
role check there is; it still cannot exceed the cap, because the cap is a condition on the
|
||||
`UPDATE` that spends the budget.
|
||||
|
||||
<Aside type="caution" title="A cap breach is a refusal, not a failure">
|
||||
A step that would exceed a cap does not run, does not retry, and is recorded `refused` with
|
||||
the dimension and both numbers — *"asks for 12 of `uo.creatures`; 0 of 5 is already spent this
|
||||
run"*. That is an authoring mistake being reported to the author, not an outage.
|
||||
</Aside>
|
||||
|
||||
## Dry run before anything unattended
|
||||
|
||||
**Verify** materialises the whole plan without touching the world: every step is dispatched
|
||||
with a verify flag, and you get back what *would* happen and what it *would* cost against the
|
||||
caps, in the module's own words. Refusals show up here, before the calendar entry exists.
|
||||
|
||||
A definition that has never been verified is exactly the one worth not scheduling. Verifying
|
||||
is cheap, and it is the last point a human sees the plan.
|
||||
|
||||
## Running one
|
||||
|
||||
Runs start on the schedule, or by hand. A **series** groups definitions into an arc, so a
|
||||
three-part story reads as one thing on the calendar rather than three unrelated entries.
|
||||
|
||||
The **run console** shows live status, the steps and their attempts, the budget consumed
|
||||
against each cap, any failures, and the cleanup. Its controls are:
|
||||
|
||||
- **Pause** and **resume** — resume carries a run past any settled step, including one that
|
||||
failed or was refused.
|
||||
- **Skip**, **retry** and **confirm** a single step. *Confirm* is how a human-cue step
|
||||
advances: the run posts the instruction, waits, and moves on when somebody says they did it.
|
||||
- **Advance** a phase by hand.
|
||||
- **Cancel**, with or without cleanup.
|
||||
|
||||
Every one of those is logged with the person who did it.
|
||||
|
||||
## What an event does to a world, and how it is undone
|
||||
|
||||
Two different things, and the difference is the whole safety story.
|
||||
|
||||
**What it owns.** Creatures, bosses, oracle NPCs, decoration, a temporary gate — things the
|
||||
run created. Each one is written to a **resource ledger** as it is made, with the run and
|
||||
step that made it.
|
||||
|
||||
**What it borrows.** A spawner's respawn timer, a starting skill cap, a seasonal flag — values
|
||||
that already existed and are being changed for the duration. Those are **leases**: the game
|
||||
keeps the original, the site records both halves, and the lease carries its own deadline.
|
||||
|
||||
<Aside type="tip" title="Cleanup is generated, never authored">
|
||||
There is no undo phase for you to write, and that is on purpose: an operator cannot be relied
|
||||
on to write the undo, and an aborted run never reaches the phase they wrote it in. Teardown
|
||||
steps are derived from the ledger and run on **every** terminal path — completion,
|
||||
cancellation and abort alike.
|
||||
|
||||
A lease is safer still. The game restores the baseline when the deadline passes whether or not
|
||||
it ever hears from the site again, and a lease is never written to disk — so a game-server
|
||||
restart puts every borrowed value back too.
|
||||
</Aside>
|
||||
|
||||
## The game server has its own switches
|
||||
|
||||
They live in the bridge plugin's config on the game server's host, not in the site's
|
||||
database, and no event can turn them on.
|
||||
|
||||
**`EventsEnabled` is off by default**, in both games. Turning it on is consenting to the site
|
||||
changing and watching your world unattended.
|
||||
|
||||
<GameExample game="uo">
|
||||
`EventsEnabled` is a different switch from `AdminWriteEnabled`. Turning the admin plane on is
|
||||
consenting to staff moderation driven from a screen somebody is looking at; turning events on
|
||||
is consenting to unattended changes. One switch could not honestly express both. Every key
|
||||
is in [`Bridge.cfg`](/docs/ultima-online/bridge-cfg/), which only the shard host can edit.
|
||||
</GameExample>
|
||||
|
||||
<GameExample game="rust">
|
||||
`EventsEnabled` is in each server's [`RunicGateway.json`](/docs/rust/runicgateway-json/). An
|
||||
administrator can edit it on the host, or from the site's
|
||||
[Mod config](/docs/rust/mod-config/) screen, which reaches the game host's config files
|
||||
through the bridge.
|
||||
</GameExample>
|
||||
|
||||
Beside it sit the game's own ceilings — how much one call may place, how long something it
|
||||
creates may stand, how much one run may own in total. **They refuse rather than clamp**, for
|
||||
the same reason the caps do: a quietly shortened request leaves the two halves disagreeing
|
||||
about what actually happened.
|
||||
|
||||
## What players see
|
||||
|
||||
The public calendar at `/site/events` carries what is scheduled, what is happening now, what
|
||||
finished recently, and published results. A run that was cancelled says so — *"Did not
|
||||
happen"* — rather than quietly disappearing.
|
||||
|
||||
**Listing is separate from publishing.** A definition has its own *listed* switch, because
|
||||
publishing is what makes an event runnable and a surprise invasion should not have to be
|
||||
advertised a fortnight in advance in order to be allowed to happen. Unlisting hides the
|
||||
definition, its runs and its results from the public pages and from a participant's own
|
||||
history; it hides nothing from staff.
|
||||
|
||||
Where a module can tell who took part, a run can keep a **participation ledger** — scores and
|
||||
ranks, published as a results table when the run finishes. Ranks are computed at publication
|
||||
and stored, so somebody added afterwards does not silently renumber a table people have
|
||||
already read. A signed-in person sees their own attendance under their account, and staff see
|
||||
theirs on the same screen.
|
||||
|
||||
## When something goes wrong
|
||||
|
||||
- **`degraded` is not `failed`.** If the game server disappears mid-run, the run degrades,
|
||||
world-changing steps park unattempted, and it recovers when the connection does. The public
|
||||
page does not say so — that is operator information.
|
||||
- **`refused` means a bound said no**, and it is reported with the numbers.
|
||||
- **The run log answers "why did phase 3 not start?"** as a query, not by reading a wall of
|
||||
text. It is kept for 90 days after a run reaches a terminal state — and a run still in
|
||||
flight keeps every line it has, however old, because the question it answers is still open.
|
||||
- **Cleanup can be re-run** from the run console if a teardown was interrupted.
|
||||
|
||||
## Where the record is
|
||||
|
||||
[`website/EVENTS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/EVENTS.md)
|
||||
is the design of record — the model, the data, the security argument and what was deliberately
|
||||
left out.
|
||||
[`website/MODULE_API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md)
|
||||
is the contract a module registers its verbs against, and
|
||||
[`link/ADMIN_CONTROLS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/ADMIN_CONTROLS.md)
|
||||
is what the site may ask a game to do at all.
|
||||
|
||||
For how the engine is put together, see
|
||||
[Events architecture](/docs/architecture/events-architecture/).
|
||||
@@ -102,7 +102,7 @@ Three rules for whatever proxy you use:
|
||||
- **Terminate TLS at the proxy.** The app speaks HTTP; it is not meant to hold a
|
||||
certificate.
|
||||
|
||||
## Upgrading the shard side
|
||||
## Upgrading the game server side
|
||||
|
||||
A different deployment on a different host, and it moves on its own schedule:
|
||||
|
||||
@@ -111,15 +111,18 @@ sudo runicgateway update # re-resolves the bundle; --verify to see it first
|
||||
sudo runicgateway doctor # confirm afterwards
|
||||
```
|
||||
|
||||
`update` replaces the sidecar and restarts its service, re-syncs the overlay, and tells you
|
||||
when ServUO needs restarting — it never restarts your shard itself. Because it resolves a
|
||||
**bundle**, the sidecar and the plugin move together and cannot end up disagreeing about the
|
||||
protocol.
|
||||
`update` replaces the sidecar and restarts its service, redeploys the bridge plugin, and
|
||||
tells you when the game server needs restarting — it never restarts your game server itself.
|
||||
Because it resolves a **bundle**, the sidecar and the plugin move together and cannot end up
|
||||
disagreeing about the protocol. Add the game's own flags as you did at install; see the
|
||||
[Installer CLI](/docs/reference/installer-cli/).
|
||||
|
||||
Each game can have its own day-two chores on top of this. Ultima Online's are in [its
|
||||
group](/docs/ultima-online/client-files/#after-a-client-update).
|
||||
|
||||
<Aside type="note" title="Update the two sides in either order, but verify after each">
|
||||
They are independent deployments joined by a version-checked contract: a mismatch is
|
||||
rejected with a `409` rather than mis-parsed. So the worst case is a bridge that refuses to
|
||||
pair until both sides are current — visible on
|
||||
[the shard connection screen](/docs/administration/the-shard-connection/), and not silent
|
||||
corruption.
|
||||
pair until both sides are current — visible on the game module's connection screen, and
|
||||
not silent corruption.
|
||||
</Aside>
|
||||
|
||||
@@ -41,6 +41,10 @@ Two consequences of how boots work:
|
||||
Paste the new release's install-manifest URL and press Install. The bundle is verified
|
||||
against its `sha256`, unpacked over the old one, and takes effect at the restart.
|
||||
|
||||
**A site runs one module.** Installing a module with a different id beside the one you have
|
||||
is refused with `409`, and nothing is downloaded. To change game, remove the installed module
|
||||
first.
|
||||
|
||||
An upgrade **deliberately leaves the state alone**: upgrading an enabled module must not
|
||||
silently switch it off, and re-installing a disabled one must not silently switch it on.
|
||||
|
||||
|
||||
133
src/content/docs/docs/administration/message-templates.mdx
Normal file
133
src/content/docs/docs/administration/message-templates.mdx
Normal file
@@ -0,0 +1,133 @@
|
||||
---
|
||||
title: Message templates
|
||||
description: Edit what your site's email actually says — the block editor, the variable palette, the preview, test sends, and the send log that tells you whether a message arrived.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
Every message your site sends — password resets, invitations, notifications — is a
|
||||
**template** you can edit. They ship working, so a fresh site mails correctly before you
|
||||
open this screen at all. You come here when you want it to sound like your community.
|
||||
|
||||
**Admin → Engagement → Templates.**
|
||||
|
||||
## What is in the list
|
||||
|
||||
Each row is one message. The ones marked **system** are the ones the site itself depends
|
||||
on: the password reset, the invitation, the address-confirmation mail. You can edit every
|
||||
word of those, but you cannot delete them — a site with no password-reset body is a site
|
||||
where nobody can get back in.
|
||||
|
||||
The rest are the general-purpose bodies that rules send. Those you can delete, as long as
|
||||
no rule is currently pointing at one.
|
||||
|
||||
<Aside type="tip" title="Your edits survive upgrades">
|
||||
When you edit a shipped template, the site remembers that a person changed it. Later
|
||||
versions may ship an improved default for the same message — and it will **not** be applied
|
||||
over your words. You will see a note on the row telling you a newer default exists, and it
|
||||
is up to you whether to look at it.
|
||||
</Aside>
|
||||
|
||||
## Editing a message
|
||||
|
||||
The editor has the message on the left and a live preview on the right.
|
||||
|
||||
### The body is blocks, not HTML
|
||||
|
||||
You build a message out of pieces: a heading, a paragraph, a button, a divider, an image,
|
||||
or an item list. Add one from the row of buttons, click it to edit it, and use the arrows
|
||||
to move it. There is no HTML to write, which is deliberate — email HTML is a genuinely
|
||||
horrible format, and the blocks already produce something that survives Outlook.
|
||||
|
||||
### Variables are chosen, never typed
|
||||
|
||||
Under most text fields is a row of small grey names: `siteName`, `resetUrl`, `title`. Those
|
||||
are the **variables** this particular message is given when it is sent. Click one and it is
|
||||
inserted as a token; the message that goes out has the real value in its place.
|
||||
|
||||
You cannot invent a variable. If you type one the message is not given — a typo, or a name
|
||||
you remembered from a different message — the save is refused and the error names the
|
||||
variable. That is on purpose: a variable that does not exist renders as *nothing*, so
|
||||
without the check the mistake would be invisible until it reached somebody's inbox as a
|
||||
sentence with a hole in it.
|
||||
|
||||
To see every variable a given event provides, with an example of each, look at
|
||||
**Admin → Engagement → Triggers**.
|
||||
|
||||
### Both halves of the message
|
||||
|
||||
Every email goes out in two forms: the designed HTML one, and a plain-text one for clients
|
||||
that will not show HTML. The plain-text half is generated from your blocks automatically,
|
||||
and you can see it under the **Plain text** tab.
|
||||
|
||||
If the generated version is not good enough, write your own in **Plain-text part** at the
|
||||
bottom of the editor. Whatever you write there replaces the generated text completely.
|
||||
|
||||
A published message must have *something* in its text part. If every block you used
|
||||
contributes nothing to it — a message made only of dividers and images, say — the save is
|
||||
refused.
|
||||
|
||||
### Draft and published
|
||||
|
||||
A **draft** is not what goes out. While a message is a draft, the site sends the shipped
|
||||
default in its place, so you can leave something half-finished without breaking anything.
|
||||
Switch it to **Published** when you want your version to be the one people receive.
|
||||
|
||||
## The preview
|
||||
|
||||
The preview is rendered by the server using the same code that renders the real message, so
|
||||
what you see is what will arrive — not an approximation drawn by the browser.
|
||||
|
||||
It fills the variables in with example values, so you never need to trigger a real event to
|
||||
see what a message looks like.
|
||||
|
||||
Three controls are worth knowing:
|
||||
|
||||
- **Desktop / Mobile** — the same body at a reading-pane width and a phone width.
|
||||
- **Dark mode** — an approximation of what mail clients that invert light messages will do
|
||||
to yours. Worth a glance: a design that relies on a light background can come out as
|
||||
dark-on-dark for a large minority of readers.
|
||||
- **Plain text** — the other half of the message, as described above.
|
||||
|
||||
## Sending yourself a test
|
||||
|
||||
The **Send a test** box sends the message to any address you type, through whatever mail
|
||||
transport the site is configured with (**Admin → Settings → Email delivery** — see
|
||||
[Notifications and email](/docs/administration/notifications-and-email/)).
|
||||
|
||||
It sends **what is on screen**, saved or not. That is the point of it: try a wording, send
|
||||
it to yourself, look at it in a real inbox, and only then decide whether to save.
|
||||
|
||||
Test sends are recorded in the send log like any other message, including when they fail.
|
||||
|
||||
## Making a new template
|
||||
|
||||
You do not start from a blank page. Pick a message that is close to what you want, press
|
||||
**Duplicate**, and give the copy a key.
|
||||
|
||||
The **key** is how a rule refers to the template — `notify.team-welcome`, say. Lowercase
|
||||
letters, digits, dots and dashes, and it cannot be changed later, so pick one that will
|
||||
still make sense in a year.
|
||||
|
||||
The copy always starts as a draft. Once you are happy with it, publish it and point a rule
|
||||
at it in **Admin → Engagement → Rules**.
|
||||
|
||||
<Aside type="caution" title="A template a rule is using cannot be deleted">
|
||||
If you try, the site tells you which rules are still pointing at it. Repoint or delete
|
||||
those first. The alternative — letting the delete through — would leave a rule that quietly
|
||||
stops producing mail, and nothing on screen would say why.
|
||||
</Aside>
|
||||
|
||||
## Did it arrive?
|
||||
|
||||
**Admin → Engagement → Send Log** lists every message the site tried to deliver, newest
|
||||
first, successes and failures alike. When mail is not arriving, this is the screen that
|
||||
tells you whether the site tried and the relay refused, or whether it never tried at all.
|
||||
|
||||
Failures carry the reason the mail server gave, which is usually the actual answer — a
|
||||
rejected sender address, a bad password, a relay that will not accept your domain.
|
||||
|
||||
The log does not store anybody's email address. It keeps a one-way fingerprint instead, so
|
||||
that a bounce can be matched back to a delivery without the log itself becoming a second
|
||||
copy of your members' addresses. The rest of that screen — and the rules that decide a
|
||||
message is sent at all — is [Engagement rules](/docs/administration/engagement-rules/).
|
||||
@@ -10,7 +10,7 @@ not overlap.
|
||||
|
||||
| Screen | Is about | Comes from |
|
||||
|---|---|---|
|
||||
| **Moderation** | Your **Discord** guild — bans, kicks, mutes, warnings, joins, leaves, filter and spam hits | the bot, captured live |
|
||||
| **Moderation** | Your **Discord** server — bans, kicks, mutes, warnings, joins, leaves, filter and spam hits | the bot, captured live |
|
||||
| **Reports** | **Team forum content** members have reported | the site |
|
||||
| **Appeals** | Sanctions people are asking you to reverse | the site |
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Notifications and email
|
||||
description: Email over Gmail OAuth2, the announcement pipeline and its legs, the Discord bot, and opt-in push to the mobile app.
|
||||
description: Email over SMTP, the announcement pipeline and its legs, the Discord bot, and opt-in push to the mobile app.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
@@ -9,21 +9,67 @@ Four separate delivery paths, each optional, each off until you configure it. A
|
||||
configures none of them still works — it just never reaches anyone who is not looking at
|
||||
it.
|
||||
|
||||
This page is about the paths themselves. What decides that a particular message gets sent
|
||||
down one of them is a rule — see [Engagement rules](/docs/administration/engagement-rules/).
|
||||
|
||||
## Email
|
||||
|
||||
**Admin → Settings → Email delivery.** The site sends contact-form messages (and test
|
||||
messages) through **Gmail over OAuth2**, delivered to the *Contact email* setting.
|
||||
**Admin → Settings → Email delivery.** The site sends contact-form messages, invitations,
|
||||
password resets, team notifications and test messages through **SMTP**. Contact-form mail
|
||||
goes to the *Contact email* setting.
|
||||
|
||||
It reuses the **Google authentication client**, so the order is fixed: configure Google on
|
||||
the [Authentication](/docs/administration/authentication/) page first, then press **Connect
|
||||
Gmail** here. Until then the panel reads *Unconfigured* and says exactly that.
|
||||
You pick a mail transport and fill in the fields it asks for. There is no consent flow and
|
||||
no redirect to bounce through — it is a form, and the credentials go straight into the
|
||||
database encrypted at rest, write-only: the panel will tell you a password is *set*, and
|
||||
will never show it to you again.
|
||||
|
||||
The refresh token it stores is encrypted at rest like every other secret.
|
||||
### Three ways to point it somewhere
|
||||
|
||||
<Aside type="note" title="There is no SMTP option">
|
||||
Gmail over OAuth2 is the only supported delivery path today. Until it is connected, the
|
||||
contact form falls back to a `mailto:` link to the contact address — which works, and puts
|
||||
the message in the visitor's own mail client rather than in your logs.
|
||||
Any SMTP server works. Which one you should use depends on how much mail you expect to send.
|
||||
|
||||
**A relay — the recommended one.** Mailgun, SES, Postmark or equivalent: their host, port
|
||||
`587`, *Implicit TLS* **off**, and your API key as the password. Deliverability is the hard
|
||||
part of sending mail — reputation, DKIM, bounce handling — and this is the option where
|
||||
somebody else owns it. Use this for anything with real volume.
|
||||
|
||||
**A mailbox provider over SMTP — the simplest.** For example `smtp.gmail.com`, port `587`,
|
||||
*Implicit TLS* **off**, your address as the username, and an
|
||||
[app password](https://support.google.com/accounts/answer/185833) — not your account
|
||||
password, and it requires 2-Step Verification to be on. Fine for a small site; subject to
|
||||
the provider's daily send caps.
|
||||
|
||||
**Your own MTA.** If you already run mail on the same host: its address, port `25`,
|
||||
*Implicit TLS* **off**, username and password blank. The site treats a username with no
|
||||
password as incomplete, since that authenticates as nobody.
|
||||
|
||||
<Aside type="caution" title="The two fields that cause most failures">
|
||||
**Implicit TLS** belongs *on* only for port **465**. On port `587` leave it **off** — the
|
||||
connection still upgrades to TLS, using STARTTLS. Port 587 with it on does not report an
|
||||
error; it hangs.
|
||||
|
||||
**Send from** must be an address the account is allowed to send as. Unlike a username, this
|
||||
is not verified when you save it — a server that refuses your sender rejects the mail for
|
||||
SPF/DMARC reasons that look like nothing at all from the outside. **Send test** is what
|
||||
proves it, and it names this specifically when it happens.
|
||||
</Aside>
|
||||
|
||||
Until a transport is configured, the contact form falls back to a `mailto:` link to the
|
||||
contact address — which works, and puts the message in the visitor's own mail client rather
|
||||
than in your logs. Invitations surface a copyable accept link instead, and password resets
|
||||
still answer normally.
|
||||
|
||||
<Aside type="note" title="Upgrading from the Gmail connect flow">
|
||||
Earlier versions authorised a mailbox with a **Connect Gmail** consent flow that borrowed
|
||||
the Google authentication client. That flow has been removed.
|
||||
|
||||
If your site used it, mail **stops** on upgrade until you enter SMTP credentials — and
|
||||
nothing errors when it does, because every sender degrades politely. The admin dashboard
|
||||
warns you while it is true. `smtp.gmail.com` port 587 with an app password is the shortest
|
||||
route back.
|
||||
|
||||
Single sign-on is unaffected: the Google provider exists for SSO in its own right, and email
|
||||
merely borrowed its credentials. Removing the borrow also removes a trap — rotating the SSO
|
||||
secret used to break outbound mail silently.
|
||||
</Aside>
|
||||
|
||||
## Announcements
|
||||
@@ -36,7 +82,7 @@ at the wrong host.
|
||||
Which legs exist depends on what has registered one:
|
||||
|
||||
- **Discord `#news`** is core's, and needs the bot below.
|
||||
- **A module may add its own.** The `uo` module adds an in-game town crier, so a news post
|
||||
- **A module may add its own.** The Ultima Online module adds an in-game town crier, so a news post
|
||||
is announced to players who are logged into the game and never visit the site.
|
||||
|
||||
A leg brings its own settings with it — the town crier's duration is a module setting, not
|
||||
@@ -44,7 +90,7 @@ a core one — which is why they are documented with the module rather than here
|
||||
|
||||
## The Discord bot
|
||||
|
||||
**Admin → Discord Bot**: enable it, give it the guild (server) ID and the bot token, and
|
||||
**Admin → Discord Bot**: enable it, give it the **Guild (server) ID** and the bot token, and
|
||||
save. The token is stored **encrypted in the database** and is never an environment
|
||||
variable.
|
||||
|
||||
@@ -75,14 +121,45 @@ Two properties matter for what you have to trust:
|
||||
Without `NTFY_PUBLIC_URL` / `NTFY_ALLOWED_ORIGINS`, the app simply shows push as
|
||||
unavailable for your instance — nothing breaks.
|
||||
|
||||
A tickle raised by an engagement rule carries a pointer to the matching item in the
|
||||
[on-site inbox](#on-site-notifications) where there is one, so the app opens on the thing
|
||||
that happened rather than on a list. It is still only a pointer: the content is fetched, not
|
||||
delivered.
|
||||
|
||||
## On-site notifications
|
||||
|
||||
The third way to reach somebody, and the only one that needs no relay, no mailbox and no
|
||||
app: an item in their **notification inbox** on the site itself. A bell in the header
|
||||
carries the unread count; the list lives at **Account → Notifications**.
|
||||
|
||||
Two things are worth knowing before you enable a rule that uses it:
|
||||
|
||||
- **It is the one channel that is on by default.** Push and email are opt-in — both reach
|
||||
somebody somewhere else, so both have to be asked for. An inbox item is a row on a page
|
||||
the person chose to open, so it is opt-*out*: they switch it off per notification under
|
||||
Account → Notifications → Settings.
|
||||
- **The body is plain text, always.** The in-app template renders through the same block
|
||||
editor as your mail, but only the text of each block is stored, so nothing an operator
|
||||
writes can become markup on somebody else's page. Links are site-relative or dropped.
|
||||
|
||||
Old, read items are pruned nightly (90 days by default). **Unread items are never pruned** —
|
||||
an inbox that quietly deleted things nobody had seen would make the unread badge meaningless.
|
||||
|
||||
## Who receives what
|
||||
|
||||
The per-person side of this lives in the player portal, not the admin panel: each member
|
||||
chooses which Team and forum notifications they want, and how. Two defaults are worth
|
||||
knowing because they are not symmetrical:
|
||||
The per-person side of this lives in the player portal, not the admin panel: **Account →
|
||||
Notifications → Settings** is a grid of every notification against every channel, and each
|
||||
member sets their own. The defaults are not symmetrical, and the asymmetry is deliberate:
|
||||
|
||||
- **Push is opt-out** once a device is registered.
|
||||
- **Email is opt-in.**
|
||||
- **Push is opt-in.**
|
||||
- **On the site is opt-out** — see above.
|
||||
- **Muting a Team silences all three for that Team**, whatever the grid says, without
|
||||
touching any of their other Teams.
|
||||
|
||||
The operator's side of the same question — which events exist, and how wide an audience each
|
||||
one may ever be given — is [Engagement rules](/docs/administration/engagement-rules/). When
|
||||
a message went nowhere and you want to know why, the send log there is the screen that says.
|
||||
|
||||
<Aside type="caution" title="Nothing here retries">
|
||||
The announcement dispatcher sends once, and the Team notification bridge states plainly that
|
||||
|
||||
@@ -9,8 +9,8 @@ Teams are a core platform primitive: membership, roles, forums, notifications, m
|
||||
and the Discord integrations are all core's, and none of it knows what a Team *is* in your
|
||||
game.
|
||||
|
||||
**Core cannot create a Team.** Teams arrive from the installed module — with the `uo`
|
||||
module, they are the shard's guilds. On a deployment with no module, the Team machinery is
|
||||
**Core cannot create a Team.** Teams arrive from the installed game module, which maps
|
||||
whatever the game calls its groups of players onto a Team. On a deployment with no module, the Team machinery is
|
||||
present and permanently empty. That is not a bug to work around; it is the contract that
|
||||
lets the same forum, notification and moderation code serve any game.
|
||||
|
||||
@@ -25,15 +25,14 @@ reconciles them.
|
||||
**Admin → Teams** shows a sync panel per module: last attempt, last success, consecutive
|
||||
failures and the last error, with **Sync now** and **Resync now**.
|
||||
|
||||
The wording on that panel is exact and worth reading:
|
||||
|
||||
> Core has never had an answer it could trust. What is shown below is not a confirmed empty
|
||||
> shard.
|
||||
The wording on that panel is exact and worth reading. Until a sync has succeeded, it says
|
||||
that core has never had an answer it could trust, and that the list below it is not a
|
||||
confirmed empty one.
|
||||
|
||||
An empty list therefore means one of two very different things — there are no Teams, or
|
||||
nobody could ask. The panel tells you which, and a *last success: never* with a *last
|
||||
error* of `no uo-link configured` is the second. Fix
|
||||
[the shard connection](/docs/administration/the-shard-connection/) and sync again.
|
||||
nobody could ask. The panel tells you which: a *last success: never* with a *last error*
|
||||
that names the game connection is the second. Fix the game module's connection to its game
|
||||
server and sync again. Each game's group in the sidebar covers its own connection screen.
|
||||
|
||||
## Forums
|
||||
|
||||
@@ -48,6 +47,52 @@ Two rules are structural rather than settings:
|
||||
about a leader has to reach someone above them. See
|
||||
[Moderation](/docs/administration/moderation/).
|
||||
|
||||
## Team notification emails
|
||||
|
||||
**Team emails are sent by the engagement rules, and they arrive switched off.**
|
||||
|
||||
Someone posting in a Team forum used to send mail with no configuration at all. It now goes
|
||||
through the same engine as everything else the site sends: the forum post raises an event,
|
||||
an **engagement rule** decides who is told and through which message template, and the
|
||||
outbox delivers it. Push notifications to the app and the Discord bridge below are
|
||||
unaffected — only the email moved.
|
||||
|
||||
The practical consequence on an existing site: **nobody gets Team email until you turn a
|
||||
rule on.** Open **Admin → Engagement → Rules**. Four rules are waiting there, one per Team
|
||||
event, all switched off, and the screen says so at the top for as long as they all are.
|
||||
Switch on the ones your site wants.
|
||||
|
||||
| Rule | Sends when |
|
||||
|---|---|
|
||||
| **Team forum posts** | someone posts a new thread or reply |
|
||||
| **Team announcements** | a leader posts an announcement |
|
||||
| **Team — new member** | someone joins, at most once an hour per person |
|
||||
| **Team — leadership change** | a new leader is named, at most once an hour per person |
|
||||
|
||||
The first two are the ones most sites want. The last two describe things that already show
|
||||
up on the Team's activity feed and arrive from a sweep rather than from a person doing
|
||||
something — which is why they ship off and with a cooldown.
|
||||
|
||||
<Aside type="note" title="Members still control their own mail">
|
||||
A rule decides whether the site sends at all. Each member still chooses, per Team, between
|
||||
no email, one message per post, and a daily digest — on their own notifications screen or
|
||||
through the unsubscribe link in any Team email. Turning a rule on does not sign anybody up.
|
||||
</Aside>
|
||||
|
||||
**Digests are re-read at the moment they are sent**, not assembled as posts arrive. A site
|
||||
that was down for two days sends one digest rather than two days of backlog, a post a
|
||||
moderator hid is not in it, and somebody who lost access to a forum between the post and the
|
||||
send does not receive it.
|
||||
|
||||
**Unsubscribe links keep working.** A link in mail sent before this change still does what
|
||||
it says. What changed is that it is now precise: it stops the emails it came with and leaves
|
||||
that Team's push notifications alone, where before it silenced both.
|
||||
|
||||
You can change what any of these messages say — see
|
||||
[Message templates](/docs/administration/message-templates/) — decide which of them are sent
|
||||
at all under [Engagement rules](/docs/administration/engagement-rules/), and see who was
|
||||
actually sent what in **Admin → Engagement → Send log**.
|
||||
|
||||
## The Discord bridges
|
||||
|
||||
Two integrations, both optional, both configured from **Admin → Teams**.
|
||||
@@ -59,8 +104,8 @@ event leaves the site.
|
||||
|
||||
**Voice channels** — gives each Team a Discord voice channel of its own, with access
|
||||
granted by a per-Team role, so a Team's members can see and join theirs and nobody else
|
||||
can. It needs the bot reachable, and members need a linked Discord account and guild
|
||||
membership.
|
||||
can. It needs the bot reachable, and members need a linked Discord account and membership of
|
||||
your Discord server.
|
||||
|
||||
Its three settings deserve a thought each:
|
||||
|
||||
@@ -68,10 +113,10 @@ Its three settings deserve a thought each:
|
||||
|---|---|
|
||||
| **Minimum members** | How large a Team must be to get a channel. Every active member counts, linked account or not. |
|
||||
| **Grace window (days)** | How long a Team keeps its channel after it stops qualifying. A Team that recovers inside the window keeps the same channel; zero removes it on the next pass. |
|
||||
| **Staff roles** | Roles that can see and join every Team's channel. Guild administrators already can, so this is for staff who are not administrators. |
|
||||
| **Staff roles** | Roles that can see and join every Team's channel. Discord server administrators already can, so this is for staff who are not administrators. |
|
||||
|
||||
<Aside type="caution" title="Voice channels are a per-guild ceiling, not a per-Team one">
|
||||
Discord's role and channel limits apply to the whole guild, so a site with many small Teams
|
||||
<Aside type="caution" title="Voice channels are a per-server ceiling, not a per-Team one">
|
||||
Discord's role and channel limits apply to the whole Discord server, so a site with many small Teams
|
||||
can exhaust them. The minimum-members setting is the lever that keeps the count sane, and
|
||||
it is easier to raise it before provisioning than to unpick channels afterwards.
|
||||
</Aside>
|
||||
|
||||
@@ -67,44 +67,98 @@ deployment has nothing supervising it — `npm start` in a terminal, a container
|
||||
|
||||
## The game screens are empty or say offline
|
||||
|
||||
Work outwards from the game, and stop at the first check that fails.
|
||||
Work outwards from the game, and stop at the first check that fails. The order is the same
|
||||
for every game; the commands are each game's own.
|
||||
|
||||
1. **In game:** `[bridge status` — `connected=False` means the shard cannot reach the
|
||||
sidecar.
|
||||
2. **On the shard host:** `curl -s http://127.0.0.1:8080/health` — `plugin_connected: true`
|
||||
is the value that matters.
|
||||
3. **On the shard host:** `runicgateway doctor` — checks the install record, every overlay
|
||||
file hash, the service, and that the sidecar and overlay agree on a protocol.
|
||||
4. **On the site:** the [shard connection screen](/docs/administration/the-shard-connection/)
|
||||
— its four indicators say which link is broken.
|
||||
1. **On the game server:** the bridge plugin says whether it is connected to the sidecar.
|
||||
2. **On the game server's host:** the sidecar's `/health` answers without a token, and
|
||||
*plugin connected* is the value that matters.
|
||||
3. **On the game server's host:** `runicgateway doctor` checks the install record, the
|
||||
files it deployed, the service, and that the sidecar and the bridge plugin agree on a
|
||||
protocol.
|
||||
4. **On the site:** the game module's connection screen says which link is broken.
|
||||
|
||||
Two log lines with specific meanings: **`409`** is a protocol mismatch (set the Protocol
|
||||
field to what `/health` reports), and **`401`** is the auth token (read the live one back
|
||||
with `uo-link-sidecar --print-config`; do not retype it from a screenshot).
|
||||
Two responses from a sidecar mean the same thing for every game: **`409`** is a protocol
|
||||
mismatch (the sidecar refuses rather than mis-parsing), and **`401`** is the auth token.
|
||||
|
||||
<Aside type="note" title="“Nothing changed and it stopped working” usually means a ServUO update">
|
||||
An update to the server tree can revert `Scripts.csproj`, at which point the plugin sits in
|
||||
the tree and never compiles — and ServUO ignores the script build's exit code, so the boot
|
||||
looks clean. `doctor` catches it by comparing file hashes against the install record.
|
||||
</Aside>
|
||||
Each game's group in the sidebar has its own troubleshooting page with the exact commands:
|
||||
[Ultima Online](/docs/ultima-online/troubleshooting/) and [Rust](/docs/rust/troubleshooting/).
|
||||
|
||||
## Teams are missing
|
||||
|
||||
Check the sync panel on **Admin → Teams** before anything else: *last success: never* with
|
||||
`no uo-link configured` means the shard connection, not the Team machinery. And on a site
|
||||
with **no module installed**, an empty Team list is correct and final — core cannot create
|
||||
a Team. See [Teams](/docs/administration/teams/).
|
||||
an error naming the game connection means the module could not ask its game server, not
|
||||
that the Team machinery is broken. And on a site with **no module installed**, an empty
|
||||
Team list is correct and final — core cannot create a Team. See
|
||||
[Teams](/docs/administration/teams/).
|
||||
|
||||
## Email and announcements never arrive
|
||||
|
||||
- **The contact form opens a mail client.** Email delivery is not connected; that is the
|
||||
documented fallback. Connect Gmail in **Settings → Email delivery** — after configuring
|
||||
the Google provider, which it reuses.
|
||||
- **The contact form opens a mail client.** Email delivery is not configured; that is the
|
||||
documented fallback. Enter SMTP credentials in **Settings → Email delivery**. If this site
|
||||
used to send mail and stopped, the Gmail connect flow was removed — the admin dashboard
|
||||
says so, and [Notifications and email](/docs/administration/notifications-and-email/) has
|
||||
the migration.
|
||||
- **Mail is configured but nothing arrives, and there is no error.** Two usual causes, both
|
||||
invisible without a test send. *Implicit TLS* left on for port 587 hangs rather than
|
||||
failing; and a **Send from** address the server will not let you send as is rejected for
|
||||
SPF/DMARC reasons. Press **Send test** — its failure message names both cases.
|
||||
- **Email was working and the toggle is still on.** *Enable email sending* now gates every
|
||||
message, not just some of them. If it is off, nothing is sent, including the contact
|
||||
form.
|
||||
- **A published post announced nothing.** The Discord bot is a separate container. If the
|
||||
Discord Bot screen says *bot unreachable*, it is not running.
|
||||
- **A missed announcement does not come back.** Nothing retries; the post itself is still
|
||||
on the site.
|
||||
|
||||
## Nothing is sent for one particular event
|
||||
|
||||
Mail works, other notifications arrive, but this one thing never produces anything. The
|
||||
answer is almost always in **Engagement → Rules**, and it is one of four:
|
||||
|
||||
- **The rule is off.** Every rule ships disabled, including the ones your modules bring
|
||||
with them, so "installed" is not "on".
|
||||
- **The rule is badged *dormant*.** It is switched on but cannot fire — usually because the
|
||||
module that declared its trigger, or the audience it points at, is no longer installed.
|
||||
- **It fired and was held back by its own cooldown**, which is per person, per subject and
|
||||
per channel. The Send Log shows nothing for a message that was never queued.
|
||||
- **The audience resolves to nobody.** The rule editor's reach preview is the fastest way
|
||||
to find that out — it will tell you the count is zero and why.
|
||||
|
||||
[Engagement rules](/docs/administration/engagement-rules/) walks through all four.
|
||||
|
||||
## One person stopped receiving email
|
||||
|
||||
Everyone else is getting mail, so the transport is fine. Check
|
||||
**Engagement → Suppressions**, then **Engagement → Send Log**.
|
||||
|
||||
- **They are on the suppression list.** The site stops mailing an address once the
|
||||
receiving server says the mailbox does not exist. Addresses are stored one way and
|
||||
shown masked (`d***@example.com`), so search by their domain to find the row. If they
|
||||
have since fixed their mailbox, press **Lift a suppression** and type the full
|
||||
address — the screen genuinely does not have it, which is why you are asked.
|
||||
- **Suppression only affects engagement rules.** Password resets, invites and address
|
||||
verification still go out to a suppressed address, because those are things the person
|
||||
asked for themselves. So "they can reset their password but get no notifications" is
|
||||
the expected shape of this problem, not a contradiction.
|
||||
- **The Send Log says *Not sent*.** That is a suppression: nothing was sent to the mail
|
||||
server at all. *Bounced* means it was sent and the mailbox does not exist. *Failed*
|
||||
means the relay refused it for some other reason — that one is about your
|
||||
configuration, not about them.
|
||||
- **The Send Log has no row for them at all.** They were excluded before anything was
|
||||
queued. Either they have not opted in on **Notifications** for that stream, or
|
||||
*Require a verified email address* is on in **Settings** and they have not confirmed
|
||||
theirs. The rule editor's audience preview shows how many people each of those removes.
|
||||
|
||||
## Everyone stopped receiving email at once
|
||||
|
||||
Do **not** start clearing the suppression list — it is almost certainly not the cause.
|
||||
A whole-deployment stop is a transport problem: an expired password, a relay that has
|
||||
started refusing you, or *Enable email sending* switched off. The Send Log will show
|
||||
*Failed* rather than *Bounced* or *Not sent*, and **Settings → Email delivery** shows the
|
||||
last error. A wrong password never suppresses anybody; only the receiving server saying a
|
||||
specific mailbox does not exist does that.
|
||||
|
||||
## Uploads and modules fail with permission errors
|
||||
|
||||
Docker created a bind-mount source that the container user cannot write — usually because
|
||||
|
||||
@@ -97,8 +97,8 @@ A module that serves game data brings its **own** audience rules, and core does
|
||||
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
|
||||
The Ultima Online module's is the worked example, and it is a real boundary rather than a
|
||||
convenience filter: an admin-configurable, per-feature and per-field audience ladder with **fail-closed
|
||||
defaults**, applied at routes, at SSE subscribe time, *and* at the navigation. All three,
|
||||
because a surface that is filtered in only two of those places leaks through the third.
|
||||
|
||||
|
||||
166
src/content/docs/docs/architecture/events-architecture.mdx
Normal file
166
src/content/docs/docs/architecture/events-architecture.mdx
Normal file
@@ -0,0 +1,166 @@
|
||||
---
|
||||
title: Events architecture
|
||||
description: An event does not edit the world — it holds a lease. How a game-agnostic engine schedules changes to a live game world it cannot name.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
The Event System is a game-agnostic engine for **scheduled, bounded, audited** changes to a
|
||||
live game world. Core runs it and cannot name a single thing in your game.
|
||||
|
||||
The administrator's view is [Scheduled events](/docs/administration/events/).
|
||||
|
||||
## The two sentences the design turns on
|
||||
|
||||
**An event does not edit the world. It holds a lease.**
|
||||
|
||||
Anything an event changes that already existed is borrowed, not set: the game keeps the
|
||||
baseline, the site records both halves, and the lease carries its own deadline. When the
|
||||
deadline passes the game restores the value — whether or not it ever hears from the site
|
||||
again. A lease is never written to the game's save file either, so a server restart also
|
||||
puts every borrowed value back. That is the difference between automating a change and
|
||||
handing an unattended process a `[set` command.
|
||||
|
||||
**The module declares; core dispatches.** A module says a verb exists, what it costs and what
|
||||
it needs; core decides whether it is permitted, when it runs, in what order, how many times,
|
||||
within what budget, what it created and who is told. Nothing crosses that line as a string
|
||||
core interprets — the browser posts an action *id* and a params object, both validated
|
||||
against the registry before anything is dispatched. There is no passthrough field and no
|
||||
place a request body can name a game command.
|
||||
|
||||
## What is a table, and what deliberately is not
|
||||
|
||||
Eleven core tables, no ORM, and no migration system — which makes every table a permanent
|
||||
commitment. The rule applied was: **a table is for what must be queried, claimed or joined.**
|
||||
|
||||
| Kind | Where it lives |
|
||||
|---|---|
|
||||
| Definitions, series, versions, runs, steps, budget, resources, participants, gates, settings, log | Tables |
|
||||
| Phases | Configuration inside an immutable version snapshot. A phase has no identity a query needs; a step does |
|
||||
| Actions, budget dimensions, conditions | Registry entries a module declares at load. A stored one would outlive the module that can perform it |
|
||||
| A reward catalog | Neither. A reward is an ordinary action, so a granted reward is an ordinary ledger row |
|
||||
|
||||
**The step is the unit of execution, and it is a row** — one action invocation with a due
|
||||
time, a status, an attempt count and a claim. Retries, timeouts, duplicate execution and
|
||||
resumption after a crash are then all properties of that row rather than of a process's
|
||||
memory, which is what lets the runner be killed mid-run and pick up where it stopped.
|
||||
|
||||
**One run per occurrence, guaranteed by a unique index** on the definition, the scope and the
|
||||
scheduled instant — not by the claim. Two application instances cannot both start the same
|
||||
occurrence, because the second insert fails.
|
||||
|
||||
## Budgets are enforced in SQL
|
||||
|
||||
Consumption is spent with a conditional update:
|
||||
|
||||
```sql
|
||||
UPDATE event_run_budget
|
||||
SET consumed = consumed + ?
|
||||
WHERE run_id = ? AND dimension = ? AND consumed + ? <= cap
|
||||
```
|
||||
|
||||
No transaction, no read-then-write, and no way for two concurrent steps to both squeeze past
|
||||
the same ceiling.
|
||||
|
||||
<Aside type="tip" title="Why that is the strongest control here">
|
||||
A compromised admin session has already passed every role check the application has. It has
|
||||
not passed this one, because this one is not a check — it is a condition on the write. That is
|
||||
the reason per-run quotas were kept after the delegation model was dropped.
|
||||
</Aside>
|
||||
|
||||
## The ledger, and why cleanup is generated
|
||||
|
||||
Every world write appends to a resource ledger before it is confirmed: the run, the step, the
|
||||
owning module, an opaque kind and reference, and — for a borrowed value — the baseline
|
||||
alongside what was applied.
|
||||
|
||||
Teardown is then **derived from the ledger**, never authored, and runs on every terminal path:
|
||||
completion, cancellation and abort alike. An operator cannot be relied on to write the undo,
|
||||
and an aborted run never reaches the phase they wrote it in.
|
||||
|
||||
Two rules make that hold up:
|
||||
|
||||
- **A unique index across non-reverted rows** stops two events leasing the same target. The
|
||||
second one is refused rather than layered on top of the first.
|
||||
- **A restore is a compare-and-set.** If the current value is not what the lease applied,
|
||||
somebody else changed it since; the row is marked `drifted` rather than stamped over. The
|
||||
ledger would rather say "I do not know what happened here" than lie about having undone it.
|
||||
|
||||
## At-most-once, on a wire that can lose an answer
|
||||
|
||||
Every command the site sends the game carries an **idempotency key**, and the game executes a
|
||||
given key at most once — a repeat is answered with the original reply rather than re-run.
|
||||
|
||||
Without it, a lost acknowledgement is indistinguishable from a command that never applied, so
|
||||
every world write has to be declared un-retryable and one has to be *lost* rather than risk
|
||||
*doubling* it. The key is what makes a world-changing step an ordinary retried row like any
|
||||
other.
|
||||
|
||||
<Aside type="caution" title="The rule that pays for it">
|
||||
**Do not answer an error after changing the world.** The store treats a handler that ran and
|
||||
deliberately refused as a transient outcome and releases the key, so the answer is not frozen
|
||||
for ever — the acceptance walk found a refusal ("the last save was 227 seconds ago") replayed
|
||||
identically six times, with a number that could never age. A handler that has already changed
|
||||
something must not take that path.
|
||||
</Aside>
|
||||
|
||||
## Three layers, and the role check is only one of them
|
||||
|
||||
1. **Declaration** — a module says a verb exists. That is code the operator installed; it is
|
||||
not a permission.
|
||||
2. **Enablement** — an admin turns an action on for this deployment and sets its caps.
|
||||
Nothing above a notification is on by default.
|
||||
3. **Invocation** — the role check, then the cap, then the game's own switches. Admin routes
|
||||
are re-validated against the database on every request, so a demotion takes effect on the
|
||||
next click.
|
||||
|
||||
The game's switches are the layer outside the site's own database: they live in the bridge
|
||||
plugin's own config on the game server's host — `EventsEnabled`, in both games — and are off
|
||||
out of the box. No event and no role check can turn one on. On Rust an administrator can
|
||||
still edit that file from the game module's config screen, which reaches the host's config
|
||||
files through the bridge, so there it is a separate deliberate act rather than an unreachable
|
||||
one. The game's own ceilings **refuse rather than clamp** — because a silently shortened
|
||||
request leaves the two halves disagreeing about what happened.
|
||||
|
||||
<Aside type="note" title="Stated plainly">
|
||||
The module boundary is **not** a security boundary — a module runs in the same process with
|
||||
full access, and the module system's own documentation says so. None of the above defends
|
||||
against a hostile module. It defends against a compromised session and an operator mistake,
|
||||
both of which are made larger by *scheduling*: a change that happens while nobody is watching.
|
||||
That is why the caps and the leases matter more here than the role check does.
|
||||
</Aside>
|
||||
|
||||
## Where it meets everything else
|
||||
|
||||
- **[Engagement](/docs/administration/engagement-rules/)** — core registers `event.` triggers
|
||||
and owns none of the delivery. Who is told about a run is an ordinary rule.
|
||||
- **[The bridge](/docs/architecture/the-bridge/)** — every world verb becomes a command on the
|
||||
same versioned wire the game already speaks, through the same sidecar. Core still holds no
|
||||
game connection.
|
||||
- **[Teams](/docs/architecture/teams-architecture/)** — "this Team's members" is already a
|
||||
registered audience, so an event scoped to one Team needs no event-side feature at all.
|
||||
- **News** — an event does not write posts. A core action links an *existing* post to a run and
|
||||
enqueues it through the announcement pipeline, so the in-game town crier and Discord arrive
|
||||
as legs that already exist.
|
||||
|
||||
## What it deliberately does not do
|
||||
|
||||
- **No branching.** The condition grammar is `and` / `or` / `not` over comparisons, and the
|
||||
phase editor is a timeline rather than a canvas, because a canvas would promise power the
|
||||
engine has not got.
|
||||
- **No delegation, grants or proposal queue.** Permissions gate on the admin roles that
|
||||
already exist. The whole authorisation decision lives behind one function, which is what
|
||||
keeps a coordinator model a later option rather than a redesign.
|
||||
- **No event invoking another event.** It already works by composition — a second event's
|
||||
condition can be the first one completing.
|
||||
- **No mutation of game-owned content without a baseline.** If it cannot be restored, it
|
||||
cannot be leased, and it is out.
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`website/EVENTS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/EVENTS.md)
|
||||
is the design of record;
|
||||
[`website/MODULE_API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md)
|
||||
is the contract a module registers against; and
|
||||
[`link/v7.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v7.md)
|
||||
is the wire protocol the world verbs travel on.
|
||||
@@ -1,29 +1,47 @@
|
||||
---
|
||||
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.
|
||||
description: One number per game, declared in three places, that decides whether a game server and a sidecar are allowed to talk to each other.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import GameExample from '../../../../components/GameExample.astro';
|
||||
import platform from '../../../../data/platform.json';
|
||||
|
||||
The loopback wire protocol between the game plugin and the sidecar is a **versioned
|
||||
The loopback wire protocol between the bridge plugin and the sidecar is a **versioned
|
||||
compatibility contract**, not a build dependency. Nothing compiles the three sides together,
|
||||
so the number is what stops a mismatch from being discovered as corrupted data.
|
||||
|
||||
The current protocol is **4**.
|
||||
Each game has its own protocol, numbered independently: {platform.games.uo.name} is on
|
||||
**{platform.games.uo.protocol}** and {platform.games.rust.name} on
|
||||
**{platform.games.rust.protocol}**. The two numbers are not comparable — they version two
|
||||
different wires. Everything below holds for both.
|
||||
|
||||
## Three declaration sites
|
||||
|
||||
The same number is written down in three places, and they must move together.
|
||||
The same number is written down in three places, and they must move together:
|
||||
|
||||
1. **The sidecar's source** declares `PROTOCOL_VERSION` — what the sidecar speaks.
|
||||
2. **The bridge plugin's release manifest** declares `protocol` — what the plugin speaks.
|
||||
3. **The bundle manifest** copies the plugin's number in CI, so a released pair carries its
|
||||
own claim.
|
||||
|
||||
<GameExample game="uo">
|
||||
| Where | What declares it |
|
||||
|---|---|
|
||||
| `link/sidecar/src/main.rs` | `pub const PROTOCOL_VERSION: u32 = 4` — what the sidecar speaks |
|
||||
| `servuo-plugins/overlay.toml` | `protocol = 4` — what the plugin overlay speaks |
|
||||
| The bundle manifest | Copied from `overlay.toml` by CI, so a released pair carries its own claim |
|
||||
| `link` `sidecar/src/main.rs` | `PROTOCOL_VERSION`, currently {platform.games.uo.protocol} |
|
||||
| `servuo-plugins` `overlay.toml` | `protocol`, currently {platform.games.uo.protocol} |
|
||||
</GameExample>
|
||||
|
||||
<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**.
|
||||
<GameExample game="rust">
|
||||
| Where | What declares it |
|
||||
|---|---|
|
||||
| `Rust-Link` `sidecar/src/main.rs` | `PROTOCOL_VERSION`, currently {platform.games.rust.protocol} |
|
||||
| `Rust-Plugins` `overlay.toml` | `protocol`, currently {platform.games.rust.protocol} |
|
||||
</GameExample>
|
||||
|
||||
<Aside type="caution" title="Bump the plugin's manifest in the same PR as the emitters">
|
||||
CI folds the plugin's manifest into the release manifest, and **the installer refuses to
|
||||
pair a bridge plugin and a sidecar whose protocol numbers disagree**.
|
||||
|
||||
A bump that lands separately from the emitters does not fail loudly — it silently fails to
|
||||
compose into a bundle, and the next release simply does not appear.
|
||||
@@ -33,30 +51,54 @@ compose into a bundle, and the next release simply does not appear.
|
||||
|
||||
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.
|
||||
**Sidecar ↔ website.** Every sidecar response carries its protocol version in a header. A
|
||||
mismatch is rejected with **`409`** rather than mis-parsed, and the game module's admin
|
||||
screen is where an administrator sees it.
|
||||
|
||||
**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
|
||||
**Bridge plugin ↔ sidecar.** The installer resolves a **bundle** — an exact,
|
||||
protocol-checked pair of sidecar and bridge plugin published by CI — and never "latest of
|
||||
each". That is the whole
|
||||
reason bundles exist: two independently released components that must agree cannot be
|
||||
allowed to be chosen independently.
|
||||
|
||||
## What a bump obliges
|
||||
|
||||
Changing a message shape means editing every side plus the specification. A protocol-4
|
||||
change touched:
|
||||
Changing a message shape means editing every side plus the specification: the bridge plugin,
|
||||
the sidecar, the game module, and the protocol document in `docs`.
|
||||
|
||||
**`website` is usually not on that list, and its absence is the interesting part.** Core
|
||||
holds no game connection and names no game noun, so most protocol bumps do not reach it at
|
||||
all. One reaches core only when what changes is the shape of something core owns — a ledger,
|
||||
a place to store a picture — rather than a game noun.
|
||||
|
||||
<GameExample game="uo">
|
||||
Protocol 8 taught the bridge to carry a game's own client files, and touched four
|
||||
repositories:
|
||||
|
||||
| Repository | What had to change |
|
||||
|---|---|
|
||||
| `servuo-plugins` | The emitters, the config keys, and `overlay.toml` |
|
||||
| `link` | `PROTOCOL_VERSION`, a store migration, and the projections |
|
||||
| `module-uo` | The tables, the ingest, and the kind-to-feature map |
|
||||
| `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 |
|
||||
|
||||
Note `link`'s entry: **a protocol bump can require a store migration**, because the sidecar
|
||||
persists what it forwards. That is not automatic, and version 4 was the first bump that
|
||||
needed one.
|
||||
Core's entire share of eight phases of work was a **deletion**: a developer tool it no longer
|
||||
needed. Everything the bump needed — somewhere to put a picture — core already offered every
|
||||
module.
|
||||
</GameExample>
|
||||
|
||||
**A protocol bump can also require a store migration**, because the sidecar persists what it
|
||||
forwards. That is not automatic, and it is rare: every frame is persisted whole, so a bump
|
||||
that only widens a frame, or adds a kind, or adds a guarantee about how a command is
|
||||
executed, asks nothing of a store that defines no schema for a frame's contents. That is the
|
||||
dumb-forwarder property paying for itself.
|
||||
|
||||
<GameExample game="uo">
|
||||
It has happened once: version 4 added a column to a table that already existed. Versions 5
|
||||
to 8 needed none. Version 8 is the largest bump the protocol has had, and it moves megabytes
|
||||
of artwork rather than events — and it changed **no line** of the sidecar's store, because
|
||||
the things it carries are answers to requests rather than events to keep.
|
||||
</GameExample>
|
||||
|
||||
## This is not the module API version
|
||||
|
||||
@@ -64,7 +106,7 @@ Two different numbers, versioning two different contracts, and confusing them is
|
||||
|
||||
| | Versions | Lives in | Checked |
|
||||
|---|---|---|---|
|
||||
| **`PROTOCOL_VERSION`** | The game ↔ sidecar wire | `link`, `servuo-plugins`, the bundle | `X-UOLink-Version`, and the installer's pairing check |
|
||||
| **`PROTOCOL_VERSION`** | The game ↔ sidecar wire, one per game | The sidecar, the bridge plugin, the bundle | The sidecar's version header, and the installer's pairing check |
|
||||
| **`MODULE_API_VERSION`** | The website ↔ module contract | `website`, and every module's `coreApi` | At module load, before the module's code runs |
|
||||
|
||||
A module that never talks to a game server has no protocol version at all. See [The module
|
||||
@@ -92,9 +134,11 @@ What is worth inheriting is the **shape**:
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`link/v4.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v4.md)
|
||||
is the protocol-4 record, including its cross-repository obligations;
|
||||
Each game's protocol has its own record in the
|
||||
[`docs` repository](https://gitea.whitlocktech.com/RunicGateway/docs). For Ultima Online,
|
||||
[`link/v8.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/v8.md)
|
||||
is the current protocol's record, including its cross-repository obligations, and
|
||||
[`link/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md)
|
||||
§7 is the wire protocol, and
|
||||
[`link/INTEGRATION.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md)
|
||||
the integration guide.
|
||||
§7 is the wire protocol. For Rust,
|
||||
[the Rust bridge protocol](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
|
||||
is both.
|
||||
|
||||
@@ -4,28 +4,49 @@ description: The whole platform in one place — what each repository is, what t
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import GameExample from '../../../../components/GameExample.astro';
|
||||
|
||||
The drawn version of this, for evaluators, is on
|
||||
[Architecture](/architecture/). This page is the detailed account.
|
||||
|
||||
## Ten repositories, deployed independently
|
||||
## Fourteen repositories, deployed independently
|
||||
|
||||
Nothing here is a monorepo. Each repository has its own history, its own CI and its own
|
||||
release cadence; what binds them is a set of **versioned contracts**, not a build.
|
||||
|
||||
Seven of them are core, and serve every game:
|
||||
|
||||
| Repository | What it is |
|
||||
|---|---|
|
||||
| `website` | The Node/Express + MariaDB + React site. The only internet-facing web app |
|
||||
| `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 |
|
||||
| `installer` | Deploys a game server's side: the bridge plugin, and the sidecar with its service |
|
||||
| `Android-app` | Native Android client of the website API |
|
||||
| `Integration-kit` | The instruction book for putting a different game on the platform |
|
||||
| `docs` | Canonical design docs and the protocol spec |
|
||||
| `docs` | Canonical design docs and the protocol specs |
|
||||
| `runicgateway.com` | This site |
|
||||
| `.profile` | The organisation landing page |
|
||||
|
||||
The other seven belong to a game. Each game has the same three: **a game module** that adds
|
||||
its screens to the site, **a sidecar** that is the only network-facing part of its bridge,
|
||||
and **a bridge plugin** that runs inside the game server and feeds the sidecar.
|
||||
|
||||
<GameExample game="uo">
|
||||
| Repository | Its part |
|
||||
|---|---|
|
||||
| `Module-uo` | The game module |
|
||||
| `link` | The sidecar, uo-link, in Rust |
|
||||
| `servuo-plugins` | The bridge plugin, a C# overlay ServUO compiles at boot |
|
||||
</GameExample>
|
||||
|
||||
<GameExample game="rust">
|
||||
| Repository | Its part |
|
||||
|---|---|
|
||||
| `Module-Rust` | The game module |
|
||||
| `Rust-Link` | The sidecar, rust-link, in Rust |
|
||||
| `Rust-Plugins` | The bridge plugin, for Oxide and Carbon |
|
||||
| `runicnpc-rust` | RunicNPC, an NPC plugin the bridge drives, which also works on its own |
|
||||
</GameExample>
|
||||
|
||||
## The layers
|
||||
|
||||
```
|
||||
@@ -59,9 +80,8 @@ particular game. Routes, tables, pages, navigation and push streams for a game a
|
||||
[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.
|
||||
That is why the architecture below describes a game module as something core *loads* rather
|
||||
than as part of the platform. There are two, and core depends on neither.
|
||||
|
||||
## The invariants
|
||||
|
||||
@@ -69,29 +89,29 @@ 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.
|
||||
The game server's bridge plugin **dials out** to the sidecar over loopback TCP,
|
||||
newline-delimited JSON, on `127.0.0.1`. The sidecar is the listener; the game opens no port.
|
||||
Only the sidecar is exposed, and only the website's backend talks to it.
|
||||
|
||||
See [The bridge](/docs/architecture/the-bridge/).
|
||||
|
||||
### A wedged sidecar can never stall the game
|
||||
|
||||
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.
|
||||
In the bridge plugin, `Emit()` enqueues onto a **bounded, drop-oldest** queue and returns
|
||||
immediately. It never touches the socket from the game's main thread. Every world read
|
||||
happens on the main thread; a dedicated writer thread drains the queue.
|
||||
|
||||
Dropping game events is strictly better than pausing the game to deliver them.
|
||||
|
||||
### The website degrades rather than fails
|
||||
|
||||
The sidecar REST client never throws — every call returns `{ ok, data, status }`. The public
|
||||
site still renders with the shard shown offline.
|
||||
site still renders with the game shown offline.
|
||||
|
||||
That guarantee covers **reading the configuration too**: resolving the admin-managed config
|
||||
decrypts a stored token, which throws if the ciphertext cannot be authenticated (a rotated
|
||||
`SECRET_ENC_KEY`, or a database dump restored under a different key). That is caught inside
|
||||
the client and reported as unavailable, so a wrong key degrades the shard surface instead of
|
||||
the client and reported as unavailable, so a wrong key degrades the game's screens instead of
|
||||
500-ing it — and the admin config screen keeps working, which is the screen you need in order
|
||||
to recover.
|
||||
|
||||
@@ -114,9 +134,10 @@ lifecycle](/docs/modules/module-lifecycle/#failure-is-contained-by-construction)
|
||||
|
||||
### Secrets are encrypted at rest
|
||||
|
||||
OAuth client secrets, the sidecar token and the Gmail refresh token are AES-256-GCM
|
||||
encrypted, keyed by `SECRET_ENC_KEY`. **The sidecar token is write-only in the API** — it is
|
||||
never returned to any client.
|
||||
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
|
||||
@@ -127,7 +148,7 @@ variables](/docs/reference/environment-variables/).
|
||||
## 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
|
||||
installer binary sets up the game server side only, and never contacts the website.** The website
|
||||
is a separate Docker deployment on, usually, a different machine.
|
||||
|
||||
The [installation path](/docs/getting-started/requirements/) walks both in order.
|
||||
|
||||
@@ -1,12 +1,13 @@
|
||||
---
|
||||
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.
|
||||
description: Teams is a contract, not a surface — how core owns every game's groups of players without ever learning what one is called.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
Most games have groups: guilds, clans, corporations, tribes, crews. Runic Gateway supports
|
||||
them as a **core platform primitive**, while core itself never learns what yours is called.
|
||||
Most games have groups of players, and every game has its own word for them. Runic Gateway
|
||||
supports them as a **core platform primitive**, the **Team**, while core itself never learns
|
||||
what your game calls one.
|
||||
|
||||
The administrator's view is [Teams](/docs/administration/teams/).
|
||||
|
||||
@@ -25,7 +26,8 @@ fill** — `registry.declareModuleSlot(id, name, { core })`, with core offering
|
||||
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
|
||||
The first version had core's fills naming three of the first game module's slots
|
||||
**literally**. It
|
||||
worked for exactly one module and silently did nothing for any other game — an empty page
|
||||
with nothing logged.
|
||||
|
||||
|
||||
@@ -15,11 +15,11 @@ 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 ──────┘
|
||||
game server ──dials out──▶ sidecar ──HTTP + WS──▶ website
|
||||
(bridge plugin) 127.0.0.1 bearer + version (game module)
|
||||
newline JSON
|
||||
▲ │
|
||||
└────────── the game opens NO port ───────┘
|
||||
```
|
||||
|
||||
Three properties fall out of that diagram, and each is a rule rather than an
|
||||
@@ -27,7 +27,7 @@ implementation detail.
|
||||
|
||||
## 1. The game dials out
|
||||
|
||||
**The sidecar is the listener. The game connects to it.** The shard opens no port at all,
|
||||
**The sidecar is the listener. The game connects to it.** The game server opens no port at all,
|
||||
and nothing on the internet can reach it even in principle.
|
||||
|
||||
This inverts the intuitive design — you would expect the thing with the data to serve it —
|
||||
@@ -41,9 +41,9 @@ loopback TCP.
|
||||
|
||||
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.
|
||||
In the bridge plugin, `Emit()` **enqueues onto a bounded, drop-oldest queue and returns
|
||||
immediately**. It never touches the socket from the game's main thread. Every world read
|
||||
happens on the main thread; a dedicated writer thread drains the queue.
|
||||
|
||||
<Aside type="caution" title="Dropping events beats pausing the game">
|
||||
If the queue fills, the oldest events are discarded. That is the correct trade: a game
|
||||
@@ -54,7 +54,7 @@ Design your own plugin the same way. The game thread must never block on I/O —
|
||||
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
|
||||
Inbound commands get the mirror rule: **every inbound handler marshals to the main thread
|
||||
before touching world state.**
|
||||
|
||||
## 3. The sidecar persists before it forwards
|
||||
@@ -68,7 +68,7 @@ responsibility. The sidecar is a **dumb forwarder** — it makes no access-contr
|
||||
and holds no policy. Access control and the admin-toggleable visibility scope live on the
|
||||
**website**, where an administrator can see and change them.
|
||||
|
||||
## Two ways in
|
||||
## 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,
|
||||
@@ -77,49 +77,58 @@ than accumulating history.
|
||||
|
||||
**Point-in-time reads and commands** go over **REST**, through a client that never throws.
|
||||
|
||||
Every call carries `Authorization: Bearer <token>` and an `X-UOLink-Version` header. **A
|
||||
**Bulk reads** — a game's own files, such as its client artwork or its string table — are
|
||||
the newest and the least obvious, and so far only one game's bridge needs them. They go over the request/reply path in **pages**, with **one
|
||||
request in flight at a time** and a hard cap on how large a single line may be.
|
||||
|
||||
<Aside type="note" title="Why bulk data must not ride the event stream">
|
||||
It is the tempting shortcut, and it is wrong for a structural reason rather than a
|
||||
performance one: the sidecar **persists every event and broadcasts it to every connected
|
||||
client**. That is exactly what you want for "a player logged in" and exactly what you do not
|
||||
want for hundreds of megabytes of artwork, which is an *answer to a question somebody
|
||||
asked* rather than news.
|
||||
|
||||
Sending it as replies instead is what lets a protocol bump move megabytes without the
|
||||
sidecar's store changing by a line. The single slot is the other half: it is what keeps the queue
|
||||
between the game and the writer thread shallow, so rule 2 above still holds while a
|
||||
transfer is running.
|
||||
</Aside>
|
||||
|
||||
Every call carries `Authorization: Bearer <token>` and a protocol-version header. **A
|
||||
protocol mismatch fails fast with `409`** rather than being mis-parsed — see [Protocol
|
||||
versions](/docs/architecture/protocol-versions/).
|
||||
|
||||
## What the shard can say
|
||||
## What a game server 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:
|
||||
Each game has its own event catalog, because each game has its own things worth telling a
|
||||
website about. Every catalog has the same structure, though: kinds the module declares,
|
||||
each one either safe for the public stream or kept to the admin one.
|
||||
|
||||
```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 [Event catalog](/docs/reference/event-catalog/).
|
||||
- **Ultima Online:** [its event catalog](/docs/ultima-online/event-catalog/), in the Ultima Online group
|
||||
- **Rust:** [its event kinds](/docs/rust/event-kinds/), in the Rust group
|
||||
|
||||
## Two design details worth stealing
|
||||
|
||||
**`server.hello` is per-connection, not per-boot.** The sidecar restarts independently of
|
||||
the game, so anything it needs up front must be re-sent on **every** connect. An earlier
|
||||
draft emitted a "started" event once at boot; a sidecar that came up second never received
|
||||
it and had no idea which shard it was attached to.
|
||||
it and had no idea which game server it was attached to.
|
||||
|
||||
It carries a `bootId` — a GUID generated at server start, stable across sidecar reconnects
|
||||
and changed on every game restart. That is how the sidecar tells *"I reconnected"* (keep
|
||||
cached state) from *"the game restarted"* (discard it).
|
||||
|
||||
**Rosters are sets, not signatures.** 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.
|
||||
**Rosters are sets, not signatures.** A bridge that reports a Team's members should send
|
||||
the membership as a set rather than fold it into a checksum, because a sum can collide: one
|
||||
member joining and another leaving between two sweeps offset each other, and the Team reads
|
||||
as unchanged. A set can also be *differenced*, which is what makes per-member leave events
|
||||
possible for a game that raises no event for leaving. The Ultima Online bridge does exactly
|
||||
this; its [event catalog](/docs/ultima-online/event-catalog/#rosters-are-sets-not-signatures)
|
||||
has the details.
|
||||
|
||||
## Building one for another game
|
||||
|
||||
The bridge is not UO-specific in shape, only in vocabulary. Chapters 3 and 4 of [the
|
||||
Both games' bridges have this shape; only their vocabulary differs. Chapters 3 and 4 of [the
|
||||
Integration Kit](/docs/modules/the-integration-kit/) cover the sidecar and the game-side
|
||||
plugin, and they are the two parts where the mistakes are most expensive.
|
||||
|
||||
|
||||
@@ -1,139 +1,52 @@
|
||||
---
|
||||
title: Connect a game server
|
||||
description: The installer binary on the shard host — what it deploys, what it asks, and the four values it prints for the website.
|
||||
title: Connect your game server
|
||||
description: The second install, on the machine that runs your game server — what every game's has in common, and where each game's own steps are.
|
||||
---
|
||||
|
||||
import platform from '../../../../data/platform.json';
|
||||
import { Aside, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
This is the second of the two installs, and it happens on the machine that runs your game
|
||||
server. One binary deploys the plugin, installs the sidecar, registers its service, and
|
||||
prints four values for you to paste into the website.
|
||||
server. It never contacts your website, and it never starts or stops your game server.
|
||||
|
||||
It never contacts your website, and it never starts or stops your shard.
|
||||
Every game's version of this step has the same shape:
|
||||
|
||||
## What gets deployed
|
||||
|
||||
| # | Component | Where it goes |
|
||||
|---|---|---|
|
||||
| 1 | **The plugin overlay** — C# source ServUO compiles at boot | into your ServUO tree |
|
||||
| 2 | **The uo-link sidecar** — a small Rust service | a system directory, plus a service |
|
||||
| 3 | **A record of the run** | `install.json`, with per-file hashes and backups |
|
||||
1. **The bridge plugin** goes onto the game server, where the game's own plugin system loads
|
||||
it.
|
||||
2. **The sidecar** goes onto the same host, as a service. It is the only part of the bridge
|
||||
that listens on a network.
|
||||
3. **You paste what the install prints into the site** — the sidecar's address and its auth
|
||||
token, plus whatever else that game's screen asks for — on the game module's admin screen.
|
||||
|
||||
```
|
||||
ServUO shard ──loopback TCP 127.0.0.1:7788──► uo-link sidecar ──HTTP + WebSocket──► website
|
||||
game server ──loopback, dials out──► sidecar ──HTTP + WebSocket──► website
|
||||
```
|
||||
|
||||
The shard **dials out**. It never listens for the website and is never reachable from the
|
||||
internet; only the sidecar is exposed, and only to your site.
|
||||
The game server **dials out** to the sidecar over loopback. It never listens for the website
|
||||
and is never reachable from the internet; only the sidecar is exposed, and only to your
|
||||
site.
|
||||
|
||||
## Install
|
||||
The [installer](/docs/reference/installer-cli/) ({platform.releases.installer}) does all of
|
||||
this for both games, told which one it is setting up. It installs a **bundle** — an exact,
|
||||
protocol-checked pair of sidecar and bridge plugin — never "the latest of each".
|
||||
|
||||
<Steps>
|
||||
## Pick your game
|
||||
|
||||
1. **Download the binary for your OS, and `SHA256SUMS`**, from the
|
||||
[installer releases page](https://gitea.whitlocktech.com/RunicGateway/installer/releases)
|
||||
({platform.releases.installer}).
|
||||
|
||||
Releases are **unsigned** — there is no code-signing certificate, so that checksum file
|
||||
is the whole trust anchor. Check it:
|
||||
|
||||
```bash
|
||||
sha256sum -c SHA256SUMS --ignore-missing
|
||||
chmod +x runicgateway-installer-linux-x86_64
|
||||
```
|
||||
|
||||
On Windows, `(Get-FileHash .\runicgateway-installer-windows-x86_64.exe -Algorithm SHA256).Hash`
|
||||
and compare. Windows will also show a SmartScreen prompt on first run, for the same
|
||||
reason.
|
||||
|
||||
2. **Stop the shard.** `ServUO.exe` locks `Scripts.dll` and rewrites `Saves/` on exit, so
|
||||
the installer refuses to deploy under a running server.
|
||||
|
||||
3. **Run it, elevated.**
|
||||
|
||||
```bash
|
||||
sudo ./runicgateway-installer-linux-x86_64 install
|
||||
```
|
||||
|
||||
Add `--verify` first if you want to see every change it would make and write nothing.
|
||||
|
||||
It asks four things: your ServUO root, whether to apply the optional patch tier, the
|
||||
hostname your website should use to reach this machine, and your site's URL (used only
|
||||
to print a link at the end).
|
||||
|
||||
4. **Read the summary.** It reports the overlay sync file by file, the sidecar binary and
|
||||
its verified hash, the config and database paths, and the service state. Then it says
|
||||
what you must do next — restart ServUO yourself, because it will not do that for you.
|
||||
|
||||
</Steps>
|
||||
|
||||
<Aside type="note" title="It installs a bundle, not “latest of each”">
|
||||
The three components version independently but must agree on one wire protocol, so what it
|
||||
resolves is a **bundle**: an exact, protocol-checked pair of sidecar and overlay versions
|
||||
({platform.bundle.tag} today — sidecar {platform.bundle.sidecar}, overlay {platform.bundle.overlay}).
|
||||
`--bundle <tag>` pins an exact past combination, so a reinstall in six months reproduces
|
||||
today's install rather than tomorrow's.
|
||||
</Aside>
|
||||
|
||||
## The patch tier is optional
|
||||
|
||||
Most of the plugin is *added* files, which is why the base install is a safe copy. Two
|
||||
features need edits to stock ServUO sources, and those are opt-in, off unless you say yes,
|
||||
and refused where the target lines are not stock. Skipping the tier costs you vendor-sale
|
||||
events and in-game moderation audit forwarding; everything else works.
|
||||
|
||||
The tier is written and tested against stock ServUO {platform.bundle.servuoMin}. On any
|
||||
other version it is unsupported and untested, and the prompt makes you answer past a
|
||||
warning.
|
||||
|
||||
## Paste the four values into the site
|
||||
|
||||
A successful run ends by printing the one step it cannot do for you:
|
||||
|
||||
```
|
||||
Base URL http://shard.example.com:8080
|
||||
WebSocket URL ws://shard.example.com:8080/ws
|
||||
Protocol version 4
|
||||
Auth token 4f9c… (also in sidecar.toml)
|
||||
```
|
||||
|
||||
Every value comes from asking the installed sidecar itself, so it cannot drift from what
|
||||
the service actually runs.
|
||||
|
||||
On the site, sign in as an administrator and open **Shard (uo-link)** in the admin
|
||||
sidebar — `/admin/uo/link`. Tick *Enable the shard integration*, paste **Base URL**,
|
||||
**WebSocket URL**, **Auth token** and **Protocol**, and save. The ingest client restarts
|
||||
immediately.
|
||||
|
||||
<Aside type="caution" title="Installer v0.1.0 prints an older path for that screen">
|
||||
v0.1.0 prints `…/admin/shard`. Since the shard screens became part of the `uo` module — and
|
||||
a module owns one path segment wherever it appears — the screen moved to
|
||||
**`/admin/uo/link`**.
|
||||
|
||||
The old path does not fail visibly: the site 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>
|
||||
|
||||
The token is encrypted at rest and **never returned to any client** — losing it means
|
||||
reading it back from `sidecar.toml` on the shard host, not from the website.
|
||||
| Game | Its steps |
|
||||
|---|---|
|
||||
| **{platform.games.uo.name}** | [Connecting the server](/docs/ultima-online/connect-a-servuo-shard/), then [verifying its bridge](/docs/ultima-online/verify-the-bridge/), in the Ultima Online group |
|
||||
| **{platform.games.rust.name}** | [Installing the bridge](/docs/rust/install-the-bridge/) — the installer, a Pterodactyl egg, or by hand — then [connecting the site](/docs/rust/connect-the-site/), in the Rust group |
|
||||
|
||||
## If the website is on a different machine
|
||||
|
||||
The sidecar binds `127.0.0.1:8080`, reachable only from the shard host. If the site runs
|
||||
elsewhere, widen the bind and then narrow the access:
|
||||
The sidecar listens on `127.0.0.1` by default, reachable only from the game server's host.
|
||||
If the site runs elsewhere, widen the sidecar's web bind and then narrow the access:
|
||||
|
||||
1. Set `[web] bind` in `sidecar.toml` to `0.0.0.0:8080` and restart the service.
|
||||
2. **Firewall that port to your website's address only.** The auth token is always on, but
|
||||
1. **Firewall that port to your website's address only.** The auth token is always on, but
|
||||
it travels as a plain bearer token — the sidecar speaks HTTP, not HTTPS.
|
||||
3. If the two hosts are not on a trusted network, put the sidecar behind a TLS reverse
|
||||
2. If the two hosts are not on a trusted network, put the sidecar behind a TLS reverse
|
||||
proxy or a VPN link and give the website the `https://` / `wss://` URLs.
|
||||
|
||||
Leave `[shard] bind` on `127.0.0.1:7788`. That socket accepts *inbound commands to the
|
||||
**Leave the sidecar's game-facing socket on loopback.** It accepts *inbound commands to the
|
||||
game*, and being loopback-only is what makes that safe.
|
||||
|
||||
Next: [Verify the whole stack](/docs/getting-started/verify-the-whole-stack/) — because a
|
||||
|
||||
@@ -6,12 +6,19 @@ description: Everything game-specific is a module. Installing one, what it adds,
|
||||
import platform from '../../../../data/platform.json';
|
||||
import { Aside, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
Core knows nothing about any game. Every game-specific screen — shard status, the map
|
||||
atlas, the player marketplace, character sheets — comes from a **module**, a directory on a
|
||||
mounted volume that the server loads at start.
|
||||
Core knows nothing about any game. Every game-specific screen — a game server's live
|
||||
status, its map, its leaderboards, its players' characters — comes from a **game module**, a
|
||||
directory on a mounted volume that the server loads at start.
|
||||
|
||||
Today there is one: **`uo`**, for ServUO shards, published as
|
||||
[`Module-uo`](https://gitea.whitlocktech.com/RunicGateway/Module-uo) ({platform.releases['Module-uo']}).
|
||||
There are two, both built inside this project, and a site runs **one** of them:
|
||||
|
||||
| Game | Module | Latest release |
|
||||
|---|---|---|
|
||||
| **{platform.games.uo.name}** | [releases](https://gitea.whitlocktech.com/RunicGateway/Module-uo/releases) | {platform.releases['Module-uo']} |
|
||||
| **{platform.games.rust.name}** | [releases](https://gitea.whitlocktech.com/RunicGateway/Module-Rust/releases) | {platform.releases['Module-Rust']} |
|
||||
|
||||
What each one adds is in its own group in the sidebar:
|
||||
[Ultima Online](/docs/ultima-online/) and [Rust](/docs/rust/).
|
||||
|
||||
## Install it
|
||||
|
||||
@@ -22,9 +29,8 @@ Today there is one: **`uo`**, for ServUO shards, published as
|
||||
2. **Paste the URL of a release's install manifest** into *Release install-manifest URL*
|
||||
and press **Install**.
|
||||
|
||||
For the current `uo` release that is the `module-uo-<version>.json` asset on
|
||||
[its releases page](https://gitea.whitlocktech.com/RunicGateway/Module-uo/releases).
|
||||
The site downloads the bundle, checks it against the `sha256` the manifest declares, and
|
||||
Every module release carries one: a `.json` asset named after the module and its
|
||||
version, on the releases page linked above. The site downloads the bundle, checks it against the `sha256` the manifest declares, and
|
||||
unpacks it onto the modules volume.
|
||||
|
||||
There is no catalog to browse, deliberately: a catalog would make core's release cadence
|
||||
@@ -50,28 +56,21 @@ must be in the allowlist at the bottom of the same screen — re-checked on ever
|
||||
It is seeded with `gitea.whitlocktech.com`, and an empty list forbids every install.
|
||||
</Aside>
|
||||
|
||||
## What the `uo` module adds
|
||||
## What a module adds
|
||||
|
||||
Watch the log at the restart and you will see exactly what it mounted:
|
||||
Watch the log at the restart and you will see exactly what it mounted: its routes, its
|
||||
database schema, and the line that says it started. Its screens appear in the navigation,
|
||||
and its admin screens in the admin sidebar.
|
||||
|
||||
```
|
||||
[uo] registered routes: public:/shard,/atlas admin:/shard,/uo-link player:/shard
|
||||
[modules] schema ensured for module "uo"
|
||||
[modules] module "uo" started
|
||||
```
|
||||
|
||||
Its capabilities are {platform.moduleUoCapabilities.join(', ')} — the shard console, the
|
||||
map atlas, the player-vendor marketplace, city governors, guilds, houses and IDOCs, champion
|
||||
boards, and the cliloc strings that make item names readable.
|
||||
|
||||
A module owns **one path segment** wherever it appears, so its pages live under `/uo/…`,
|
||||
`/admin/uo/…` and `/player/uo/…`. That boundary is visible in the URL on purpose.
|
||||
A module owns **one path segment** wherever it appears, so a module with the id `<id>` has
|
||||
its pages under `/<id>/…`, `/admin/<id>/…` and `/player/<id>/…`. That boundary is visible
|
||||
in the URL on purpose.
|
||||
|
||||
<Aside type="caution" title="A module with no game server behind it is empty, not broken">
|
||||
Installing `uo` does not connect anything. Its screens exist and report the shard as
|
||||
Installing a module does not connect anything. Its screens exist and report the game as
|
||||
offline until you
|
||||
[connect a game server](/docs/getting-started/connect-a-game-server/) — which is the same
|
||||
thing the public site does when the shard goes down, and is designed to be unremarkable.
|
||||
[connect your game server](/docs/getting-started/connect-a-game-server/) — which is the same
|
||||
thing the public site does when the game goes down, and is designed to be unremarkable.
|
||||
</Aside>
|
||||
|
||||
## The declarative alternative
|
||||
|
||||
@@ -93,7 +93,7 @@ it down. Docker Compose is the supervisor here, and this line is what makes it o
|
||||
## Two variables worth reading twice
|
||||
|
||||
**`SECRET_ENC_KEY`** encrypts secrets at rest — OAuth client secrets, the Discord bot
|
||||
token, the shard's auth token. In production the server **refuses to start** without it.
|
||||
token, the game module's sidecar token. In production the server **refuses to start** without it.
|
||||
Changing it later does not re-encrypt anything: what was stored under the old key can no
|
||||
longer be read, and every stored secret has to be entered again.
|
||||
|
||||
|
||||
@@ -3,11 +3,10 @@ title: Requirements
|
||||
description: What you need on the website host, and what you need on the game server host, before you begin.
|
||||
---
|
||||
|
||||
import platform from '../../../../data/platform.json';
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
Two hosts, two lists. They can be the same machine, but they are separate deployments and
|
||||
have nothing in common except the four values you will paste between them.
|
||||
have nothing in common except the few values you will paste between them.
|
||||
|
||||
## The website host
|
||||
|
||||
@@ -29,32 +28,28 @@ mounts and the reverse-proxy notes all read that way.
|
||||
|
||||
## The game server host
|
||||
|
||||
Only if you are connecting a game server. Today that means a ServUO shard, which is what
|
||||
the [`uo` module](/docs/getting-started/install-a-game-module/) and the installer support.
|
||||
Only if you are connecting a game server. Each game lists what its own host needs on its
|
||||
connect page, because each game's server asks for different things. These hold for every
|
||||
game:
|
||||
|
||||
| Requirement | Detail |
|
||||
|---|---|
|
||||
| **A working ServUO install** | It must currently boot and compile scripts cleanly. The installer deploys onto a healthy shard; it does not repair a broken one. |
|
||||
| **ServUO {platform.bundle.servuoMin}** *(patch tier only)* | The base install works on any reasonably current ServUO. The optional patch tier is written and tested against stock {platform.bundle.servuoMin}; on any other version it is unsupported, and skipping it still leaves you with a working bridge. |
|
||||
| **The shard stopped** | `ServUO.exe` locks `Scripts.dll` and rewrites `Saves/` on exit. The installer refuses to deploy under a running shard. |
|
||||
| **Administrator / root** | It writes into system directories and registers a service. |
|
||||
| **Outbound HTTPS** | To fetch the bundle and its two artifacts. No Gitea account and no git client are needed. |
|
||||
| **The sidecar on the same host as the shard** | The shard connects to `127.0.0.1:7788`. Splitting them is not supported — that loopback socket *is* the trust boundary for inbound commands. |
|
||||
| **A working game server** | It must boot and load plugins cleanly before you start. The installer deploys onto a healthy server; it does not repair a broken one. |
|
||||
| **Administrator / root** | The installer writes into system directories and registers a service. |
|
||||
| **Outbound HTTPS** | To fetch the bundle and its artifacts. No Gitea account and no git client are needed. |
|
||||
| **The sidecar on the same host as the game server** | The bridge plugin dials the sidecar over loopback. That loopback socket *is* the trust boundary for inbound commands to the game, so the two are never split across machines. |
|
||||
|
||||
<Aside type="caution" title="Back up before the shard install">
|
||||
The overlay overwrites `Scripts/Scripts.csproj`, a stock file, and the optional patch tier
|
||||
edits stock sources. A copy of `Scripts/` and `Config/` costs nothing and is the difference
|
||||
between an experiment and a gamble. The installer keeps its own backups too — see
|
||||
[Connect a game server](/docs/getting-started/connect-a-game-server/).
|
||||
</Aside>
|
||||
Then the game's own list: [Ultima Online](/docs/ultima-online/connect-a-servuo-shard/#what-the-shard-host-needs),
|
||||
or [Rust](/docs/rust/install-the-bridge/#before-you-begin).
|
||||
|
||||
## What you do not need
|
||||
|
||||
- **A Gitea account.** Everything the installers fetch is a public release asset.
|
||||
- **A build toolchain.** Not on either host. The site pulls images; the module arrives as a
|
||||
verified tarball; the shard plugin is C# source that ServUO itself compiles at boot.
|
||||
- **An inbound port on the game host** — for the *game*. The shard never listens for the
|
||||
website. If the website runs on a different machine from the shard, the **sidecar** needs
|
||||
to be reachable by the website, and that is the one hole you will open deliberately.
|
||||
verified tarball; the bridge plugin is source that the game server compiles itself.
|
||||
- **An inbound port on the game host** — for the *game*. The game server never listens for
|
||||
the website. If the website runs on a different machine from the game server, the
|
||||
**sidecar** needs to be reachable by the website, and that is the one hole you will open
|
||||
deliberately.
|
||||
|
||||
Next: [Install the site](/docs/getting-started/install-the-site/).
|
||||
|
||||
@@ -1,103 +1,53 @@
|
||||
---
|
||||
title: Verify the whole stack
|
||||
description: Four checks, one per link in the chain, that distinguish "files copied" from "the bridge works".
|
||||
description: Four checks, one per link in the chain, that distinguish "files copied" from "the bridge works" — the same four for every game.
|
||||
---
|
||||
|
||||
import { Aside, Steps } from '@astrojs/starlight/components';
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
A successful install is not a working bridge, and the failure is quiet in a specific way:
|
||||
**ServUO shells out to `dotnet build`, prints the output, ignores the exit code, and
|
||||
reloads the existing `Scripts.dll`.** A broken script build looks exactly like a clean boot.
|
||||
A successful install is not a working bridge. Files can be in the right place and the game
|
||||
server can boot cleanly while nothing reaches the site, and the site is *designed* to keep
|
||||
working when the game is unreachable — so a broken bridge does not announce itself.
|
||||
|
||||
So verify each link in the chain, in order. Each check tells you which one to fix.
|
||||
So verify each link in the chain, in order, starting at the game. Each check tells you which
|
||||
link to fix.
|
||||
|
||||
<Steps>
|
||||
| # | The link | What you check | What "working" means |
|
||||
|---|---|---|---|
|
||||
| 1 | **The bridge plugin loaded** | The game server's own console or log at boot | The plugin announces itself, with the sidecar address it will dial |
|
||||
| 2 | **The game server reached the sidecar** | The bridge plugin's status command, on the game server | It reports itself connected, and is not dropping events |
|
||||
| 3 | **The sidecar is healthy** | `curl -s http://127.0.0.1:<port>/health` on the game server's host. It needs no token | *plugin connected* is true. It is the one value in the whole sequence that distinguishes "files copied" from "the bridge works" |
|
||||
| 4 | **The website is ingesting** | The game module's connection screen, under **Admin** | It reads connected, and live events start arriving within seconds |
|
||||
|
||||
1. **The plugin compiled — watch the boot output.**
|
||||
The order is the same for every game. The commands and the screen names are not, so each
|
||||
game has its own page with the exact steps:
|
||||
|
||||
Start your shard the way you always do. You want the build to succeed *and* the bridge
|
||||
to announce itself:
|
||||
- **Ultima Online:** [Verify the bridge](/docs/ultima-online/verify-the-bridge/)
|
||||
- **Rust:** [Verify the bridge](/docs/rust/verify-the-bridge/)
|
||||
|
||||
```
|
||||
Core: Compiling scripts...
|
||||
Build succeeded.
|
||||
[Bridge] enabled=True endpoint=127.0.0.1:7788 queueCap=10000 …
|
||||
```
|
||||
## Two responses that mean the same for every game
|
||||
|
||||
If you scrolled past it, force the question:
|
||||
|
||||
```bash
|
||||
dotnet build Scripts/Scripts.csproj -c Release -p:Platform=x64 # must be 0 errors
|
||||
```
|
||||
|
||||
2. **The shard is connected — ask it in game.**
|
||||
|
||||
As an administrator:
|
||||
|
||||
```
|
||||
[bridge status
|
||||
```
|
||||
|
||||
It reports `connected=True depth=0 sent=… dropped=0`. `connected=False` means the shard
|
||||
cannot reach the sidecar. `dropped` climbing means the sidecar is wedged and the shard
|
||||
is shedding events rather than stalling — which is what it is designed to do, and why a
|
||||
broken bridge never freezes your game.
|
||||
|
||||
`[bridge reload` re-reads `Bridge.cfg` without a restart; `[bridge sweepnow` forces one
|
||||
pass of every stream.
|
||||
|
||||
3. **The sidecar is healthy — ask it over HTTP.**
|
||||
|
||||
`/health` needs no auth, so it is safe to curl on the shard host:
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8080/health
|
||||
```
|
||||
|
||||
```json
|
||||
{"status":"ok","protocol":4,"plugin_connected":true,"database":"ok","uptime":"2m"}
|
||||
```
|
||||
|
||||
**`plugin_connected: true` is the one that matters.** It is the only value in this whole
|
||||
sequence that distinguishes "files copied" from "the bridge works".
|
||||
|
||||
4. **The website is ingesting — look at the shard screen.**
|
||||
|
||||
On the site, open **Shard (uo-link)** (`/admin/uo/link`). The header should read
|
||||
**Connected**, with *Shard link: up* and *WS ingest: online*, and the live feed at the
|
||||
bottom should start showing events within seconds rather than sitting on
|
||||
*Waiting for shard events…*.
|
||||
|
||||
Then check the public side: the shard status page should stop reporting the game as
|
||||
offline.
|
||||
|
||||
</Steps>
|
||||
|
||||
## When one of them fails
|
||||
|
||||
| What you see | What it means |
|
||||
| What the site logs | What it means |
|
||||
|---|---|
|
||||
| Shard boots clean, nothing reaches the site | The classic silent failure — a stale `Scripts.dll`. Run the `dotnet build` line above and read the errors. |
|
||||
| `[bridge` is not a command | The plugin did not compile, or the bridge is disabled in `Bridge.cfg`. |
|
||||
| `connected=False` | The sidecar is not listening on `127.0.0.1:7788`. Check the service, and that `[shard] bind` matches `Host`/`Port` in `Bridge.cfg`. |
|
||||
| `/health` is fine locally, the site says offline | The website cannot reach port 8080 — bind address or firewall. The site is *designed* to render normally with the shard down, so this fails quietly. |
|
||||
| The site logs `409` from the sidecar | Protocol mismatch. Set the Protocol field to what `/health` reports rather than guessing; the sidecar rejects rather than mis-parsing. |
|
||||
| `401` from the sidecar | Wrong or missing token. Read the live one back with `uo-link-sidecar --print-config`; do not retype it from a screenshot. |
|
||||
| `409` from the sidecar | Protocol mismatch. The sidecar and the game module disagree on a wire protocol, and the sidecar refuses rather than mis-parsing. Set the protocol to what `/health` reports, or update whichever side is behind. |
|
||||
| `401` from the sidecar | Wrong or missing token. Read the live one back on the game server's host rather than retyping it from a screenshot. |
|
||||
|
||||
<Aside type="note" title="`runicgateway doctor` answers most of this in one command">
|
||||
Run on the shard host, it checks the install record, the ServUO tree, every overlay file
|
||||
hash, the patch tier, the sidecar, its service, `/health`, and that the sidecar and overlay
|
||||
agree on a protocol. Its output is the first thing anyone helping you will ask for. It
|
||||
exits non-zero when a check failed, so a monitoring system can run it too.
|
||||
Run on the game server's host, it checks the install record, the files it deployed, the
|
||||
sidecar, its service, `/health`, and that the sidecar and the bridge plugin agree on a
|
||||
protocol. Its output is the first thing anyone helping you will ask for. It exits non-zero
|
||||
when a check failed, so a monitoring system can run it too.
|
||||
</Aside>
|
||||
|
||||
## What "working" looks like a week later
|
||||
|
||||
- The public shard page shows live status, and the admin dashboard shows events arriving.
|
||||
- `dropped` in `[bridge status` stays at zero. A climbing number means the sidecar is
|
||||
wedged, not that the shard is unhealthy.
|
||||
- `doctor` is still green after a shard update — that is what catches an overlay file
|
||||
reverted by hand or by a ServUO upgrade.
|
||||
- The game module's public pages show live status, and the admin dashboard shows events
|
||||
arriving.
|
||||
- The bridge plugin is not dropping events. A climbing drop count means the sidecar is
|
||||
wedged, not that the game server is unhealthy: the plugin sheds events rather than
|
||||
stalling the game, which is what it is designed to do.
|
||||
- `doctor` is still green after a game server update. That is what catches a deployed file
|
||||
that an update put back to stock.
|
||||
|
||||
You have finished the installation path. From here,
|
||||
[Administration](/docs/administration/configuration/) covers running the site day to day.
|
||||
|
||||
@@ -8,26 +8,39 @@ import platform from '../../../data/platform.json';
|
||||
Runic Gateway puts a private game server's live state on a public website without ever
|
||||
exposing the game to the internet.
|
||||
|
||||
The shard dials **out** to a small sidecar over loopback; the sidecar is the only
|
||||
The game server dials **out** to a small sidecar over loopback; the sidecar is the only
|
||||
network-facing component, and only the website's backend is allowed to talk to it. The
|
||||
website degrades gracefully when the game is down, and sensitive events never reach the
|
||||
public event stream.
|
||||
|
||||
## What the platform is on today
|
||||
|
||||
Two versions are shared by every deployment, whichever game it runs:
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr><td>Wire protocol</td><td>{platform.protocol}</td></tr>
|
||||
<tr><td>Module API</td><td>{platform.moduleApi}</td></tr>
|
||||
<tr><td>Current bundle</td><td>{platform.bundle.tag}</td></tr>
|
||||
<tr><td>uo-link sidecar</td><td>{platform.releases.link}</td></tr>
|
||||
<tr><td>Plugin overlay</td><td>{platform.bundle.overlay}</td></tr>
|
||||
<tr><td>Installer</td><td>{platform.releases.installer}</td></tr>
|
||||
<tr><td>ServUO (minimum)</td><td>{platform.bundle.servuoMin}</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
Every value in that table is read from `src/data/platform.json` and re-checked against its
|
||||
Everything else belongs to a game. Each game has its own wire protocol and its own bundle —
|
||||
the exact, protocol-checked pair of sidecar and game plugin the installer deploys:
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr><th></th><th>{platform.games.uo.name}</th><th>{platform.games.rust.name}</th></tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td>Game module</td><td>{platform.releases['Module-uo']}</td><td>{platform.releases['Module-Rust']}</td></tr>
|
||||
<tr><td>Wire protocol</td><td>{platform.games.uo.protocol}</td><td>{platform.games.rust.protocol}</td></tr>
|
||||
<tr><td>Current bundle</td><td>{platform.games.uo.bundle.tag}</td><td>{platform.games.rust.bundle.tag}</td></tr>
|
||||
<tr><td>Sidecar</td><td>{platform.games.uo.bundle.sidecar}</td><td>{platform.games.rust.bundle.sidecar}</td></tr>
|
||||
<tr><td>Game plugin</td><td>{platform.games.uo.bundle.overlay}</td><td>{platform.games.rust.bundle.plugin}</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
Every value in those tables is read from `src/data/platform.json` and re-checked against its
|
||||
source of truth on each build. None of it is typed into prose — including here.
|
||||
|
||||
## An install is two installs
|
||||
@@ -36,15 +49,16 @@ Worth stating before anything else, because it is a real trap: a Runic Gateway i
|
||||
two independent deployments.
|
||||
|
||||
1. **The site** is a Docker deployment — the website, a database, and a game module.
|
||||
2. **The shard side** is the installer binary, run on the game server's host. It sets up
|
||||
the plugin overlay and the sidecar, and it never contacts the website.
|
||||
2. **The game server side** is the installer binary, run on the game server's host. It sets
|
||||
up the bridge plugin and the sidecar, and it never contacts the website.
|
||||
|
||||
They meet at four values pasted into the module's shard screen, and at protocol
|
||||
{platform.protocol}, which both sides check before they will pair.
|
||||
They meet at the values the installer prints, pasted into the game module's connection
|
||||
screen, and at the game's wire protocol, which both sides check before they will pair.
|
||||
|
||||
You can stop after the first one. A site with no game server attached is a complete
|
||||
community website — news, wiki, pages, Teams, forums, accounts and moderation are all core,
|
||||
and none of them knows a game exists. The second install is what fills the game screens.
|
||||
community website — news, wiki, pages, Teams, forums, accounts, moderation and the event
|
||||
calendar are all core, and none of them knows a game exists. The second install is what
|
||||
fills the game screens, and what lets an event reach into a world.
|
||||
|
||||
## Start here
|
||||
|
||||
@@ -55,12 +69,15 @@ you should expect to see before you move on:
|
||||
2. [Install the site](/docs/getting-started/install-the-site/) — Docker Compose, pull-only
|
||||
3. [First run](/docs/getting-started/first-run/) — the first admin, and maintenance → live
|
||||
4. [Install a game module](/docs/getting-started/install-a-game-module/) — what makes the game screens exist
|
||||
5. [Connect a game server](/docs/getting-started/connect-a-game-server/) — the installer, on the shard host
|
||||
5. [Connect your game server](/docs/getting-started/connect-a-game-server/) — the installer, on the game server's host
|
||||
6. [Verify the whole stack](/docs/getting-started/verify-the-whole-stack/) — proving it works, rather than assuming
|
||||
|
||||
Then **Administration** covers running it: configuration, branding, content, users,
|
||||
authentication, Teams, moderation, notifications, modules, the shard connection, upgrades,
|
||||
and what to do when something is wrong.
|
||||
authentication, Teams, scheduled events, moderation, notifications, modules, upgrades, and
|
||||
what to do when something is wrong.
|
||||
|
||||
Everything that belongs to one game has its own group at the end of the sidebar, after
|
||||
**Reference**: [Ultima Online](/docs/ultima-online/) and [Rust](/docs/rust/).
|
||||
|
||||
## Where the truth lives
|
||||
|
||||
|
||||
@@ -29,6 +29,13 @@ Two artifacts:
|
||||
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
|
||||
|
||||
@@ -18,10 +18,17 @@ time**. The database is not consulted: what is on the volume determines what mou
|
||||
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.
|
||||
|
||||
Modules load **alphabetically by `id`**, deterministically. There is no dependency
|
||||
resolution between modules, and alphabetical order is the honest way of saying so: any
|
||||
other order would imply a precedence nobody is computing. Do not build a module that needs
|
||||
to load before or after another one.
|
||||
**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
|
||||
|
||||
|
||||
@@ -49,14 +49,16 @@ your game server ──dials out──▶ your sidecar ──HTTP + WS──
|
||||
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.
|
||||
the whole job. That module has since been built for real, as
|
||||
[the Rust module](https://gitea.whitlocktech.com/RunicGateway/Module-Rust), so the dry run now
|
||||
reads as the plan beside a finished result.
|
||||
|
||||
## The template is built, not just quoted
|
||||
|
||||
Chapters 1 and 2 quote `template/`, a real module that CI builds against a pinned core. The
|
||||
code in those chapters is **a tree that is proved rather than prose that looks like one**.
|
||||
|
||||
Chapters 3 and 4 cite `uo-link` and `servuo-plugins` by file and identifier rather than by
|
||||
Chapters 3 and 4 cite the Ultima Online sidecar and bridge plugin by file and identifier rather than by
|
||||
line number, deliberately: those repositories move for their own reasons, and a line number
|
||||
in a book is wrong the moment they do.
|
||||
|
||||
@@ -88,7 +90,7 @@ 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
|
||||
the first game module's slots **literally** — so the mechanism worked for that one module and silently
|
||||
did nothing for any other game, producing an empty page with nothing logged.
|
||||
|
||||
That is exactly the class of defect a book written for an audience outside this org exists
|
||||
|
||||
@@ -4,6 +4,7 @@ description: The two arguments core hands your module — what you can reach, wh
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import platform from '../../../../data/platform.json';
|
||||
|
||||
Your server entry point exports one function:
|
||||
|
||||
@@ -14,7 +15,7 @@ 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 **1.6.0**, and your manifest's
|
||||
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.
|
||||
|
||||
|
||||
@@ -4,6 +4,8 @@ description: Every key in module.json, what the loader does with each, and why a
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import platform from '../../../../data/platform.json';
|
||||
import GameExample from '../../../../components/GameExample.astro';
|
||||
|
||||
`module.json` sits at the root of your bundle. The loader reads it synchronously, before
|
||||
anything else about your module runs.
|
||||
@@ -14,12 +16,15 @@ module that boots and mysteriously does half its job.
|
||||
|
||||
## A complete manifest
|
||||
|
||||
A real one, the Ultima Online module's, with the values that change every release elided:
|
||||
|
||||
<GameExample game="uo">
|
||||
```json
|
||||
{
|
||||
"id": "uo",
|
||||
"name": "Ultima Online",
|
||||
"version": "1.0.0",
|
||||
"coreApi": "^1.0.0",
|
||||
"version": "…",
|
||||
"coreApi": "…",
|
||||
"server": "server/index.js",
|
||||
"client": { "entry": "client/dist/entry.js" },
|
||||
"schema": "server/db/schema.sql",
|
||||
@@ -30,9 +35,10 @@ module that boots and mysteriously does half its job.
|
||||
"player": ["/shard"]
|
||||
},
|
||||
"extensions": ["admin.users.detail"],
|
||||
"capabilities": ["shard", "atlas", "market"]
|
||||
"capabilities": ["shard", "atlas", "market", "…"]
|
||||
}
|
||||
```
|
||||
</GameExample>
|
||||
|
||||
## The keys
|
||||
|
||||
@@ -63,9 +69,10 @@ register exactly.
|
||||
`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.
|
||||
That is why the manifest above declares `admin` prefixes that are not its admin screens'
|
||||
URLs: the first is where its API routes live, the second is where the SPA puts its pages. Two
|
||||
different mechanisms, and [the module system](/docs/modules/the-module-system/) explains why
|
||||
the split is deliberate.
|
||||
</Aside>
|
||||
|
||||
## `capabilities` is for feature detection
|
||||
@@ -78,18 +85,20 @@ repository is branching on them.
|
||||
|
||||
## `coreApi` and what a range means
|
||||
|
||||
Core exports a single semver string, currently **1.6.0**. Your range is checked at boot,
|
||||
before your code is required.
|
||||
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 `^1.3.0`
|
||||
keeps resolving against 1.6.0 — which is exactly why `module-uo` still declares `^1.3.0`
|
||||
and runs fine.
|
||||
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
|
||||
`coreApi` versions the **website module contract**. `PROTOCOL_VERSION` versions **a game's
|
||||
wire** and says nothing about a website module. See [Protocol
|
||||
versions](/docs/architecture/protocol-versions/).
|
||||
</Aside>
|
||||
|
||||
@@ -4,9 +4,10 @@ description: What a module is, why the platform is built this way, and the one r
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import GameExample from '../../../../components/GameExample.astro';
|
||||
|
||||
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 —
|
||||
site one game's site — that game's live status, its map, its leaderboards, its own 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
|
||||
@@ -69,21 +70,26 @@ 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`:
|
||||
**A module owns one path segment wherever it appears.** A module with the id `<id>` has its
|
||||
public pages under `/<id>/…`, its admin pages under `/admin/<id>/…`, and its player pages
|
||||
under `/player/<id>/…`.
|
||||
|
||||
**API routes are the exception, and keep their exact paths.** A surface that existed before
|
||||
it moved into a module keeps the API path it always had. This is why the Android app and
|
||||
the Discord bot needed no API changes at the cutover.
|
||||
|
||||
<GameExample game="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.
|
||||
| The shard admin API — the exception | `/api/v1/admin/shard/*`, not `/api/v1/admin/uo/shard/*` |
|
||||
</GameExample>
|
||||
|
||||
<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
|
||||
The installer kept printing the first game's pre-module admin path well after the screen had
|
||||
moved under the module's segment. 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.
|
||||
|
||||
|
||||
@@ -4,6 +4,7 @@ description: Where the normative specifications live — the documents that win
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import GameExample from '../../../../components/GameExample.astro';
|
||||
import { canonicalDocs } from '../../../../data/reference.mjs';
|
||||
|
||||
Everything on this site is a **summary**. These are the documents it summarises, and where
|
||||
@@ -14,15 +15,21 @@ A documentation site that quietly re-specifies a contract becomes a second sourc
|
||||
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.
|
||||
|
||||
One page is a deliberate exception: [RunicNPC's API](/docs/rust/runicnpc/api/) is carried in
|
||||
full, because its readers are plugin authors outside this project. Its every signature and field
|
||||
name is checked against `runicnpc/API.md` on every build, and that document still wins.
|
||||
|
||||
If you find a disagreement, it is worth reporting — it means a check is missing.
|
||||
</Aside>
|
||||
|
||||
## The documents
|
||||
|
||||
The platform's own, which every deployment shares:
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Document</th><th>Answers</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(canonicalDocs).map(([docPath, why]) => (
|
||||
{Object.entries(canonicalDocs.core).map(([docPath, why]) => (
|
||||
<tr key={docPath}>
|
||||
<td>
|
||||
<a href={`https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/${docPath}`}>
|
||||
@@ -35,6 +42,44 @@ If you find a disagreement, it is worth reporting — it means a check is missin
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
And each game's, which only matter if you run that game:
|
||||
|
||||
<GameExample game="uo">
|
||||
<table>
|
||||
<thead><tr><th>Document</th><th>Answers</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(canonicalDocs.uo).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>
|
||||
</GameExample>
|
||||
|
||||
<GameExample game="rust">
|
||||
<table>
|
||||
<thead><tr><th>Document</th><th>Answers</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(canonicalDocs.rust).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>
|
||||
</GameExample>
|
||||
|
||||
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.
|
||||
|
||||
@@ -45,10 +90,14 @@ moved turns this page red rather than leaving a dead link.
|
||||
- **"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 `v4.md` for the current protocol.
|
||||
- **"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`.
|
||||
- **"What can a game server send?"** → that game's protocol document, in its table above.
|
||||
- **"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?"** → core's roles in `BACKEND_DESIGN.md`; a game's own audience
|
||||
rules are in that game's module documents.
|
||||
- **"How do I set a game server up?"** → `installer/INSTALL.md`, and that game's install
|
||||
guide.
|
||||
|
||||
## Where they live
|
||||
|
||||
|
||||
@@ -35,7 +35,7 @@ The first boot is also when your admin account is written, so `ADMIN_USERNAME` a
|
||||
## 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 game module's sidecar 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
|
||||
@@ -53,7 +53,7 @@ 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
|
||||
**Most settings are not here.** Branding, navigation, theming and the game connection are
|
||||
**admin-managed and live in the database**, deliberately — so changing them does not mean
|
||||
redeploying a container.
|
||||
|
||||
|
||||
@@ -60,8 +60,9 @@ loses access immediately rather than at token expiry.
|
||||
|
||||
## The sidecar's API is a different thing
|
||||
|
||||
The uo-link sidecar exposes its own small REST and WebSocket surface, reached **only** by the
|
||||
website's backend. It carries `X-UOLink-Version` and answers `409` on a protocol mismatch.
|
||||
Each game's sidecar exposes its own small REST and WebSocket surface, reached **only** by the
|
||||
website's backend. It carries its protocol version in a header and answers `409` on a
|
||||
protocol mismatch.
|
||||
|
||||
It is not part of this API and is not served from your site. See [The
|
||||
bridge](/docs/architecture/the-bridge/).
|
||||
|
||||
@@ -4,13 +4,14 @@ description: The four commands the installer offers, what each does to a host, a
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import GameExample from '../../../../components/GameExample.astro';
|
||||
import { installerCommands } from '../../../../data/reference.mjs';
|
||||
|
||||
The installer is one binary per operating system that deploys the **shard side only**. It
|
||||
never contacts the website.
|
||||
The installer is one binary per operating system that deploys the **game server side
|
||||
only**: the bridge plugin, and the sidecar with its service. It never contacts the website.
|
||||
|
||||
Downloads and the walkthrough are [Connect a game
|
||||
server](/docs/getting-started/connect-a-game-server/). This page is the command surface.
|
||||
The walkthrough is [Connect your game server](/docs/getting-started/connect-a-game-server/),
|
||||
which hands off to each game's steps. This page is the command surface.
|
||||
|
||||
## The commands
|
||||
|
||||
@@ -25,47 +26,67 @@ server](/docs/getting-started/connect-a-game-server/). This page is the command
|
||||
|
||||
`doctor`, `update` and `uninstall` are the day-two commands.
|
||||
|
||||
## Telling it which game
|
||||
|
||||
One binary serves both games. A flag says which one a run is about, and each game has flags
|
||||
of its own:
|
||||
|
||||
<GameExample game="uo">
|
||||
```bash
|
||||
runicgateway-installer install --game servuo --servuo /path/to/ServUO
|
||||
```
|
||||
|
||||
`--game servuo` is the default, so a ServUO run can leave it out.
|
||||
</GameExample>
|
||||
|
||||
<GameExample game="rust">
|
||||
```bash
|
||||
runicgateway-installer install --game rust --rust /srv/rust --server-id main
|
||||
```
|
||||
|
||||
One sidecar serves one Rust server, so `--server-id` is required on install. The Rust flags
|
||||
are refused on a run that is not `--game rust`, rather than silently ignored. The whole Rust
|
||||
install, including a Pterodactyl egg for hosts the installer cannot run on, is in
|
||||
[its group](/docs/rust/install-the-bridge/).
|
||||
</GameExample>
|
||||
|
||||
## Rehearsing a run
|
||||
|
||||
Two mechanisms, and they answer different questions.
|
||||
|
||||
```bash
|
||||
runicgateway-installer install --servuo /path/to/ServUO --verify
|
||||
```
|
||||
|
||||
**`--verify` writes nothing.** It reports what would change — the diff against the ServUO
|
||||
tree — which is the right thing to run first against a shard that has players on it.
|
||||
|
||||
```bash
|
||||
RUNICGATEWAY_STATE_DIR=/tmp/rehearsal runicgateway-installer install --servuo …
|
||||
```
|
||||
**`--verify` writes nothing.** On `install` and `update` it reports every change the run
|
||||
would make and stops, which is the right thing to run first against a game server that has
|
||||
players on it.
|
||||
|
||||
**`RUNICGATEWAY_STATE_DIR` relocates everything the installer writes** — state, data, and
|
||||
the sidecar binary — *and suppresses service registration*. That is how a full run is
|
||||
exercised without root, and it is what the project's own tests use.
|
||||
|
||||
```bash
|
||||
RUNICGATEWAY_STATE_DIR=/tmp/rehearsal runicgateway-installer install …
|
||||
```
|
||||
|
||||
## What an install actually does
|
||||
|
||||
1. Resolves a **bundle** — an exact, protocol-checked sidecar and overlay pair published by
|
||||
CI. Never "latest of each"; see [Protocol
|
||||
1. Resolves a **bundle** — an exact, protocol-checked pair of sidecar and bridge plugin
|
||||
published by CI. Never "latest of each"; see [Protocol
|
||||
versions](/docs/architecture/protocol-versions/).
|
||||
2. Syncs the plugin overlay into the ServUO tree, backing up whatever it is about to
|
||||
2. Deploys the bridge plugin onto the game server, backing up whatever it is about to
|
||||
overwrite.
|
||||
3. Offers the opt-in patch tier.
|
||||
4. Installs the sidecar and registers its service.
|
||||
5. Prints four values to paste into the site's shard screen.
|
||||
3. Installs the sidecar and registers its service.
|
||||
4. Records what it deployed, with per-file hashes, so `doctor` can tell later whether
|
||||
anything changed.
|
||||
5. Prints the values to paste into the game module's admin screen on the site.
|
||||
|
||||
<Aside type="caution" title="Installer v0.1.0 prints an older path in step 5">
|
||||
It names `<site>/admin/shard`. The screen moved to **`/admin/uo/link`** when the shard
|
||||
surface became part of the `uo` module. Fixed in v0.1.1.
|
||||
</Aside>
|
||||
Each game adds its own steps: the Ultima Online install, for one, offers an optional patch
|
||||
tier, covered in [its group](/docs/ultima-online/connect-a-servuo-shard/).
|
||||
|
||||
## Platforms
|
||||
|
||||
Linux `x86_64`, Linux `aarch64`, and Windows `x86_64`.
|
||||
|
||||
**macOS and Windows-on-ARM are deliberately absent**: the game server and the sidecar must
|
||||
share a host, and no ServUO host is either.
|
||||
share a host, and no game server the platform supports runs on either.
|
||||
|
||||
Releases are **unsigned**, and `SHA256SUMS` is the trust anchor — verify before running.
|
||||
Windows will show a SmartScreen prompt, which is expected for an unsigned binary.
|
||||
|
||||
108
src/content/docs/docs/rust/connect-the-site.mdx
Normal file
108
src/content/docs/docs/rust/connect-the-site.mdx
Normal file
@@ -0,0 +1,108 @@
|
||||
---
|
||||
title: Connect the site
|
||||
description: Adding a Rust server to the site on Admin → Rust servers, what the Test button's answers mean, and the rest of a server's settings — its wipe schedule, world-event credit and chat titles.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
Every Rust server the site follows is one row on **Admin → Rust servers**
|
||||
(`/admin/rust/servers`). A row tells the site where that server's sidecar is; the sidecar
|
||||
itself lives on the game host, put there by [Install the bridge](/docs/rust/install-the-bridge/).
|
||||
|
||||
## Add a server
|
||||
|
||||
Press **Add a server** and fill in four values:
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| **Id** | The server id — the installer's `--server-id`, or the egg's variable. It must equal `ServerId` in the plugin's config |
|
||||
| **Name** | Anything. Players see it |
|
||||
| **Sidecar address** | The sidecar URL the installer or the console printed, such as `http://10.0.0.5:8090` |
|
||||
| **Sidecar token** | The token, from the sidecar's own config |
|
||||
|
||||
**The id is permanent.** It is in every link to the server and the site will not change it
|
||||
later. It is deliberately not the hostname: you will rename a server for a season, and its
|
||||
history must not go with the name. Changing the plugin's `ServerId` after the site has seen it
|
||||
strands everything recorded under the old one.
|
||||
|
||||
**The token is write-only.** It is stored encrypted and never shown again once saved; the row
|
||||
says only *token stored*. Saving the form with the field blank keeps the stored token, so
|
||||
renaming a server does not mean re-pasting a credential.
|
||||
|
||||
## Test it
|
||||
|
||||
**Test the sidecar** asks the sidecar for its health and reports what came back. A working
|
||||
server answers *The sidecar answered (protocol N)*, and its row reads online, with its
|
||||
player count, the protocol and *last seen just now*. *The sidecar answered, but the game's
|
||||
plugin is not connected to it* means the site's half works and the game's does not — go to
|
||||
[Verify the bridge](/docs/rust/verify-the-bridge/).
|
||||
|
||||
A wrong address, a wrong token and a mismatched protocol all look the same from the public
|
||||
site — *the server is offline* — so the Test button is what tells them apart. A failure reads
|
||||
*The sidecar did not answer:* followed by one of these:
|
||||
|
||||
| Status | What is wrong | Where to look |
|
||||
|---|---|---|
|
||||
| `no-token` | The form was saved without one | This screen |
|
||||
| `unauthorized` | The token does not match | The sidecar's config on the game host |
|
||||
| `protocol-mismatch` | The sidecar and the module speak different protocols | Update whichever is behind |
|
||||
| `timeout` | The sidecar answered too slowly, or not at all | The sidecar's own log |
|
||||
| `transport-error` | Nothing is listening at that address | The address, the firewall, whether the sidecar runs |
|
||||
| `http-<code>` | Something answered, and it was not a sidecar | Usually a reverse proxy in front of the wrong thing |
|
||||
|
||||
Within a poll interval the server appears at `/rust`.
|
||||
|
||||
## If the site is on another machine
|
||||
|
||||
The installer's sidecar listens on `127.0.0.1`, reachable only from the game host. Put a TLS
|
||||
reverse proxy or a VPN link in front of it and give the site that URL — the token is a plain
|
||||
bearer token, and the sidecar speaks HTTP. The egg's sidecar listens on its allocation, which
|
||||
the network can reach, so firewall it to your site's address.
|
||||
|
||||
<Aside type="caution" title="Leave the game bind on loopback">
|
||||
The sidecar's other socket, the one the bridge plugin dials, takes commands for the game
|
||||
server and has no token. Being loopback-only is what makes that safe. Only the web bind ever
|
||||
moves.
|
||||
</Aside>
|
||||
|
||||
## The rest of a server's settings
|
||||
|
||||
**Edit** on a row opens the same form, plus:
|
||||
|
||||
- **Enabled** and **Order** — whether the site follows the server, and where it sits in the
|
||||
list.
|
||||
- **Wipe schedule.** *No schedule*, *Forced wipe only* (Facepunch's monthly forced wipe, the
|
||||
first Thursday of the month at 19:00 UK time), *Weekly* or *Every other week*, on a day,
|
||||
time and time zone you choose. A **one-off wipe** covers a delayed or extra one. It is a
|
||||
forecast: the next wipe shows on the server's public page. The wipe itself is whatever the
|
||||
game reports, which is what splits the leaderboard and the history.
|
||||
- **Who downs a helicopter or a Bradley.** *Killing blow* (the default), *Last hit*, *Most
|
||||
damage*, or *Everyone who hurt it*. It decides whose name the feed shows and who it counts
|
||||
for, from the moment you save.
|
||||
|
||||
**Optional mods** on a row lists what the bridge found on that server — BetterChat,
|
||||
PopupNotifications, Economics, Backpacks, TruePVE, Dynamic PVP, Dangerous Treasures, Guarded
|
||||
Crate, ZLevels, RaidableBases — with each one's version and what it lets the site do there.
|
||||
[Optional plugins](/docs/rust/optional-plugins/) explains each.
|
||||
|
||||
### Chat titles
|
||||
|
||||
**Chat titles** on a row gives titles to the top players of the current wipe, one rule per
|
||||
stat: *the top 1 by guarded crates cleared earns "Warden"*. Up to ten rules a server; a stat
|
||||
of zero earns nothing, so a fresh wipe has no titles until somebody plays. Titles show beside
|
||||
the name on the leaderboard, and in game chat where BetterChat is installed.
|
||||
|
||||
Below the servers, **Category titles** sets each stat's default title once for every server,
|
||||
and **Announcement voice** lets news posts and event announcements said in game chat wear the
|
||||
title and colours of one permission group that has a chat style. That style is set on the
|
||||
group, in [Permissions and groups](/docs/rust/permissions-and-groups/#chat-styles).
|
||||
|
||||
Next: [Verify the bridge](/docs/rust/verify-the-bridge/).
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`rust-link/INSTALL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INSTALL.md#connect-the-website)
|
||||
and [`rust-link/INTEGRATION.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INTEGRATION.md)
|
||||
§3 hold the connection and the Test button's answers;
|
||||
[`modules/rust/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/PLAN.md)
|
||||
is the module's design of record.
|
||||
106
src/content/docs/docs/rust/event-kinds.mdx
Normal file
106
src/content/docs/docs/rust/event-kinds.mdx
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: Event kinds
|
||||
description: Every kind of event a Rust server can tell the site, in three classes — public, presence and staff — and why the module, not the game, decides which is which.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import platform from '../../../../data/platform.json';
|
||||
import { rustEventKinds } from '../../../../data/reference.mjs';
|
||||
|
||||
What a Rust server tells the site, unprompted, as things happen in the world — every kind the
|
||||
bridge sends through protocol {platform.games.rust.protocol}, and who may see each.
|
||||
|
||||
**Not to be confused with a scheduled event.** That is a thing you put on the calendar and run —
|
||||
see [Events, zones and rewards](/docs/rust/events-zones-and-rewards/). The two meet: what happens
|
||||
here is what a phase can wait for.
|
||||
|
||||
The exact wire shapes are in the protocol specification and are **not** restated here. This page
|
||||
is the map and the security model.
|
||||
|
||||
## The module decides, not the game
|
||||
|
||||
The wire carries no visibility field. **A boundary is enforced by the side that serves, never
|
||||
declared by the side that sends**: a field the game stamped on each frame would be a boundary that
|
||||
a compromised — or merely out-of-date — game host could widen. So the Rust module holds the lists
|
||||
below, and they are **default-deny**: a kind it has never heard of, from a newer bridge, is not
|
||||
public until somebody classifies it.
|
||||
|
||||
These three lists are checked against the module's own on every build. A kind moved between
|
||||
classes upstream turns this page red.
|
||||
|
||||
## Public
|
||||
|
||||
Anybody may see these. Some are filtered field by field for each viewer — a world event's player
|
||||
name only for the presence audience, a Steam id and a position only for staff — but the kind
|
||||
itself is public.
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Kind</th><th>What it says</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(rustEventKinds.public).map(([kind, what]) => (
|
||||
<tr key={kind}><td><code>{kind}</code></td><td>{what}</td></tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
## Presence
|
||||
|
||||
Public kinds that say a **named** player was on the server at a given moment. Their audience is an
|
||||
operator's choice on [Who sees who is online](/docs/rust/who-sees-who-is-online/), and it is **staff
|
||||
only** until somebody widens it.
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Kind</th><th>What it says</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(rustEventKinds.presence).map(([kind, what]) => (
|
||||
<tr key={kind}><td><code>{kind}</code></td><td>{what}</td></tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
`player.death` and `player.chat` are here on purpose. They are the kill feed and the chat — the
|
||||
content a feed exists for — and each says *this person was on at 12:03* as plainly as a connect
|
||||
does.
|
||||
|
||||
<Aside type="note" title="Gathering is counted, not sent">
|
||||
A tree is hit hundreds of times a minute. One frame per swing would make the bridge the most
|
||||
expensive thing on the server, so the plugin keeps a per-player tally and sends `player.tally`
|
||||
once a minute, on disconnect and at shutdown. The leaderboard is exact and the wire is quiet. The
|
||||
rule behind it: if a hook can fire more than once a second per player, it is a counter, not an
|
||||
event.
|
||||
</Aside>
|
||||
|
||||
## Staff
|
||||
|
||||
Admins and moderators, and nobody else, at any setting.
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Kind</th><th>What it says</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(rustEventKinds.staff).map(([kind, what]) => (
|
||||
<tr key={kind}><td><code>{kind}</code></td><td>{what}</td></tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
Bans, unbans, login attempts and approvals carry **IP addresses**, and `player.reported` carries the text of one player's
|
||||
complaint about another. They are stored because an operator chasing ban evasion needs them; they
|
||||
reach no page below admin, and the sidecar's raw history that holds them is bounded by
|
||||
`retain_days` in [`sidecar.toml`](/docs/rust/sidecar-toml/).
|
||||
|
||||
Clan membership changes are staff kinds on the server's feed, but not hidden from the clan: they
|
||||
reach a clan's own members through its [Team](/docs/administration/teams/) feed, where core decides
|
||||
who is a member.
|
||||
|
||||
## Every frame says when and where
|
||||
|
||||
Every frame carries the server's id and the **wipe** it happened in — derived by the plugin from
|
||||
the save's creation time, absent on a server that has never saved. A wipe splits a server's history
|
||||
rather than ending it, which is how the leaderboard is per wipe while a player's totals survive.
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
|
||||
§8 defines the catalogue and every later section adds to it;
|
||||
[`server/catalogue.js`](https://gitea.whitlocktech.com/RunicGateway/Module-Rust/src/branch/main/server/catalogue.js)
|
||||
in the module is the classification this page is checked against.
|
||||
104
src/content/docs/docs/rust/events-zones-and-rewards.mdx
Normal file
104
src/content/docs/docs/rust/events-zones-and-rewards.mdx
Normal file
@@ -0,0 +1,104 @@
|
||||
---
|
||||
title: Events, zones and rewards
|
||||
description: What the Rust module adds to core's scheduled events — its steps, the values an event may borrow, zone presets, and the switch on each server that has to be on first.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
An event is core's: phases, steps, a schedule, a dry run, and a record of what happened — see
|
||||
[Scheduled events](/docs/administration/events/). This page is what the Rust module puts into
|
||||
that editor, and what a Rust server needs before any of it can run.
|
||||
|
||||
## First, switch it on
|
||||
|
||||
Each server's bridge plugin has **`EventsEnabled`**, and it is **off** until you turn it on —
|
||||
in [`RunicGateway.json`](/docs/rust/runicgateway-json/), from
|
||||
[Mod config](/docs/rust/mod-config/) or on the host. It gates everything an event writes: a
|
||||
borrowed value, a zone, a crate, an NPC, a tally, a line in chat.
|
||||
|
||||
Letting staff moderate from a screen they are looking at and letting a schedule change the world
|
||||
at four in the morning are different consents, so this is its own switch. Turning it off never
|
||||
strands anything: giving back what an event took, and cleaning up what it placed, always work.
|
||||
|
||||
<Aside type="note" title="A server's own ceilings">
|
||||
The same file holds how much one step may do on that server — crates, NPCs, people rewarded,
|
||||
tallies at once, the length of a chat line, world events called. **A step over a bound is
|
||||
refused, never trimmed to fit.** An operator may lower each bound; none can be raised past the
|
||||
plugin's own ceiling.
|
||||
</Aside>
|
||||
|
||||
## The steps
|
||||
|
||||
Picked from the step's **Action** list, beside core's own:
|
||||
|
||||
| Group | Step | What it does |
|
||||
|---|---|---|
|
||||
| **The world** | Open a zone | A ZoneManager zone, at a monument or coordinates, with flags from a [preset](#zone-presets), messages on entering and leaving, and optionally a dome |
|
||||
| | Place crates | Crates, barrels and supply drops |
|
||||
| | Place NPCs | Rust's scientists and guards, or [RunicNPC profiles](/docs/rust/runicnpc/npc-profiles/) — placed through RunicNPC |
|
||||
| | Call a world event | Rust's own: a patrol helicopter, an airdrop, the cargo ship, a Bradley, the Travelling Vendor and the rest |
|
||||
| **Counting** | Start counting participants | A tally of who is present in a zone or on the server, by seconds present, kills, or both |
|
||||
| | Record participants | Reads the tally into the run, so later steps can reward from it |
|
||||
| **Rewards** | Reward a kit | A Kits kit, as a credit the player redeems |
|
||||
| | Pay coins | Economics coins |
|
||||
| | Bigger backpack | Lends a larger Backpacks size until the event ends |
|
||||
| | Permissions until the event ends | Lent, and taken back at the end |
|
||||
| | Permissions for good | Given, and kept. Needs a tick saying you are sure |
|
||||
| | Reward by console command | Commands run once per recipient, with `{steamid}` and `{name}` filled in |
|
||||
| **Saying it** | Say it in game chat | A line in chat, or a popup where PopupNotifications is installed |
|
||||
| **Optional plugins** | Start a Dangerous Treasures event | |
|
||||
| | Place a guarded crate | |
|
||||
| | Spawn a raid base | A RaidableBases base that is the event's own |
|
||||
| **Anything else** | Run console commands | Free text, as typed at the server console, with commands to run when the event ends. Needs a tick saying you are sure |
|
||||
|
||||
The optional-plugin steps need their plugin on the server; [Optional
|
||||
plugins](/docs/rust/optional-plugins/) covers each. Every reward step picks its recipients the same
|
||||
way: everyone who scored, the top N, a minimum score, N drawn at random, the top X per cent — or
|
||||
every player with a [linked Steam account](/docs/rust/linking-steam-accounts/), with no tally at
|
||||
all, for something like a kit weekend. A recipient need not be linked otherwise: rewards go to
|
||||
Steam accounts, and one who is offline gets theirs on their next time in.
|
||||
|
||||
**What an event places is the event's.** At its end, the run gives back what it borrowed and
|
||||
removes what it placed — its zones, crates, NPCs, and a raid base it spawned. A server restart in
|
||||
the middle does not lose track: the plugin keeps the registry on disk, and something that outlives
|
||||
its deadline is removed and recorded as *expired*.
|
||||
|
||||
## Values an event may borrow
|
||||
|
||||
Core's **Borrow a value** step holds a setting for the length of the event and gives it back at
|
||||
the end. Rust lends four kinds of value, on each server:
|
||||
|
||||
- **Decay rate**
|
||||
- **Population** — an animal or vehicle population
|
||||
- **Spawn scalar**
|
||||
- **Group permission** — a permission on a group, which the [permission
|
||||
mirror](/docs/rust/permissions-and-groups/) leaves alone while the lease holds
|
||||
|
||||
## Zone presets
|
||||
|
||||
**Admin → Rust zone presets** (`/admin/rust/zones`) holds named sets of ZoneManager flags and
|
||||
settings. Core's step editor has single-value fields, so a zone's flags are ticked here, and an
|
||||
event's *Open a zone* step offers the presets in its **Options** field. Picking one **copies** it
|
||||
into the step, so changing a preset later does not change an event already published.
|
||||
|
||||
The screen lists each server's ZoneManager version, how many flags it has, and whether domes are
|
||||
available. None ship with the module: what an arena is differs by server. Who is exempt from a
|
||||
flag is a `zonemanager.ignoreflag.*` permission, set on the permissions page. Where TruePVE is
|
||||
installed, a zone can also turn PvP protection off inside it, or name a TruePVE ruleset.
|
||||
|
||||
## Triggers
|
||||
|
||||
A phase can advance when something happens in the game, and the vocabulary of *something* is
|
||||
the module's trigger catalog. Rust's includes a server wiping, coming online or going offline, a
|
||||
new kills leader, a raided base, a guarded crate landing or being cleared, a treasure event
|
||||
starting or being won, and a RunicNPC boss appearing, changing phase or dying. The same catalog
|
||||
drives [Engagement rules](/docs/administration/engagement-rules/).
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
|
||||
§14 to §16 and §20 are leases, world verbs, rewards and the step editor on the wire;
|
||||
[`website/EVENTS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/EVENTS.md)
|
||||
is core's event system, and
|
||||
[`modules/rust/PLAN_REDESIGNS.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/PLAN_REDESIGNS.md)
|
||||
the design of the step editor and the zones.
|
||||
102
src/content/docs/docs/rust/index.mdx
Normal file
102
src/content/docs/docs/rust/index.mdx
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
title: The Rust module
|
||||
description: What the rust module adds to a site, the pieces that connect it to a Rust server running Oxide or Carbon, and where each page in this group fits.
|
||||
---
|
||||
|
||||
import platform from '../../../../data/platform.json';
|
||||
|
||||
The `rust` module turns a Runic Gateway site into a *Rust* community's site. It follows any
|
||||
number of Rust servers, each running **Oxide** or **Carbon**. Everything in this group is
|
||||
specific to it; the rest of the documentation is core, and describes the platform in core's
|
||||
own words.
|
||||
|
||||
## The pieces
|
||||
|
||||
| Piece | What it is | Release |
|
||||
|---|---|---|
|
||||
| **The module** | [`Module-Rust`](https://gitea.whitlocktech.com/RunicGateway/Module-Rust) — every Rust screen on the site | {platform.releases['Module-Rust']} |
|
||||
| **The sidecar** | [`Rust-Link`](https://gitea.whitlocktech.com/RunicGateway/Rust-Link), the **rust-link sidecar** — the only part of the bridge that listens on a network | {platform.games.rust.bundle.sidecar} |
|
||||
| **The bridge plugin** | [`Rust-Plugins`](https://gitea.whitlocktech.com/RunicGateway/Rust-Plugins) — `RunicGateway.cs`, one file that runs unchanged on Oxide and Carbon, plus its optional helpers | {platform.games.rust.bundle.plugin} |
|
||||
| **RunicNPC** | [`runicnpc-rust`](https://gitea.whitlocktech.com/RunicGateway/runicnpc-rust) — our NPC plugin, which the bridge drives for every NPC an event places. **Required** | {platform.games.rust.bundle.runicnpc} |
|
||||
|
||||
The sidecar, the bridge plugin and RunicNPC are installed together on the game host as a
|
||||
**bundle** — {platform.games.rust.bundle.tag} today, speaking protocol
|
||||
{platform.games.rust.protocol}. A bundle is an exact set CI has checked, never "the latest of
|
||||
each". **One sidecar serves one Rust server**: a community running six servers runs six
|
||||
sidecars, each with its own port, database and token, and the site holds six rows.
|
||||
|
||||
The bundle needs Oxide {platform.games.rust.bundle.oxideMin} or Carbon
|
||||
{platform.games.rust.bundle.carbonMin} or newer, and the uMod plugins
|
||||
{platform.games.rust.bundle.requiresPlugins.join(' and ')}. RunicNPC will not load without
|
||||
Kits, so a server without it cannot place NPCs in an event.
|
||||
|
||||
## What the module adds
|
||||
|
||||
Install it from **Admin → Modules** like any module — the install manifest is the
|
||||
`module-rust-<version>.json` asset on
|
||||
[its releases page](https://gitea.whitlocktech.com/RunicGateway/Module-Rust/releases). It
|
||||
needs Module API {platform.games.rust.module.coreApi}.
|
||||
|
||||
**For visitors**, at `/rust`: every server as it last reported itself, and a page per server
|
||||
with six tabs.
|
||||
|
||||
| Tab | What it shows |
|
||||
|---|---|
|
||||
| **Feed** | Kills, chat, comings and goings, the server's own story, RunicNPC bosses, and Rust's world events — cargo, helicopters, airdrops — as they happen |
|
||||
| **Leaderboard** | Per wipe: kills, deaths, NPC kills, structures, time played, and the chat titles players have earned |
|
||||
| **Online** | Who is on right now |
|
||||
| **Map** | The [live map](/docs/rust/the-live-map/): the server's own map picture, with layers |
|
||||
| **Wipes** | Every wipe the site has seen. The next one, once the server has a wipe schedule, is in the page's header |
|
||||
| **Clans** | Each clan's name, colour, score and members |
|
||||
|
||||
A server's **clans are the site's [Teams](/docs/administration/teams/)**, so a clan gets a
|
||||
page, a feed for its members, and core's Team notifications. Who may see a clan's roster —
|
||||
and who may see a named player at all — is an operator's choice, set on
|
||||
[Who sees who is online](/docs/rust/who-sees-who-is-online/).
|
||||
|
||||
**For players**, at `/player/rust`: linking a Steam account, what they can do in game, their
|
||||
NPC kills, coins and backpack. See [Linking Steam accounts](/docs/rust/linking-steam-accounts/).
|
||||
|
||||
**For staff**, seven screens in the admin sidebar, each covered in this group:
|
||||
|
||||
| Sidebar row | Page here |
|
||||
|---|---|
|
||||
| Rust servers | [Connect the site](/docs/rust/connect-the-site/) |
|
||||
| Rust permissions | [Permissions and groups](/docs/rust/permissions-and-groups/) |
|
||||
| Rust mod config | [Mod config from the site](/docs/rust/mod-config/) |
|
||||
| Rust visibility | [Who sees who is online](/docs/rust/who-sees-who-is-online/) |
|
||||
| Rust zone presets | [Events, zones and rewards](/docs/rust/events-zones-and-rewards/) |
|
||||
| Rust NPC profiles | [NPC profiles](/docs/rust/runicnpc/npc-profiles/), in the RunicNPC subgroup |
|
||||
| Rust NPC placements | [NPC placements](/docs/rust/runicnpc/npc-placements/), in the RunicNPC subgroup |
|
||||
|
||||
The module also adds a **Rust** section to each user's page under **Admin → Users** (their
|
||||
linked Steam accounts, permissions, coins and backpack), Rust steps and triggers to core's
|
||||
[Scheduled events](/docs/administration/events/), and Rust triggers to
|
||||
[Engagement rules](/docs/administration/engagement-rules/) — *your base was raided*, *a server
|
||||
wiped*, *a new kills leader* and more.
|
||||
|
||||
Its capabilities are {platform.games.rust.module.capabilities.join(', ')}.
|
||||
|
||||
Until a server is connected, its pages exist and report it as offline. That is the same
|
||||
thing the public site does when a server goes down, and it is designed to be unremarkable:
|
||||
every list, count and last-reported time comes from what the site stored.
|
||||
|
||||
## In this group
|
||||
|
||||
| Page | Read it when |
|
||||
|---|---|
|
||||
| [Install the bridge](/docs/rust/install-the-bridge/) | Setting a Rust server up: the installer, a Pterodactyl egg, or by hand |
|
||||
| [Connect the site](/docs/rust/connect-the-site/) | Adding the server to the site, and the rest of its settings |
|
||||
| [Verify the bridge](/docs/rust/verify-the-bridge/) | Proving the server, the sidecar and the site are really talking |
|
||||
| [Linking Steam accounts](/docs/rust/linking-steam-accounts/) | Joining a player's Steam account to their site account |
|
||||
| [Permissions and groups](/docs/rust/permissions-and-groups/) | Granting permissions and managing groups from the site |
|
||||
| [Mod config from the site](/docs/rust/mod-config/) | Editing your plugins' config files without a file manager |
|
||||
| [Who sees who is online](/docs/rust/who-sees-who-is-online/) | Deciding what the public sees: names, rosters, map layers |
|
||||
| [Events, zones and rewards](/docs/rust/events-zones-and-rewards/) | Running scheduled events on a Rust server |
|
||||
| [Optional plugins](/docs/rust/optional-plugins/) | What each supported uMod plugin adds, and two that catch operators out |
|
||||
| [The live map](/docs/rust/the-live-map/) | What the map shows, and where the picture comes from |
|
||||
| [Troubleshooting](/docs/rust/troubleshooting/) | Something on the game side is wrong |
|
||||
| [sidecar.toml](/docs/rust/sidecar-toml/) | Changing the sidecar's binds, token, store or history |
|
||||
| [RunicGateway.json](/docs/rust/runicgateway-json/) | Changing the bridge plugin's own settings and bounds |
|
||||
| [Event kinds](/docs/rust/event-kinds/) | Knowing what the server can tell the site, and who may see each |
|
||||
| [RunicNPC](/docs/rust/runicnpc/) | Our NPC plugin: placing NPCs, their profiles, and its API for other plugins — eight pages of its own |
|
||||
161
src/content/docs/docs/rust/install-the-bridge.mdx
Normal file
161
src/content/docs/docs/rust/install-the-bridge.mdx
Normal file
@@ -0,0 +1,161 @@
|
||||
---
|
||||
title: Install the bridge
|
||||
description: Setting a Rust server up for the site — with the installer, from a Pterodactyl egg, or by hand — and what each puts where.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import platform from '../../../../data/platform.json';
|
||||
|
||||
This happens on the machine that runs your Rust server. It puts three things there — the
|
||||
bridge plugin, the sidecar and RunicNPC — from one bundle, {platform.games.rust.bundle.tag}
|
||||
today, and prints what the site needs. It never contacts your site, and it never starts or
|
||||
stops your game server.
|
||||
|
||||
```
|
||||
Rust server ──loopback, dials out──► rust-link sidecar ──HTTP + WebSocket──► your site
|
||||
```
|
||||
|
||||
The game server opens no port for the bridge: the plugin dials the sidecar on `127.0.0.1`.
|
||||
|
||||
## Before you begin
|
||||
|
||||
- **Oxide or Carbon is installed, and the server has started once with it**, so its
|
||||
directories exist. A vanilla server has nothing to load a plugin with. Oxide
|
||||
{platform.games.rust.bundle.oxideMin} or Carbon {platform.games.rust.bundle.carbonMin} or
|
||||
newer — never both in one tree.
|
||||
- **Kits and ZoneManager**, from uMod. The bridge runs without them and names what is missing,
|
||||
but rewards and zones need them, and **RunicNPC will not load without Kits**. Nothing here
|
||||
installs them.
|
||||
- **The site has the Rust module**, and you are an administrator on it.
|
||||
|
||||
## Three ways, one result
|
||||
|
||||
| | Use it when |
|
||||
|---|---|
|
||||
| [**The installer**](#the-installer) | The server runs on Linux with systemd, or on Windows |
|
||||
| [**The Pterodactyl egg**](#the-pterodactyl-egg) | The server runs on a Pterodactyl panel |
|
||||
| [**By hand**](#by-hand) | Neither fits, or you want to place every file yourself |
|
||||
|
||||
## The installer
|
||||
|
||||
The [Runic Gateway installer](/docs/reference/installer-cli/), {platform.releases.installer},
|
||||
told it is setting up Rust. Run it as root, or from an elevated PowerShell:
|
||||
|
||||
```bash
|
||||
sudo ./runicgateway-installer-linux-x86_64 install --game rust --rust /srv/rust --server-id main
|
||||
```
|
||||
|
||||
```powershell
|
||||
.\runicgateway-installer-windows-x86_64.exe install --game rust --rust D:\rust --server-id main
|
||||
```
|
||||
|
||||
`--rust` is the server root, the directory holding `RustDedicated`. **`--server-id` is
|
||||
required**: it is the id the site will know this server by — lowercase letters, digits and
|
||||
`-`, up to 64 — and it is permanent (see [Connect the site](/docs/rust/connect-the-site/)).
|
||||
Add `--verify` to see everything it would do and write nothing.
|
||||
|
||||
A run resolves the bundle, detects Oxide or Carbon from the server itself, and refuses a tree
|
||||
that has both or neither. It writes the plugin's config with just `ServerId` and `Port`,
|
||||
**only if there is none** — an existing config is never rewritten, and one that names a
|
||||
different server stops the run. It installs the sidecar and registers its service, places the
|
||||
plugin, its helpers and RunicNPC, and prints what the site needs. Both frameworks load a
|
||||
plugin the moment it lands, so on a running server the bridge comes up at once.
|
||||
|
||||
**More than one server on a host:** run it once per server, each with its own `--rust` and
|
||||
`--server-id`. Each gets its own service, config, database, game port (from 7799) and web
|
||||
port (from 8090), and they share one sidecar binary.
|
||||
|
||||
| | Linux | Windows |
|
||||
|---|---|---|
|
||||
| The sidecar binary, shared | `/usr/bin/runicgateway-rust-link` | `%ProgramFiles%\RunicGateway\rust-link-sidecar.exe` |
|
||||
| One server's sidecar config — **holds its token** | `/etc/runicgateway/rust/<id>.toml`, mode 600 | `%ProgramData%\RunicGateway\rust\<id>\sidecar.toml` |
|
||||
| One server's service | `runicgateway-rust@<id>.service` | `RunicGatewayRust-<id>` |
|
||||
|
||||
The full list, including the database and the install record, is in the
|
||||
[Rust bridge install guide](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INSTALL.md#where-everything-lands).
|
||||
|
||||
## The Pterodactyl egg
|
||||
|
||||
Each Rust-Link release carries **`egg-rust-runicgateway.json`**: the panel's *Rust Autowipe*
|
||||
egg with the bridge added. A panel administrator imports it under **Admin → Nests → Import
|
||||
Egg**. When you create a server from it, these variables matter:
|
||||
|
||||
| Variable | |
|
||||
|---|---|
|
||||
| **Modding Framework** | `oxide` or `carbon`. `vanilla` installs no bridge |
|
||||
| **Runic Gateway: server id** | The id on the site. Read **once**, when the plugin writes its first config; changing it later changes nothing |
|
||||
| **Runic Gateway: sidecar port** | **One of this server's allocations.** A port the server was not allocated binds, but is never reachable |
|
||||
| **Runic Gateway: sidecar token** | Leave blank, and the sidecar generates one. Anyone who can see this server's startup variables can read a token typed here |
|
||||
| **Runic Gateway: bundle** | Blank takes the current bundle; a tag pins one |
|
||||
|
||||
The install checks every file against the bundle's checksums before it places any of them.
|
||||
The **first boot** prints the generated token in the console, **once**, and a line with what
|
||||
the site needs:
|
||||
|
||||
```
|
||||
[rust-link] Admin -> Rust -> Servers: server id 'main', sidecar URL http://<this node's address>:21009 (listening on 0.0.0.0:21009)
|
||||
```
|
||||
|
||||
The sidecar runs inside the server's container and stops with it.
|
||||
|
||||
- **Updating is a reinstall**, with *Regen Server* off to keep the map. A restart never
|
||||
fetches anything, so it can never change the protocol under a site that has not been
|
||||
updated.
|
||||
- **A wipe keeps the bridge's history.** The egg moves `rust-link/` out of the way while
|
||||
`REMOVE_FILES` runs, so no delete list can reach the database or the token.
|
||||
|
||||
## By hand
|
||||
|
||||
1. **Pick the bundle.** The current one is
|
||||
[`v2/rust/current.json`](https://gitea.whitlocktech.com/RunicGateway/installer/src/branch/bundles/v2/rust/current.json)
|
||||
on the installer's `bundles` branch. It names the sidecar for your platform, the plugin
|
||||
tarball and RunicNPC's, each with a `sha256`.
|
||||
2. **Download and verify** each against its checksum.
|
||||
3. **The plugin:** copy `RunicGateway.cs` into `oxide/plugins/` or `carbon/plugins/`, with
|
||||
every other `.cs` the tarball's `manifest.json` lists beside it, and `RunicNPC.cs` from
|
||||
its own tarball. To name the server, create `oxide/config/RunicGateway.json` (Carbon:
|
||||
`carbon/configs/RunicGateway.json`) first, holding `{ "ServerId": "<id>", "Port": 7799 }`.
|
||||
Without it the plugin calls the server `main`.
|
||||
4. **The sidecar:** put the binary somewhere stable, give it a
|
||||
[`sidecar.toml`](/docs/rust/sidecar-toml/), and run
|
||||
`rust-link-sidecar --print-config --config <file>` once — it generates the token, saves
|
||||
it, and prints it.
|
||||
5. **Run it** under your supervisor with `--config <file>`, as an unprivileged user that can
|
||||
write the database directory. On Windows the same `.exe` runs as a service.
|
||||
|
||||
<Aside type="caution" title="Do not create RunicNPC's data folder yourself">
|
||||
RunicNPC makes `data/RunicNPC/` on its first load. One made from outside the game — a panel's
|
||||
file manager, say — may not be writable by it.
|
||||
</Aside>
|
||||
|
||||
## The helpers beside the plugin
|
||||
|
||||
The bundle ships three optional helpers beside the plugin, and the installer and the egg
|
||||
place all three. By hand, the tarball's `manifest.json` lists them in `files`:
|
||||
|
||||
- **`RunicGatewayZones.cs`** lets ZoneManager count a player already standing in an event
|
||||
zone when it opens or comes back after a restart, and enforce the flags of a zone opened
|
||||
after it loaded. Without it, events still score everybody, but a zone's flags — PvP off,
|
||||
no building — may not hold.
|
||||
- **`RunicGatewayDomes.cs`** lets the bridge ask ZoneDomes for a dome over an event zone.
|
||||
Without it, zones open without one.
|
||||
- **`RunicGatewayRaids.cs`** lets an event spawn a RaidableBases base of its own and despawn
|
||||
just that base when the event ends; see
|
||||
[Optional plugins](/docs/rust/optional-plugins/#raidablebases).
|
||||
|
||||
## Day two
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| `doctor --game rust` | Per server: the framework, whether each deployed file is still the one deployed, RunicNPC (a **failure** when missing — it is required), the required uMod plugins, the service, and `/health` through to *plugin connected* |
|
||||
| `update --game rust` | Moves the sidecar and every server's plugin to the current bundle, together — they share one binary |
|
||||
| `uninstall --game rust` | Removes the service, the plugin, its helpers and RunicNPC. **Keeps the plugin's config** and RunicNPC's data, because they name the server. `--purge` also removes the token and the database |
|
||||
|
||||
Next: [Connect the site](/docs/rust/connect-the-site/).
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`rust-link/INSTALL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INSTALL.md)
|
||||
is the operator guide, and its flags, paths and egg variables are the authority;
|
||||
[`installer/INSTALL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md)
|
||||
covers the installer itself.
|
||||
79
src/content/docs/docs/rust/linking-steam-accounts.mdx
Normal file
79
src/content/docs/docs/rust/linking-steam-accounts.mdx
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: Linking Steam accounts
|
||||
description: How a player joins their Steam account to their site account — a code from /link in game, or Steam sign-in — and how staff undo a wrong link.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
A Rust player is a Steam account. A site member is a site account. **Linking** joins the two,
|
||||
and it is what lets the site say *this member is that player*: their own page shows their
|
||||
kills, coins and backpack, a clan becomes a [Team](/docs/administration/teams/) whose members
|
||||
the site knows, and an event can reward a member by name.
|
||||
|
||||
## Two ways to link
|
||||
|
||||
**From the game, with a code.** The player page at `/player/rust` walks a player through it:
|
||||
|
||||
1. Join any of the community's Rust servers and type **`/link`** in chat.
|
||||
2. The server answers with a **six-character code** that only that player can see. It lasts
|
||||
five minutes.
|
||||
3. Type it on `/player/rust`. It works once.
|
||||
|
||||
Typing a code that only reached one player into a signed-in browser is the proof that the
|
||||
person at the browser is the person in the game. **The code never crosses the bridge**: what
|
||||
the server tells the site is only that somebody asked for one.
|
||||
|
||||
**By signing in with Steam.** When an administrator has turned on Steam under
|
||||
[Authentication](/docs/administration/authentication/#steam), a member who links Steam to
|
||||
their site account from their account page has linked that Steam account for Rust too. It is
|
||||
the same link, reached through Steam's own sign-in rather than through the game.
|
||||
|
||||
## What a link is
|
||||
|
||||
- **Fleet-wide.** A code from any of your servers links for all of them, and a member's
|
||||
totals on their page are summed across every server and every wipe.
|
||||
- **One owner at a time.** A Steam account belongs to one site account. If somebody links the
|
||||
wrong account, the site refuses to move it — including through Steam sign-in, which refuses a
|
||||
Steam account that is already another member's Rust link.
|
||||
- **Kept by the site, not the game.** Nothing about a link is stored on the game host.
|
||||
- **A member may hold several Steam accounts.**
|
||||
|
||||
## Undoing a link
|
||||
|
||||
- **The player:** **`/unlink`** in game asks the site to let go.
|
||||
- **Staff:** **Admin → Users**, open the member, and the **Rust** section lists each linked
|
||||
Steam account with an **Unlink** button. It is the way back for a player who linked the
|
||||
wrong account and cannot reach it in game, and it is recorded in the activity log.
|
||||
|
||||
<Aside type="note" title="Unlinking Steam sign-in leaves the Rust link in place">
|
||||
Removing Steam from a member's sign-in methods stops them signing in with it, and nothing
|
||||
else. The Rust link is removed on the Rust side — `/unlink`, or the Rust section of the
|
||||
member's page — so a member who only meant to stop using Steam to sign in does not lose
|
||||
their history.
|
||||
</Aside>
|
||||
|
||||
## What a linked player sees
|
||||
|
||||
On `/player/rust`: their linked Steam accounts, what they can do in game (the permissions
|
||||
the site has given them on each server), the NPCs they have killed this wipe, their coins on
|
||||
each server, and their backpack — once something is linked. Staff are sent to the admin
|
||||
area rather than the player portal, and see the same facts for anybody from that member's
|
||||
page.
|
||||
|
||||
## What staff see
|
||||
|
||||
On a member's page under **Admin → Users**, the Rust section shows each linked Steam account
|
||||
with when it was linked and last played, and kills, deaths and time played per server. Below
|
||||
it, staff can grant the member permissions, deposit, withdraw or set their coins on each
|
||||
server, and open their backpack.
|
||||
|
||||
A link request and an unlink are **staff-only** [event kinds](/docs/rust/event-kinds/):
|
||||
together they name a Steam account beside a site account's activity, and *this player is
|
||||
that person* is not a public page's business.
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
|
||||
§9 is the link on the wire, and
|
||||
[`website/STEAM_SIGNIN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/STEAM_SIGNIN.md)
|
||||
is Steam sign-in, including how it meets the Rust link.
|
||||
76
src/content/docs/docs/rust/mod-config.mdx
Normal file
76
src/content/docs/docs/rust/mod-config.mdx
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Mod config from the site
|
||||
description: Admin → Rust mod config — editing your plugins' config files on the game host from the site, with a backup, a watched reload, and an automatic undo.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
**Admin → Rust mod config** (`/admin/rust/config`) edits the configuration files on the game host
|
||||
itself, read live through the bridge. It works for whatever plugins you have installed, because
|
||||
it generates its form from the values it finds in each file.
|
||||
|
||||
## What it lists
|
||||
|
||||
Pick a server, and the screen names the directory it is reading — `oxide/config` or
|
||||
`carbon/configs`, or wherever your framework was told to keep them — and lists the files there,
|
||||
**grouped by the plugin each one probably belongs to**, with whether that plugin is loaded and
|
||||
its version.
|
||||
|
||||
**The data directory is not listed, on purpose.** `oxide/data` and `carbon/data` hold live state
|
||||
— kit cooldowns, zone definitions, the permission store itself — not settings. Editing them from
|
||||
a web form edits your players' cooldowns, and the running plugin writes over the change on its
|
||||
next save anyway. The one exception is RaidableBases' **profiles**, which live under its data
|
||||
directory but are settings, and are listed beside its config as *Profile · …*.
|
||||
|
||||
## Editing a file
|
||||
|
||||
Open a file and it shows as a form (**Settings**), or as **Raw JSON** for a change the form does
|
||||
not suit. Then choose what to **Reload** — the site suggests the plugin the file belongs to, and
|
||||
*nothing — just write the file* is an option. A folder name is convention rather than contract,
|
||||
so the guess is a field you can change, not an assumption.
|
||||
|
||||
**Save and reload** then:
|
||||
|
||||
1. backs the file up,
|
||||
2. writes it,
|
||||
3. reloads the plugin you named, and watches the reload,
|
||||
4. and if the plugin does not come back, **puts the old file back on its own**, and shows you
|
||||
the line from the server's log that says why.
|
||||
|
||||
A typo costs you a few seconds, not a plugin. The answer you see is one of:
|
||||
|
||||
- *Saved, and the plugin reloaded.*
|
||||
- *The plugin did not come back, so the old file was put back automatically.*
|
||||
- *…and it did not come back on the old file either. It is down: check the server console.* —
|
||||
the old file was broken too, which is worth knowing before anything else.
|
||||
- *The server never said how the reload went* — the bridge itself was reloaded, or the link
|
||||
dropped. Re-read the file to see what is on disk.
|
||||
|
||||
A reload fails on evidence — the framework's log saying the plugin did not compile or start —
|
||||
and a reload that says nothing at all is called lost only once a fixed ceiling has passed.
|
||||
|
||||
**Recent changes**, at the bottom, is every save, including the ones that did not land: what
|
||||
changed, field by field, and whether it was applied or rolled back.
|
||||
|
||||
<Aside type="caution" title="The bridge's own file is special">
|
||||
`RunicGateway.json` is editable here, except **`Host`, `Port` and `ServerId`**, which are shown
|
||||
read-only. Changing them from the site would cut the link carrying the change, or strand every
|
||||
row the site holds for the server — edit them on the host. And the bridge cannot be reloaded
|
||||
from here, for the same reason. See [RunicGateway.json](/docs/rust/runicgateway-json/).
|
||||
</Aside>
|
||||
|
||||
<Aside type="caution" title="RaidableBases: restart, never reload">
|
||||
Change RaidableBases' config, then **restart the server** instead of reloading the plugin. A
|
||||
reload can leave its live raids broken until a restart. See
|
||||
[Optional plugins](/docs/rust/optional-plugins/#raidablebases).
|
||||
</Aside>
|
||||
|
||||
`rg.config` at the server console prints which directory the site is reading, the log it
|
||||
watches, a reload in progress, and what the last write from the site did.
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
|
||||
§11 and §19.1 are configuration on the wire;
|
||||
[`modules/rust/OPERATING.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/OPERATING.md#plugin-configuration-plugins-configuration)
|
||||
has uMod's own page on plugin configuration.
|
||||
93
src/content/docs/docs/rust/optional-plugins.mdx
Normal file
93
src/content/docs/docs/rust/optional-plugins.mdx
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: Optional plugins
|
||||
description: The uMod plugins the Rust module recognises beyond the required two, what each one adds to the site, and the two — RaidableBases and Guarded Crate — that catch operators out.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import platform from '../../../../data/platform.json';
|
||||
|
||||
The bridge needs {platform.games.rust.bundle.requiresPlugins.join(' and ')}, and RunicNPC. Everything
|
||||
below is optional: install what your server wants, and the site notices. The bridge reports what it
|
||||
finds when it connects and whenever a plugin loads or unloads, and **Optional mods** on a row of
|
||||
[Admin → Rust servers](/docs/rust/connect-the-site/#the-rest-of-a-servers-settings) prints it —
|
||||
each plugin's version, and what it lets the site do on that server.
|
||||
|
||||
**Runic Gateway never ships or modifies any of these.** They are their authors' plugins, installed
|
||||
the way uMod's own guide describes, and a server without one simply lacks that feature.
|
||||
|
||||
| Plugin | What the site does with it |
|
||||
|---|---|
|
||||
| **BetterChat** | Shows [chat titles](/docs/rust/connect-the-site/#chat-titles) and [group chat styles](/docs/rust/permissions-and-groups/#chat-styles) in game chat. Titles still show on the leaderboard without it |
|
||||
| **PopupNotifications** | Lets news, event lines and zone messages arrive as a popup. Without it a popup falls back to chat, or is refused with a reason |
|
||||
| **Economics** | Coins: the *Pay coins* step, the *Richest* title, and balances on a member's page that staff can adjust |
|
||||
| **Backpacks** | Shows a player's backpack, and lets an event lend a bigger size |
|
||||
| **TruePVE** | Lets an event's zone turn PvP protection off, or name a ruleset |
|
||||
| **Dynamic PVP** | Its PvP zones — around a downed helicopter, a Bradley, cargo — appear in the feed and on the map |
|
||||
| **Dangerous Treasures** | Its events appear in the feed and on the map, earn the *Treasure Hunter* title, and a step may start one |
|
||||
| **Guarded Crate** | Its crates appear in the feed and on the map, earn the *Warden* title, and a step may place one. [Needs NpcSpawn](#guarded-crate) |
|
||||
| **RaidableBases** | Its bases appear in the feed and on the map, earn the *Warlord* title, and a step may spawn one that is the event's own. [Read this first](#raidablebases) |
|
||||
| **ZLevels Remastered** | An event may lend its XP boosts, which are permissions |
|
||||
| **ZoneDomes** | A dome over an event's zone, through the bridge's domes helper |
|
||||
|
||||
PopupNotifications has a recommended look — a banner across the top of the screen — which the
|
||||
installer and the egg write only where its config is missing or still its own defaults. The
|
||||
[install guide](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/INTEGRATION.md#24-the-recommended-popupnotifications-look-optional)
|
||||
has the config.
|
||||
|
||||
**Clans is not on the list, deliberately.** A server's clans come from Rust's own clan system,
|
||||
which that plugin never touches, so installing it would split your players across two unrelated
|
||||
clan systems.
|
||||
|
||||
## RaidableBases
|
||||
|
||||
Either edition works, the paid or the free one. The bridge's **raids helper**,
|
||||
`RunicGatewayRaids.cs`, installed beside the plugin by default, is what lets an event spawn a base
|
||||
of its own — at a spot, with its own settings and lock — and despawn only that base when the event
|
||||
ends. Without it a base an event spawned despawns on its own timer. Difficulty, profile and base
|
||||
names in the step editor come from RaidableBases itself, so they are whatever your copy has.
|
||||
|
||||
Two of RaidableBases' own behaviours catch operators out:
|
||||
|
||||
<Aside type="caution" title="Change its config with a restart, never a reload">
|
||||
After a reload of RaidableBases on a running server, its list of live raids can hold an empty
|
||||
entry, and every hook that walks the list fails: damage to a base, its SAM sites, players'
|
||||
commands, and the purchase command, so a purchase does nothing and charges nothing. Only a full
|
||||
server restart clears it. It is RaidableBases' own bug. Edit its config — from
|
||||
[Mod config](/docs/rust/mod-config/) with *nothing* chosen to reload, or on the host — then restart
|
||||
the server.
|
||||
</Aside>
|
||||
|
||||
<Aside type="caution" title="Back up before switching editions">
|
||||
Putting the free edition in place of the paid one rewrites the profiles a paid base pack installed,
|
||||
and drops their bases from them. Going back to the paid edition does not bring them back. Back up
|
||||
RaidableBases' config and data folders first.
|
||||
</Aside>
|
||||
|
||||
## Guarded Crate
|
||||
|
||||
Guarded Crate **needs NpcSpawn** for its guards, and NpcSpawn is not on uMod: it is a free download
|
||||
from Codefling. Install it before Guarded Crate:
|
||||
|
||||
1. Put `NpcSpawn.cs` in the plugins directory.
|
||||
2. Put the archive's `data/Images/` files in the data directory's `Images` folder. **Without them
|
||||
NpcSpawn unloads itself.**
|
||||
3. Leave `data/NpcSpawn/` for NpcSpawn to create. A folder made by a panel's file manager may not be
|
||||
writable by the game.
|
||||
4. Install Guarded Crate from uMod.
|
||||
|
||||
**NpcSpawn contacts its author's server when it loads**: it calls a version server and downloads
|
||||
clothing images. If your server may not reach the internet, or you do not want it to, know that
|
||||
before installing it.
|
||||
|
||||
Without NpcSpawn, the *Place a guarded crate* step is refused with a reason — the bridge checks,
|
||||
because Guarded Crate would otherwise drop a crate with no guards. Its events are rows in its data
|
||||
file (Easy, Medium, Hard and Elite as it ships), and the site offers whatever names that file holds.
|
||||
**A crate placed by an event is kept when the event ends**: Guarded Crate has no way to end one
|
||||
event without ending them all.
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`modules/rust/OPERATING.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/OPERATING.md)
|
||||
holds the RaidableBases and Guarded Crate notes in full;
|
||||
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
|
||||
§18 and §20 are each plugin on the wire.
|
||||
90
src/content/docs/docs/rust/permissions-and-groups.mdx
Normal file
90
src/content/docs/docs/rust/permissions-and-groups.mdx
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Permissions and groups
|
||||
description: Admin → Rust permissions — the site holds every server's permissions and groups, pushes them into Oxide or Carbon, and decides what happens to a change made in game.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
**Admin → Rust permissions** (`/admin/rust`) is where the site holds every permission and group
|
||||
on each server: what was there before the site, what is made here, and what is changed in the
|
||||
game. It reads each server's own permission store and pushes the site's set back into it, so
|
||||
every plugin you already run honours it — Kits, ZoneManager, anything that asks Oxide or
|
||||
Carbon whether a player has a permission. Nothing is configured twice, and nothing is asked of
|
||||
those plugins.
|
||||
|
||||
## The first sync imports
|
||||
|
||||
A server's first sync **imports everything** in its store, so taking the site into use loses
|
||||
nothing an operator had already set up at the console. Until then the server is marked *not
|
||||
imported yet*. After that, the site's set is the one that holds.
|
||||
|
||||
**A wipe loses nothing.** The site pushes the whole set again when the server comes back, so a
|
||||
wipe script that clears the data directory costs a minute, not your permissions.
|
||||
|
||||
## In-game changes
|
||||
|
||||
An operator will still grant something at the console during an incident. What happens to it is
|
||||
a per-server choice:
|
||||
|
||||
| Mode | A change made in the game |
|
||||
|---|---|
|
||||
| **auto-adopt** | Becomes the site's own, for that server |
|
||||
| **adopt** | Waits under *Waiting for a person*, to be adopted or undone |
|
||||
| **revoke** | Is undone at the next sync |
|
||||
|
||||
The chip beside the mode says when the server last synced. **Sync now** pushes at once.
|
||||
|
||||
## Players
|
||||
|
||||
The **Players** tab lists everybody who holds something on the selected server; pressing Enter in
|
||||
its search reaches every player the server has seen. A player shows their site account, when they
|
||||
have [linked one](/docs/rust/linking-steam-accounts/).
|
||||
|
||||
Pick one, and their permissions are listed by the plugin that registers them, with **Grant all**
|
||||
and **Revoke all** per plugin. Tick **Grant on every server** to make a grant fleet-wide rather
|
||||
than for this server only. Chips on a permission explain what you are looking at:
|
||||
|
||||
| Chip | Meaning |
|
||||
|---|---|
|
||||
| *not registered here* | No loaded plugin on this server registers it, so it cannot be granted — Oxide and Carbon silently do nothing for an unknown name. Load the plugin and the grant lands by itself |
|
||||
| *revoked here only* | Granted on every other server, and taken away on this one |
|
||||
| *from an event* | An event gave it, and the event's end takes it back |
|
||||
| *waiting for their first connection* | The server has never seen this player. A grant to them lands when they first join; every sync pushes it again |
|
||||
|
||||
## Groups
|
||||
|
||||
The **Groups** tab lists the server's groups with their member counts, and **Create** makes a
|
||||
new one. Each group has four tabs:
|
||||
|
||||
- **Permissions**, laid out as a player's are.
|
||||
- **Players** — who is in it. Every player who connects is in `default`, so it lists nobody.
|
||||
A player the server has never seen cannot be put in a group yet; the site says the membership
|
||||
is waiting, and it lands on their first connection.
|
||||
- **Settings** — the group's title, its rank and its parent group, whose permissions it
|
||||
inherits.
|
||||
- **Servers.** A group belongs to one server unless it is **shared**. A shared group carries the
|
||||
same permissions and players on every server it is on — including servers added later, if you
|
||||
tick that — and a change made in one game gives that server its own copy.
|
||||
|
||||
### Chat styles
|
||||
|
||||
A group's **Settings** tab has a **Chat style (BetterChat)** section. Give a group a style and
|
||||
BetterChat, where it is installed, shows its members' titles, colours and sizes as you set them
|
||||
here, with a priority deciding between a player's groups. A group with a style can also be the
|
||||
**announcement voice** on [Admin → Rust servers](/docs/rust/connect-the-site/#chat-titles), so
|
||||
news and event lines in game chat wear its title.
|
||||
|
||||
<Aside type="note" title="rg.perms at the server console">
|
||||
Prints what the last sync did. It is the fastest way to tell *that permission does not exist
|
||||
here* from *that player has never been seen here* — both look like "the site says they have it
|
||||
and the game disagrees" from the other end.
|
||||
</Aside>
|
||||
|
||||
## Canonical documents
|
||||
|
||||
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
|
||||
§10 and §19.9 are the permission mirror on the wire;
|
||||
[`modules/rust/OPERATING.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/OPERATING.md#permissions-plugins-permissions)
|
||||
has uMod's own guide to permissions and groups, and
|
||||
[`CARBON.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/CARBON.md)
|
||||
how Carbon's store differs.
|
||||
74
src/content/docs/docs/rust/runicgateway-json.mdx
Normal file
74
src/content/docs/docs/rust/runicgateway-json.mdx
Normal file
@@ -0,0 +1,74 @@
|
||||
---
|
||||
title: RunicGateway.json
|
||||
description: The bridge plugin's own config file on the Rust server — every key, which three the site will not edit, and the event bounds that refuse rather than trim.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
import { rustPluginConfig } from '../../../../data/reference.mjs';
|
||||
|
||||
The bridge plugin's config, written by the framework as `oxide/config/RunicGateway.json`, or
|
||||
`carbon/configs/RunicGateway.json` on Carbon. The plugin fills in every key it is missing on
|
||||
load, so a config written by an older version shows the newer keys after the first load with the
|
||||
new one — which is what lets [Mod config](/docs/rust/mod-config/) show a switch before anybody needs
|
||||
it.
|
||||
|
||||
**Where the first one comes from.** The installer writes one holding just `ServerId` and `Port`,
|
||||
and only when there is none. On a Pterodactyl egg, the plugin's first load takes the server id from
|
||||
the `RUSTLINK_SERVER_ID` variable. After that the file is canonical, and changing either source
|
||||
changes nothing.
|
||||
|
||||
## The keys
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Key</th><th>What it is for</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(rustPluginConfig).flatMap(([group, keys]) => [
|
||||
<tr key={group}><th colspan="2">{group}</th></tr>,
|
||||
...Object.entries(keys).map(([name, k]) => (
|
||||
<tr key={name}>
|
||||
<td><code>{name}</code>{k.readOnlyFromSite ? <><br /><small>read-only from the site</small></> : null}</td>
|
||||
<td>{k.why}</td>
|
||||
</tr>
|
||||
)),
|
||||
])}
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
This list is checked against the plugin's own source on every build.
|
||||
|
||||
<Aside type="caution" title="Three keys are the host's">
|
||||
`Host`, `Port` and `ServerId` are read-only in the site's config editor. Changing the first two
|
||||
from the site would cut the link carrying the change; changing `ServerId` would strand every row
|
||||
the site holds for this server. **`ServerId` is permanent** — it is not the hostname, so a server
|
||||
can be renamed for a season without losing its history.
|
||||
</Aside>
|
||||
|
||||
## The event bounds
|
||||
|
||||
`EventsEnabled` ships **off**. While it is off the site may still list and give back what events
|
||||
hold, so switching it off never strands anything; it may not borrow, place, count, pay or say
|
||||
anything new. See [Events, zones and rewards](/docs/rust/events-zones-and-rewards/).
|
||||
|
||||
Saved from [Mod config](/docs/rust/mod-config/), **`EventsEnabled` takes effect at once**. The
|
||||
bridge never reloads itself, so its other settings apply at its next reload — a server restart,
|
||||
or a reload at the console.
|
||||
|
||||
Each `EventsMax…` key is how much **one step** may do on this server — or, for
|
||||
`EventsMaxWorldCalls`, one run, and for `EventsMaxTallies`, the whole server at once. Two rules
|
||||
hold for all of them:
|
||||
|
||||
- **An operator may lower a bound, never raise it** past the plugin's own ceiling. A value above it
|
||||
is brought down to it when the plugin loads.
|
||||
- **A step over a bound is refused, never trimmed to fit.** An event that does less than its
|
||||
author wrote, quietly, is worse than one that says it cannot.
|
||||
|
||||
The two `Map…` keys are different: a map answer over its bound is cut short and says so, because a
|
||||
read has nobody to refuse.
|
||||
|
||||
## Canonical documents
|
||||
|
||||
The `PluginConfig` class in
|
||||
[`RunicGateway.cs`](https://gitea.whitlocktech.com/RunicGateway/Rust-Plugins/src/branch/main/overlay/oxide/plugins/RunicGateway.cs)
|
||||
is the authority;
|
||||
[`rust-link/PROTOCOL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md)
|
||||
§6.1 describes the file and §14 to §17 each key as it arrived.
|
||||
362
src/content/docs/docs/rust/runicnpc/api.mdx
Normal file
362
src/content/docs/docs/rust/runicnpc/api.mdx
Normal file
@@ -0,0 +1,362 @@
|
||||
---
|
||||
title: The API
|
||||
description: RunicNPC's API for other Oxide and Carbon plugins, in full — every call, every hook it raises, and the shapes of an NPC, a placement and a route.
|
||||
---
|
||||
|
||||
import { Aside, Code } from '@astrojs/starlight/components';
|
||||
import platform from '../../../../../data/platform.json';
|
||||
import Signature from '../../../../../components/Signature.astro';
|
||||
import Ticks from '../../../../../components/Ticks.astro';
|
||||
import {
|
||||
runicnpcOwners,
|
||||
runicnpcHooks,
|
||||
runicnpcListKeys,
|
||||
runicnpcPlacementKeys,
|
||||
runicnpcRouteKeys,
|
||||
} from '../../../../../data/runicnpc.mjs';
|
||||
|
||||
<Aside title="The specification is normative">
|
||||
This page carries RunicNPC's API in full, for plugin authors. Its specification is
|
||||
[`docs/runicnpc/API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/runicnpc/API.md),
|
||||
and where the two ever disagree, that wins. Every signature and every field name below is
|
||||
checked against it on every build, so a call, hook or field that changes there turns this site
|
||||
red until this page follows.
|
||||
</Aside>
|
||||
|
||||
This is **API version {platform.runicnpc.api}**, shipped in RunicNPC
|
||||
{platform.releases['runicnpc-rust']}. RunicNPC works without Runic Gateway, and so does
|
||||
everything on this page.
|
||||
|
||||
## Calling it
|
||||
|
||||
RunicNPC is called by name through `Call`, like any Oxide or Carbon plugin API. Every call is
|
||||
prefixed `RunicNpc_`, so no hook of another plugin is ever matched by accident.
|
||||
|
||||
<Code
|
||||
lang="csharp"
|
||||
code={[
|
||||
'[PluginReference] private Plugin RunicNPC;',
|
||||
'',
|
||||
'int api = RunicNPC?.Call<int>("RunicNpc_ApiVersion") ?? 0;',
|
||||
`if (api < ${platform.runicnpc.api}) { /* too old for this caller: say so */ }`,
|
||||
'',
|
||||
'BasePlayer npc = RunicNPC.Call("RunicNpc_Spawn", position, "warden", "plugin:MyPlugin", null) as BasePlayer;',
|
||||
].join('\n')}
|
||||
/>
|
||||
|
||||
**The API version moves when a call or a raised hook changes shape**, not on every release. The
|
||||
release's manifest carries it too, so an installer can refuse a RunicNPC too old for its caller
|
||||
before it is loaded. Check it before relying on a call.
|
||||
|
||||
**A call that cannot do what it was asked returns null, 0 or false, and says why in the server
|
||||
log.** Calls that change data return the reason as a string instead, and null means success.
|
||||
|
||||
## Owners
|
||||
|
||||
Every NPC has an owner, and the owner decides how long it lives.
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Owner</th><th>Who uses it</th><th>Lifetime</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(runicnpcOwners).map(([owner, o]) => (
|
||||
<tr key={owner}><td><code>{owner}</code></td><td><Ticks text={o.who} /></td><td><Ticks text={o.lifetime} /></td></tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
## Spawning and removing
|
||||
|
||||
### RunicNpc_ApiVersion
|
||||
|
||||
<Signature call="RunicNpc_ApiVersion" />
|
||||
|
||||
The API version: {platform.runicnpc.api}.
|
||||
|
||||
### RunicNpc_Spawn
|
||||
|
||||
<Signature call="RunicNpc_Spawn" />
|
||||
|
||||
Spawns one NPC now, or returns null.
|
||||
|
||||
- `owner` must be `run:<id>` or `plugin:<name>`.
|
||||
- `overrides` may change any [profile field](/docs/rust/runicnpc/profile-fields/) for this NPC
|
||||
only, in the profile's own shape, or be null. For example:
|
||||
`{"health": 500, "names": ["Captain"], "movement": {"mode": "route:gate", "radius": 0}}`.
|
||||
Arrays are replaced, not merged, and the merged profile is checked like a saved one.
|
||||
- A roamer must stand on Rust's navmesh, within 3 m across and 2 m up or down of `at`. A sentry
|
||||
may stand anywhere.
|
||||
- It is refused until the map's navmesh is built, which takes 8–10 minutes on a map's first boot.
|
||||
|
||||
It is refused for an unknown or refused profile, a bad owner, an override that fails, a spot off
|
||||
the navmesh, a cap an admin has set, or a navmesh not built yet.
|
||||
|
||||
### RunicNpc_Despawn
|
||||
|
||||
<Signature call="RunicNpc_Despawn" />
|
||||
|
||||
Removes one NPC by its net id, and returns 1, or 0 if it is not one of RunicNPC's. A placement's
|
||||
NPC comes back after its respawn delay. **For a boss, it also removes the adds that boss
|
||||
summoned**, even once the boss is dead, and counts them in what it returns: whoever placed the
|
||||
boss knows only the boss's net id.
|
||||
|
||||
### RunicNpc_DespawnOwner
|
||||
|
||||
<Signature call="RunicNpc_DespawnOwner" />
|
||||
|
||||
Removes every NPC of `owner`, and returns how many it removed.
|
||||
|
||||
### RunicNpc_IsRunicNpc
|
||||
|
||||
<Signature call="RunicNpc_IsRunicNpc" />
|
||||
|
||||
Whether `entity` is one of RunicNPC's NPCs.
|
||||
|
||||
### RunicNpc_ProfileOf
|
||||
|
||||
<Signature call="RunicNpc_ProfileOf" />
|
||||
|
||||
The name of its profile, or null.
|
||||
|
||||
### RunicNpc_CostWarning
|
||||
|
||||
<Signature call="RunicNpc_CostWarning" />
|
||||
|
||||
The [cost warning](/docs/rust/runicnpc/cost-and-caps/) for the NPCs the server plans, plus
|
||||
`adding`: what they add to a server frame, idle and fighting, and how slowly each then reacts. A
|
||||
caller that adds NPCs should show it to whoever added them.
|
||||
|
||||
## Listing NPCs
|
||||
|
||||
### RunicNpc_List
|
||||
|
||||
<Signature call="RunicNpc_List" />
|
||||
|
||||
The live NPCs of `owner`, or of every owner when it is null. Each row has:
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Key</th><th>Type</th><th>What it is</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(runicnpcListKeys).map(([key, k]) => (
|
||||
<tr key={key}><td><code>{key}</code></td><td><code>{k.type}</code></td><td><Ticks text={k.what} /></td></tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
## Orders for one NPC
|
||||
|
||||
### RunicNpc_Escort
|
||||
|
||||
<Signature call="RunicNpc_Escort" />
|
||||
|
||||
One of RunicNPC's NPCs escorts `target`: a player, or any other entity — a crate it guards, a
|
||||
vehicle. It keeps within a few metres, never targets it, and fights whoever damages it. **When the
|
||||
target dies, is destroyed or, for a player, leaves the server**, it walks back to its spot,
|
||||
carries on as its profile does there, and `OnRunicNpcEscortEnded` is raised. A null `target`
|
||||
stops it. Null on success; refused for a sentry, which never moves, and for a player who is not on
|
||||
the server.
|
||||
|
||||
### RunicNpc_Ally
|
||||
|
||||
<Signature call="RunicNpc_Ally" />
|
||||
|
||||
Allies one NPC to `clan` (the game's own clan id), `team` (a Rust team id) or `player` (a Steam
|
||||
id: that player, and their team if they have one), or to nobody with `none`. It **never targets**
|
||||
the ally's people, and **defends them and what they own** — building blocks, doors, deployables:
|
||||
whoever damages one of them within its leash is fought. Rust's own clans and teams only. Null on
|
||||
success; refused for a clan or team the server does not have.
|
||||
|
||||
### RunicNpc_Tether
|
||||
|
||||
<Signature call="RunicNpc_Tether" />
|
||||
|
||||
Holds one NPC inside a ZoneManager zone: it never chases or wanders out, and if it ends up outside
|
||||
— pushed, or the zone moved — it forgets the fight and walks home. A null `zone` frees it. Refused
|
||||
for a sentry, on a server without ZoneManager, for a zone the server does not have, and for a zone
|
||||
that does not hold the NPC.
|
||||
|
||||
## Profiles and factions
|
||||
|
||||
### RunicNpc_Profiles
|
||||
|
||||
<Signature call="RunicNpc_Profiles" />
|
||||
|
||||
`{"managed": bool, "profiles": {name: profile, …}, "factions": [pair, …], "refused": {name: reason, …}}`.
|
||||
`managed` is whether a site manages this server. A refused profile is kept in the file but never
|
||||
spawns — a kit the server lacks, for example. `factions` is the faction table. Every field of a
|
||||
profile is on [Profile fields](/docs/rust/runicnpc/profile-fields/).
|
||||
|
||||
### RunicNpc_SetProfiles
|
||||
|
||||
<Signature call="RunicNpc_SetProfiles" />
|
||||
|
||||
Replaces the whole profile set with `all` (`{name: profile, …}`), as a site does on every push,
|
||||
and **marks the server managed**: from then on, the console commands that edit profiles are
|
||||
refused. It returns the profiles refused and why; the rest are in use at once. A placement whose
|
||||
profile has gone waits, and spawns again when the profile returns.
|
||||
|
||||
### RunicNpc_Factions
|
||||
|
||||
<Signature call="RunicNpc_Factions" />
|
||||
|
||||
The faction table: `[{"a": "bandits", "b": "guards", "relation": "hostile"}, …]`, one row per
|
||||
pair, meaning both ways. A pair not listed is neutral, and a faction is always allied to itself.
|
||||
|
||||
### RunicNpc_SetFactions
|
||||
|
||||
<Signature call="RunicNpc_SetFactions" />
|
||||
|
||||
Replaces the faction table, as a site does with every push, and **marks the server managed**.
|
||||
Null on success; otherwise the first problem, and the old table is kept. Refused: a pair of one
|
||||
faction with itself; a pair of `scientists` and `animals`, because RunicNPC does not change how
|
||||
Rust's own NPCs treat each other; a relation other than `hostile`, `neutral` or `allied`; and a
|
||||
pair given twice, in either order.
|
||||
|
||||
## Placements
|
||||
|
||||
A **placement** is a spot where a profile's NPCs stand and come back after they die. It is saved;
|
||||
its NPCs never are. Its keys:
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Key</th><th>What it is</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(runicnpcPlacementKeys).map(([key, what]) => (
|
||||
<tr key={key}><td><code>{key}</code></td><td><Ticks text={what} /></td></tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
```json
|
||||
{
|
||||
"profile": "warden",
|
||||
"position": { "x": 100.0, "y": 12.5, "z": -340.0 },
|
||||
"yaw": 90,
|
||||
"count": 3,
|
||||
"respawn": 300,
|
||||
"respawnMode": "each",
|
||||
"movement": { "mode": "route:gate", "radius": 0 }
|
||||
}
|
||||
```
|
||||
|
||||
A placement whose profile or zone has gone **waits**, and spawns again when it returns. **If the
|
||||
ground under a placement goes later** — a player-built floor destroyed — a live NPC is put on the
|
||||
nearest navmesh within 2 s, and the placement respawns its NPCs on the nearest navmesh until its
|
||||
spot is walkable again. Rust itself would leave such an NPC standing in the air.
|
||||
|
||||
### RunicNpc_Placements
|
||||
|
||||
<Signature call="RunicNpc_Placements" />
|
||||
|
||||
Each placement as `{id, placement, alive, waiting, lastError, note}`: `placement` is its JSON,
|
||||
`alive` how many of its NPCs are alive, and `waiting` why it cannot spawn now, or null. `note` is
|
||||
set while its NPCs stand somewhere other than its spot because the ground there went, and null
|
||||
otherwise.
|
||||
|
||||
### RunicNpc_AddPlacement
|
||||
|
||||
<Signature call="RunicNpc_AddPlacement" />
|
||||
|
||||
**Creates a placement and names it as `/rnpc place` does**: the profile's name and the first free
|
||||
number, `warden-3`. It is checked and refused exactly as `/rnpc place` is, with the same
|
||||
sentences, so a placement made by another plugin or a website and one made in game never disagree.
|
||||
|
||||
- `placement` has no id. **A `position` without `y` is a point on the map**: it is put on the
|
||||
ground there by a ray down onto terrain and rock, never a building or a tree, then checked
|
||||
against the navmesh like any other. A point off the map, or under water, is refused.
|
||||
- The answer is `{id, position, built, cost}` — the name given, where it landed, whether that spot
|
||||
is on something players built, and the cost warning — or `{error}`, the sentence `/rnpc place`
|
||||
would have said.
|
||||
|
||||
### RunicNpc_SetPlacement
|
||||
|
||||
<Signature call="RunicNpc_SetPlacement" />
|
||||
|
||||
Adds or replaces a placement with the id you give. Null on success, or the reason. Replacing one
|
||||
removes its NPCs and spawns them again from the new values. Every set logs the cost warning.
|
||||
|
||||
A roamer's spot must be on Rust's navmesh, within 2 m up or down, when it is set; otherwise the
|
||||
answer says how far off it is. The check is skipped while the map's navmesh is still being built,
|
||||
and for a profile that does not exist yet.
|
||||
|
||||
### RunicNpc_RenamePlacement
|
||||
|
||||
<Signature call="RunicNpc_RenamePlacement" />
|
||||
|
||||
Renames a placement, as `/rnpc rename` does: its live NPCs keep living under the new name. Null on
|
||||
success, or why not — no such placement, the name taken, or not a name.
|
||||
|
||||
### RunicNpc_RespawnPlacement
|
||||
|
||||
<Signature call="RunicNpc_RespawnPlacement" />
|
||||
|
||||
Removes a placement's NPCs and spawns them again at once, as `/rnpc respawn` does. Returns how
|
||||
many, or `-1` if there is no such placement.
|
||||
|
||||
### RunicNpc_RemovePlacement
|
||||
|
||||
<Signature call="RunicNpc_RemovePlacement" />
|
||||
|
||||
Removes a placement and its NPCs.
|
||||
|
||||
## Routes
|
||||
|
||||
A route is a line of points an NPC walks. An NPC joins a route at its nearest point.
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Key</th><th>What it is</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(runicnpcRouteKeys).map(([key, what]) => (
|
||||
<tr key={key}><td><code>{key}</code></td><td><Ticks text={what} /></td></tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
```json
|
||||
{ "points": [ { "x": 1, "y": 2, "z": 3 }, { "x": 4, "y": 2, "z": 6 } ], "loop": true }
|
||||
```
|
||||
|
||||
### RunicNpc_Routes
|
||||
|
||||
<Signature call="RunicNpc_Routes" />
|
||||
|
||||
Every route, as `{name: route, …}`.
|
||||
|
||||
### RunicNpc_SetRoute
|
||||
|
||||
<Signature call="RunicNpc_SetRoute" />
|
||||
|
||||
Adds or replaces a route. Every point must be on Rust's navmesh. Null on success, or the reason.
|
||||
**Unlike `/rnpc path`, it does not check that an NPC can walk from each point to the next**: a leg
|
||||
Rust cannot path leaves the NPC standing at the last point it reached, so a caller that builds
|
||||
routes should check its own legs.
|
||||
|
||||
### RunicNpc_RemoveRoute
|
||||
|
||||
<Signature call="RunicNpc_RemoveRoute" />
|
||||
|
||||
Removes a route. Placements that walk it wait until it exists again.
|
||||
|
||||
## Hooks it raises
|
||||
|
||||
Every hook is called on every plugin, and **none of them answers**: a return value is ignored.
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Hook</th><th>When</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(runicnpcHooks).map(([hook, h]) => (
|
||||
<tr key={hook}><td><code>{`${hook}(${h.params})`}</code></td><td><Ticks text={h.when} /></td></tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
## Its files
|
||||
|
||||
`data/RunicNPC/profiles.json` (the profiles, the faction table and whether a site manages them),
|
||||
`placements.json` and `routes.json`, under `oxide/` or `carbon/`. From a plugin, change them
|
||||
through the calls above rather than the files. See [Install RunicNPC](/docs/rust/runicnpc/install/#its-files)
|
||||
for every file and who writes it.
|
||||
|
||||
<Aside type="caution" title="A Kits reload reloads RunicNPC">
|
||||
RunicNPC requires Kits, so both frameworks reload RunicNPC with it, and every NPC it had spawned is
|
||||
lost. Placements come back; NPCs a plugin or an event spawned do not, and `OnRunicNpcDespawned` is
|
||||
not raised for them.
|
||||
</Aside>
|
||||
104
src/content/docs/docs/rust/runicnpc/commands.mdx
Normal file
104
src/content/docs/docs/rust/runicnpc/commands.mdx
Normal file
@@ -0,0 +1,104 @@
|
||||
---
|
||||
title: Commands
|
||||
description: Every /rnpc chat command and rnpc.* console command RunicNPC answers, the two permissions they need, and the options for placing NPCs.
|
||||
---
|
||||
|
||||
import Ticks from '../../../../../components/Ticks.astro';
|
||||
import {
|
||||
runicnpcCommands,
|
||||
runicnpcPermissions,
|
||||
runicnpcPlaceOptions,
|
||||
} from '../../../../../data/runicnpc.mjs';
|
||||
|
||||
export const Commands = ({ section }) => (
|
||||
<table>
|
||||
<thead><tr><th>Command</th><th>Does</th><th>Needs</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(runicnpcCommands[section]).map(([usage, c]) => (
|
||||
<tr key={usage}>
|
||||
<td><code>{c.console ? `rnpc.${usage}` : `/rnpc ${usage}`}</code></td>
|
||||
<td><Ticks text={c.does} /></td>
|
||||
<td>{c.perm.startsWith('runicnpc.') ? <code>{c.perm}</code> : c.perm}</td>
|
||||
</tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
);
|
||||
|
||||
## How commands are reached
|
||||
|
||||
- **In chat:** `/rnpc <verb> …`. `/rnpc` alone lists the verbs you are allowed to use.
|
||||
- **In a console:** `rnpc.<verb> …`, in a player's F1 console, the server console or RCON. The
|
||||
same code answers both, with the same permissions.
|
||||
- **Four verbs answer only in a console** — `profile`, `faction`, `status` and `reload`. In chat
|
||||
they tell you to open F1.
|
||||
- **The server console has every permission.** It has no position, so placing there takes `at=`
|
||||
and `yaw=` instead of where you look.
|
||||
|
||||
The verbs, the permissions and the placing options on this page are checked against the plugin's
|
||||
own source on every build.
|
||||
|
||||
## Permissions
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Permission</th><th>Grants</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(runicnpcPermissions).map(([perm, grants]) => (
|
||||
<tr key={perm}><td><code>{perm}</code></td><td><Ticks text={grants} /></td></tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
On a Runic Gateway server both show in **Admin → Rust permissions** like any plugin's, and the
|
||||
site grants them there — see [Permissions and groups](/docs/rust/permissions-and-groups/).
|
||||
|
||||
## Placements
|
||||
|
||||
A **placement** is a spot where a profile's NPCs stand and come back after they die. It is saved
|
||||
on the server and survives restarts. Placements made in game are named after their profile and a
|
||||
number, `bandit-1`, and can be renamed. The site's [placements screen](/docs/rust/runicnpc/npc-placements/)
|
||||
edits the same list.
|
||||
|
||||
<Commands section="Placements" />
|
||||
|
||||
### Options for `place` and `here`
|
||||
|
||||
`key=value`, in any order: `/rnpc place raider count=3 respawn=600 mode=group`.
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Option</th><th>Means</th><th>Default</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(runicnpcPlaceOptions).map(([key, o]) => (
|
||||
<tr key={key}><td><code>{key}=</code></td><td><Ticks text={o.means} /></td><td><Ticks text={o.default} /></td></tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
**Every placement is checked against Rust's navmesh.** A roamer must stand on it; only a sentry,
|
||||
or a passive NPC that stands, may stand off it. On a player-built floor the placement is made with
|
||||
a warning: if the floor is destroyed, the NPCs fall back to the nearest navmesh, and return to
|
||||
their spot once it is rebuilt. Every command that adds NPCs answers with the
|
||||
[cost warning](/docs/rust/runicnpc/cost-and-caps/).
|
||||
|
||||
## Routes
|
||||
|
||||
A route is a line of points an NPC walks, recorded in game where you walk, one point at a time.
|
||||
A recording is kept in memory only: a reload of RunicNPC discards it. A placement walks one with
|
||||
`move=route:<name>`.
|
||||
|
||||
<Commands section="Routes" />
|
||||
|
||||
## At the console
|
||||
|
||||
**On a Runic Gateway server the site manages the profiles and the faction table.** There,
|
||||
`rnpc.profile create`, `set` and `delete`, and `rnpc.faction set` and `clear`, are refused with
|
||||
"managed by its website"; `show` and `list` still answer. On a server with no site, they are how
|
||||
profiles are made: see [Profile fields](/docs/rust/runicnpc/profile-fields/) for every field
|
||||
`set` takes.
|
||||
|
||||
<Commands section="At the console" />
|
||||
|
||||
A boss block or a press-E block is added with its defaults by `set <name> boss on` or
|
||||
`set <name> use on`, and removed with `none`. Their fields are then set one at a time —
|
||||
`boss.spawnLine The Juggernaut has risen!` — and a list of objects as JSON:
|
||||
`boss.phases [{"at":0.5,"line":"…"}]`. Setting `role passive` also turns `hurtByPlayers` off.
|
||||
79
src/content/docs/docs/rust/runicnpc/cost-and-caps.mdx
Normal file
79
src/content/docs/docs/rust/runicnpc/cost-and-caps.mdx
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: Cost and caps
|
||||
description: What RunicNPC's NPCs cost a Rust server, measured rather than guessed, the warning that says so wherever NPCs are added, and the caps an operator can set.
|
||||
---
|
||||
|
||||
import Ticks from '../../../../../components/Ticks.astro';
|
||||
import { runicnpcConfig } from '../../../../../data/runicnpc.mjs';
|
||||
|
||||
**RunicNPC has no caps by default.** Instead, everything that adds NPCs answers with what the
|
||||
server's RunicNPC NPCs will then cost: `/rnpc place`, the site's
|
||||
[placements screen](/docs/rust/runicnpc/npc-placements/), an event's *Place NPCs* step, the API's
|
||||
`RunicNpc_CostWarning`, and the end of `rnpc.status`. A server's owner knows their hardware and
|
||||
their players; a number someone else picked would be wrong for most of them.
|
||||
|
||||
## The cost warning
|
||||
|
||||
It reads like this:
|
||||
|
||||
```
|
||||
RunicNPC: 100 NPC(s) on this server. Measured on a test server, they add about 3 ms to every
|
||||
server frame while idle with a player near enough to wake them, and about 0.5 ms once they sleep
|
||||
with nobody near. If all fight at once they add about 9 ms, and Rust's shared 2 ms AI budget then
|
||||
lets each react only every 3 s. …
|
||||
```
|
||||
|
||||
What it means:
|
||||
|
||||
- **Idle NPCs are cheap, and sleeping ones cheaper.** NPCs that stand, wander or patrol with
|
||||
nobody to fight add a little to a frame. One with no player within its sleep distance — 160 m
|
||||
unless its profile says otherwise — walks home and sleeps, and then costs about a sixth of what
|
||||
it did awake.
|
||||
- **Fighting NPCs hit Rust's AI budget before the frame rate.** All of Rust's human NPCs, its own
|
||||
scientists included, share one AI budget of 2 ms a frame (`aithinkmanager.framebudgetms`). With
|
||||
many fighting at once, each reacts less often. The server stays smooth, and the NPCs get slower
|
||||
to react.
|
||||
- **Fighting other NPCs costs about what fighting players does.** That is a faction setting, and
|
||||
off unless a profile opts in. On a map whose own AI is busy, each then reacts less often still;
|
||||
the warning says by how much once any profile fights NPCs.
|
||||
|
||||
## Where the figures come from
|
||||
|
||||
They are measured, not guessed: 100 of the released NPC on both frameworks, on a 6000 map, as what
|
||||
they add to the median server frame of the same session's empty server. Beside them is Rust's own
|
||||
scientist, measured the same day.
|
||||
|
||||
| 100 NPCs, over an empty server | RunicNPC on Oxide | RunicNPC on Carbon | Rust's scientist (Oxide / Carbon) |
|
||||
|---|---|---|---|
|
||||
| Idle, a player near enough to keep them awake | +2.7 to +2.9 ms | +1.5 ms | +1.0 / +1.0 ms |
|
||||
| Idle, asleep with nobody within 160 m | — | +0.5 ms | — |
|
||||
| Fighting 20 players | +7.2 ms | +9.0 ms | +7.5 / +8.0 ms |
|
||||
|
||||
**Fighting costs what Rust's own AI costs.** The warning uses the worst figure in each row,
|
||||
rounded up: 3 ms awake, 0.5 ms asleep and 9 ms fighting, per 100. The awake figure on Oxide is
|
||||
higher than it should be, and is being worked on in
|
||||
[runicnpc-rust#13](https://gitea.whitlocktech.com/RunicGateway/runicnpc-rust/issues/13). Your
|
||||
server's own figures depend on its CPU, its map and its players.
|
||||
|
||||
## Caps
|
||||
|
||||
To cap them anyway, set any of these in `config/RunicNPC.json` (Carbon: `configs/RunicNPC.json`)
|
||||
and reload RunicNPC. Every cap is 0, meaning none, until you set it.
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Key</th><th>What it limits</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(runicnpcConfig).map(([key, what]) => (
|
||||
<tr key={key}><td><code>{key}</code></td><td><Ticks text={what} /></td></tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
These keys are checked against the plugin's own source on every build.
|
||||
|
||||
**A spawn over a cap is refused, naming the cap**, whether it came from `/rnpc`, the site, an
|
||||
event step or another plugin.
|
||||
|
||||
**The bridge has its own bound too.** On a Runic Gateway server, `EventsMaxNpcs` in the bridge
|
||||
plugin's [RunicGateway.json](/docs/rust/runicgateway-json/) limits how many NPCs one event step may
|
||||
place — whatever RunicNPC's caps allow.
|
||||
75
src/content/docs/docs/rust/runicnpc/index.mdx
Normal file
75
src/content/docs/docs/rust/runicnpc/index.mdx
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: RunicNPC
|
||||
description: Runic Gateway's own NPC plugin for Rust — what it is, how it works with and without a Runic Gateway site, and where each page about it fits.
|
||||
---
|
||||
|
||||
import platform from '../../../../../data/platform.json';
|
||||
|
||||
**RunicNPC** is an NPC plugin for Rust, on Oxide and Carbon, written by this project. It puts
|
||||
NPCs where you want them, with the kit, health, aim, ranges and behaviour you give them, and
|
||||
brings them back after they die. It is one file, `RunicNPC.cs`, compiled by the framework from
|
||||
source like any uMod plugin.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Release** | {platform.releases['runicnpc-rust']}, from [`runicnpc-rust`](https://gitea.whitlocktech.com/RunicGateway/runicnpc-rust/releases) |
|
||||
| **API version** | {platform.runicnpc.api} |
|
||||
| **Runs on** | Oxide {platform.runicnpc.oxideMin} or Carbon {platform.runicnpc.carbonMin}, or newer |
|
||||
| **Needs** | {platform.runicnpc.requiresPlugins.join(' and ')}. ZoneManager is optional, for holding NPCs inside a zone |
|
||||
|
||||
## Two ways to run it
|
||||
|
||||
**On its own.** RunicNPC runs on any Rust server, with no Runic Gateway site anywhere. You place
|
||||
NPCs in game with `/rnpc`, edit their profiles at the console, and other plugins drive it through
|
||||
its [API](/docs/rust/runicnpc/api/). Nothing on this page beyond this section is needed to use it
|
||||
that way.
|
||||
|
||||
**On a Runic Gateway server.** There it is **required**, and installed with the bridge from the
|
||||
same bundle. Every NPC an event places is RunicNPC's, Rust's own scientists included. The site
|
||||
then owns the NPC **profiles** and the **faction table**, and pushes them to each server; the
|
||||
console commands that would edit them are refused with "managed by its website". **Placements
|
||||
stay the server's**: they are made in game or from the site's map, and both see the same list.
|
||||
|
||||
## What it is made of
|
||||
|
||||
- **A profile** is a named description of an NPC: its names and kits, its role, how it moves, how
|
||||
hard it is, whom it fights, and optionally a boss's phases, what pressing E on it does, and its
|
||||
own loot. See [Profile fields](/docs/rust/runicnpc/profile-fields/).
|
||||
- **A placement** is a spot where a profile's NPCs stand and come back after they die. It is saved
|
||||
on the server and survives restarts. **The NPCs themselves are never saved**: at boot, each
|
||||
placement spawns fresh ones.
|
||||
- **A route** is a line of points, recorded in game, that an NPC walks.
|
||||
- **An owner.** Every NPC has one, and the owner decides how long it lives: a placement, an event
|
||||
run, or another plugin. An event's NPCs go when the event is torn down, and another plugin's go
|
||||
when it unloads.
|
||||
|
||||
**The roles.** A *roamer* moves, chases and fights. A *sentry* stands still and shoots. A *guard*
|
||||
holds its spot, chases within its leash and walks back. A *passive* NPC never fights, and pressing
|
||||
E on it says a line or opens a window — a quest-giver or a quartermaster. Any role but passive can
|
||||
be a **boss**: a health bar at the top of the screen, phases as its health falls, and lines said
|
||||
in game.
|
||||
|
||||
**Factions.** With no faction settings an NPC fights players only. Profiles can be put on sides,
|
||||
made hostile to Rust’s scientists or animals, or to each other; through the API, one NPC can
|
||||
also be allied to a clan, a team or a player, and defend what they own.
|
||||
|
||||
**On a Runic Gateway site** RunicNPC's NPCs also show up elsewhere: their names in a server’s
|
||||
[feed](/docs/rust/), NPC kills on the leaderboard, bosses and event NPCs on the
|
||||
[live map](/docs/rust/the-live-map/), and a step's "3 of 8 left" on a running event's page. An
|
||||
event places them with its *Place NPCs* step and can wait on them dying or on a boss's health; see
|
||||
[Events, zones and rewards](/docs/rust/events-zones-and-rewards/).
|
||||
|
||||
**It never phones home.** RunicNPC makes no network call, downloads nothing and scans nothing at
|
||||
boot.
|
||||
|
||||
## In this group
|
||||
|
||||
| Page | Read it when |
|
||||
|---|---|
|
||||
| [Install RunicNPC](/docs/rust/runicnpc/install/) | Putting it on a server, with or without Runic Gateway, and after a Rust update |
|
||||
| [Commands](/docs/rust/runicnpc/commands/) | Placing NPCs and recording routes in game, and the console |
|
||||
| [NPC profiles](/docs/rust/runicnpc/npc-profiles/) | Authoring profiles and the faction table on the site |
|
||||
| [NPC placements](/docs/rust/runicnpc/npc-placements/) | Placing NPCs from the site's map |
|
||||
| [Cost and caps](/docs/rust/runicnpc/cost-and-caps/) | Knowing what NPCs cost a server, and capping them |
|
||||
| [Profile fields](/docs/rust/runicnpc/profile-fields/) | Every field of a profile, for the editor, the console and the API alike |
|
||||
| [The API](/docs/rust/runicnpc/api/) | Writing a plugin that spawns, orders or listens to RunicNPC's NPCs |
|
||||
115
src/content/docs/docs/rust/runicnpc/install.mdx
Normal file
115
src/content/docs/docs/rust/runicnpc/install.mdx
Normal file
@@ -0,0 +1,115 @@
|
||||
---
|
||||
title: Install RunicNPC
|
||||
description: Putting RunicNPC on a Rust server — from the Runic Gateway bundle, or by hand on a server with no site — its files, and what to check after a Rust update.
|
||||
---
|
||||
|
||||
import { Aside, Code } from '@astrojs/starlight/components';
|
||||
import platform from '../../../../../data/platform.json';
|
||||
|
||||
## What it needs
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Oxide {platform.runicnpc.oxideMin} or Carbon {platform.runicnpc.carbonMin}**, or newer | The builds it is known good on. Its release manifest states them, and the installer checks them |
|
||||
| **[Kits](https://umod.org/plugins/kits)** | **Required.** A profile equips its NPCs with Kits kits, and RunicNPC declares `// Requires: Kits`, so neither framework loads it without Kits |
|
||||
| **[ZoneManager](https://umod.org/plugins/zone-manager)** | Optional. Only holding NPCs inside a zone uses it |
|
||||
|
||||
**Kits and ZoneManager are reported, never installed.** The installer's `doctor` says when either
|
||||
is missing; you install them from uMod.
|
||||
|
||||
<Aside type="caution" title="Do not reload Kits while an event runs">
|
||||
RunicNPC requires Kits, so both frameworks reload RunicNPC whenever Kits reloads, and every NPC it
|
||||
had spawned is gone. Placements come back on their own; an event's NPCs do not.
|
||||
</Aside>
|
||||
|
||||
## On a Runic Gateway server
|
||||
|
||||
There is nothing to do by hand. RunicNPC is part of the Rust bundle — {platform.games.rust.bundle.tag}
|
||||
carries RunicNPC {platform.games.rust.bundle.runicnpc} — beside the bridge plugin and the sidecar,
|
||||
and it arrives the way they do. See [Install the bridge](/docs/rust/install-the-bridge/).
|
||||
|
||||
- **The installer** places `RunicNPC.cs` beside the bridge plugin, checked against the bundle's
|
||||
checksum, and refuses a bundle without it. `doctor --game rust` **fails** when RunicNPC is
|
||||
missing, and warns when the file was edited by hand. `uninstall` removes `RunicNPC.cs` and keeps
|
||||
its data.
|
||||
- **The Pterodactyl egg** places it the same way on every install and reinstall.
|
||||
|
||||
Once the server has started, **Admin → Rust servers** shows it as complete. A server without
|
||||
RunicNPC, or with one older than the bridge needs, reads *Incomplete* with the reason, and every
|
||||
*Place NPCs* step on it is refused. **Admin → Rust NPC profiles** lists each server's RunicNPC
|
||||
version and API.
|
||||
|
||||
**The first push adopts what the server had.** When the site first pushes profiles to a server,
|
||||
the profiles that server already had become site profiles for that server alone, so nothing on it
|
||||
changes. See [NPC profiles](/docs/rust/runicnpc/npc-profiles/).
|
||||
|
||||
## Without Runic Gateway
|
||||
|
||||
1. Download `runicnpc-<version>.tar.gz` and `SHA256SUMS` from the
|
||||
[releases page](https://gitea.whitlocktech.com/RunicGateway/runicnpc-rust/releases), and check
|
||||
the tarball: `sha256sum -c SHA256SUMS`.
|
||||
2. Install Kits from uMod if the server does not have it.
|
||||
3. Copy `runicnpc/RunicNPC.cs` from the tarball into `oxide/plugins/` or `carbon/plugins/`. The
|
||||
framework compiles and loads it at once.
|
||||
4. At the server console, run `rnpc.status`. It should say `navmesh=ready` — a fresh map builds
|
||||
its navmesh for several minutes after its first boot — and `swap fields: … missing=- added=-`.
|
||||
5. Grant `runicnpc.place` or `runicnpc.admin` to whoever places NPCs, then `/rnpc place raider`
|
||||
where you look.
|
||||
|
||||
**It comes with examples.** On its first load RunicNPC writes four example kits into Kits' data
|
||||
file — `rnpc_raider`, `rnpc_campguard`, `rnpc_sniper` and `rnpc_juggernaut`, each where its name is
|
||||
free and each behind a Kits permission nobody is granted, so no player can claim one. On a server
|
||||
no site manages it also adds four example profiles: a raider, a camp guard, a sniper and the
|
||||
Juggernaut, a boss. It then reloads Kits once so the new kits are known. **Nothing is written
|
||||
again**, even if you delete them.
|
||||
|
||||
<Aside type="caution" title="Do not create RunicNPC's data folder yourself">
|
||||
RunicNPC makes `data/RunicNPC/` on its first load. One made from outside the game — a panel's
|
||||
file manager, for example — may not be writable by the game.
|
||||
</Aside>
|
||||
|
||||
## Its files
|
||||
|
||||
Under `oxide/`, or `carbon/` on Carbon.
|
||||
|
||||
| File | What it holds | Who writes it |
|
||||
|---|---|---|
|
||||
| `plugins/RunicNPC.cs` | The plugin | The installer, the egg, or you |
|
||||
| `config/RunicNPC.json` (Carbon: `configs/`) | The caps and the spawn budget — see [Cost and caps](/docs/rust/runicnpc/cost-and-caps/) | You |
|
||||
| `data/RunicNPC/profiles.json` | The profiles and the faction table, and whether a site manages them | The site, on a Runic Gateway server; otherwise `rnpc.profile` and `rnpc.faction` |
|
||||
| `data/RunicNPC/placements.json` | The placements | `/rnpc`, the API, and the site's map |
|
||||
| `data/RunicNPC/routes.json` | The recorded routes | `/rnpc path` |
|
||||
| `data/RunicNPC/state.json` | Its own bookkeeping: whether the examples were written | RunicNPC |
|
||||
|
||||
After editing `profiles.json` or `routes.json` by hand, run `rnpc.reload`.
|
||||
|
||||
## After a Rust update
|
||||
|
||||
Rust's monthly update can change the scientist RunicNPC is built on. After it:
|
||||
|
||||
1. **Wait for the navmesh.** `rnpc.status` says `navmesh=building` while Rust rebuilds it, about
|
||||
ten minutes on a large map. Placements wait, and spawn when it is ready; a spawn through the
|
||||
API is refused until then.
|
||||
2. **Check the swap.** The `swap fields` line should end `missing=- added=-`. Anything else means
|
||||
Rust's scientist has changed since this RunicNPC was released: update RunicNPC. On a Runic
|
||||
Gateway server, `update --game rust` or an egg reinstall takes the current bundle.
|
||||
3. **Check the hooks.** `rnpc.status` names any hook that has never fired as `silent`. One that
|
||||
stays silent long after players have been on is the first sign Rust renamed it, because
|
||||
neither framework reports a hook that matches nothing.
|
||||
|
||||
In the week before each monthly forced wipe, every new Rust staging build is tried against
|
||||
RunicNPC, so a release that needs fixing is usually out before the update is.
|
||||
|
||||
## Reading `rnpc.status`
|
||||
|
||||
<Code
|
||||
lang="text"
|
||||
code={[
|
||||
`RunicNPC ${platform.releases['runicnpc-rust'].replace(/^v/, '')} api=${platform.runicnpc.api} hooks=12 fired=12 silent=0`,
|
||||
'framework=oxide navmesh=ready swap fields: npc=55/55 brain=32/32 missing=- added=-',
|
||||
'npcs=14 awake=9 goingHome=0 asleep=5 owners: placement:bandit-1=3 run:42=11',
|
||||
].join('\n')}
|
||||
/>
|
||||
|
||||
The rest of its answer lists the profiles it refuses and why, the placements waiting and why, the
|
||||
faction pairs, the caps, and the [cost warning](/docs/rust/runicnpc/cost-and-caps/).
|
||||
68
src/content/docs/docs/rust/runicnpc/npc-placements.mdx
Normal file
68
src/content/docs/docs/rust/runicnpc/npc-placements.mdx
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: NPC placements
|
||||
description: Placing RunicNPC's NPCs from the site's live map — how a click becomes a placement, and editing, renaming, respawning and removing what is already placed.
|
||||
---
|
||||
|
||||
**Admin → Rust NPC placements** shows one server's RunicNPC placements on its live map, and
|
||||
places new ones where you click. **Placements live on the server**, not on the site: an admin's
|
||||
`/rnpc place` in game and this screen edit the same list, and both see each other's at once. So
|
||||
every read and write here is a live round trip to the game, and a server that is down has nothing
|
||||
to show.
|
||||
|
||||
A server appears in the **Server** list once its RunicNPC can take placements from the site. If
|
||||
none can yet, the screen says why for each.
|
||||
|
||||
## Placing NPCs
|
||||
|
||||
**Click the map where they should stand.** The site sends the point — a spot on the map, with no
|
||||
height — and the server does the rest, exactly as `/rnpc place` would:
|
||||
|
||||
- it **puts the point on the ground**, by a ray down onto terrain and rock — never a building or a
|
||||
tree;
|
||||
- it **checks the spot against Rust's navmesh**, and refuses a roamer's spot that is off it, with
|
||||
how far off it is;
|
||||
- it refuses a point off the map or under water;
|
||||
- it **names the placement** after its profile and the first free number, `raider-3`.
|
||||
|
||||
The form under the map takes what `/rnpc place` takes:
|
||||
|
||||
| Field | Means |
|
||||
|---|---|
|
||||
| **Profile** | The profiles this server is pushed — see [NPC profiles](/docs/rust/runicnpc/npc-profiles/) |
|
||||
| **How many** | How many NPCs stand there; all but the first are scattered within 3 m |
|
||||
| **Respawn (s)** | Seconds after a death before an NPC comes back |
|
||||
| **Come back** | *each*, after its own death, or *together*, once all are dead |
|
||||
| **Movement** | The profile's own, `wander`, `monument`, or one of the server's recorded routes. Not shown for a sentry |
|
||||
| **Radius (m)** | How far a wanderer strays |
|
||||
| **Keep inside zone** | A ZoneManager zone its NPCs never leave. The server refuses a zone it does not have, or one that does not hold the spot |
|
||||
|
||||
**The answer** says the placement's name, where it landed and how high, and the
|
||||
[cost warning](/docs/rust/runicnpc/cost-and-caps/) for the NPCs the server will then have. If the
|
||||
spot is on something players built, it says so: if that is destroyed, the NPCs stand on the
|
||||
nearest navmesh until it is rebuilt.
|
||||
|
||||
**A roof or the top of a building is placed in game.** The map only knows the ground; stand on
|
||||
the roof and use `/rnpc place` or `/rnpc here`.
|
||||
|
||||
## What is already placed
|
||||
|
||||
Each placement is a pin on the map — yellow, or grey while it waits — and a row in **Placements**:
|
||||
its name, how many of which profile, how many are alive, the respawn, the movement, its zone and
|
||||
where it is. Above the list is the cost warning for everything this server runs now.
|
||||
|
||||
| Button | Does |
|
||||
|---|---|
|
||||
| **Edit** | Change any of the form's fields. Its NPCs are removed and spawn again from the new values |
|
||||
| **Rename** | Give it a new name. Its live NPCs keep living under it |
|
||||
| **Respawn** | Remove its NPCs and spawn them again at once |
|
||||
| **Remove** | Remove the placement and its NPCs, after a second click to confirm |
|
||||
|
||||
**A placement can wait.** Its row says why in red — *profile 'guard' is missing*, for example,
|
||||
because the profile was deleted or is no longer pushed to this server; or its route or zone has
|
||||
gone; or the map's navmesh is still being built after an update. A waiting placement spawns again
|
||||
by itself once the thing it waits for is back. A grey note under a row says its NPCs stand
|
||||
somewhere other than their spot because the ground there went; *Last spawn failed* gives the last
|
||||
error.
|
||||
|
||||
**Recording a route is done in game**, with `/rnpc path` — see
|
||||
[Commands](/docs/rust/runicnpc/commands/#routes). Once saved, it is offered in **Movement** here.
|
||||
110
src/content/docs/docs/rust/runicnpc/npc-profiles.mdx
Normal file
110
src/content/docs/docs/rust/runicnpc/npc-profiles.mdx
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: NPC profiles
|
||||
description: Authoring RunicNPC's profiles and faction table on the site — which servers each profile is for, how the site pushes them, what the first push adopts, and the editor's sections.
|
||||
---
|
||||
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
**Admin → Rust NPC profiles** is where a Runic Gateway site authors RunicNPC's profiles. There is
|
||||
no in-game profile editor: on a server a site manages, the profiles and the faction table are the
|
||||
site's, and the console commands that would change them are refused. Where NPCs stand is a
|
||||
separate question, answered on [NPC placements](/docs/rust/runicnpc/npc-placements/), in game with
|
||||
`/rnpc place`, or by an event's *Place NPCs* step.
|
||||
|
||||
The screen has four parts: the servers, the profiles, the faction table, and — once there are
|
||||
any — the profiles a first push replaced.
|
||||
|
||||
## Servers
|
||||
|
||||
One row per Rust server: its RunicNPC version and API, and when the site last pushed to it, or
|
||||
why the last push failed. A server without RunicNPC, or with one too old to be managed, shows the
|
||||
reason instead and is left alone; its events keep Rust's own scientists.
|
||||
|
||||
**The site pushes on its own.** Every half-minute it asks each server whether it needs a push —
|
||||
the first one, a change to its set, a restart, a failure worth retrying, or a quarter-hourly
|
||||
audit — and pushes only then. A saved profile reaches each server within about half a minute.
|
||||
**Push now** does it at once, and says what happened: how many profiles went, what was adopted,
|
||||
and any RunicNPC refused, with the reason.
|
||||
|
||||
**A refusal shows under its server.** A push replaces the server's whole set, and RunicNPC keeps
|
||||
every profile it can accept: one it refuses — a kit that server lacks, say — is listed under the
|
||||
server in red, and the rest are in use at once.
|
||||
|
||||
## The first push adopts what the server had
|
||||
|
||||
A server that ran RunicNPC before the site managed it already has profiles, and placements that
|
||||
use them. So **before the first push, the site reads that server's own profiles and imports them
|
||||
as profiles for that server alone**, then pushes them back. Nothing on the server changes, and its
|
||||
placements keep spawning. An adopted profile says *adopted from* its server in the list.
|
||||
|
||||
Where a site profile of the same name already covered that server, the site's wins, and the
|
||||
server's own is kept under **Replaced**, with **Restore** to put it back in use on its server and
|
||||
**Delete** to drop it.
|
||||
|
||||
## Profiles
|
||||
|
||||
Each row shows a profile's label and RunicNPC name, the servers it is for, its role, whether it is
|
||||
a boss or has its own loot, its health, kits and movement, and how its kills count. **New profile**
|
||||
and **Edit** open the editor below the list.
|
||||
|
||||
### Which servers
|
||||
|
||||
A profile is for **every server** — including servers added later — or for the ones ticked. Each
|
||||
server is pushed only the profiles that cover it, so two servers can each have a different
|
||||
`warden`.
|
||||
|
||||
### The editor
|
||||
|
||||
**Name** is RunicNPC's name for the profile — 1 to 40 of a-z, 0-9, `_` and `-` — and what
|
||||
`/rnpc place` and an event step use. The rest is in sections, each a group of
|
||||
[profile fields](/docs/rust/runicnpc/profile-fields/), which says what every field does and its
|
||||
limits:
|
||||
|
||||
| Section | What it sets | Shown |
|
||||
|---|---|---|
|
||||
| **Looks** | Names, kits, prefab and role | Always |
|
||||
| **Moving** | How it moves, its wander radius, and when it sleeps | Not for a sentry, which never moves |
|
||||
| **Fighting** | Health, damage dealt and taken, aim, vision, ranges, and the health thresholds an event can wait for | Always |
|
||||
| **Press E** | A line in the player's chat, or a window | A passive profile only |
|
||||
| **Boss** | The health bar, the lines said in game, and the phases | Any role but passive |
|
||||
| **Loot** | What the corpse starts with, the rows always rolled, the pool, and the crate | Always; off keeps Rust's scientist loot |
|
||||
| **Sides** | Faction, its own exceptions, alert radius, turrets, and whether players and it can hurt each other | Always |
|
||||
| **The kit's extras** | Healing, grenades, melee, rockets and the flamethrower | Always |
|
||||
|
||||
**Choosing *Passive* changes two other fields** for you: it stops players hurting the NPC and
|
||||
makes it stand where it is placed. Choosing another role again sets them back.
|
||||
|
||||
**The editor speaks in friendlier units than the file.** Health thresholds, a loot row's chance
|
||||
and a phase's *At health* are percentages here, and a locked crate's hack time is in minutes; the
|
||||
file and the API hold fractions and seconds. The site converts both ways.
|
||||
|
||||
**Kits are checked when you save.** Every server the profile is for that answers is asked for
|
||||
its kits, and a kit any of them lacks refuses the save, naming the server and the kit. A server
|
||||
that does not answer is left to RunicNPC, which refuses the profile there at the next push.
|
||||
|
||||
**Kills count** is the site's, not RunicNPC's: how the leaderboard and chat titles count this
|
||||
profile's kills.
|
||||
|
||||
| Choice | Counts |
|
||||
|---|---|
|
||||
| **Per server** (the default) | Kills of this name on the server a leaderboard is for |
|
||||
| **Every server with this name** | Kills of this name on every server |
|
||||
| **This profile only** | Kills of this profile only, on whichever servers it is pushed to |
|
||||
|
||||
**Delete profile** removes it from every server it covered at the next push. Placements that use
|
||||
it **wait** rather than vanish, and spawn again if a profile of that name comes back.
|
||||
|
||||
## The faction table
|
||||
|
||||
How factions treat each other, for the whole site, pushed to every server with the profiles. One
|
||||
row is both ways: *bandits ↔ guards: hostile* makes each hunt the other. A pair that is not listed
|
||||
is neutral, and a faction is always allied to itself. `scientists` and `animals` are Rust's own; a
|
||||
profile hostile to scientists fights them, and they only take cover. A profile's own exceptions,
|
||||
set in its **Sides**, win over the table.
|
||||
|
||||
<Aside title="Fighting NPCs is opt-in">
|
||||
With no faction settings, a profile fights players only. Fighting Rust's scientists, animals or
|
||||
other profiles costs about what fighting players does — see
|
||||
[Cost and caps](/docs/rust/runicnpc/cost-and-caps/) — and an NPC only fights what comes within its
|
||||
chase range of its spot: it never walks into a monument to look for scientists.
|
||||
</Aside>
|
||||
152
src/content/docs/docs/rust/runicnpc/profile-fields.mdx
Normal file
152
src/content/docs/docs/rust/runicnpc/profile-fields.mdx
Normal file
@@ -0,0 +1,152 @@
|
||||
---
|
||||
title: Profile fields
|
||||
description: Every field of a RunicNPC profile, by its JSON path — the same path the site's editor, rnpc.profile set, the data file and the API all use — with its limits and what it does.
|
||||
---
|
||||
|
||||
import Ticks from '../../../../../components/Ticks.astro';
|
||||
import { runicnpcProfileFields } from '../../../../../data/runicnpc.mjs';
|
||||
|
||||
export const Fields = ({ group }) => (
|
||||
<table>
|
||||
<thead><tr><th>Field</th><th>On the site</th><th>Allowed</th><th>What it does</th></tr></thead>
|
||||
<tbody>
|
||||
{Object.entries(runicnpcProfileFields[group]).map(([path, f]) => (
|
||||
<tr key={path}>
|
||||
<td><code>{path}</code></td>
|
||||
<td>{f.site ?? <em>not in the editor</em>}</td>
|
||||
<td><Ticks text={f.rule} /></td>
|
||||
<td><Ticks text={f.meaning} /></td>
|
||||
</tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
);
|
||||
|
||||
A profile is a named description of an NPC. Its fields are the same wherever a profile is
|
||||
written, so this one page serves all four places:
|
||||
|
||||
- **The site's [profile editor](/docs/rust/runicnpc/npc-profiles/)**, whose sections this page
|
||||
follows, and whose label for each field is in the second column.
|
||||
- **The console**, where `rnpc.profile set <name> <field> <value>` takes the path in the first
|
||||
column: `rnpc.profile set warden ranges.sense 40`.
|
||||
- **The data file**, `data/RunicNPC/profiles.json`, on a server no site manages.
|
||||
- **[The API](/docs/rust/runicnpc/api/)**: `RunicNpc_SetProfiles` takes profiles in this shape,
|
||||
and `RunicNpc_Spawn`'s overrides change any of these fields for one NPC.
|
||||
|
||||
The paths are checked against the API's specification on every build. **The site's editor shows
|
||||
some values in friendlier units**: health thresholds, a loot row's chance and a phase's health as
|
||||
percentages, and the hack time in minutes. Everywhere else they are fractions and seconds.
|
||||
|
||||
**A profile is checked whole when it is saved.** A kit the server does not have refuses the
|
||||
profile then, not when an NPC spawns; a refused profile is kept, and listed with its reason, but
|
||||
never spawns.
|
||||
|
||||
## Looks
|
||||
|
||||
<Fields group="Looks" />
|
||||
|
||||
## Moving
|
||||
|
||||
<Fields group="Moving" />
|
||||
|
||||
## Fighting
|
||||
|
||||
<Fields group="Fighting" />
|
||||
|
||||
## Press E
|
||||
|
||||
<Fields group="Press E" />
|
||||
|
||||
A passive profile, as it looks in the file:
|
||||
|
||||
```json
|
||||
{
|
||||
"names": ["Quartermaster"], "kits": ["outpost_clothes"], "role": "passive",
|
||||
"movement": { "mode": "stand", "radius": 0 },
|
||||
"hurtByPlayers": false,
|
||||
"use": { "mode": "chat", "lines": ["Back again, {player}?", "Supplies are short."], "title": "", "text": "" }
|
||||
}
|
||||
```
|
||||
|
||||
## Boss
|
||||
|
||||
<Fields group="Boss" />
|
||||
|
||||
A boss gives no reward of its own. On a Runic Gateway server, an event's reward steps do, and can
|
||||
name everyone who hurt it.
|
||||
|
||||
## Loot
|
||||
|
||||
<Fields group="Loot" />
|
||||
|
||||
## Sides
|
||||
|
||||
<Fields group="Sides" />
|
||||
|
||||
**Whom it fights besides players** is decided by its own senses: only factions it is hostile to,
|
||||
within its sense range of itself and its chase range of its spot, so it never walks into a
|
||||
monument to look for scientists. Rust's scientists never fight back, by Rust's own rule; they take
|
||||
cover. Whoever shoots one of RunicNPC's NPCs, it fights back, whatever the table says.
|
||||
|
||||
## The kit's extras
|
||||
|
||||
<Fields group="The kit’s extras" />
|
||||
|
||||
## A whole profile
|
||||
|
||||
A roamer that is also a boss, with its own loot, as it looks in the file and through the API:
|
||||
|
||||
```json
|
||||
{
|
||||
"names": ["Warden", "Old Warden"],
|
||||
"kits": ["warden_rifle", "warden_smg"],
|
||||
"prefab": "scientistnpc_roam",
|
||||
"role": "roamer",
|
||||
"movement": { "mode": "wander", "radius": 20 },
|
||||
"health": 250,
|
||||
"damageDealt": 1.0,
|
||||
"damageTaken": { "head": 1.0, "body": 1.0, "legs": 1.0 },
|
||||
"aimCone": 2.0,
|
||||
"ranges": { "sense": 30, "loseTarget": 40, "chase": 40, "attack": 30 },
|
||||
"visionCone": -0.8,
|
||||
"sleepDistance": 160,
|
||||
"healthThresholds": [0.5],
|
||||
"faction": "bandits",
|
||||
"relations": { "scientists": "hostile" },
|
||||
"alertRadius": 40,
|
||||
"turrets": "default",
|
||||
"hurtByPlayers": true,
|
||||
"hurtsPlayers": true,
|
||||
"kitUse": { "heal": false, "grenades": false, "melee": false, "rockets": false, "flamethrower": false },
|
||||
"boss": {
|
||||
"barDistance": 100,
|
||||
"announce": "chat",
|
||||
"spawnLine": "{name} has risen!",
|
||||
"deathLine": "{name} has fallen to {killer}.",
|
||||
"phases": [
|
||||
{ "at": 0.5, "adds": { "profile": "raider", "count": 3 }, "line": "{name} calls for help!" },
|
||||
{ "at": 0.25, "damageDealt": 1.5, "speed": 1.3, "kit": "warden_heavy", "line": "{name} is enraged!" }
|
||||
]
|
||||
},
|
||||
"use": null,
|
||||
"loot": {
|
||||
"start": "rust",
|
||||
"always": [
|
||||
{ "item": "scrap", "min": 100, "max": 300, "chance": 1 },
|
||||
{ "item": "rope", "min": 1, "max": 1, "chance": 0.5 }
|
||||
],
|
||||
"pool": {
|
||||
"pick": 1,
|
||||
"nothing": 85,
|
||||
"rows": [
|
||||
{ "item": "lmg.m249", "min": 1, "max": 1, "weight": 10 },
|
||||
{ "item": "explosive.timed", "min": 1, "max": 1, "weight": 5 }
|
||||
]
|
||||
},
|
||||
"crate": "locked",
|
||||
"hackSeconds": 600,
|
||||
"corpseSeconds": 0,
|
||||
"dropTable": true
|
||||
}
|
||||
}
|
||||
```
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user