libp2p_core/
upgrade.rs

1// Copyright 2018 Parity Technologies (UK) Ltd.
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//! Contains everything related to upgrading a connection or a substream to use a protocol.
22//!
23//! After a connection with a remote has been successfully established or a substream successfully
24//! opened, the next step is to *upgrade* this connection or substream to use a protocol.
25//!
26//! This is where the `UpgradeInfo`, `InboundUpgrade` and `OutboundUpgrade` traits come into play.
27//! The `InboundUpgrade` and `OutboundUpgrade` traits are implemented on types that represent a
28//! collection of one or more possible protocols for respectively an ingoing or outgoing
29//! connection or substream.
30//!
31//! > **Note**: Multiple versions of the same protocol are treated as different protocols.
32//! > For example, `/foo/1.0.0` and `/foo/1.1.0` are totally unrelated as far as
33//! > upgrading is concerned.
34//!
35//! # Upgrade process
36//!
37//! An upgrade is performed in two steps:
38//!
39//! - A protocol negotiation step. The `UpgradeInfo::protocol_info` method is called to determine
40//!   which protocols are supported by the trait implementation. The `multistream-select` protocol
41//!   is used in order to agree on which protocol to use amongst the ones supported.
42//!
43//! - A handshake. After a successful negotiation, the `InboundUpgrade::upgrade_inbound` or
44//!   `OutboundUpgrade::upgrade_outbound` method is called. This method will return a `Future` that
45//!   performs a handshake. This handshake is considered mandatory, however in practice it is
46//!   possible for the trait implementation to return a dummy `Future` that doesn't perform any
47//!   action and immediately succeeds.
48//!
49//! After an upgrade is successful, an object of type `InboundUpgrade::Output` or
50//! `OutboundUpgrade::Output` is returned. The actual object depends on the implementation and
51//! there is no constraint on the traits that it should implement, however it is expected that it
52//! can be used by the user to control the behaviour of the protocol.
53//!
54//! > **Note**: You can use the `apply_inbound` or `apply_outbound` methods to try upgrade a
55//! > connection or substream. However if you use the recommended `Swarm` or
56//! > `ConnectionHandler` APIs, the upgrade is automatically handled for you and you don't
57//! > need to use these methods.
58
59mod apply;
60mod denied;
61mod either;
62mod error;
63mod pending;
64mod ready;
65mod select;
66
67pub(crate) use apply::{
68    apply, apply_inbound, apply_outbound, InboundUpgradeApply, OutboundUpgradeApply,
69};
70pub(crate) use error::UpgradeError;
71use futures::future::Future;
72pub use multistream_select::{NegotiatedComplete, NegotiationError, ProtocolError, Version};
73
74pub use self::{
75    denied::DeniedUpgrade, pending::PendingUpgrade, ready::ReadyUpgrade, select::SelectUpgrade,
76};
77pub use crate::Negotiated;
78
79/// Common trait for upgrades that can be applied on inbound substreams, outbound substreams,
80/// or both.
81pub trait UpgradeInfo {
82    /// Opaque type representing a negotiable protocol.
83    type Info: AsRef<str> + Clone;
84    /// Iterator returned by `protocol_info`.
85    type InfoIter: IntoIterator<Item = Self::Info>;
86
87    /// Returns the list of protocols that are supported. Used during the negotiation process.
88    fn protocol_info(&self) -> Self::InfoIter;
89}
90
91/// Possible upgrade on an inbound connection or substream.
92pub trait InboundUpgrade<C>: UpgradeInfo {
93    /// Output after the upgrade has been successfully negotiated and the handshake performed.
94    type Output;
95    /// Possible error during the handshake.
96    type Error;
97    /// Future that performs the handshake with the remote.
98    type Future: Future<Output = Result<Self::Output, Self::Error>>;
99
100    /// After we have determined that the remote supports one of the protocols we support, this
101    /// method is called to start the handshake.
102    ///
103    /// The `info` is the identifier of the protocol, as produced by `protocol_info`.
104    fn upgrade_inbound(self, socket: C, info: Self::Info) -> Self::Future;
105}
106
107/// Possible upgrade on an outbound connection or substream.
108pub trait OutboundUpgrade<C>: UpgradeInfo {
109    /// Output after the upgrade has been successfully negotiated and the handshake performed.
110    type Output;
111    /// Possible error during the handshake.
112    type Error;
113    /// Future that performs the handshake with the remote.
114    type Future: Future<Output = Result<Self::Output, Self::Error>>;
115
116    /// After we have determined that the remote supports one of the protocols we support, this
117    /// method is called to start the handshake.
118    ///
119    /// The `info` is the identifier of the protocol, as produced by `protocol_info`.
120    fn upgrade_outbound(self, socket: C, info: Self::Info) -> Self::Future;
121}
122
123/// Possible upgrade on an inbound connection
124pub trait InboundConnectionUpgrade<T>: UpgradeInfo {
125    /// Output after the upgrade has been successfully negotiated and the handshake performed.
126    type Output;
127    /// Possible error during the handshake.
128    type Error;
129    /// Future that performs the handshake with the remote.
130    type Future: Future<Output = Result<Self::Output, Self::Error>>;
131
132    /// After we have determined that the remote supports one of the protocols we support, this
133    /// method is called to start the handshake.
134    ///
135    /// The `info` is the identifier of the protocol, as produced by `protocol_info`.
136    fn upgrade_inbound(self, socket: T, info: Self::Info) -> Self::Future;
137}
138
139/// Possible upgrade on an outbound connection
140pub trait OutboundConnectionUpgrade<T>: UpgradeInfo {
141    /// Output after the upgrade has been successfully negotiated and the handshake performed.
142    type Output;
143    /// Possible error during the handshake.
144    type Error;
145    /// Future that performs the handshake with the remote.
146    type Future: Future<Output = Result<Self::Output, Self::Error>>;
147
148    /// After we have determined that the remote supports one of the protocols we support, this
149    /// method is called to start the handshake.
150    ///
151    /// The `info` is the identifier of the protocol, as produced by `protocol_info`.
152    fn upgrade_outbound(self, socket: T, info: Self::Info) -> Self::Future;
153}
libp2p_core/upgrade.rs

libp2p_core/
upgrade.rs
