Skip to content

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.

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:

  1. presets::Minimal only. presets::N0 adds 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.
  2. Never into_0rtt(). In the 0-RTT state remote_id() becomes fallible, and the ? someone adds to satisfy the compiler quietly turns every trust check in this crate advisory.
  3. Pairing grants reachability, never native execution. A trusted peer gets a sandbox by default.
DependencyKind
vox-mesh-typesNormal
vox-mesh-typesDevelopment
ModuleDescription
caps_spec—
directory—
endpoint—
identity—
interp_executor—
mailbox—
protocol—
trust—
Dependency Topology, diagram 15 nodes, 4 edges: vox-mesh-transport → vox-mesh-types; vox-ml-cli → vox-mesh-transport; vox-orchestrator → vox-mesh-transport; vox-workflow-runtime → vox-mesh-transportvox-mesh-transportvox-mesh-typesvox-ml-clivox-orchestratorvox-workflow-runtime
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
}
Consumer CrateRole
vox-ml-cliDirect workspace dependent
vox-orchestratorDirect workspace dependent
vox-workflow-runtimeDirect workspace dependent
KindSymbolSignatureSourceDescription
structcaps_spec::CapsSpecpub struct CapsSpeccrates/vox-mesh-transport/src/caps_spec.rs#L17-L19A receiver-imposed capability grant, already turned into CLI tokens.
fncaps_spec::from_rootspub fn from_roots(ro: Vec<PathBuf>, rw: Vec<PathBuf>, extra: &[&str]) -> anyhow::Result<Self>crates/vox-mesh-transport/src/caps_spec.rs#L23-L47Typed constructor: roots are PathBufs, extras are individual tokens.
fncaps_spec::to_tokenspub fn to_tokens(&self) -> Vec<String>crates/vox-mesh-transport/src/caps_spec.rs#L50-L52Tokens suitable for vox run --caps <token> --caps <token>.
structdirectory::PeerEntrypub struct PeerEntrycrates/vox-mesh-transport/src/directory.rs#L28-L37One reachable peer, as demonstrated by a Probe round-trip.
fndirectory::directorypub async fn directory(ep: &Endpoint, trust: &Arc<MeshTrust>) -> Vec<PeerEntry>crates/vox-mesh-transport/src/directory.rs#L47-L74Probe 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.
structdirectory::MeshQueueTotalspub struct MeshQueueTotalscrates/vox-mesh-transport/src/directory.rs#L82-L87Queue 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.
fndirectory::queue_statspub async fn queue_stats(ep: &Endpoint, trust: &Arc<MeshTrust>) -> MeshQueueTotalscrates/vox-mesh-transport/src/directory.rs#L94-L103Ask 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.
structendpoint::ReceivedJobpub struct ReceivedJobcrates/vox-mesh-transport/src/endpoint.rs#L41-L49A job that passed the trust gate and the payload check.
traitendpoint::JobExecutorpub trait JobExecutor: Send + Sync + 'staticcrates/vox-mesh-transport/src/endpoint.rs#L54-L59What 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.
fnendpoint::inbound_firewall_advicepub fn inbound_firewall_advice(program: &std::path::Path) -> Option<String>crates/vox-mesh-transport/src/endpoint.rs#L78-L89On 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.
fnendpoint::inbound_firewall_advicepub fn inbound_firewall_advice(_program: &std::path::Path) -> Option<String>crates/vox-mesh-transport/src/endpoint.rs#L93-L96Non-Windows hosts do not gate inbound traffic per application by default.
fnendpoint::bindpub async fn bind(sk: SecretKey) -> Result<Endpoint>crates/vox-mesh-transport/src/endpoint.rs#L102-L121Bind 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.
fnendpoint::servepub async fn serve(crates/vox-mesh-transport/src/endpoint.rs#L129Accept 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.
fnidentity::load_or_createpub fn load_or_create(path: &Path) -> Result<SecretKey>crates/vox-mesh-transport/src/identity.rs#L28-L45Load 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”.
structinterp_executor::InterpExecutorpub struct InterpExecutorcrates/vox-mesh-transport/src/interp_executor.rs#L110-L117Runs mesh-received VoxLang as vox run --mode interp under trust-mapped caps.
fninterp_executor::newpub fn new(trust: Arc<MeshTrust>, vox: PathBuf, limits: JobLimits) -> Selfcrates/vox-mesh-transport/src/interp_executor.rs#L120-L130—
fninterp_executor::caps_forpub fn caps_for(level: TrustLevel, job_dir: &Path) -> anyhow::Result<Vec<String>>crates/vox-mesh-transport/src/interp_executor.rs#L133-L139Trust-mapped --caps tokens for a job directory. Never grants secrets.
fninterp_executor::read_cappedpub async fn read_capped<R: tokio::io::AsyncRead + Unpin>(crates/vox-mesh-transport/src/interp_executor.rs#L141—
fninterp_executor::read_capped_for_testpub async fn read_capped_for_test<R: tokio::io::AsyncRead + Unpin>(crates/vox-mesh-transport/src/interp_executor.rs#L169—
structmailbox::MailboxLimitspub struct MailboxLimitscrates/vox-mesh-transport/src/mailbox.rs#L102-L116Bounds 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.
enummailbox::MailboxRequestpub enum MailboxRequestcrates/vox-mesh-transport/src/mailbox.rs#L149-L151What 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.
fnmailbox::deliverpub fn deliver(req: &A2ADeliverRequest) -> Result<Self>crates/vox-mesh-transport/src/mailbox.rs#L155-L159Wrap a message for the wire.
fnmailbox::into_requestpub fn into_request(self) -> Result<A2ADeliverRequest>crates/vox-mesh-transport/src/mailbox.rs#L162-L165Unwrap a message from the wire.
enummailbox::MailboxAckpub enum MailboxAckcrates/vox-mesh-transport/src/mailbox.rs#L170-L177What the receiver answers, after the message is on its disk.
structmailbox::Inboxpub struct Inboxcrates/vox-mesh-transport/src/mailbox.rs#L308-L312Messages 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.
fnmailbox::atpub fn at(dir: &Path) -> Selfcrates/vox-mesh-transport/src/mailbox.rs#L315-L317—
fnmailbox::with_limitspub fn with_limits(dir: &Path, limits: MailboxLimits) -> Selfcrates/vox-mesh-transport/src/mailbox.rs#L319-L325—
fnmailbox::dirpub fn dir(&self) -> &Pathcrates/vox-mesh-transport/src/mailbox.rs#L327-L329—
fnmailbox::limitspub fn limits(&self) -> MailboxLimitscrates/vox-mesh-transport/src/mailbox.rs#L331-L333—
fnmailbox::storepub fn store(&self, peer: &EndpointId, req: &A2ADeliverRequest) -> Result<bool>crates/vox-mesh-transport/src/mailbox.rs#L341-L369Durably 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.
fnmailbox::messagespub fn messages(&self) -> Vec<A2ADeliverRequest>crates/vox-mesh-transport/src/mailbox.rs#L372-L381Everything received, from every peer.
fnmailbox::removepub fn remove(&self, peer: &EndpointId, req: &A2ADeliverRequest) -> Result<()>crates/vox-mesh-transport/src/mailbox.rs#L388-L403Remove 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.
structmailbox::Outboxpub struct Outboxcrates/vox-mesh-transport/src/mailbox.rs#L411-L415Messages 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.
fnmailbox::atpub fn at(dir: &Path) -> Selfcrates/vox-mesh-transport/src/mailbox.rs#L418-L420—
fnmailbox::with_limitspub fn with_limits(dir: &Path, limits: MailboxLimits) -> Selfcrates/vox-mesh-transport/src/mailbox.rs#L422-L428—
fnmailbox::dirpub fn dir(&self) -> &Pathcrates/vox-mesh-transport/src/mailbox.rs#L430-L432—
fnmailbox::queuepub fn queue(&self, peer: &EndpointId, req: &A2ADeliverRequest) -> Result<()>crates/vox-mesh-transport/src/mailbox.rs#L435-L461Queue req for peer, durably, before anything is dialed.
fnmailbox::depthpub fn depth(&self) -> usizecrates/vox-mesh-transport/src/mailbox.rs#L464-L472How many messages are queued for all peers.
fnmailbox::pending_forpub fn pending_for(&self, peer: &EndpointId) -> Vec<A2ADeliverRequest>crates/vox-mesh-transport/src/mailbox.rs#L475-L480What is queued for one peer, oldest slot first.
fnmailbox::flushpub async fn flush(&self, ep: &Endpoint, trust: &MeshTrust) -> usizecrates/vox-mesh-transport/src/mailbox.rs#L489-L540Try 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].
fnmailbox::handlepub async fn handle(crates/vox-mesh-transport/src/mailbox.rs#L617Serve 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.
structprotocol::JobIdpub struct JobId(pub u64)crates/vox-mesh-transport/src/protocol.rs#L22Opaque 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.
structprotocol::Hellopub struct Hellocrates/vox-mesh-transport/src/protocol.rs#L28-L31First 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.
fnprotocol::currentpub fn current() -> Selfcrates/vox-mesh-transport/src/protocol.rs#L35-L40This node’s own greeting.
enumprotocol::JobRequestpub enum JobRequestcrates/vox-mesh-transport/src/protocol.rs#L47-L66What 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.