fix: stop dropping tokio runtimes inside the async context

CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - **data plane**: the headers a browser sends unasked reach the upstream without being declared: `referer`, the `sec-fetch-*` set, the `sec-ch-ua*` client hints, `dnt`, `sec-gpc` and `priority`. They describe the request rather than the caller, which is why `user-agent`, `accept-language` and `origin` were already in the baseline. The fetch-metadata set is the one that mattered: an upstream uses it to reject cross-site requests, so dropping it silently removed a defence the upstream believed it had. It also made `serve --dev` unusable, naming eight headers on every browser request that no operation should ever declare, which buried the ones an author had to act on.
+- **data plane**: `barbacane serve` exits 0 on `SIGTERM` instead of panicking and exiting 101. The plugin host builds a NATS publisher, a Kafka publisher and an LDAP client whatever the artifact contains, each carrying its own tokio runtime, and dropping a runtime inside an async context is a panic. Every clean shutdown therefore looked like a crash to a supervisor: restart backoff, crash-loop counters and alerts fired on an ordinary stop. The same panic fired when startup failed after the artifact loaded, for instance on a taken port, burying the real cause and making a configuration error indistinguishable from a crash by exit code.
+- **compiler**: `compile` resolves a URL-sourced plugin instead of panicking. `reqwest::blocking` refuses to run inside a tokio runtime, on construction and on every request, and `compile` runs inside one, so a manifest with a remote plugin could not be compiled at all from a dev-profile build. The download now runs on a thread of its own.
 
 ## [0.11.0] - 2026-09-17
 

crates/barbacane-compiler/Cargo.toml

@@ -32,6 +32,8 @@ workspace = true
 
 [dev-dependencies]
 tempfile = { workspace = true }
+# `compile` runs inside a runtime; the download tests reproduce that context.
+tokio = { workspace = true }
 criterion = { workspace = true }
 serde_json = { workspace = true }
 # Proves a parsed schema is usable by the data plane's validator, which builds

crates/barbacane-compiler/src/download.rs

@@ -23,14 +23,44 @@ pub struct DownloadResult {
     pub plugin_toml: Option<String>,
 }
 
-/// Build a blocking HTTP client with appropriate defaults.
-fn build_client() -> Result<reqwest::blocking::Client, CompileError> {
-    reqwest::blocking::Client::builder()
-        .connect_timeout(Duration::from_secs(30))
-        .timeout(Duration::from_secs(120))
-        .user_agent(format!("barbacane-compiler/{}", env!("CARGO_PKG_VERSION")))
-        .build()
-        .map_err(|e| CompileError::PluginResolution(format!("failed to build HTTP client: {e}")))
+/// The blocking HTTP client used for every plugin download.
+///
+/// Built once and never dropped. A blocking client owns a tokio runtime, and
+/// `compile` runs inside one, where dropping a runtime is a panic in tokio.
+/// Keeping it in a `OnceLock` means the process never drops it, and downloads
+/// reuse one connection pool rather than building a client each time.
+static CLIENT: std::sync::OnceLock<Result<reqwest::blocking::Client, String>> =
+    std::sync::OnceLock::new();
+
+/// The shared blocking HTTP client.
+///
+/// Built on a plain thread, once, and never dropped. `compile` runs inside a
+/// tokio runtime, and a blocking client both creates and drops a temporary
+/// runtime while being constructed, which tokio refuses to do inside an async
+/// context. A thread of our own has no such context. Storing the result means
+/// the cost is paid once and downloads share one connection pool.
+fn client() -> Result<&'static reqwest::blocking::Client, CompileError> {
+    CLIENT
+        .get_or_init(|| {
+            std::thread::Builder::new()
+                .name("barbacane-http-init".into())
+                .spawn(|| {
+                    reqwest::blocking::Client::builder()
+                        .connect_timeout(Duration::from_secs(30))
+                        .timeout(Duration::from_secs(120))
+                        .user_agent(format!("barbacane-compiler/{}", env!("CARGO_PKG_VERSION")))
+                        .build()
+                        .map_err(|e| format!("failed to build HTTP client: {e}"))
+                })
+                .map_err(|e| format!("failed to start the HTTP client thread: {e}"))
+                .and_then(|h| {
+                    h.join()
+                        .map_err(|_| "the HTTP client thread panicked".to_string())
+                })
+                .and_then(|r| r)
+        })
+        .as_ref()
+        .map_err(|e| CompileError::PluginResolution(e.clone()))
 }
 
 /// Derive candidate plugin.toml URLs from a .wasm URL.
