Expand description
§federation-net
A generic peer-to-peer networking engine built on Iroh.
The library establishes direct (NAT-traversing, relay-assisted) QUIC connections between peers and exchanges typed, application-defined messages over them. It deliberately contains no domain logic: the application chooses its own message type and the engine treats it as an opaque, serde-serializable payload.
§Core concepts
NetworkId— isolates independent P2P networks from each other.SchemaId— isolates applications with incompatible message schemas.PeerTicket— a shareable string invitation used to reach a peer.RendezvousConfig— optional automatic peer discovery: peers of a network find each other through the BitTorrent Mainline DHT knowing nothing but the network id.NetworkEngine— the engine itself;NetworkEventReceiverdeliversNetworkEvents to the application.
§Example
use federation_net::{NetworkConfig, NetworkEngine, NetworkId, SchemaId};
#[derive(Debug, serde::Serialize, serde::Deserialize)]
enum MyMessage {
Hello { from: String },
}
let config = NetworkConfig::builder()
.data_dir("./peer-a")
.network_id(NetworkId::from_name("example-network"))
.schema_id(SchemaId::from_name("my-message-v1"))
.build()?;
let (engine, mut events) = NetworkEngine::<MyMessage>::start(config).await?;
let ticket = engine.ticket().await?;
println!("share this ticket: {ticket}");
while let Some(event) = events.recv().await {
println!("{event:?}");
}
engine.shutdown().await?;Structs§
- Byte
Stream - A raw bidirectional byte stream to a peer, running over a dedicated connection on an auxiliary ALPN.
- Byte
Stream Connection Stats - Snapshot of low-level transport statistics for a byte stream connection.
- Endpoint
Addr - Network-level addressing information for an iroh endpoint.
- Network
Config - Configuration for a
crate::NetworkEngine. - Network
Config Builder - Builder for
NetworkConfig. - Network
Engine - A generic peer-to-peer network engine on top of Iroh.
- Network
Event Receiver - Receiving side of the engine’s event channel.
- Network
Health Snapshot - Point-in-time health snapshot of a running network engine.
- Network
Id - Identifier of a distinct P2P network.
- Peer
Ticket - A shareable invitation to connect to a peer.
- Recv
Stream noqtypes that are used in the public iroh API. A stream that can only be used to receive data- Rendezvous
Config - Configuration of the mainline-DHT rendezvous.
- Schema
Id - Identifier of the domain message schema used on top of the network.
- Secret
Key - A secret key.
- Send
Stream noqtypes that are used in the public iroh API. A stream that can only be used to send data- Signature
- Ed25519 signature.
- Stream
Acceptor - Receiver of incoming
ByteStreams for one declared stream protocol.
Enums§
- Connection
Direction - Direction of an established peer connection.
- Connection
Path Kind - The currently selected transport path kind for a byte stream connection.
- Network
Error - All errors that can be returned by the public API of this library.
- Network
Event - Events emitted by a
crate::NetworkEngine. - Network
Health State - Coarse health state of a running network engine.
Constants§
- ALPN
- ALPN identifier for the federation-net protocol.
- DEFAULT_
EVENT_ CHANNEL_ CAPACITY - Default capacity of the event channel.
- DEFAULT_
MAX_ CONCURRENT_ STREAMS_ PER_ PEER - Default limit of concurrently processed streams per peer.
- DEFAULT_
MAX_ MESSAGE_ SIZE - Default maximum size of an encoded domain message (256 KiB).
- DEFAULT_
RENDEZVOUS_ ENTRY_ TTL - Default time after which a published peer entry is considered stale.
- DEFAULT_
RENDEZVOUS_ INTERVAL - Default interval between rendezvous rounds (read + publish).
- DEFAULT_
REQUEST_ TIMEOUT - Default timeout applied to handshakes and message round-trips.
- PROTOCOL_
VERSION - Version of the application-level wire protocol.
- RENDEZVOUS_
RECORD_ VERSION - Version of the rendezvous record wire format. Version of the Mainline-DHT rendezvous record envelope.
- TICKET_
VERSION - Current version of the ticket wire format.
Traits§
- Message
- Bounds required of a domain message type.
- Ticket
- A ticket is a serializable object combining information required for an operation.
Type Aliases§
- Endpoint
Id - The identifier for an endpoint in the (iroh) network.
- Result
- Convenient result alias used across the library.