Skip to main content

karyon_p2p/
node.rs

1use std::{
2    collections::{HashMap, HashSet},
3    sync::Arc,
4};
5
6use log::{debug, error, info};
7
8use karyon_core::{
9    async_runtime::Executor,
10    async_util::{TaskGroup, TaskResult},
11    crypto::KeyPair,
12};
13use karyon_eventemitter::EventListener;
14use karyon_net::Endpoint;
15
16use crate::{
17    PeerID, Result,
18    access_control::{Action, Subject},
19    codec::PeerNetMsgCodec,
20    config::Config,
21    conn_direction::ConnDirection,
22    conn_queue::ConnQueue,
23    connector::Connector,
24    discovery::{DiscoveredPeer, Discovery, PeerConnectionEvent, kademlia::KademliaDiscovery},
25    listener::Listener,
26    message::{Protocol, pick_endpoint},
27    monitor::{Monitor, PoolEvent},
28    peer_pool::{PeerEvent, PeerEventTopic, PeerPool},
29    protocol::{PeerConn, Protocol as ProtocolTrait, ProtocolFlags, ProtocolID},
30    protocols::PingProtocol,
31};
32
33/// Central entry point for the p2p network.
34///
35/// Manages peer connections, discovery, and protocol registration.
36///
37/// # Example
38///
39/// ```no_run
40/// use karyon_core::async_runtime::global_executor;
41/// use karyon_p2p::{Node, Config, keypair::{KeyPair, KeyPairType}};
42///
43/// let key_pair = KeyPair::generate(&KeyPairType::Ed25519);
44/// let config = Config {
45///     listen_endpoints: vec![
46///         "tcp://0.0.0.0:8000".parse().unwrap(),
47///     ],
48///     ..Config::default()
49/// };
50///
51/// let node = Node::new(&key_pair, config, global_executor());
52///
53/// // node.run().await.unwrap();
54/// // node.attach_protocol(MyProto::new).await;
55/// // node.shutdown().await;
56/// ```
57pub struct Node {
58    /// The Configuration for the P2P network.
59    config: Arc<Config>,
60
61    /// Identity Key pair
62    key_pair: KeyPair,
63
64    /// Peer ID
65    peer_id: PeerID,
66
67    /// Responsible for network and system monitoring.
68    monitor: Arc<Monitor>,
69
70    /// Discovery instance.
71    discovery: Arc<dyn Discovery>,
72
73    /// PeerPool instance.
74    peer_pool: Arc<PeerPool>,
75
76    /// Connector for outbound connections.
77    connector: Arc<Connector<PeerNetMsgCodec>>,
78
79    /// Listener for inbound connections.
80    listener: Arc<Listener<PeerNetMsgCodec>>,
81
82    /// Managing spawned tasks.
83    task_group: TaskGroup,
84}
85
86impl Node {
87    /// Creates a new Node with the default Kademlia discovery.
88    pub fn new(key_pair: &KeyPair, config: Config, ex: Executor) -> Arc<Node> {
89        let config = Arc::new(config);
90        let monitor = Arc::new(Monitor::new(config.clone()));
91        let peer_id = PeerID::try_from(key_pair.public())
92            .expect("Derive a peer id from the provided key pair.");
93        info!("PeerID: {peer_id}");
94
95        let conn_queue = ConnQueue::new();
96        let peer_pool = PeerPool::new(
97            &peer_id,
98            conn_queue.clone(),
99            config.clone(),
100            monitor.clone(),
101            ex.clone(),
102        );
103
104        let discovery: Arc<dyn Discovery> = KademliaDiscovery::new(
105            key_pair,
106            &peer_id,
107            config.clone(),
108            monitor.clone(),
109            ex.clone(),
110        );
111
112        let connector = Connector::new_with_queue(
113            key_pair,
114            config.max_connect_retries,
115            config.outbound_slots,
116            config.handshake_timeout,
117            conn_queue.clone(),
118            monitor.clone(),
119            ex.clone(),
120        );
121
122        let listener = Listener::new_with_queue(
123            key_pair,
124            config.inbound_slots,
125            conn_queue,
126            monitor.clone(),
127            config.handshake_timeout,
128            config.access_control.clone(),
129            ex.clone(),
130        );
131
132        let task_group = TaskGroup::with_executor(ex);
133
134        Arc::new(Self {
135            key_pair: key_pair.clone(),
136            peer_id,
137            monitor,
138            discovery,
139            config,
140            peer_pool,
141            connector,
142            listener,
143            task_group,
144        })
145    }
146
147    /// Creates a new Node with a custom discovery implementation.
148    pub fn with_discovery(
149        key_pair: &KeyPair,
150        config: Config,
151        discovery: Arc<dyn Discovery>,
152        ex: Executor,
153    ) -> Arc<Node> {
154        let config = Arc::new(config);
155        let monitor = Arc::new(Monitor::new(config.clone()));
156        let peer_id = PeerID::try_from(key_pair.public())
157            .expect("Derive a peer id from the provided key pair.");
158        info!("PeerID: {peer_id}");
159
160        let conn_queue = ConnQueue::new();
161        let peer_pool = PeerPool::new(
162            &peer_id,
163            conn_queue.clone(),
164            config.clone(),
165            monitor.clone(),
166            ex.clone(),
167        );
168
169        let connector = Connector::new_with_queue(
170            key_pair,
171            config.max_connect_retries,
172            config.outbound_slots,
173            config.handshake_timeout,
174            conn_queue.clone(),
175            monitor.clone(),
176            ex.clone(),
177        );
178
179        let listener = Listener::new_with_queue(
180            key_pair,
181            config.inbound_slots,
182            conn_queue,
183            monitor.clone(),
184            config.handshake_timeout,
185            config.access_control.clone(),
186            ex.clone(),
187        );
188
189        let task_group = TaskGroup::with_executor(ex);
190
191        Arc::new(Self {
192            key_pair: key_pair.clone(),
193            peer_id,
194            monitor,
195            discovery,
196            config,
197            peer_pool,
198            connector,
199            listener,
200            task_group,
201        })
202    }
203
204    /// Run the Node, starting listeners, PeerPool, and Discovery.
205    pub async fn run(self: &Arc<Self>) -> Result<()> {
206        // Core protocols (PING) are attached before the pool starts so
207        // they're advertised on every handshake.
208        self.attach_core_protocols().await?;
209
210        self.peer_pool.start().await?;
211
212        // Start data listeners.
213        for endpoint in &self.config.listen_endpoints {
214            let resolved = self.listener.start(endpoint.clone()).await?;
215            info!("Listening on {resolved}");
216        }
217
218        // Start discovery.
219        self.discovery.clone().start().await?;
220
221        // Forward peer lifecycle events to discovery.
222        self.task_group.spawn_then(
223            {
224                let this = self.clone();
225                async move { this.forward_peer_events().await }
226            },
227            |res: TaskResult<()>| async move {
228                debug!("forward_peer_events task ended: {res}");
229            },
230        );
231
232        // Spawn task to connect discovered peers.
233        self.task_group.spawn_then(
234            {
235                let this = self.clone();
236                async move { this.connect_discovered_peers().await }
237            },
238            |res: TaskResult<()>| async move {
239                debug!("connect_discovered_peers task ended: {res}");
240            },
241        );
242
243        Ok(())
244    }
245
246    /// Forward peer-pool lifecycle events to discovery so it can
247    /// update its routing state. Each registered listener (Node's
248    /// here, plus any external Swarm subscriber) gets every event
249    /// independently - no MPMC stealing.
250    async fn forward_peer_events(self: Arc<Self>) {
251        let listener = self.peer_pool.register_peer_events();
252        while let Ok(event) = listener.recv().await {
253            let mapped = match event {
254                PeerEvent::Added(pid) => PeerConnectionEvent::Connected(pid),
255                PeerEvent::Removed(pid) => PeerConnectionEvent::Disconnected(pid),
256                PeerEvent::HandshakeFailed(pid) => PeerConnectionEvent::ConnectFailed(pid),
257            };
258            self.discovery.on_event(mapped);
259        }
260    }
261
262    /// Consume discovered peers from the discovery service and connect to them.
263    /// Runs forever; the task_group cancels it on Node::shutdown.
264    async fn connect_discovered_peers(self: Arc<Self>) {
265        let supported = [Protocol::Tcp, Protocol::Tls, Protocol::Quic];
266
267        loop {
268            let discovered = self.discovery.recv().await;
269
270            let endpoint = match pick_endpoint(&discovered.addrs, &supported) {
271                Some(ep) => ep,
272                None => continue,
273            };
274
275            if !self.config.access_control.allow(
276                &Subject::Endpoint(&endpoint),
277                Action::Connect(ConnDirection::Outbound),
278            ) {
279                debug!("Skipped dialing denied endpoint {endpoint}");
280                continue;
281            }
282
283            // Already connected: a second connection would only be
284            // rejected or replace the first.
285            if let Some(pid) = &discovered.peer_id
286                && self.peer_pool.contains_peer(pid).await
287            {
288                continue;
289            }
290
291            // Take the slot here, so this loop waits when all slots are
292            // busy. The dial runs in its own task, so one slow endpoint
293            // does not hold back the next dial.
294            let slot = match self.connector.acquire_slot().await {
295                Ok(slot) => slot,
296                Err(err) => {
297                    error!("Acquire outbound slot: {err}");
298                    break;
299                }
300            };
301
302            let peer_id = discovered.peer_id.clone();
303            let this = self.clone();
304            self.task_group.spawn(async move {
305                let res = this
306                    .connector
307                    .connect_and_queue(&endpoint, &peer_id, slot)
308                    .await;
309                if res.is_err() {
310                    this.monitor
311                        .notify(PoolEvent::ConnectFailed(peer_id.clone(), endpoint))
312                        .await;
313                    this.discovery
314                        .on_event(PeerConnectionEvent::ConnectFailed(peer_id));
315                }
316            });
317        }
318    }
319
320    /// Attach a custom protocol. karyon runs the constructor closure
321    /// once per connected peer with a typed `PeerConn` scoped to this
322    /// protocol. The protocol type is inferred from the closure's
323    /// return value. The protocol id is advertised through discovery
324    /// according to `P::flags()`.
325    ///
326    /// ```ignore
327    /// node.attach_protocol(MyProtocol::new).await?;
328    /// ```
329    pub async fn attach_protocol<P: ProtocolTrait + 'static>(
330        &self,
331        c: impl Fn(PeerConn) -> P + Send + Sync + 'static,
332    ) -> Result<()> {
333        let c = move |conn| Arc::new(c(conn)) as Arc<dyn ProtocolTrait>;
334        self.peer_pool.attach_protocol::<P>(Box::new(c)).await?;
335        self.advertise(P::id().as_bytes(), P::flags());
336        Ok(())
337    }
338
339    /// Attach the core protocols (PING). Called once during `run`.
340    async fn attach_core_protocols(self: &Arc<Self>) -> Result<()> {
341        self.attach_protocol(PingProtocol::new).await
342    }
343
344    /// Advertise an item (protocol id, swarm key, ...) through
345    /// discovery. See [`ProtocolFlags`]. Used by Swarm and other
346    /// layers.
347    pub fn advertise(&self, item: impl AsRef<[u8]>, flags: ProtocolFlags) {
348        self.discovery.advertise(item.as_ref(), flags);
349    }
350
351    /// Find peers in the routing table that may support `item`.
352    /// Useful for swarm-targeted lookups (e.g. "peers in this room")
353    /// without changing handshake semantics.
354    pub fn find_peers_with(&self, item: impl AsRef<[u8]>) -> Vec<DiscoveredPeer> {
355        self.discovery.find_peers_with(item.as_ref())
356    }
357
358    /// Returns the number of currently connected peers.
359    pub async fn peers(&self) -> usize {
360        self.peer_pool.peers_len().await
361    }
362
363    /// Returns the `Config`.
364    pub fn config(&self) -> Arc<Config> {
365        self.config.clone()
366    }
367
368    /// Returns the `PeerID`.
369    pub fn peer_id(&self) -> &PeerID {
370        &self.peer_id
371    }
372
373    /// Returns the `KeyPair`.
374    pub fn key_pair(&self) -> &KeyPair {
375        &self.key_pair
376    }
377
378    /// Returns a map of inbound connected peers with their endpoints.
379    pub async fn inbound_peers(&self) -> HashMap<PeerID, Endpoint> {
380        self.peer_pool.inbound_peers().await
381    }
382
383    /// Returns a map of outbound connected peers with their endpoints.
384    pub async fn outbound_peers(&self) -> HashMap<PeerID, Endpoint> {
385        self.peer_pool.outbound_peers().await
386    }
387
388    /// Returns the monitor to receive system events.
389    pub fn monitor(&self) -> Arc<Monitor> {
390        self.monitor.clone()
391    }
392
393    /// Register a listener for peer lifecycle events. Each call returns
394    /// a fresh listener that receives every event (true broadcast).
395    pub fn register_peer_events(&self) -> EventListener<PeerEventTopic, PeerEvent> {
396        self.peer_pool.register_peer_events()
397    }
398
399    /// Broadcast a message to a specific set of peers on a given protocol.
400    /// Used by Swarm and other layers to scope broadcasts.
401    pub async fn broadcast_to(
402        &self,
403        proto_id: &ProtocolID,
404        msg: Vec<u8>,
405        targets: &HashSet<PeerID>,
406    ) {
407        self.peer_pool.broadcast_to(proto_id, msg, targets).await;
408    }
409
410    /// Send a message to a specific peer on the given protocol.
411    /// Returns `PeerNotFound` if the peer is not currently connected.
412    pub async fn send_to(
413        &self,
414        peer_id: &PeerID,
415        proto_id: &ProtocolID,
416        msg: Vec<u8>,
417    ) -> Result<()> {
418        self.peer_pool.send_to(peer_id, proto_id, msg).await
419    }
420
421    /// Returns the negotiated protocol set for a connected peer, or
422    /// `None` if no peer with that id is currently in the pool.
423    pub async fn peer_protocol_set(&self, pid: &PeerID) -> Option<HashSet<ProtocolID>> {
424        self.peer_pool.peer_protocol_set(pid).await
425    }
426
427    /// Shuts down the Node.
428    pub async fn shutdown(&self) {
429        self.discovery.shutdown().await;
430        self.peer_pool.shutdown().await;
431        self.connector.shutdown().await;
432        self.listener.shutdown().await;
433        self.task_group.cancel().await;
434    }
435}