@@ -56,13 +86,27 @@ fn derive_plugin_toml_urls(wasm_url: &str) -> Vec<String> {
 /// Fetches the .wasm binary and attempts to fetch `plugin.toml` from
 /// the same directory (best-effort — 404 is fine).
 pub fn download_plugin(url: &str) -> Result<DownloadResult, CompileError> {
+    // `reqwest::blocking` refuses to run inside a tokio runtime, on construction
+    // and on every request, and `compile` runs inside one. A scoped thread has
+    // no async context and can still borrow `url`.
+    std::thread::scope(
+        |scope| match scope.spawn(|| download_plugin_blocking(url)).join() {
+            Ok(result) => result,
+            Err(_) => Err(CompileError::PluginResolution(format!(
+                "the download thread panicked fetching {url}"
+            ))),
+        },
+    )
+}
+
+fn download_plugin_blocking(url: &str) -> Result<DownloadResult, CompileError> {
     if !url.starts_with("https://") {
         return Err(CompileError::PluginResolution(format!(
             "plugin URL must use HTTPS: {url}"
         )));
     }
 
-    let client = build_client()?;
+    let client = client()?;
 
     tracing::info!(url, "downloading remote plugin");
 
@@ -164,3 +208,54 @@ mod tests {
         );
     }
 }
+
+#[cfg(test)]
+mod runtime_context_tests {
+    use super::*;
+
+    /// `compile` runs inside a tokio runtime, and `reqwest::blocking` refuses
+    /// to run inside one, on construction and on every request alike. A
+    /// manifest with a remote plugin could not be compiled at all because of
+    /// it. The call must reach the network and come back with an error, not
+    /// take the process down.
+    #[test]
+    fn downloading_from_inside_a_runtime_returns_an_error_rather_than_panicking() {
+        let rt = tokio::runtime::Builder::new_multi_thread()
+            .worker_threads(1)
+            .enable_all()
+            .build()
+            .expect("runtime");
+
+        let result = rt.block_on(async {
+            // A reserved domain that resolves nowhere, so the request fails
+            // fast without depending on the network being reachable.
+            download_plugin("https://barbacane-does-not-resolve.invalid/plugin.wasm")
+        });
+
+        assert!(
+            result.is_err(),
+            "the download should fail, not succeed against an invalid host"
+        );
+    }
+
+    /// The same from a spawned task, which is a worker thread rather than the
+    /// one `block_on` runs on.
+    #[test]
+    fn downloading_from_a_spawned_task_returns_an_error_rather_than_panicking() {
+        let rt = tokio::runtime::Builder::new_multi_thread()
+            .worker_threads(2)
+            .enable_all()
+            .build()
+            .expect("runtime");
+
+        let result = rt.block_on(async {
+            tokio::spawn(async {
+                download_plugin("https://barbacane-does-not-resolve.invalid/plugin.wasm")
+            })
+            .await
+            .expect("the task must not panic")
+        });
+
+        assert!(result.is_err());
+    }
+}

crates/barbacane-test/Cargo.toml

@@ -8,6 +8,8 @@ license.workspace = true
 publish = false
 
 [dependencies]
+# Sending a real SIGTERM in the process-lifecycle test.
+libc = "0.2"
 barbacane-compiler = { workspace = true }
 tokio = { workspace = true }
 reqwest = { workspace = true }

crates/barbacane-test/tests/process_lifecycle.rs

