swactor/crates/iroh-driver/README.md

iroh-driver

iroh-driver is the iroh-backed transport bridge for the actorized distribution stack. It owns the concrete iroh endpoint, QUIC connections, relay configuration, peer authorization, and frame shuttling between iroh and swactor actor mailboxes.

Tokio runtime ownership

The driver needs Tokio because iroh's endpoint, accepts, dials, stream reads/writes, retry timers, and shutdown APIs are async. New call sites should make that engine explicit by constructing the driver with:

let driver = IrohDriver::with_handle(tokio_handle, config)?;

with_handle does not own the Tokio runtime. The caller must keep the runtime alive for as long as the driver exists.

Legacy implicit constructor

IrohDriver::new(config) is still present as a compatibility convenience, but it hides runtime ownership:

• If called inside an existing Tokio runtime, it uses Handle::try_current() and shares that ambient engine.
• If called outside Tokio, it silently builds and owns a multi-threaded Tokio runtime with enable_all().

Avoid IrohDriver::new in new production code. Use with_handle or an explicit engine wrapper at the application boundary so every Tokio engine in the process is visible in construction code.

Sync facade caveat

The synchronous facade methods that bridge to async with block_on must run from a non-async thread. Do not call those methods from inside tasks running on the same Tokio runtime; Tokio will panic on nested block_on.