darkfi/net/
mod.rs

1/* This file is part of DarkFi (https://dark.fi)
2 *
3 * Copyright (C) 2020-2026 Dyne.org foundation
4 *
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU Affero General Public License as
7 * published by the Free Software Foundation, either version 3 of the
8 * License, or (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 * GNU Affero General Public License for more details.
14 *
15 * You should have received a copy of the GNU Affero General Public License
16 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
17 */
18
19#[cfg(test)]
20mod tests;
21
22/// Defines how to decode generic messages as well as implementing the
23/// common network messages that are sent between nodes as described
24/// by the [`protocol`] submodule.
25///
26/// Implements a type called `Packet` which is the base message type.
27/// Packets are converted into messages and passed to an event loop.
28pub mod message;
29pub use message::Message;
30
31/// Generic publish/subscribe class that can dispatch any kind of message
32/// to a subscribed list of dispatchers.
33///
34/// Dispatchers subscribe to a single message format of any type. This is
35/// a generalized version of the simple publish-subscribe class in
36/// system::Publisher.
37///
38/// Message Subsystem also enables the creation of new message subsystems,
39/// adding new dispatchers and clearing inactive channels.
40///
41/// Message Subsystem maintains a list of dispatchers, which is a generalized
42/// version of a publisher. Pub-sub is called on dispatchers through the
43/// functions `subscribe` and `notify`. Whereas system::Publisher only allows
44/// messages of a single type, dispatchers can handle any kind of message. This
45/// generic message is called a payload and is processed and decoded by the
46/// Message Dispatcher.
47///
48/// The Message Dispatcher is a class of publishers that implement a generic
49/// trait called Message Dispatcher Interface, which allows us to process any
50/// kind of payload as a message.
51pub mod message_publisher;
52pub use message_publisher::MessageSubscription;
53
54/// Network transports, holds implementations of pluggable transports.
55/// Exposes agnostic dialers and agnostic listeners.
56pub mod transport;
57
58/// Port mapping protocols (UPnP, NAT-PMP, PCP)
59#[cfg(feature = "upnp-igd")]
60pub mod upnp;
61
62/// Hosts are a list of network addresses used when establishing outbound
63/// connections.
64///
65/// Hosts are shared across the network through the address protocol.
66/// When attempting to connect, a node will loop through addresses in the
67/// hosts store until it finds ones to connect to.
68pub mod hosts;
69
70/// Async channel that handles the sending of messages across the network.
71/// Public interface is used to create new channels, to stop and start a
72/// channel, and to send messages.
73pub mod channel;
74pub use channel::ChannelPtr;
75
76/// P2P provides all core functionality to interact with the P2P network.
77///
78/// Used to create a network, to start and run it, to broadcast messages
79/// across all channels, and to manage the channel store.
80///
81/// The channel store is a hashmap of channel addresses that we can use
82/// to add and remove channels or check whether a channel is already in
83/// the store.
84pub mod p2p;
85pub use p2p::{P2p, P2pPtr};
86
87/// Defines the networking protocol used at each stage in a connection.
88/// Consists of a series of messages that are sent across the network at
89/// the different connection stages.
90///
91/// When a node connects to a network for the first time, it must follow
92/// a seed protocol, which provides it with a list of network hosts to
93/// connect to. To establish a connection to another node, nodes must send
94/// version and version acknowledgement messages. During a connection, nodes
95/// continually get address and get-address messages to inform each other
96/// about what nodes are on the network. Nodes also send out a ping and pong
97/// message which keeps the network from shutting down.
98///
99/// Protocol submodule also implements a jobs manager that handles the
100/// asynchronous execution of the protocols.
101pub mod protocol;
102pub use protocol::{
103    protocol_base::{ProtocolBase, ProtocolBasePtr},
104    protocol_jobs_manager::{ProtocolJobsManager, ProtocolJobsManagerPtr},
105};
106
107/// Defines the interaction between nodes during a connection.
108///
109/// Consists of an inbound session, which describes how to set up an
110/// incoming connection, and an outbound session, which describes setting
111/// up an outbound connection. Also describes the sesd session, which is
112/// the type of connection used when a node connects to the network for
113/// the first time. Implements the `Session` trait which describes the
114/// common functions across all sessions.
115pub mod session;
116
117/// Handles the acceptance of inbound socket connections.
118/// Used to start listening on a local socket, to accept incoming connections,
119/// and to handle network errors.
120pub mod acceptor;
121
122/// Handles the creation of outbound connections.
123/// Used to establish an outbound connection.
124pub mod connector;
125
126/// Network configuration settings. This holds the configured P2P instance
127/// behaviour and is controlled by clients of this API.
128pub mod settings;
129pub use settings::{BanPolicy, Settings};
130
131/// Optional events based debug-notify subsystem. Off by default. Enabled in P2P instance,
132/// and then call `p2p.dnet_sub()` to start receiving events.
133#[macro_use]
134pub mod dnet;
135
136/// Metering related definitions.
137pub mod metering;
darkfi/net/mod.rs

darkfi/net/
mod.rs
