feat(rust): --game rust, named instances, and schema-2 bundles (phase 18)

Module-rust phase 18, step 5 of docs/modules/rust/PLAN.md §34.2.7 (D146,
D148, D149, D153).

Bundles: ServUO is read at schema 2 from v2/servuo/ and lowered into the
schema-1 model. Schema 1 at the root is the fallback, so a pin from before
schema 2 still reproduces. Rust bundles are read from v2/rust/. v2 reads use
the contents API, because /raw/ is CDN-cached for six hours.

--game rust runs install, update, doctor and uninstall for Rust servers
(src/rustgame/):
- the framework is detected from its marker files, which were read off both
  rigs; both or neither is refused;
- --server-id names an instance: its own service (runicgateway-rust@<id>, or
  RunicGatewayRust-<id>), config, database and ports;
- the plugin config is written once, with ServerId and Port only. An existing
  one is never rewritten, and one naming another server refuses the run;
- each instance's sidecar.toml is written once with its ports and an absolute
  database path, and the sidecar generates the token into it;
- one binary per host. update moves every instance, and a replaced binary
  restarts all of them;
- doctor checks the plugin file hash, the plugin config's ServerId, the
  required uMod plugins (a warning), the service and /health, and passes when
  the plugin is connected;
- uninstall removes our plugin and keeps its config. --purge also removes the
  sidecar config and database. The last instance takes the binary, the
  template and the record, and the shared user only when no ServUO record
  remains.

service.rs takes the service name as a parameter internally. The ServUO
public API is unchanged.

Finding: Carbon 2.0.259's config.json has no folder keys, so carbon/plugins
and carbon/configs are what the installer uses. The plan expected a moved
directory to be readable there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY

src/rustgame/sidecar.rs

