wtclaude
f41ff92c67
The book, written out of the tree slice 1 proved. Four chapters in the order the
work happens: the first module in twenty minutes, the website module, the sidecar,
and the game-side plugin.
Shape, settled with the org lead:
* template/README.md stays the REFERENCE — it travels with a copied template and
CI holds it against the tree — and chapter 1 is the narration: what you should
see after each step, the state your module lands in, and the four ways it fails.
The chapter links to the checklist rather than restating it.
* chapters 3 and 4 cite link/ and servuo-plugins/ by FILE AND IDENTIFIER, never by
line. Those repositories move for their own reasons and checkLinks already
forbids commit permalinks, so a line number in this book is wrong the moment
they do. The template stays the only code quoted verbatim.
* one PR: the outline's status table and the link check are only coherent when the
whole set lands.
scripts/checkChapterPaths.js is the anti-rot half a machine can answer: every path
a chapter names in backticks must exist. None of those mentions is a markdown link,
so checkLinks never looked at them, and none is code, so nothing else did either —
renaming one template file would have left four chapters quietly pointing at
nothing. Its anchor list is STATED rather than derived from the tree, for the reason
the template's own build guard states it: a list derived from what exists cannot
fail when what exists changes, and an anchor that stops matching is a check that has
silently stopped checking. So each anchor must exist or the check fails. Eleven
tests, every "must not catch" case a span that really appears in the book.
stripFences moved to scripts/lib/markdown.js and both checks use it — shared code,
not a shared description.
CHAPTER 1 WAS RUN, NOT REASONED ABOUT. The template was copied into a real core on
edge, booted against the dev database, and every claim in "what you should see"
checked: the five log lines, /examplegame/status with its injected
<script type="module" src="/modules/examplegame/entry.js">, the chunk served
no-cache while module.json 404s, /api/v1/public/world/status, the capabilities in
/api/v1/public/modules, and the route in the merged /api/docs.json. Then the three
failures the chapter tells a reader to cause on purpose, because a chapter that
predicts the wrong debugging heuristic is worse than one that predicts none:
* an undeclared prefix -> stage `register`, "declared public/extra but never
registered it", routes 404 and absent from /public/modules;
* a table without the id prefix -> stage `schema`, at LOAD time, before mounting;
* a throwing onBoot -> after mounting, so the same route answers 503 "Module
unavailable" rather than vanishing.
All three came out exactly as written, and the messages in the chapter are that
core's own. Two small corrections fell out of the run: the log sample now shows the
real interleaving of core's three lines with the module's two, and the section on
failure adds that a module disappears from /api/v1/public/modules in every failure
case — a check that needs no login.
MODULE_SYSTEM.md 2.11.1 slice 2. Docs half: docs#146.
Co-Authored-By: Claude <noreply@anthropic.com>
186 lines
9.5 KiB
Markdown
186 lines
9.5 KiB
Markdown
# 3. The sidecar
|
|
|
|
Your module may not open a connection to a game server. Not a game socket, not an
|
|
RCON channel, not a query port, not an engine's admin API. It talks to a
|
|
**sidecar**, and the sidecar talks to the game.
|
|
|
|
That is a rule in the contract ([`MODULE_API.md`][api] §2.7, as of
|
|
`MODULE_API_VERSION` 1.4.0) rather than advice this kit is offering. It is also
|
|
the rule most likely to feel like ceremony when your game already exposes a
|
|
perfectly good remote-control protocol and your module is fifty lines from
|
|
working. This chapter is why it is not.
|
|
|
|
**It is the one rule in that list with no CI behind it.** An outbound socket is
|
|
not statically detectable the way an internal `require` is. So it is enforced by
|
|
review, and by you having read this.
|
|
|
|
---
|
|
|
|
## What a sidecar is
|
|
|
|
A small, separate service that owns the connection to your game, keeps a durable
|
|
copy of what the game said, and exposes an HTTP + WebSocket API that the website's
|
|
backend reads.
|
|
|
|
```
|
|
your game server ──dials out──▶ your sidecar ──HTTP + WS──▶ website core
|
|
│ (your module)
|
|
▼
|
|
its own store
|
|
```
|
|
|
|
Three properties, and each is doing real work.
|
|
|
|
## 1. The game dials out; the sidecar listens
|
|
|
|
The sidecar binds the listener. The game connects **to it**, and the game opens no
|
|
listening port at all.
|
|
|
|
This is the inversion people find surprising and it is the load-bearing one. The
|
|
website is the internet-facing process; your game is not, and must not become
|
|
reachable because a web app knows how to reach it. A module holding the connection
|
|
makes the public web app the thing the game trusts, and puts the game's address
|
|
inside the same process as every request from the internet.
|
|
|
|
In `uo-link`, that listener is `sidecar/src/shard.rs` — `serve` binds a loopback
|
|
address and accepts shard connections forever, handling one at a time and looping
|
|
back to accept the next. The game plugin does the dialling, with its own backoff.
|
|
Loopback, in that deployment, because the sidecar runs on the game host: the only
|
|
socket the game speaks over never leaves the machine.
|
|
|
|
Only the website's backend talks to the sidecar, and it authenticates. `uo-link`'s
|
|
`web.rs` requires a token on every request — accepted as a bearer header, an API-key
|
|
header, or a query parameter, that last one only because browser WebSocket clients
|
|
cannot set handshake headers — and compares it in constant time. Auth is always on;
|
|
there is no unauthenticated mode to accidentally deploy.
|
|
|
|
## 2. Persist before you forward
|
|
|
|
This is the property that makes a sidecar worth having even when your game is
|
|
already remote-controllable, and the one a message-passing diagram never conveys.
|
|
|
|
**The sidecar owns the durable copy.** It writes what the game said into its own
|
|
store, and answers reads from that store — not by round-tripping the game.
|
|
|
|
`uo-link` does this in `sidecar/src/store.rs`: SQLite, holding event history, the
|
|
latest snapshot of every board the site renders, the economy series and the
|
|
published ruleset. `insert_event` is called for every live event as it is
|
|
broadcast; the `upsert_*` functions keep one current row per board; the REST read
|
|
paths query that store.
|
|
|
|
What it buys, concretely:
|
|
|
|
- **A website that is down, restarting or mid-deploy loses nothing.** Events that
|
|
arrive while nothing is listening are still recorded. Without a store they are
|
|
simply gone, and your first deploy of the week is a hole in your data.
|
|
- **A page renders the last thing the game said rather than going blank.** A rules
|
|
page that empties itself because the game restarted is worse than a stale one.
|
|
- **The live feed is allowed to be lossy.** `uo-link`'s WebSocket fan-out drops
|
|
frames for a consumer that has fallen behind and logs that it did — deliberately,
|
|
because durability is the store's job and not the socket's. A feed that instead
|
|
buffered without limit for a slow client would eventually take the sidecar down.
|
|
|
|
That last point is the reasoning to carry into your own design. Once the store is
|
|
authoritative, every other component is allowed to be best-effort, and each of them
|
|
gets simpler. Skip the store and you find yourself trying to make a socket reliable,
|
|
which is the hard version of this problem.
|
|
|
|
A module cannot do any of this from inside the website process. There is nowhere to
|
|
put what arrives while the website is not running, because the website not running
|
|
is exactly the case.
|
|
|
|
## 3. The wire is a versioned contract, not a build dependency
|
|
|
|
Your sidecar and your module ship separately, on different schedules, to hosts you
|
|
do not control. So the wire between them is a compatibility contract with a version
|
|
on it.
|
|
|
|
`uo-link` declares `PROTOCOL_VERSION` in `sidecar/src/main.rs`, stamps
|
|
`X-UOLink-Version` onto every response from `web.rs`, and **refuses a request whose
|
|
declared version does not match** rather than parsing it optimistically. A refusal
|
|
is a clear failure an operator can act on; a mis-parse is a wrong number on a page
|
|
with nobody to tell.
|
|
|
|
Two habits come with that:
|
|
|
|
- **Bump the version in the same change that changes a message shape**, on every
|
|
side that declares it. In this project a protocol bump has three declaration
|
|
sites — the sidecar, the game-side overlay's manifest, and the documented spec —
|
|
and the tooling refuses to pair components that disagree.
|
|
- **Version the *shape*, not the content.** Adding a new event kind that old
|
|
consumers ignore is not a break. Changing what a field means is, even when the
|
|
JSON still parses.
|
|
|
|
## The worked example
|
|
|
|
`uo-link` is a complete implementation of everything above, and it is small enough
|
|
to read:
|
|
|
|
| File | What it owns |
|
|
| --- | --- |
|
|
| `sidecar/src/shard.rs` | The listener the game dials into; one connection at a time, then accept the next. |
|
|
| `sidecar/src/store.rs` | SQLite: event history, per-board snapshots, the series and the ruleset. |
|
|
| `sidecar/src/web.rs` | HTTP + WebSocket for the website, the auth middleware, the version header and the lossy live fan-out. |
|
|
| `sidecar/src/rpc.rs` | Request/reply correlation, so a website read can ask the game a question and match the answer. |
|
|
| `sidecar/src/config.rs` | The config file, including a token generated on first run rather than defaulted. |
|
|
|
|
The protocol it speaks is specified in [`link/PLAN.md`][linkplan] and
|
|
[`link/INTEGRATION.md`][linkint]. Those are normative for that sidecar; your game
|
|
is not Ultima Online and your messages will not be its messages. What transfers is
|
|
the structure — a listener the game dials into, a store written before anything is
|
|
forwarded, a lossy live feed, an authenticated read API with a version on it.
|
|
|
|
## "But my game already speaks a remote-control protocol"
|
|
|
|
Then your sidecar is **thin**, not absent.
|
|
|
|
Rust — the survival game — is the worked example here, in
|
|
[`rust-dryrun.md`][dryrun]: a module designed on paper for a game chosen for how
|
|
little it shares with Ultima Online. Rust ships RCON over WebSocket, so a
|
|
`rust-link` has no protocol to invent and no game-side plugin to write at all. It
|
|
keeps:
|
|
|
|
- the RCON connection, its credentials and its reconnect loop, **out of an Express
|
|
process** — where the failure mode is a wedged request handler;
|
|
- a store, so the site is not blank whenever the game is restarting, which for that
|
|
genre is a daily scheduled event;
|
|
- an HTTP + WS API with a version on it, so the module talks to one shape of thing
|
|
regardless of what the game speaks.
|
|
|
|
It drops the bespoke wire protocol and the plugin. That is what "thin" means: less
|
|
code, not a different architecture.
|
|
|
|
That document originally concluded the opposite — "no sidecar, the module dials
|
|
RCON directly" — and it carries a dated correction saying so, rather than having
|
|
been quietly rewritten. The value of a dry run is the record of what it found,
|
|
including where it was overruled.
|
|
|
|
## Building yours
|
|
|
|
There is no template for a sidecar in this kit; it is your program, in your
|
|
language, and the surface it must expose is the surface your module reads. What to
|
|
settle before writing code:
|
|
|
|
1. **Which direction does the connection go?** The game dials out. If your game
|
|
cannot — if it only accepts connections — then your sidecar is the client to the
|
|
game and the listener for the website, and the rule that stands is the one that
|
|
matters: the address of the game is known to the sidecar and to nothing else.
|
|
2. **What is durable?** Everything a page must still render when the game is down.
|
|
Write it before you forward it.
|
|
3. **What is a snapshot and what is an event?** They are different storage
|
|
problems: an event is appended and read back as history, a board is one current
|
|
row per subject that you overwrite. `uo-link`'s store holds both, and keeping
|
|
them separate is why a restart does not replay a year of events at a page.
|
|
4. **What is the version, and where is it declared?** One place, on every response,
|
|
refused on mismatch.
|
|
5. **How does the website authenticate?** A token, generated rather than defaulted,
|
|
always required.
|
|
|
|
Then chapter 4, if your game needs code inside it — which is the part where getting
|
|
it wrong takes the game down rather than the website.
|
|
|
|
[api]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md
|
|
[linkplan]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md
|
|
[linkint]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md
|
|
[dryrun]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust-dryrun.md
|