Skip to main content

karyon_p2p/
config.rs

1use std::{net::IpAddr, sync::Arc};
2
3use karyon_net::Endpoint;
4
5use crate::{
6    Version,
7    access_control::{AccessControl, AllowAll},
8};
9
10/// Configuration for the p2p network.
11///
12/// `dial_peers` are static peers dialed directly (use for fixed
13/// topologies). `bootstrap_peers` are seeds for the default Kademlia
14/// discovery; the DHT grows the connection set from there. Custom
15/// `Discovery` implementations may interpret `bootstrap_peers`
16/// differently or ignore it. Pick one, or combine.
17///
18/// # Example
19///
20/// ```
21/// use karyon_p2p::Config;
22///
23/// let config = Config {
24///     listen_endpoints: vec![
25///         "tcp://0.0.0.0:8000".parse().unwrap(),
26///     ],
27///     discovery_endpoints: vec![
28///         "tcp://0.0.0.0:7000".parse().unwrap(),
29///         "udp://0.0.0.0:7000".parse().unwrap(),
30///     ],
31///     bootstrap_peers: vec![
32///         "tcp://seed.example.com:7000".parse().unwrap(),
33///     ],
34///     ..Config::default()
35/// };
36/// ```
37pub struct Config {
38    /// Represents the network version.
39    pub version: Version,
40
41    /// Enable monitor
42    pub enable_monitor: bool,
43
44    /// Policy deciding who this node talks to. Defaults to `AllowAll`.
45    pub access_control: Arc<dyn AccessControl>,
46
47    /////////////////
48    // PeerPool
49    ////////////////
50    /// Timeout duration for the handshake with new peers, in seconds.
51    /// Applied twice on an inbound connection: once for the transport
52    /// handshake (TLS, or the first QUIC stream), then once for the
53    /// protocol handshake.
54    pub handshake_timeout: u64,
55    /// Interval at which the ping protocol sends ping messages to a peer to
56    /// maintain connections, in seconds.
57    pub ping_interval: u64,
58    /// Timeout duration for receiving the pong message corresponding to the
59    /// sent ping message, in seconds.
60    pub ping_timeout: u64,
61    /// The maximum number of retries for outbound connection establishment.
62    pub max_connect_retries: usize,
63
64    /////////////////
65    // DISCOVERY
66    ////////////////
67    //
68    // Discovery is pluggable via the `Discovery` trait. The default
69    // implementation is `KademliaDiscovery`, which is what the fields
70    // below describe. Custom implementations may interpret these fields
71    // differently or ignore them entirely.
72    //
73    /// A list of bootstrap peers for the seeding process.
74    pub bootstrap_peers: Vec<Endpoint>,
75    /// Endpoints to listen on for incoming peer connections.
76    /// e.g. [tcp://0.0.0.0:8000, quic://0.0.0.0:9000]
77    pub listen_endpoints: Vec<Endpoint>,
78    /// Endpoints used by the discovery service (Kademlia by default).
79    ///
80    /// Kademlia needs two sockets that serve different roles:
81    /// - one stream endpoint for the lookup service
82    ///   (`tcp://`, `tls://`, or `quic://` when the `quic` feature is on).
83    ///   Handles short-lived FIND_NODE / Ping queries from other peers.
84    /// - one `udp://` endpoint for the refresh service.
85    ///   Handles UDP liveness pings against routing-table entries.
86    ///
87    /// Either provide both (one of each kind) or leave the vector empty
88    /// to disable Kademlia-style DHT discovery and rely on
89    /// `dial_peers` + `bootstrap_peers` for static peering.
90    ///
91    /// e.g. [tcp://0.0.0.0:7000, udp://0.0.0.0:7000]
92    pub discovery_endpoints: Vec<Endpoint>,
93    /// A list of endpoints representing peers that the `Discovery` will
94    /// manually connect to.
95    pub dial_peers: Vec<Endpoint>,
96    /// This node's public IP, if known (e.g. learned with karyon_stun).
97    ///
98    /// When set, discovery advertises it in place of the IP of every listen
99    /// and discovery endpoint of the same family. Ports are kept as
100    /// configured, so they must be reachable from outside (port
101    /// forwarding). `None` (the default) advertises endpoints as
102    /// configured.
103    pub public_ip: Option<IpAddr>,
104    /// The number of available inbound slots for incoming connections.
105    pub inbound_slots: usize,
106    /// The number of available outbound slots for outgoing connections.
107    pub outbound_slots: usize,
108    /// Time interval, in seconds, at which the Discovery restarts the
109    /// seeding process.
110    pub seeding_interval: u64,
111
112    /////////////////
113    // LOOKUP
114    ////////////////
115    /// The number of available inbound slots for incoming connections during
116    /// the lookup process.
117    pub lookup_inbound_slots: usize,
118    /// The number of available outbound slots for outgoing connections during
119    /// the lookup process.
120    pub lookup_outbound_slots: usize,
121    /// Timeout duration for a peer response during the lookup process, in
122    /// seconds.
123    pub lookup_response_timeout: u64,
124    /// Maximum allowable time for a live connection with a peer during the
125    /// lookup process, in seconds.
126    pub lookup_connection_lifespan: u64,
127    /// The maximum number of retries for outbound connection establishment
128    /// during the lookup process.
129    pub lookup_connect_retries: usize,
130
131    /////////////////
132    // REFRESH
133    ////////////////
134    /// Interval at which the table refreshes its entries, in seconds.
135    pub refresh_interval: u64,
136    /// Timeout duration for a peer response during the table refresh process,
137    /// in seconds.
138    pub refresh_response_timeout: u64,
139    /// The maximum number of retries for outbound connection establishment
140    /// during the refresh process.
141    pub refresh_connect_retries: usize,
142}
143
144impl Default for Config {
145    fn default() -> Self {
146        Config {
147            version: "0.2.0".parse().unwrap(),
148
149            enable_monitor: false,
150            access_control: Arc::new(AllowAll),
151
152            handshake_timeout: 4,
153            ping_interval: 20,
154            ping_timeout: 2,
155
156            bootstrap_peers: vec![],
157            listen_endpoints: vec![],
158            discovery_endpoints: vec![],
159            dial_peers: vec![],
160            public_ip: None,
161            inbound_slots: 12,
162            outbound_slots: 12,
163            max_connect_retries: 3,
164            seeding_interval: 60,
165
166            lookup_inbound_slots: 20,
167            lookup_outbound_slots: 20,
168            lookup_response_timeout: 1,
169            lookup_connection_lifespan: 3,
170            lookup_connect_retries: 3,
171
172            refresh_interval: 1800,
173            refresh_response_timeout: 1,
174            refresh_connect_retries: 3,
175        }
176    }
177}