fastn_net/
lib.rs

1//! # fastn-net
2//!
3//! Network utilities and P2P communication between fastn entities.
4//!
5//! This crate provides P2P networking capabilities for fastn entities using Iroh.
6//! Each fastn instance is called an "entity" in the P2P network, identified by
7//! its unique ID52 (a 52-character encoded Ed25519 public key).
8//!
9//! ## Example
10//!
11//! ```no_run
12//! use fastn_net::{global_iroh_endpoint, ping, PONG};
13//!
14//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
15//! // Get the global Iroh endpoint for this entity
16//! let endpoint = global_iroh_endpoint().await;
17//!
18//! // Connect to another entity
19//! let entity_id = "entity_id52_here".parse()?;
20//! let connection = endpoint.connect(entity_id, "").await?;
21//!
22//! // Open a bidirectional stream between entities
23//! let (mut send, mut recv) = connection.open_bi().await?;
24//!
25//! // Send ping and receive pong
26//! ping(&mut send).await?;
27//! let response = fastn_net::next_string(&mut recv).await?;
28//! assert_eq!(response, PONG);
29//! # Ok(())
30//! # }
31//! ```
32//!
33//! ## Supported Protocols
34//!
35//! - [`Protocol::Ping`] - Test connectivity between entities
36//! - [`Protocol::Http`] - Proxy HTTP requests through entities
37//! - [`Protocol::Tcp`] - Tunnel TCP connections between entities
38//! - [`Protocol::Socks5`] - SOCKS5 proxy support
39
40extern crate self as fastn_net;
41
42pub mod dot_fastn;
43pub mod get_endpoint;
44mod get_stream;
45mod graceful;
46pub mod http;
47mod http_connection_manager;
48mod http_to_peer;
49mod peer_to_http;
50mod ping;
51pub mod protocol;
52mod secret;
53mod tcp;
54mod utils;
55mod utils_iroh;
56
57pub use get_endpoint::get_endpoint;
58pub use get_stream::{PeerStreamSenders, get_stream};
59pub use graceful::Graceful;
60pub use http::ProxyResult;
61pub use http_connection_manager::{HttpConnectionManager, HttpConnectionPool, HttpConnectionPools};
62pub use http_to_peer::{http_to_peer, http_to_peer_non_streaming};
63pub use peer_to_http::peer_to_http;
64pub use ping::{PONG, ping};
65pub use protocol::{APNS_IDENTITY, Protocol, ProtocolHeader};
66pub use secret::{
67    SECRET_KEY_FILE, generate_and_save_key, generate_secret_key, get_secret_key, read_or_create_key,
68};
69pub use tcp::{peer_to_tcp, pipe_tcp_stream_over_iroh, tcp_to_peer};
70pub use utils::mkdir;
71pub use utils_iroh::{
72    accept_bi, accept_bi_with, get_remote_id52, global_iroh_endpoint, next_json, next_string,
73};
74
75// Deprecated helper functions - use fastn_id52 directly
76pub use utils::{id52_to_public_key, public_key_to_id52};
77
78/// Map of entity IDs to their port and endpoint.
79///
80/// Stores tuples of (ID52 prefix, (port, Iroh endpoint)) for entity lookup.
81/// Uses a Vec instead of HashMap because:
82/// - We need prefix matching for shortened IDs in subdomains
83/// - The number of entities is typically small per instance
84/// - Linear search with prefix matching is fast enough
85///
86/// The ID52 strings may be truncated when used in DNS subdomains due to the
87/// 63-character limit, so prefix matching allows finding the correct entity.
88pub type IDMap = std::sync::Arc<tokio::sync::Mutex<Vec<(String, (u16, iroh::Endpoint))>>>;
89
90/// Acknowledgment message used in protocol handshakes.
91pub const ACK: &str = "ack";
fastn_net/lib.rs

fastn_net/
lib.rs