@@ -0,0 +1,194 @@
+//! The gateway as a process: does it start, serve, and stop cleanly?
+//!
+//! Every other test drives the gateway in-process, so nothing started the real
+//! binary, signalled it and looked at its exit code. That is how a panic on
+//! every graceful shutdown reached a release: the drain was correct, only the
+//! exit code lied about it, and a supervisor reads a non-zero exit as a crash.
+//!
+//! The cause was a runtime dropped inside the async context. The plugin host
+//! owns broker and directory clients that each carry one, so the panic fired
+//! whatever the artifact contained.
+
+use std::process::{Command, Stdio};
+use std::time::{Duration, Instant};
+
+/// The gateway binary built alongside these tests.
+///
+/// A test executable lives at `target/<profile>/deps/<name>-<hash>`, so the
+/// gateway is two levels up: one pop drops the file name, the second drops
+/// `deps`.
+fn gateway_binary() -> std::path::PathBuf {
+    let mut dir = std::env::current_exe().expect("test binary path");
+    dir.pop(); // the test executable's own file name
+    dir.pop(); // deps/
+    dir.join("barbacane")
+}
+
+/// The smallest artifact the repository can build: one mock route.
+///
+/// Returns the reason it could not, never a bare `None`: a test that skips
+/// without saying so reads as a pass, and `cargo test` hides the output of one.
+fn build_artifact(dir: &std::path::Path) -> Result<std::path::PathBuf, String> {
+    let repo = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .and_then(std::path::Path::parent)
+        .ok_or("the repository root is not two levels above the crate")?
+        .to_path_buf();
+    let mock = repo.join("plugins/mock/mock.wasm");
+    if !mock.exists() {
+        return Err(format!(
+            "{} is not built; run `make plugins`",
+            mock.display()
+        ));
+    }
+
+    let manifest = dir.join("barbacane.yaml");
+    std::fs::write(
+        &manifest,
+        format!("plugins:\n  mock:\n    path: {}\n", mock.display()),
+    )
+    .map_err(|e| format!("could not write the manifest: {e}"))?;
+
+    let spec = dir.join("api.yaml");
+    std::fs::write(
+        &spec,
+        r#"openapi: "3.0.3"
+info: { title: lifecycle, version: "1.0.0" }
+paths:
+  /ping:
+    get:
+      operationId: ping
+      x-barbacane-dispatch: { name: mock, config: { status: 200, body: "pong" } }
+      responses: { "200": { description: ok } }
+"#,
+    )
+    .map_err(|e| format!("could not write the spec: {e}"))?;
+
+    let out = dir.join("api.bca");
+    let status = Command::new(gateway_binary())
+        .args(["compile", "-s"])
+        .arg(&spec)
+        .arg("-m")
+        .arg(&manifest)
+        .arg("-o")
+        .arg(&out)
+        .output()
+        .map_err(|e| format!("could not run the compiler: {e}"))?;
+    if !status.status.success() {
+        return Err(format!(
+            "compiling the fixture failed: {}",
+            String::from_utf8_lossy(&status.stderr)
+        ));
+    }
+    Ok(out)
+}
+
+fn wait_for_port(port: u16, limit: Duration) -> bool {
+    let deadline = Instant::now() + limit;
+    while Instant::now() < deadline {
+        if std::net::TcpStream::connect(("127.0.0.1", port)).is_ok() {
+            return true;
+        }
+        std::thread::sleep(Duration::from_millis(100));
+    }
+    false
+}
+
+/// SIGTERM on a healthy gateway must drain and exit 0. A non-zero exit is how
+/// a supervisor decides the process crashed, so a clean stop that exits 101
+/// produces restart backoff, crash-loop counters and alerts on every deploy.
+#[test]
+fn sigterm_on_a_serving_gateway_exits_zero() {
+    let binary = gateway_binary();
+    assert!(
+        binary.exists(),
+        "{} is not built. Every test in this crate drives the real binary, so a \
+         missing one is a broken run, not a reason to pass quietly",
+        binary.display()
+    );
+    let dir = tempfile::tempdir().expect("temp dir");
+    let artifact = build_artifact(dir.path()).expect("build the fixture artifact");
+
+    let mut child = Command::new(&binary)
+        .arg("serve")
+        .arg("--artifact")
+        .arg(&artifact)
+        .args(["--listen", "127.0.0.1:34201"])
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .expect("spawn the gateway");
+
+    assert!(
+        wait_for_port(34201, Duration::from_secs(30)),
+        "the gateway never accepted a connection"
+    );
+
+    unsafe {
+        libc::kill(child.id() as i32, libc::SIGTERM);
+    }
+
+    let deadline = Instant::now() + Duration::from_secs(30);
+    let status = loop {
+        match child.try_wait().expect("wait") {
+            Some(status) => break status,
+            None if Instant::now() > deadline => {
+                let _ = child.kill();
+                panic!("the gateway did not exit within 30s of SIGTERM");
+            }
+            None => std::thread::sleep(Duration::from_millis(100)),
+        }
+    };
+
+    let mut stderr = String::new();
+    if let Some(mut e) = child.stderr.take() {
+        use std::io::Read;
+        let _ = e.read_to_string(&mut stderr);
+    }
+
+    assert!(
+        !stderr.contains("panicked"),
+        "the gateway panicked while shutting down:\n{stderr}"
+    );
+    assert_eq!(
+        status.code(),
+        Some(0),
+        "SIGTERM must exit 0, got {status:?}\nstderr:\n{stderr}"
+    );
+}
+
+/// A taken port is a configuration error. It must report the cause and exit
+/// non-zero without panicking, so a misconfiguration stays distinguishable
+/// from a crash.
+#[test]
+fn a_taken_port_reports_the_cause_without_panicking() {
+    let binary = gateway_binary();
+    if !binary.exists() {
+        return;
+    }
+    let dir = tempfile::tempdir().expect("temp dir");
+    let artifact = build_artifact(dir.path()).expect("build the fixture artifact");
+
+    let held = std::net::TcpListener::bind("127.0.0.1:34202").expect("hold the port");
+
+    let output = Command::new(&binary)
+        .arg("serve")
+        .arg("--artifact")
+        .arg(&artifact)
+        .args(["--listen", "127.0.0.1:34202"])
+        .output()
+        .expect("run the gateway");
+
+    drop(held);
+
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("failed to bind"),
+        "the real cause must be reported:\n{stderr}"
+    );
+    assert!(
+        !stderr.contains("panicked"),
+        "a taken port is a configuration error, not a panic:\n{stderr}"
+    );
+    assert_eq!(output.status.code(), Some(1), "stderr:\n{stderr}");
+}