vox-mesh-transport API Reference (generated)
Crate: vox-mesh-transport · Version: 0.6.0 · Target: Library (lib.rs)
iroh QUIC mesh transport: persisted mesh identity, EndpointId trust allowlist, and the job wire protocol.
Crate Overview
Section titled “Crate Overview”iroh QUIC mesh transport (ADR-047).
Replaces the hand-rolled HTTP control plane, ed25519 envelope, and JWT auth
matrix that vox populi used to carry. iroh supplies transport, identity,
and NAT traversal; vox keeps capability scheduling.
Three invariants this crate exists to hold, all of them learned the hard way and recorded in ADR-047:
presets::Minimalonly.presets::N0adds pkarr publishing, DNS address lookup, and n0’s relay servers. The mesh must contact no third party and must work with both machines off the internet.- Never
into_0rtt(). In the 0-RTT stateremote_id()becomes fallible, and the?someone adds to satisfy the compiler quietly turns every trust check in this crate advisory. - Pairing grants reachability, never native execution. A trusted peer gets a sandbox by default.
Workspace Dependencies
Section titled “Workspace Dependencies”| Dependency | Kind |
|---|---|
vox-mesh-types | Normal |
vox-mesh-types | Development |
Public API Surface
Section titled “Public API Surface”Modules
Section titled “Modules”| Module | Description |
|---|---|
caps_spec | — |
directory | — |
endpoint | — |
identity | — |
interp_executor | — |
mailbox | — |
protocol | — |
trust | — |
Dependency Topology
Section titled “Dependency Topology”Diagram source
graph { direction: right node vox_mesh_transport: "vox-mesh-transport" node vox_mesh_types: "vox-mesh-types" vox_mesh_transport -> vox_mesh_types node vox_ml_cli: "vox-ml-cli" vox_ml_cli -> vox_mesh_transport node vox_orchestrator: "vox-orchestrator" vox_orchestrator -> vox_mesh_transport node vox_workflow_runtime: "vox-workflow-runtime" vox_workflow_runtime -> vox_mesh_transport}Reverse Dependents (Used By)
Section titled “Reverse Dependents (Used By)”| Consumer Crate | Role |
|---|---|
vox-ml-cli | Direct workspace dependent |
vox-orchestrator | Direct workspace dependent |
vox-workflow-runtime | Direct workspace dependent |
Deep Public Symbols (Source-Anchored)
Section titled “Deep Public Symbols (Source-Anchored)”| Kind | Symbol | Signature | Source | Description |
|---|---|---|---|---|
struct | caps_spec::CapsSpec | pub struct CapsSpec | crates/vox-mesh-transport/src/caps_spec.rs#L17-L19 | A receiver-imposed capability grant, already turned into CLI tokens. |
fn | caps_spec::from_roots | pub fn from_roots(ro: Vec<PathBuf>, rw: Vec<PathBuf>, extra: &[&str]) -> anyhow::Result<Self> | crates/vox-mesh-transport/src/caps_spec.rs#L23-L47 | Typed constructor: roots are PathBufs, extras are individual tokens. |
fn | caps_spec::to_tokens | pub fn to_tokens(&self) -> Vec<String> | crates/vox-mesh-transport/src/caps_spec.rs#L50-L52 | Tokens suitable for vox run --caps <token> --caps <token>. |
struct | directory::PeerEntry | pub struct PeerEntry | crates/vox-mesh-transport/src/directory.rs#L28-L37 | One reachable peer, as demonstrated by a Probe round-trip. |
fn | directory::directory | pub async fn directory(ep: &Endpoint, trust: &Arc<MeshTrust>) -> Vec<PeerEntry> | crates/vox-mesh-transport/src/directory.rs#L47-L74 | Probe every trusted peer; return those that answered. Peers are probed concurrently, so the call is bounded by [PROBE_TIMEOUT] rather than PROBE_TIMEOUT * peers — a directory that got slower the more machines you own would be the wrong shape. Never returns Err: one unreachable peer must not hide the others, so a failure is an omission from the list rather than an error for all of it. |
struct | directory::MeshQueueTotals | pub struct MeshQueueTotals | crates/vox-mesh-transport/src/directory.rs#L82-L87 | Queue depth summed over the peers that answered. The totals are the sum of what peers claimed; peers_answered is there so a caller can tell “the mesh says zero” from “no mesh answered”, which is the difference between reporting a depth and falling back to a local source. |
fn | directory::queue_stats | pub async fn queue_stats(ep: &Endpoint, trust: &Arc<MeshTrust>) -> MeshQueueTotals | crates/vox-mesh-transport/src/directory.rs#L94-L103 | Ask every trusted peer how deep its queue is. Same shape as [directory] and for the same reason: concurrent, bounded by [PROBE_TIMEOUT], and never Err — one dark machine must not erase the depth the others reported. |
struct | endpoint::ReceivedJob | pub struct ReceivedJob | crates/vox-mesh-transport/src/endpoint.rs#L41-L49 | A job that passed the trust gate and the payload check. |
trait | endpoint::JobExecutor | pub trait JobExecutor: Send + Sync + 'static | crates/vox-mesh-transport/src/endpoint.rs#L54-L59 | What actually runs received work. Kept behind a trait so the accept loop can be tested without a sandbox, and so the sandbox can change without touching the transport. |
fn | endpoint::inbound_firewall_advice | pub fn inbound_firewall_advice(program: &std::path::Path) -> Option<String> | crates/vox-mesh-transport/src/endpoint.rs#L78-L89 | On Windows, report whether inbound UDP to this process is likely to be dropped by the firewall. Windows’ default inbound action is block, and a per-application allow rule is not created automatically for a console binary. The failure this produces is silent and badly misleading: outbound dials still work, so the node looks healthy, and any VPN on the box (Tailscale delivers over utun, after its own daemon has accepted the packet) transparently carries the traffic that the LAN cannot. Measured 2026-09-05: LAN dial timed out at 30 s while the tailnet dial to the same peer connected in 73 ms, and one inbound rule took the LAN path to 25.7 ms. Returns None where the question does not apply, and Some(advice) where the operator should act. Deliberately advisory: creating a firewall rule needs elevation, and silently elevating during mesh join would be worse than telling the truth. |
fn | endpoint::inbound_firewall_advice | pub fn inbound_firewall_advice(_program: &std::path::Path) -> Option<String> | crates/vox-mesh-transport/src/endpoint.rs#L93-L96 | Non-Windows hosts do not gate inbound traffic per application by default. |
fn | endpoint::bind | pub async fn bind(sk: SecretKey) -> Result<Endpoint> | crates/vox-mesh-transport/src/endpoint.rs#L102-L121 | Bind a mesh endpoint. presets::Minimal is not a default to be revisited — it is the whole isolation guarantee. See the crate docs and ADR-047. |
fn | endpoint::serve | pub async fn serve( | crates/vox-mesh-transport/src/endpoint.rs#L129 | Accept loop. Bounded, trust-gated, and free of 0-RTT. mailbox is the durable A2A inbox (plan Task 3.1). None serves jobs only and refuses mail at the ALPN, which is the honest answer for a node that has nowhere to put it — accepting mail into a discarded buffer would let a peer delete its only copy. |
fn | identity::load_or_create | pub fn load_or_create(path: &Path) -> Result<SecretKey> | crates/vox-mesh-transport/src/identity.rs#L28-L45 | Load the mesh identity at path, generating and persisting one if absent. Never silently regenerates: a key that is present but unreadable is an error, because replacing it would orphan every peer that trusted the old public key and the user would see only “pairing stopped working”. |
struct | interp_executor::InterpExecutor | pub struct InterpExecutor | crates/vox-mesh-transport/src/interp_executor.rs#L110-L117 | Runs mesh-received VoxLang as vox run --mode interp under trust-mapped caps. |
fn | interp_executor::new | pub fn new(trust: Arc<MeshTrust>, vox: PathBuf, limits: JobLimits) -> Self | crates/vox-mesh-transport/src/interp_executor.rs#L120-L130 | — |
fn | interp_executor::caps_for | pub fn caps_for(level: TrustLevel, job_dir: &Path) -> anyhow::Result<Vec<String>> | crates/vox-mesh-transport/src/interp_executor.rs#L133-L139 | Trust-mapped --caps tokens for a job directory. Never grants secrets. |
fn | interp_executor::read_capped | pub async fn read_capped<R: tokio::io::AsyncRead + Unpin>( | crates/vox-mesh-transport/src/interp_executor.rs#L141 | — |
fn | interp_executor::read_capped_for_test | pub async fn read_capped_for_test<R: tokio::io::AsyncRead + Unpin>( | crates/vox-mesh-transport/src/interp_executor.rs#L169 | — |
struct | mailbox::MailboxLimits | pub struct MailboxLimits | crates/vox-mesh-transport/src/mailbox.rs#L102-L116 | Bounds applied to every mailbox message and to the queue itself. Same shape and spirit as JobLimits: a cap on the wire, a cap on disk, and a cap on concurrency, none of them the peer’s to choose. |
enum | mailbox::MailboxRequest | pub enum MailboxRequest | crates/vox-mesh-transport/src/mailbox.rs#L149-L151 | What the sender puts on the wire. The message travels as JSON inside the postcard frame, which looks redundant and is not. A2ADeliverRequest marks its optional fields skip_serializing_if = "Option::is_none", and postcard is not self-describing: a skipped field is simply absent from the byte stream, and the decoder — which expects every field positionally — reads the next field’s bytes as the missing one’s discriminant. The failure is a decode error at best and a silently mis-parsed message at worst, and it is invisible until a message with a None field is sent. The alternative, changing those attributes, is a wire-format change to a type the HTTP plane still serves. No PartialEq: A2ADeliverRequest has none, and deriving one here would mean adding it to a type in another crate to satisfy a test. |
fn | mailbox::deliver | pub fn deliver(req: &A2ADeliverRequest) -> Result<Self> | crates/vox-mesh-transport/src/mailbox.rs#L155-L159 | Wrap a message for the wire. |
fn | mailbox::into_request | pub fn into_request(self) -> Result<A2ADeliverRequest> | crates/vox-mesh-transport/src/mailbox.rs#L162-L165 | Unwrap a message from the wire. |
enum | mailbox::MailboxAck | pub enum MailboxAck | crates/vox-mesh-transport/src/mailbox.rs#L170-L177 | What the receiver answers, after the message is on its disk. |
struct | mailbox::Inbox | pub struct Inbox | crates/vox-mesh-transport/src/mailbox.rs#L308-L312 | Messages this node has durably accepted from its peers. One file per message, named by idempotency slot, so redelivery after a lost ack is a no-op rather than a duplicate. The consumer drains it; this crate only ever adds. |
fn | mailbox::at | pub fn at(dir: &Path) -> Self | crates/vox-mesh-transport/src/mailbox.rs#L315-L317 | — |
fn | mailbox::with_limits | pub fn with_limits(dir: &Path, limits: MailboxLimits) -> Self | crates/vox-mesh-transport/src/mailbox.rs#L319-L325 | — |
fn | mailbox::dir | pub fn dir(&self) -> &Path | crates/vox-mesh-transport/src/mailbox.rs#L327-L329 | — |
fn | mailbox::limits | pub fn limits(&self) -> MailboxLimits | crates/vox-mesh-transport/src/mailbox.rs#L331-L333 | — |
fn | mailbox::store | pub fn store(&self, peer: &EndpointId, req: &A2ADeliverRequest) -> Result<bool> | crates/vox-mesh-transport/src/mailbox.rs#L341-L369 | Durably store req. Ok(false) means the slot already existed, which is a successful delivery of a message we already have. Returns Err rather than swallowing an I/O failure: the caller turns that into a refusal, and an ack sent over a failed write is how a store-and-forward system loses mail. |
fn | mailbox::messages | pub fn messages(&self) -> Vec<A2ADeliverRequest> | crates/vox-mesh-transport/src/mailbox.rs#L372-L381 | Everything received, from every peer. |
fn | mailbox::remove | pub fn remove(&self, peer: &EndpointId, req: &A2ADeliverRequest) -> Result<()> | crates/vox-mesh-transport/src/mailbox.rs#L388-L403 | Remove a message the consumer has finished with. Keyed by the same slot the sender’s idempotency key produced, so a redelivery after removal is stored again — the alternative, a permanent tombstone, is an unbounded on-disk set. |
struct | mailbox::Outbox | pub struct Outbox | crates/vox-mesh-transport/src/mailbox.rs#L411-L415 | Messages queued for peers, on disk, one directory per peer. The queue is written before the dial, so it is the sender’s durable copy: a message is removed only once a peer has said it stored it. |
fn | mailbox::at | pub fn at(dir: &Path) -> Self | crates/vox-mesh-transport/src/mailbox.rs#L418-L420 | — |
fn | mailbox::with_limits | pub fn with_limits(dir: &Path, limits: MailboxLimits) -> Self | crates/vox-mesh-transport/src/mailbox.rs#L422-L428 | — |
fn | mailbox::dir | pub fn dir(&self) -> &Path | crates/vox-mesh-transport/src/mailbox.rs#L430-L432 | — |
fn | mailbox::queue | pub fn queue(&self, peer: &EndpointId, req: &A2ADeliverRequest) -> Result<()> | crates/vox-mesh-transport/src/mailbox.rs#L435-L461 | Queue req for peer, durably, before anything is dialed. |
fn | mailbox::depth | pub fn depth(&self) -> usize | crates/vox-mesh-transport/src/mailbox.rs#L464-L472 | How many messages are queued for all peers. |
fn | mailbox::pending_for | pub fn pending_for(&self, peer: &EndpointId) -> Vec<A2ADeliverRequest> | crates/vox-mesh-transport/src/mailbox.rs#L475-L480 | What is queued for one peer, oldest slot first. |
fn | mailbox::flush | pub async fn flush(&self, ep: &Endpoint, trust: &MeshTrust) -> usize | crates/vox-mesh-transport/src/mailbox.rs#L489-L540 | Try to deliver everything queued. Returns how many messages were accepted. Never returns Err: a peer that is off is the normal case, not a failure, and one dark machine must not stop the others being flushed. Peers are flushed concurrently up to [MailboxLimits::max_inflight_peers]. |
fn | mailbox::handle | pub async fn handle( | crates/vox-mesh-transport/src/mailbox.rs#L617 | Serve one mailbox connection: greet, store, ack, repeat until the peer closes. Trust is re-checked per message, not only at accept: a connection opened while trusted must stop being served the moment an operator revokes it. |
struct | protocol::JobId | pub struct JobId(pub u64) | crates/vox-mesh-transport/src/protocol.rs#L22 | Opaque job identifier assigned by the sender. Newtype so two peers’ ids cannot be confused with a bare counter, and so (EndpointId, JobId) can key the running map. |
struct | protocol::Hello | pub struct Hello | crates/vox-mesh-transport/src/protocol.rs#L28-L31 | First frame on every stream. This layout is frozen forever; every other message may change. Without it, version skew is a hang or a postcard deserialisation error rather than a sentence a human can act on. |
fn | protocol::current | pub fn current() -> Self | crates/vox-mesh-transport/src/protocol.rs#L35-L40 | This node’s own greeting. |
enum | protocol::JobRequest | pub enum JobRequest | crates/vox-mesh-transport/src/protocol.rs#L47-L66 | What the sender is asking for. kind is the existing [vox_mesh_types::TaskKind] — a second job-kind enum here would be exactly the split-brain the deletion phase exists to end. |