@@ -0,0 +1,290 @@
+//! One instance's rust-link sidecar: its config, and asking the installed binary about it.
+//!
+//! **The installer writes each instance's `sidecar.toml` itself, once.** ServUO's sidecar is one per
+//! host and its defaults are right as shipped; a Rust host runs several, and every one of them needs
+//! its own game port, web port and database, which no default can give it. So the first run writes
+//! the file with those three decided and the token blank, and `--print-config` then generates the
+//! token and saves it into that same file — the sidecar still owns the secret, exactly as for ServUO.
+//! An existing file is never rewritten: after the first run it is the operator's, and the ports it
+//! names are the ones recorded.
+//!
+//! The same rule as `crate::sidecar` holds for the token: it crosses one process boundary, here,
+//! and goes to the terminal and nowhere else.
+
+use std::path::Path;
+
+use anyhow::{bail, Context, Result};
+use serde::Deserialize;
+
+/// What `rust-link-sidecar --print-config` prints (Rust-Link `sidecar/src/config.rs::describe`).
+#[derive(Debug, Clone, Deserialize)]
+pub struct ConfigDoc {
+    pub component: String,
+    pub version: String,
+    pub protocol: u32,
+    pub config_path: String,
+    pub token_generated: bool,
+    pub game: GameDoc,
+    pub web: WebDoc,
+    pub store: StoreDoc,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct GameDoc {
+    pub bind: String,
+    #[serde(default)]
+    pub server_id: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct WebDoc {
+    pub bind: String,
+    /// **A secret.** Printed in the handoff and recorded nowhere.
+    pub auth_token: String,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct StoreDoc {
+    pub path: String,
+}
+
+/// The first `sidecar.toml` for an instance. Pure, so its content is a test.
+///
+/// Paths are TOML **literal** strings (single quotes): a Windows path is all backslashes, and a basic
+/// string would read each one as an escape. A literal string cannot hold a single quote, and neither
+/// a server id nor any path this installer builds contains one.
+pub fn instance_config(server_id: &str, game_port: u16, web_port: u16, db: &Path) -> String {
+    format!(
+        "# rust-link sidecar for Rust server {server_id:?}.\n\
+         #\n\
+         # Written once by the Runic Gateway installer, which decided the ports and the database\n\
+         # below; it is never rewritten, so it is yours to edit from here. The token is generated\n\
+         # by the sidecar on first start and saved into this file.\n\
+         \n\
+         [game]\n\
+         # Where the plugin dials in. Loopback: there is no token on this link.\n\
+         bind = '127.0.0.1:{game_port}'\n\
+         # Cross-checked against the serverId the plugin announces.\n\
+         server_id = '{server_id}'\n\
+         \n\
+         [web]\n\
+         # Where the website reaches this sidecar. Put a TLS proxy in front to reach it from\n\
+         # another machine (docs/rust-link/INSTALL.md).\n\
+         bind = '127.0.0.1:{web_port}'\n\
+         auth_token = \"\"\n\
+         \n\
+         [store]\n\
+         path = '{db}'\n",
+        db = db.display(),
+    )
+}
+
+/// Runs the installed binary's `--print-config` against one instance's config, provisioning the
+/// token on first use. **Must not print or attach the child's stdout** — it holds the token.
+pub fn print_config(binary: &Path, config: &Path) -> Result<ConfigDoc> {
+    let output = std::process::Command::new(binary)
+        .arg("--print-config")
+        .arg("--config")
+        .arg(config)
+        // An operator's shell may export RUSTLINK_* while testing; an installed instance is
+        // described by its file alone, so none of them may leak into this read.
+        .env_remove("RUSTLINK_CONFIG")
+        .env_remove("RUSTLINK_GAME_BIND")
+        .env_remove("RUSTLINK_WEB_BIND")
+        .env_remove("RUSTLINK_WEB_TOKEN")
+        .env_remove("RUSTLINK_DB_PATH")
+        .env_remove("RUSTLINK_SERVER_ID")
+        .output()
+        .with_context(|| {
+            format!(
+                "cannot run {} --print-config — the binary cannot execute here",
+                binary.display()
+            )
+        })?;
+    if !output.status.success() {
+        let reason = String::from_utf8_lossy(&output.stderr)
+            .lines()
+            .map(str::trim)
+            .find(|l| !l.is_empty())
+            .unwrap_or("(nothing on stderr)")
+            .to_string();
+        bail!(
+            "{} --print-config --config {} failed: {reason}",
+            binary.display(),
+            config.display()
+        );
+    }
+    let doc: ConfigDoc = serde_json::from_slice(&output.stdout).context(
+        "the rust-link sidecar's --print-config output is not the document this installer \
+         expects. It is not shown here because it contains the auth token.",
+    )?;
+    if doc.component != "rust-link-sidecar" {
+        bail!(
+            "the binary at {} identifies itself as {:?}, not rust-link-sidecar",
+            binary.display(),
+            doc.component
+        );
+    }
+    if doc.web.auth_token.trim().is_empty() {
+        bail!(
+            "the sidecar reported an empty auth token from {}; refusing to continue",
+            doc.config_path
+        );
+    }
+    Ok(doc)
+}
+
+/// The port half of a bind.
+pub fn port_of(bind: &str) -> Option<u16> {
+    bind.rsplit_once(':').and_then(|(_, p)| p.parse().ok())
+}
+
+/// The lowest port from `start` that no recorded instance holds and nothing on this host is bound
+/// to. `keep`, when given, is the port this instance already has, which is always kept.
+pub fn choose_port(start: u16, held: &[u16], keep: Option<u16>) -> Result<u16> {
+    if let Some(port) = keep {
+        return Ok(port);
+    }
+    (start..=u16::MAX)
+        .take(1000)
+        .find(|p| !held.contains(p) && std::net::TcpListener::bind(("127.0.0.1", *p)).is_ok())
+        .ok_or_else(|| anyhow::anyhow!("no free port found in the 1000 from {start}"))
+}
+
+/// The end-of-run block for one instance: what `/admin/rust/servers` asks for.
+pub fn handoff(
+    server_id: &str,
+    doc: &ConfigDoc,
+    host: &str,
+    site_url: Option<&str>,
+    registered: bool,
+) -> String {
+    let port = port_of(&doc.web.bind)
+        .map(|p| p.to_string())
+        .unwrap_or_else(|| doc.web.bind.clone());
+    let site = site_url
+        .map(|s| s.trim_end_matches('/').to_string())
+        .unwrap_or_else(|| "https://<your-site>".to_string());
+    let loopback = doc.web.bind.starts_with("127.") || doc.web.bind.starts_with("[::1]");
+    format!(
+        "\nRust server {server_id:?} is connected to its sidecar.\n\n\
+         One manual step remains — add it to the website:\n\n  \
+         Server id         {server_id}\n  \
+         Sidecar URL       http://{host}:{port}\n  \
+         Auth token        {token}\n                    \
+         (also in {config})\n  \
+         Protocol          {protocol}\n\n\
+         Add these at      {site}/admin/rust/servers\n{loopback_note}{service_note}",
+        token = doc.web.auth_token,
+        config = doc.config_path,
+        protocol = doc.protocol,
+        loopback_note = if loopback {
+            format!(
+                "\nThe sidecar listens on {} only. If the website runs on another machine, put a \
+                 TLS proxy in\nfront of it and give the site the proxy's URL \
+                 (docs/rust-link/INSTALL.md).\n",
+                doc.web.bind
+            )
+        } else {
+            String::new()
+        },
+        service_note = if registered {
+            ""
+        } else {
+            "\nNo service was registered, so nothing is listening yet — see the steps above.\n"
+        },
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn the_instance_config_parses_and_keeps_a_windows_path_intact() {
+        let db = Path::new(r"C:\ProgramData\RunicGateway\rust\alpha\rust-link.db");
+        let text = instance_config("alpha", 7800, 8091, db);
+        let value: toml_lite::Doc = toml_lite::parse(&text);
+        assert_eq!(value.get("game", "bind"), Some("127.0.0.1:7800"));
+        assert_eq!(value.get("game", "server_id"), Some("alpha"));
+        assert_eq!(value.get("web", "bind"), Some("127.0.0.1:8091"));
+        assert_eq!(value.get("web", "auth_token"), Some(""));
+        assert_eq!(
+            value.get("store", "path"),
+            Some(r"C:\ProgramData\RunicGateway\rust\alpha\rust-link.db")
+        );
+    }
+
+    #[test]
+    fn the_print_config_document_parses() {
+        // What Rust-Link v0.1.0 prints (sidecar/src/config.rs::describe).
+        let doc: ConfigDoc = serde_json::from_str(
+            r#"{ "component": "rust-link-sidecar", "version": "0.1.0", "protocol": 12,
+                 "config_path": "/etc/runicgateway/rust/alpha.toml", "config_created": false,
+                 "token_generated": true,
+                 "game": { "bind": "127.0.0.1:7800", "server_id": "alpha" },
+                 "web": { "bind": "127.0.0.1:8091", "ws_path": "/ws", "auth_required": true,
+                          "auth_token": "t0k" },
+                 "store": { "path": "/var/lib/runicgateway/rust/alpha/rust-link.db" } }"#,
+        )
+        .unwrap();
+        assert_eq!(port_of(&doc.web.bind), Some(8091));
+        let text = handoff("alpha", &doc, "rust.example", None, true);
+        for needle in [
+            "alpha",
+            "http://rust.example:8091",
+            "t0k",
+            "/admin/rust/servers",
+            "12",
+        ] {
+            assert!(text.contains(needle), "{needle} missing from:\n{text}");
+        }
+        assert!(text.contains("TLS proxy"), "{text}");
+    }
+
+    #[test]
+    fn a_held_port_is_skipped_and_a_kept_one_is_kept() {
+        let port = choose_port(47_990, &[47_990, 47_991], None).unwrap();
+        assert!(port >= 47_992);
+        assert_eq!(
+            choose_port(47_990, &[47_990], Some(47_990)).unwrap(),
+            47_990
+        );
+    }
+
+    /// Enough TOML to read back the file `instance_config` writes — `[section]` and
+    /// `key = 'literal'` / `key = "basic"` lines. The installer has no TOML dependency and this
+    /// test is the only reader it needs.
+    mod toml_lite {
+        pub struct Doc(Vec<(String, String, String)>);
+        impl Doc {
+            pub fn get(&self, section: &str, key: &str) -> Option<&str> {
+                self.0
+                    .iter()
+                    .find(|(s, k, _)| s == section && k == key)
+                    .map(|(_, _, v)| v.as_str())
+            }
+        }
+        pub fn parse(text: &str) -> Doc {
+            let mut section = String::new();
+            let mut out = Vec::new();
+            for line in text.lines().map(str::trim) {
+                if line.starts_with('#') || line.is_empty() {
+                    continue;
+                }
+                if let Some(name) = line.strip_prefix('[').and_then(|l| l.strip_suffix(']')) {
+                    section = name.to_string();
+                } else if let Some((k, v)) = line.split_once('=') {
+                    let v = v.trim();
+                    let v = v
+                        .strip_prefix('\'')
+                        .and_then(|v| v.strip_suffix('\''))
+                        .or_else(|| v.strip_prefix('"').and_then(|v| v.strip_suffix('"')))
+                        .unwrap_or(v);
+                    out.push((section.clone(), k.trim().to_string(), v.to_string()));
+                }
+            }
+            Doc(out)
+        }
+    }
+}