wtclaude
6fb063818a
This file is the ancestor of installer's release.yml, and installer#22's
release run found two gaps in it the hard way: the run built every artifact,
pushed its tag, then took a 500 from POST /releases one second later and exited
22, leaving the tag orphaned with no binaries published.
link has not hit that, but it has the same two gaps verbatim.
`curl -sSf` prints no response body on an error status, so the only thing such
a failure leaves in the log is "curl: (22) ... error: 500" and the cause has to
be inferred from timestamps. Every call in the release step now captures the
body and prints it on failure, including the asset uploads.
And nothing retried, so a transient 5xx becomes a permanent orphan. The POST
now retries five times with a 5/10/15/20s backoff. 4xx is deliberately not
retried: a bad token or a malformed body will not improve by being sent again,
and retrying would turn a clear failure into a slow one.
The asset uploads get the same treatment, because a release whose SHA256SUMS
does not cover every binary it advertises is worse than no release -- that file
is the trust anchor for an unsigned download.
The third gap is the one worth reading. The orphan-tag recovery in the plan
step is VERSION-SCOPED: it computes VERSION from the newest tag plus the bump,
then only checks refs/tags/v${VERSION}. That recovers an orphan on the very
next run and is useless afterwards, because once any releasable commit lands
the next run computes a NEW version and never looks at the old tag again.
servuo-plugins v0.1.0 proves it, and the proof is pointed: the commit that
ADDED that recovery was itself typed "fix(release): ... recover the orphaned
v0.1.0 tag", so it bumped to v0.1.1 and the run that introduced the recovery
stepped straight past the tag it was written to rescue. That tag is orphaned to
this day.
So the plan step now sweeps every v* tag and warns about any without a release.
Deliberately warns rather than recovers: publishing an old version would mean
building today's tree and shipping it under a tag whose tree it is not, which
is worse than the inconsistency it fixes. It also never fails the run -- a
sweep that can break a good release is a sweep someone will delete.
Verified by extracting both steps from the YAML and running them: bash -n
clean, the YAML parses, no empty template token in either step, the retry loop
exercised against a stubbed curl across seven cases (first-try success,
500-then-success, two 500s then success, five 500s giving up, 403 and 404
aborting without retrying, and a 000 network failure retried), and the sweep
run against the real repositories -- link clean, servuo-plugins reporting
v0.1.0, installer clean.
Typed ci(...) rather than fix(...) on purpose: the plan step bumps on feat/fix,
and this changes no binary, so a release here would be an empty one. That is
the same rule the fix commit above tripped over.
Co-Authored-By: Claude <noreply@anthropic.com>
uo-link — Rust sidecar
The Rust sidecar half of the Runic Gateway bridge. The ServUO shard dials out to this sidecar over a loopback TCP socket (newline-delimited JSON); the sidecar owns the WebSocket + REST API the website consumes, along with auth, buffering, and fan-out.
ServUO plugin (C#, net48) ──loopback TCP, newline-JSON──► Rust sidecar ──WebSocket/JSON──► website
(RunicGateway/servuo-plugins) >>> THIS REPO <<<
The shard never speaks WebSocket and exposes no port of its own — the sidecar is the only network-facing component, which is what keeps the game unreachable from the internet.
Running a shard? Don't build this
The Runic Gateway installer installs this sidecar for you — the released binary, its config, a hardened service account and the service registration — alongside the shard plugin, in one run, on Linux or Windows:
sudo ./runicgateway-installer-linux-x86_64 install
It ends by printing the base URL, WebSocket URL, protocol version and auth token to paste into Admin → Shard on your site. Guide: installer/INSTALL.md.
Installing it yourself is supported too — the release binaries on this repo's releases page are the same ones the installer fetches, and INSTALL.md Appendix A3–A4 covers placing the binary and registering the service by hand.
Everything below this line is for developing on the sidecar.
Related repos
| Repo | What |
|---|---|
this — RunicGateway/link |
The Rust sidecar (sidecar/). |
| RunicGateway/installer | The installer — deploys this sidecar and the plugin onto a shard host. The supported way to set one up. |
| RunicGateway/servuo-plugins | The C# ServUO plugin — the shard side of the bridge (overlay/, patches/, deploy.ps1, test scaffolding). |
| RunicGateway/docs | All project documentation — design docs, protocol spec, integration guide, research. |
Layout
| Path | What |
|---|---|
sidecar/ |
The Rust sidecar crate — terminates the loopback link to the shard, exposes WS + REST to the website. See sidecar/README.md. |
.gitea/workflows/pr-checks.yml |
Gates every PR into main on cargo fmt --check, cargo clippy -D warnings, and cargo test. |
.gitea/workflows/release.yml |
Builds + releases the sidecar binary (Linux + Windows) on every merge to main. |
Build & run (development)
Building from source is for working on the sidecar; a deployment gets its binary from a release, via the installer or by hand. The sidecar is a standard cargo crate:
cd sidecar
cargo build --release # binary at target/release/uo-link-sidecar
cp sidecar.toml.example sidecar.toml # then edit
cargo run --release
Deploying it by hand rather than developing on it: --config <PATH> names the config file (as does
$UOLINK_CONFIG), and --print-config prints the resolved settings — including the auth token
the website needs — as JSON, provisioning the config file on first run. That is the supported way
to read the token back; it is not meant to be scraped from the log.
uo-link-sidecar --print-config --config /etc/runicgateway/sidecar.toml
Running as a service
The same binary runs in the foreground and as a system service — there is no --service flag to
remember, because the process can tell how it was started.
- Linux/systemd supervises any foreground process, so the unit just runs the binary.
SIGTERM(whatsystemctl stopsends) andSIGINTboth unwind it cleanly; logs go to the journal. - Windows cannot. The service control manager only supervises a process that connects back to
it within ~30 seconds via
StartServiceCtrlDispatcher; a plain console program registered withsc.exe createis killed with error 1053 despite running perfectly. So on Windows the sidecar speaks that handshake: started by the SCM it runs as a service, started from a shell the connect fails withERROR_FAILED_SERVICE_CONTROLLER_CONNECTand it falls through to an ordinary foreground run. It reportsRunningonly once the shard port is bound and the store is open, and — having no console — logs touo-link-sidecar.<date>.logbeside its config, rolled daily.
Only the starting and stopping is platform-specific: src/app.rs is the entire sidecar and is
shared, while src/windows.rs and src/unix.rs do nothing but start it and tell it when to stop.
The Windows crates are declared under [target.'cfg(windows)'.dependencies], so Cargo neither
resolves nor builds them for a Linux target.
Registering the service is the installer's job; to do it by hand see INSTALL.md Appendix A4.
.gitea/workflows/release.yml cross-compiles Linux + Windows binaries and cuts a Gitea release on
every merge to main (conventional-commit versioning). See sidecar/README.md
for configuration and the wire protocol.
Before that, .gitea/workflows/pr-checks.yml runs the same gates on every pull request into main —
cargo fmt --check, cargo clippy --all-targets -- -D warnings, then cargo test --locked. Run them
locally before pushing and the PR will be green:
cd sidecar
cargo fmt # or --check to just report
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
Deployment & compatibility
The plugin (RunicGateway/servuo-plugins) and this sidecar are deployed together but built independently:
- The plugin is deployed as source into the ServUO server root and compiled by ServUO at boot — no build artifact, no CI build.
- The sidecar is a standalone Rust binary released from this repo.
The only coupling is the loopback JSON protocol (the shard dials 127.0.0.1). Compatibility is a
protocol concern, not a build-order one — keep the event/command catalog in sync across the two
repos. Canonical spec:
PLAN.md §5/§7 and
INTEGRATION.md.
Because a wedged or absent sidecar cannot stall the shard, either side can be deployed or restarted
independently.
License
Runic Gateway is free software, licensed under the GNU General Public License v3.0 or later — see LICENSE.md.
Copyright (C) 2026 Runic Gateway
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version. It is distributed WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
Contributions are welcome — please read CONTRIBUTING.md (note the AI-usage disclosure requirement) and our Code of Conduct. Report vulnerabilities privately per SECURITY.md.