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}