eggfetch-ffi 0.2.2

Stable C ABI bindings for the eggfetch-core HTTP engine
Documentation
//! Tokio runtime management for FFI.

use std::sync::OnceLock;

use futures_util::FutureExt as _;
use tokio::runtime::Runtime;

static RUNTIME: OnceLock<Runtime> = OnceLock::new();

/// Try to get or initialize the global FFI runtime.
///
/// Returns `Error::Io` if `Runtime::new()` fails (fd exhaustion, memory)
/// instead of aborting the host process via `expect`.
pub(crate) fn try_ffi_runtime() -> eggfetch_core::Result<&'static Runtime> {
    if let Some(rt) = RUNTIME.get() {
        return Ok(rt);
    }
    // Create the runtime outside the `OnceLock` so failure does not poison it.
    let rt = Runtime::new().map_err(|e| {
        eggfetch_core::Error::Io(std::sync::Arc::new(std::io::Error::other(format!(
            "failed to create eggfetch-ffi tokio runtime: {e}"
        ))))
    })?;
    Ok(RUNTIME.get_or_init(|| rt))
}

/// Block on an async future, safe to call from any context (tokio or not).
///
/// If we are already inside a multi-thread tokio runtime (e.g. from
/// napi-rs), we use `block_in_place` to safely block the current worker
/// thread while driving the future on the runtime. In every other context
/// (no runtime, or a current-thread runtime where `block_in_place` would
/// panic) the future is spawned on the global FFI runtime and awaited
/// through a channel; the calling thread blocks on the channel while the
/// global runtime's workers make progress.
pub(crate) fn blocking_send<
    F: std::future::Future<Output = T> + Send + 'static,
    T: Send + 'static,
>(
    future: F,
) -> eggfetch_core::Result<T> {
    match tokio::runtime::Handle::try_current() {
        Ok(handle)
            if matches!(
                handle.runtime_flavor(),
                tokio::runtime::RuntimeFlavor::MultiThread
            ) =>
        {
            // We're inside a multi-thread tokio runtime (e.g. napi-rs
            // async executor). block_in_place converts the current worker
            // thread into a blocking context, allowing handle.block_on to
            // run the future.
            Ok(tokio::task::block_in_place(move || handle.block_on(future)))
        }
        _ => {
            // Not inside a multi-thread tokio runtime — either no runtime
            // at all or a current-thread runtime (drive the future on the
            // dedicated FFI runtime so the caller's single worker stays
            // responsive).
            let rt = try_ffi_runtime()?;
            let (tx, rx) = std::sync::mpsc::channel();
            rt.spawn(async move {
                // Preserve the panic payload for the blocking caller.
                // Without `catch_unwind` a panicking future merely drops
                // `tx` and the receiver maps the disconnect to a generic
                // "task dropped" error that hides the cause.
                let outcome = std::panic::AssertUnwindSafe(future).catch_unwind().await;
                let to_send = match outcome {
                    Ok(val) => Ok(val),
                    Err(payload) => {
                        let msg = if let Some(s) = payload.downcast_ref::<&str>() {
                            *s
                        } else if let Some(s) = payload.downcast_ref::<String>() {
                            s.as_str()
                        } else {
                            "task panicked"
                        };
                        Err(eggfetch_core::Error::Io(std::sync::Arc::new(
                            std::io::Error::other(format!(
                                "eggfetch-ffi blocking_send: task panicked: {msg}"
                            )),
                        )))
                    }
                };
                let _ = tx.send(to_send);
            });
            rx.recv().unwrap_or_else(|e| {
                Err(eggfetch_core::Error::Io(std::sync::Arc::new(
                    std::io::Error::other(format!(
                        "eggfetch-ffi blocking_send: runtime task dropped ({e})"
                    )),
                )))
            })
        }
    }
}