Skip to main content

federation_net/
lib.rs

1//! # federation-net
2//!
3//! A generic peer-to-peer networking engine built on [Iroh](https://iroh.computer).
4//!
5//! The library establishes direct (NAT-traversing, relay-assisted) QUIC
6//! connections between peers and exchanges typed, application-defined
7//! messages over them. It deliberately contains no domain logic: the
8//! application chooses its own message type and the engine treats it as an
9//! opaque, serde-serializable payload.
10//!
11//! ## Core concepts
12//!
13//! * [`NetworkId`] — isolates independent P2P networks from each other.
14//! * [`SchemaId`] — isolates applications with incompatible message schemas.
15//! * [`PeerTicket`] — a shareable string invitation used to reach a peer.
16//! * [`RendezvousConfig`] — optional automatic peer discovery: peers of a
17//!   network find each other through the BitTorrent Mainline DHT knowing
18//!   nothing but the network id.
19//! * [`NetworkEngine`] — the engine itself; [`NetworkEventReceiver`] delivers
20//!   [`NetworkEvent`]s to the application.
21//!
22//! ## Example
23//!
24//! ```no_run
25//! use federation_net::{NetworkConfig, NetworkEngine, NetworkId, SchemaId};
26//!
27//! #[derive(Debug, serde::Serialize, serde::Deserialize)]
28//! enum MyMessage {
29//!     Hello { from: String },
30//! }
31//!
32//! # async fn run() -> federation_net::Result<()> {
33//! let config = NetworkConfig::builder()
34//!     .data_dir("./peer-a")
35//!     .network_id(NetworkId::from_name("example-network"))
36//!     .schema_id(SchemaId::from_name("my-message-v1"))
37//!     .build()?;
38//!
39//! let (engine, mut events) = NetworkEngine::<MyMessage>::start(config).await?;
40//! let ticket = engine.ticket().await?;
41//! println!("share this ticket: {ticket}");
42//!
43//! while let Some(event) = events.recv().await {
44//!     println!("{event:?}");
45//! }
46//! engine.shutdown().await?;
47//! # Ok(())
48//! # }
49//! ```
50
51#![warn(missing_docs)]
52#![forbid(unsafe_code)]
53
54mod config;
55mod engine;
56mod error;
57mod event;
58mod health;
59mod identity;
60mod protocol;
61mod rendezvous;
62mod ticket;
63mod wire;
64
65pub use config::{
66    DEFAULT_EVENT_CHANNEL_CAPACITY, DEFAULT_MAX_CONCURRENT_STREAMS_PER_PEER,
67    DEFAULT_MAX_MESSAGE_SIZE, DEFAULT_REQUEST_TIMEOUT, NetworkConfig, NetworkConfigBuilder,
68};
69pub use engine::{
70    ByteStream, ByteStreamConnectionStats, ConnectionPathKind, Message, NetworkEngine,
71    StreamAcceptor,
72};
73pub use error::{NetworkError, Result};
74pub use event::{ConnectionDirection, NetworkEvent, NetworkEventReceiver};
75pub use health::{NetworkHealthSnapshot, NetworkHealthState};
76pub use protocol::{ALPN, NetworkId, PROTOCOL_VERSION, SchemaId};
77pub use rendezvous::RENDEZVOUS_RECORD_VERSION;
78pub use rendezvous::{DEFAULT_RENDEZVOUS_ENTRY_TTL, DEFAULT_RENDEZVOUS_INTERVAL, RendezvousConfig};
79pub use ticket::{PeerTicket, TICKET_VERSION};
80
81// Re-exported Iroh types that appear in the public API.
82pub use iroh::endpoint::{RecvStream, SendStream};
83pub use iroh::{EndpointAddr, EndpointId, SecretKey, Signature};
84// Re-exported so applications can use the generic ticket helpers.
85pub use iroh_tickets::Ticket;