litep2p/protocol/
mod.rs

1// Copyright 2023 litep2p developers
2//
3// Permission is hereby granted, free of charge, to any person obtaining a
4// copy of this software and associated documentation files (the "Software"),
5// to deal in the Software without restriction, including without limitation
6// the rights to use, copy, modify, merge, publish, distribute, sublicense,
7// and/or sell copies of the Software, and to permit persons to whom the
8// Software is furnished to do so, subject to the following conditions:
9//
10// The above copyright notice and this permission notice shall be included in
11// all copies or substantial portions of the Software.
12//
13// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
14// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
18// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
19// DEALINGS IN THE SOFTWARE.
20
21//! Protocol-related defines.
22
23use crate::{
24    codec::ProtocolCodec,
25    error::SubstreamError,
26    substream::Substream,
27    transport::Endpoint,
28    types::{protocol::ProtocolName, SubstreamId},
29    PeerId,
30};
31
32use multiaddr::Multiaddr;
33
34use std::fmt::Debug;
35
36pub(crate) use connection::Permit;
37pub(crate) use protocol_set::{InnerTransportEvent, ProtocolCommand, ProtocolSet};
38
39pub use transport_service::TransportService;
40
41pub mod libp2p;
42pub mod mdns;
43pub mod notification;
44pub mod request_response;
45
46mod connection;
47mod protocol_set;
48mod transport_service;
49
50/// Substream direction.
51#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
52pub enum Direction {
53    /// Substream was opened by the remote peer.
54    Inbound,
55
56    /// Substream was opened by the local peer.
57    Outbound(SubstreamId),
58}
59
60/// Events emitted by one of the installed transports to protocol(s).
61#[derive(Debug)]
62pub enum TransportEvent {
63    /// Connection established to `peer`.
64    ConnectionEstablished {
65        /// Peer ID.
66        peer: PeerId,
67
68        /// Endpoint.
69        endpoint: Endpoint,
70    },
71
72    /// Connection closed to peer.
73    ConnectionClosed {
74        /// Peer ID.
75        peer: PeerId,
76    },
77
78    /// Failed to dial peer.
79    ///
80    /// This is reported to that protocol which initiated the connection.
81    DialFailure {
82        /// Peer ID.
83        peer: PeerId,
84
85        /// Dialed address.
86        address: Multiaddr,
87    },
88
89    /// Substream opened for `peer`.
90    SubstreamOpened {
91        /// Peer ID.
92        peer: PeerId,
93
94        /// Protocol name.
95        ///
96        /// One protocol handler may handle multiple sub-protocols (such as `/ipfs/identify/1.0.0`
97        /// and `/ipfs/identify/push/1.0.0`) or it may have aliases which should be handled by
98        /// the same protocol handler. When the substream is sent from transport to the protocol
99        /// handler, the protocol name that was used to negotiate the substream is also sent so
100        /// the protocol can handle the substream appropriately.
101        protocol: ProtocolName,
102
103        /// Fallback protocol.
104        fallback: Option<ProtocolName>,
105
106        /// Substream direction.
107        ///
108        /// Informs the protocol whether the substream is inbound (opened by the remote node)
109        /// or outbound (opened by the local node). This allows the protocol to distinguish
110        /// between the two types of substreams and execute correct code for the substream.
111        ///
112        /// Outbound substreams also contain the substream ID which allows the protocol to
113        /// distinguish between different outbound substreams.
114        direction: Direction,
115
116        /// Substream.
117        substream: Substream,
118    },
119
120    /// Failed to open substream.
121    ///
122    /// Substream open failures are reported only for outbound substreams.
123    SubstreamOpenFailure {
124        /// Substream ID.
125        substream: SubstreamId,
126
127        /// Error that occurred when the substream was being opened.
128        error: SubstreamError,
129    },
130}
131
132/// Trait defining the interface for a user protocol.
133#[async_trait::async_trait]
134pub trait UserProtocol: Send {
135    /// Get user protocol name.
136    fn protocol(&self) -> ProtocolName;
137
138    /// Get user protocol codec.
139    fn codec(&self) -> ProtocolCodec;
140
141    /// Start the the user protocol event loop.
142    async fn run(self: Box<Self>, service: TransportService) -> crate::Result<()>;
143}
litep2p/protocol/mod.rs

litep2p/protocol/
mod.rs
