Expand description
Kitsune2 transport implementation backed by iroh.
This transport establishes peer-to-peer connections using iroh’s QUIC-based networking. It manages outgoing and incoming connections dynamically, sending and receiving data as framed messages over persistent uni-directional streams.
Each message is framed with a header that specifies the frame type (preflight or data) and the data length, leading to ordered and bounded message delivery. The peer URL is sent as part of the preflight to inform the remote about it and make it available to respond to on the transport level. Since there is no discovery service present in the kitsune2 architecture, the remote URL must be sent with the preflight. Incoming streams are accepted and handled asynchronously per connection. There is one stream open per direction, over which all frames are sent.
§Architecture
Complete trait abstraction of all I/O operations, enabling full testability without network dependencies.
Traits Implementations
┌──────────┐ ┌──────────────┐
│ Endpoint │ │ IrohEndpoint │
└────┬─────┘ └──────┬───────┘
│ │
▼ ▼
┌────────────┐ ┌────────────────┐
│ Connection │ │ IrohConnection │
└─────┬──────┘ └───────┬────────┘
│ │
┌────┴────┐ ┌────┴────┐
▼ ▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────────┐ ┌────────────┐
│ Send │ │ Recv │ │ IrohSend │ │ IrohRecv │
│ Stream │ │ Stream │ │ Stream │ │ Stream │
└────────┘ └────────┘ └────────────┘ └────────────┘§IrohTransport task management
┌───────────────┐
│ IrohTransport │
└───────┬───────┘
│
┌───────────────┴───────────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ watch_addr_task │ │ accept_task │
└────────┬────────┘ └───┬─────────┬───┘
│ │ │
│ monitors │ └──────────┬──────────┐
▼ │ accepts │ │
┌─────────────────┐ ▼ ▼ ▼
│ Relay Address │ ┌────────────┐ ┌──────────┐┌──────────┐┌──────────┐
│ Changes │ │ Incoming │ │ conn_ ││ conn_ ││ conn_ │
└─────────────────┘ │ Connections│ │ reader 1 ││ reader 2 ││ reader N │
└────────────┘ └────┬─────┘└────┬─────┘└────┬─────┘
│ │ │
│ reads │ reads │ reads
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Peer 1 │ │ Peer 2 │ │ Peer N │
│ Frames │ │ Frames │ │ Frames │
└─────────┘ └─────────┘ └─────────┘§Connection establishment
The transport handlers TxImp::send implementation contains the logic
for connection establishment.
┌────────────────┐
│ send to peer X │
└───────┬────────┘
│
▼
┌───────────────────┐
│ Connection exists?│
└─────────┬─────────┘
│
┌─────────────┴─────────────┐
│ Yes No │
▼ ▼
┌────────────────────┐ ┌─────────────────────────┐
│ Use existing │ │ Acquire peer-specific │
│ connection │ │ lock │
└─────────┬──────────┘ └────────────┬────────────┘
│ │
│ ▼
│ ┌────────────────────────┐
│ │ Recheck connection │
│ │ after lock │
│ └───────────┬────────────┘
│ │
│ ┌────────────┴────────────┐
│ │ Created by No │
│ │ another task │
│ ▼ ▼
│ ┌────┘ ┌──────────────────────┐
│ │ │ Create new connection│
│ │ └──────────┬───────────┘
│ │ │
│ │ ▼
│ │ ┌──────────────────┐
│ │ │ Send preflight │
│ │ └────────┬─────────┘
│ │ │
│ │ ▼
│ │ ┌──────────────────┐
│ │ │ Store in map │
│ │ └────────┬─────────┘
│ │ │
▼ ▼ │
┌────────────────────┐◄──────────────────────┘
│ Use existing │
│ connection │
└─────────┬──────────┘
│
▼
┌────────────┐
│ Send data │
└────────────┘Every connection starts with a mandatory bidirectional handshake:
Peer A Peer B
│ │
│ ┌────────────────────────┐ │
│ │ Connection Established │ │
│ └────────────────────────┘ │
│ │
│ Preflight Frame (Type 0) │
│ [URL + Handshake Data] │
│ ──────────────────────────────────────────>│
│ │
│ ┌───────────────┐ │
│ │ 10s timeout │ │
│ │ enforced │ │
│ └───────────────┘ │
│ │
│ Return Preflight Frame │
│ [URL + Handshake Data] │
│<───────────────────────────────────────────│
│ │
│ ┌────────────────────┐ │
│ │ Connection Ready │ │
│ └────────────────────┘ │
│ │
│ Data Frame (Type 1) │
│ ──────────────────────────────────────────>│
│ │
│ Data Frame (Type 1) │
│<───────────────────────────────────────────│
│ │
Peer A Peer B
§iroh transport frames
Preflight Frame (Type 0):
┌─────┬────────┬─────────┬─────┬───────────┐
│ 0x0 │ Length │ URL Len │ URL │ Preflight │
│ 1 B │ 4 B │ 4 B │ Var │ Data │
└─────┴────────┴─────────┴─────┴───────────┘
Data Frame (Type 1):
┌─────┬────────┬──────┐
│ 0x1 │ Length │ Data │
│ 1 B │ 4 B │ Var │
└─────┴────────┴──────┘Re-exports§
pub use config::*;
Modules§
- config
- IrohTransport configuration types
Structs§
- Iroh
Transport Factory - Kitsune2 transport factory backed by iroh.