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,147 @@
+//! # openfut-blaze-host
+//!
+//! A deliberately thin TCP host for the FIFA 17 Blaze RPC surface.
+//!
+//! ```text
+//!   listener  →  Fire2 stream framing  →  per-connection Session
+//!                                              │
+//!                                    openfut-adapter-fifa17::dispatch
+//!                                              │
+//!                                    write returned frames, in order
+//! ```
+//!
+//! ## What it owns
+//!
+//! A socket, a read buffer, one `Session` per connection, and diagnostics.
+//! That is the complete list.
+//!
+//! ## What it must never acquire
+//!
+//! Coins, club state, packs, profiles, market state, UTAS logic. Those belong
+//! to OpenFUT Core, reached later through the adapter. A transport host that
+//! starts holding game state becomes a second backend, which is exactly the
+//! architecture this migration exists to avoid.
+//!
+//! ## No TLS
+//!
+//! The Blaze main port is **plaintext**. Verified against the running Python
+//! backend by sending a raw Fire2 `Util::ping` and receiving a plaintext
+//! `PingResponse`; `blaze_responder_v3b.py::blaze_handle` uses the raw socket,
+//! and only `redir_handle` wraps `ssl`. TLS belongs to the redirector phase.
+//!
+//! ## Running beside Python, never instead of it
+//!
+//! The listen port is required configuration with no default, so this cannot
+//! silently collide with the working container. See the crate README for the
+//! A/B procedure and the gate list.
+
+pub mod config;
+pub mod conn;
+pub mod trace;
+
+pub use config::HostConfig;
+pub use conn::CloseReason;
+
+use std::io;
+use std::net::{SocketAddr, TcpListener};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+
+use openfut_adapter_fifa17::blaze::Adapter;
+
+/// The two values a live host reads from the outside world.
+///
+/// Injectable so a test can replay a recorded conversation byte-for-byte: the
+/// session key and the server clock appear inside response bodies, so with the
+/// real ones no live run could ever reproduce a fixture exactly. This is the
+/// only test seam in the crate, and it exists because the alternative is to
+/// verify transport *structurally only* and lose the byte-level guarantee.
+pub struct Hooks {
+    pub session_key: Box<dyn Fn() -> String + Send + Sync>,
+    pub now: Box<dyn Fn() -> i64 + Send + Sync>,
+}
+
+impl Default for Hooks {
+    fn default() -> Hooks {
+        Hooks {
+            session_key: Box::new(conn::mint_session_key),
+            now: Box::new(conn::unix_now),
+        }
+    }
+}
+
+impl std::fmt::Debug for Hooks {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str("Hooks { .. }")
+    }
+}
+
+/// A bound listener plus everything a connection needs.
+pub struct Server {
+    pub local_addr: SocketAddr,
+    listener: TcpListener,
+    cfg: Arc<HostConfig>,
+    adapter: Arc<Adapter>,
+    tracer: Arc<trace::Tracer>,
+    hooks: Arc<Hooks>,
+}
+
+/// Bind without accepting, so a caller can learn the real port first (useful
+/// when binding port 0).
+pub fn bind(cfg: HostConfig, hooks: Hooks) -> io::Result<Server> {
+    let listener = TcpListener::bind(cfg.listen_on())?;
+    let local_addr = listener.local_addr()?;
+    let tracer = Arc::new(trace::Tracer::new(cfg.trace_path.as_deref())?);
+    let adapter = Arc::new(Adapter::new(cfg.adapter.clone()));
+    Ok(Server {
+        local_addr,
+        listener,
+        cfg: Arc::new(cfg),
+        adapter,
+        tracer,
+        hooks: Arc::new(hooks),
+    })
+}
+
+impl Server {
+    /// Accept forever, one thread per connection.
+    ///
+    /// A FIFA client opens a handful of connections, so a thread each mirrors
+    /// the Python oracle and keeps the host readable; a work-stealing runtime
+    /// would be weight without benefit.
+    pub fn run(self) -> io::Result<()> {
+        trace::log(&format!(
+            "blaze-host listening on {} (advertise={}, config-bind={})",
+            self.local_addr, self.cfg.adapter.endpoints.advertise, self.cfg.adapter.endpoints.bind
+        ));
+        if self.tracer.enabled() {
+            trace::log(&format!(
+                "structural trace -> {}",
+                self.cfg.trace_path.as_deref().unwrap_or("")
+            ));
+        }
+
+        let counter = AtomicU64::new(0);
+        for incoming in self.listener.incoming() {
+            match incoming {
+                Ok(stream) => {
+                    let id = counter.fetch_add(1, Ordering::Relaxed) + 1;
+                    let cfg = self.cfg.clone();
+                    let adapter = self.adapter.clone();
+                    let tracer = self.tracer.clone();
+                    let hooks = self.hooks.clone();
+                    std::thread::spawn(move || {
+                        conn::handle(stream, id, &cfg, &adapter, &tracer, &hooks);
+                    });
+                }
+                Err(e) => trace::log(&format!("accept failed: {e}")),
+            }
+        }
+        Ok(())
+    }
+}
+
+/// Bind and serve until the process is killed.
+pub fn serve(cfg: HostConfig) -> io::Result<()> {
+    bind(cfg, Hooks::default())?.run()
+}