openfut-blaze-host: thin Blaze sidecar, live-parity with Python

Third migration step, and the one that turns fixture parity into transport parity. A TCP host that frames a Fire2 stream, keeps one Session per connection, calls openfut-adapter-fifa17::dispatch(), and writes the returned frames in order. It owns a socket, a buffer, a session and diagnostics -- that is the complete list. No coins, club, packs, profiles or UTAS logic: those belong to Core, reached through the adapter later. NO TLS, and that is evidence-based rather than an omission. The Blaze main port is plaintext: sending a raw Fire2 Util::ping to the running backend returns a plaintext PingResponse, blaze_handle uses the raw socket, and only redir_handle wraps ssl. TLS belongs to the redirector phase. LIVE A/B AGAINST THE RUNNING PYTHON BACKEND: 101 frames across three conversations, identical normalized traces. This is the first result in the migration that is not purely offline. check-live-parity.sh replays the recorded conversations against both endpoints over real sockets and diffs volatile-masked traces; session keys and clocks are masked, so anything that differs is behavioural. Transport tests cover what fixtures cannot: byte-for-byte replay over a socket, requests dribbled one byte at a time, several requests in one write, the four-frame login burst ordered on the wire, session state persisting across frames and NOT leaking between connections, an absurd payload length closing the connection instead of allocating, and an undecodable body still getting a reply. 18 tests here, 116 across the three migration crates. MUTATION TESTED, including the comparison itself. Dropping a post-login notification is caught by the probe (frame count) AND the diff; a same-length content change deep inside a notification body (CTY "US"->"GB", payload 116 both sides) is caught ONLY by the trace digest. So the probe's exit code is not the test -- the diff is, and the README says so. check-live-parity.sh was itself verified to exit 1 under mutation. The listen port is required configuration with no default, so the sidecar cannot silently collide with the working container. OPENFUT_BIND stays the advertised-config bind (the adapter derives nucleusConnect from it, reproducing the oracle) and the listener gets its own setting, so the two are not conflated. Gates 1-4 pass and are re-runnable. Gates 5-10 need a FIFA client and are listed in the README, including the Python -> Rust -> Python -> Rust back-and-forth that proves the rollback path rather than asserting it. Python backend untouched and still the live runtime; contract suite 446/446 after this work. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-11 01:42:23 +00:00
parent cf961603fe
commit a9eb54ae9c
11 changed files with 1847 additions and 0 deletions
@@ -0,0 +1,175 @@
+//! Host configuration, entirely from the environment.
+//!
+//! Two rules carried over from the Python deployment:
+//!
+//! * **No silent loopback.** `OPENFUT_ADVERTISE` is required, exactly as the
+//!   Python entrypoint requires it. A backend that guesses its own reachable
+//!   address is the bug the client/server split removed.
+//! * **No default port.** The sidecar runs beside the working Python container
+//!   and must never collide with it, so the listen port is explicit. There is
+//!   no "test port" constant anywhere in this crate.
+
+use std::env;
+use std::fmt;
+
+use openfut_adapter_fifa17::blaze::{AdapterConfig, Endpoints, Identity};
+
+#[derive(Debug)]
+pub struct ConfigError(String);
+
+impl fmt::Display for ConfigError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl std::error::Error for ConfigError {}
+
+#[derive(Debug, Clone)]
+pub struct HostConfig {
+    /// Address the listener binds.
+    pub listen_addr: String,
+    /// Port the listener binds. Required; no default.
+    pub listen_port: u16,
+    /// Seconds of inactivity before a connection is dropped. Matches the
+    /// oracle's 300s socket timeout.
+    pub idle_timeout_secs: u64,
+    /// Reject a frame claiming a larger payload than this, as the oracle does.
+    pub max_payload_bytes: u32,
+    /// Optional path for the normalized structural trace.
+    pub trace_path: Option<String>,
+    /// What the adapter answers with.
+    pub adapter: AdapterConfig,
+}
+
+fn required(key: &str, why: &str) -> Result<String, ConfigError> {
+    match env::var(key) {
+        Ok(v) if !v.trim().is_empty() => Ok(v),
+        _ => Err(ConfigError(format!("{key} must be set — {why}"))),
+    }
+}
+
+fn optional(key: &str, default: &str) -> String {
+    env::var(key)
+        .ok()
+        .filter(|v| !v.trim().is_empty())
+        .unwrap_or_else(|| default.to_string())
+}
+
+impl HostConfig {
+    pub fn from_env() -> Result<HostConfig, ConfigError> {
+        // The address handed to the CLIENT for every next hop.
+        let advertise = required(
+            "OPENFUT_ADVERTISE",
+            "it is the address the game machine uses to reach this host; \
+             there is no loopback fallback in remote mode",
+        )?;
+
+        // NOTE: this is the *advertised-config* bind, not the listener bind.
+        // The adapter derives nucleusConnect from it, reproducing the oracle
+        // (see the adapter's config docs and the vault's known-issue entry), so
+        // it must mirror whatever the Python container runs with if the two are
+        // to be compared. The listener has its own setting below.
+        let config_bind = optional("OPENFUT_BIND", "127.0.0.1");
+
+        let listen_port_raw = required(
+            "OPENFUT_BLAZE_HOST_PORT",
+            "the sidecar runs beside the working Python backend and must not \
+             collide with it, so the port is explicit and has no default",
+        )?;
+        let listen_port: u16 = listen_port_raw.trim().parse().map_err(|_| {
+            ConfigError(format!(
+                "OPENFUT_BLAZE_HOST_PORT is not a valid port: {listen_port_raw:?}"
+            ))
+        })?;
+
+        let listen_addr = optional("OPENFUT_BLAZE_HOST_BIND", &config_bind);
+
+        let endpoints = Endpoints {
+            advertise,
+            bind: config_bind,
+            pow_content_host: optional("POW_CONTENT_HOST", "127.0.0.1:8080"),
+            pow_host: optional("POW_HOST", "127.0.0.1:8094"),
+            ..Endpoints::default()
+        };
+
+        Ok(HostConfig {
+            listen_addr,
+            listen_port,
+            idle_timeout_secs: optional("OPENFUT_BLAZE_IDLE_TIMEOUT", "300")
+                .parse()
+                .unwrap_or(300),
+            max_payload_bytes: 4 * 1024 * 1024,
+            trace_path: env::var("OPENFUT_BLAZE_TRACE")
+                .ok()
+                .filter(|v| !v.trim().is_empty()),
+            adapter: AdapterConfig {
+                identity: Identity::default(),
+                endpoints,
+                server_version: AdapterConfig::default().server_version,
+            },
+        })
+    }
+
+    pub fn listen_on(&self) -> String {
+        format!("{}:{}", self.listen_addr, self.listen_port)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Env is process-global, so these run under one lock rather than as
+    /// separate tests that would race each other.
+    #[test]
+    fn env_contract() {
+        let keys = [
+            "OPENFUT_ADVERTISE",
+            "OPENFUT_BIND",
+            "OPENFUT_BLAZE_HOST_PORT",
+            "OPENFUT_BLAZE_HOST_BIND",
+        ];
+        let saved: Vec<_> = keys.iter().map(|k| (*k, env::var(k).ok())).collect();
+        for k in keys {
+            env::remove_var(k);
+        }
+
+        // Missing advertise is refused, not defaulted.
+        let err = HostConfig::from_env().unwrap_err().to_string();
+        assert!(err.contains("OPENFUT_ADVERTISE"), "{err}");
+
+        // Missing port is refused too — no default that could collide.
+        env::set_var("OPENFUT_ADVERTISE", "10.0.0.5");
+        let err = HostConfig::from_env().unwrap_err().to_string();
+        assert!(err.contains("OPENFUT_BLAZE_HOST_PORT"), "{err}");
+
+        // A non-numeric port is a clear error, not a silent fallback.
+        env::set_var("OPENFUT_BLAZE_HOST_PORT", "not-a-port");
+        let err = HostConfig::from_env().unwrap_err().to_string();
+        assert!(err.contains("not a valid port"), "{err}");
+
+        // Happy path: listener bind defaults to the config bind.
+        env::set_var("OPENFUT_BLAZE_HOST_PORT", "42230");
+        env::set_var("OPENFUT_BIND", "0.0.0.0");
+        let cfg = HostConfig::from_env().expect("configured");
+        assert_eq!(cfg.listen_on(), "0.0.0.0:42230");
+        assert_eq!(cfg.adapter.endpoints.advertise, "10.0.0.5");
+        // The adapter's nucleus URL follows the CONFIG bind, reproducing the
+        // oracle's behaviour rather than the listener's address.
+        assert_eq!(cfg.adapter.nucleus_base(), "http://0.0.0.0:42131");
+
+        // The listener bind can differ from the advertised-config bind.
+        env::set_var("OPENFUT_BLAZE_HOST_BIND", "127.0.0.1");
+        let cfg = HostConfig::from_env().expect("configured");
+        assert_eq!(cfg.listen_on(), "127.0.0.1:42230");
+        assert_eq!(cfg.adapter.nucleus_base(), "http://0.0.0.0:42131");
+
+        for (k, v) in saved {
+            match v {
+                Some(v) => env::set_var(k, v),
+                None => env::remove_var(k),
+            }
+        }
+    }
+}