Zachery Aaron Shores-Chmielewski
b887e941cb
Introduce the swactor engine: a swactor-owned composite that retains a selected execution substrate, drives the core runtime, and hosts the async/blocking/timer work that backs actors. Integrations receive one cloneable EngineHandle and never construct or borrow a raw Tokio runtime/handle. Engine crate (crates/engine): - The contract: spawn / spawn_blocking / timer / interval / now, a per-implementation capability model with construction-time binding (require()), and engine-owned time. The engine owns all progression; actor handlers stay synchronous and never .await. - TokioBackend owns the Tokio runtime and schedules core ticks and supporting futures on it; SteppingBackend is a single-threaded deterministic scheduler with virtual time (the non-Tokio portability proof). Core is driven through its existing tick() surface; a self-rescheduling CoreDriver is installed at construction and is the sole place permitted to call try_tick. iroh-driver: - Receives an EngineHandle instead of a raw Tokio Handle. Accepts, reads, dials, writes, endpoint construction, and teardown schedule through it; required capabilities (tasks/timers/io) are validated before the endpoint binds. Engine-hosted interval pumps drive actor-bridge, datastream, and edge ingress. myelin: - One node/orchestrator engine owns core, protocol tick injection, and transport progression; the application loop only drains integration-owned queues. Stage-shard process readers, delayed actor messages, helper stdout/stderr, prompt RPC, and CPU sampling all schedule through the engine (spawn_blocking / engine tasks / timers). - Removed the split-engine APIs: install_actor_bridge_pump(period) and spawn_protocol_ticker(period) use each component's stored engine; deleted the no-op pump_network callback and its plumbing; deleted the dashboard raw-Tokio/standalone-runtime conveniences. Enforcement: - A clippy disallowed-methods boundary forbids direct runtime/scheduling/ time/core-driving bypasses, denied in swactor-engine, iroh-driver, and myelin. Retained excluded uses (VastAI provider, provider process supervision/log capture, OS-signal/stdin/process-control sequencing) carry narrow allowances with reasons. Verification: - Engine contract + unit tests (incl. the SteppingBackend portability proof), iroh integration tests (capability rejection before binding, multi-node actor behavior), and a production execution-composition smoke test that observes engine-driven actor progress with no ambient Tokio runtime and no manual tick/pump. Workspace all-target/all-feature clippy and tests are green. Specs co-located with their crates: ENGINE_SPEC.md in crates/engine, IROH_DRIVER_SPEC.md in crates/iroh-driver. VastAI remains explicitly out of scope pending its separate redesign.
31 lines
1.6 KiB
Markdown
31 lines
1.6 KiB
Markdown
# 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.
|
|
|
|
## Engine ownership
|
|
|
|
The driver runs on a caller-supplied swactor [`EngineHandle`](swactor_engine) — the
|
|
single engine that owns the node's Tokio substrate. All accepts, reads, dials,
|
|
writes, retries, and teardown are scheduled through that handle; the driver
|
|
stores no raw Tokio handle and performs no ambient-runtime detection
|
|
(ENGINE_SPEC.md §7).
|
|
|
|
```rust
|
|
let driver = IrohDriver::with_engine(engine.handle(), config)?;
|
|
```
|
|
|
|
The driver validates that the engine provides the `tasks`, `timers`, and `io`
|
|
capabilities before binding the endpoint or starting any background work
|
|
(ENGINE_SPEC.md). Endpoint construction runs as an engine-hosted
|
|
task; `with_engine` blocks on a synchronous channel until the endpoint is bound
|
|
(or fails), so callers need not enter or possess the raw substrate runtime.
|
|
|
|
## Engine-hosted progression
|
|
|
|
All adapter progression — actor-bridge ingress/egress, datastream ingress, and
|
|
edge ingress — is driven by an engine-hosted interval pump installed via
|
|
`install_actor_bridge_pump`. Applications do not (and cannot) manually pump
|
|
these adapters; the single engine owns progression for the node's lifetime
|
|
(ENGINE_SPEC.md). `snapshot` is a pure-synchronous read of driver
|
|
state, callable from any thread. The `shutdown` method closes the endpoint via
|
|
an engine-hosted task, blocking on a synchronous channel until completion.
|