Skip to main content

Crate federation_net

Crate federation_net 

Source
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; NetworkEventReceiver delivers NetworkEvents 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§

ByteStream
A raw bidirectional byte stream to a peer, running over a dedicated connection on an auxiliary ALPN.
ByteStreamConnectionStats
Snapshot of low-level transport statistics for a byte stream connection.
EndpointAddr
Network-level addressing information for an iroh endpoint.
NetworkConfig
Configuration for a crate::NetworkEngine.
NetworkConfigBuilder
Builder for NetworkConfig.
NetworkEngine
A generic peer-to-peer network engine on top of Iroh.
NetworkEventReceiver
Receiving side of the engine’s event channel.
NetworkHealthSnapshot
Point-in-time health snapshot of a running network engine.
NetworkId
Identifier of a distinct P2P network.
PeerTicket
A shareable invitation to connect to a peer.
RecvStream
noq types that are used in the public iroh API. A stream that can only be used to receive data
RendezvousConfig
Configuration of the mainline-DHT rendezvous.
SchemaId
Identifier of the domain message schema used on top of the network.
SecretKey
A secret key.
SendStream
noq types that are used in the public iroh API. A stream that can only be used to send data
Signature
Ed25519 signature.
StreamAcceptor
Receiver of incoming ByteStreams for one declared stream protocol.

Enums§

ConnectionDirection
Direction of an established peer connection.
ConnectionPathKind
The currently selected transport path kind for a byte stream connection.
NetworkError
All errors that can be returned by the public API of this library.
NetworkEvent
Events emitted by a crate::NetworkEngine.
NetworkHealthState
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§

EndpointId
The identifier for an endpoint in the (iroh) network.
Result
Convenient result alias used across the library.