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//!
59
60mod apply;
61mod denied;
62mod either;
63mod error;
64mod pending;
65mod ready;
66mod select;
67
68pub(crate) use apply::{
69    apply, apply_inbound, apply_outbound, InboundUpgradeApply, OutboundUpgradeApply,
70};
71pub(crate) use error::UpgradeError;
72use futures::future::Future;
73
74pub use self::{
75    denied::DeniedUpgrade, pending::PendingUpgrade, ready::ReadyUpgrade, select::SelectUpgrade,
76};
77pub use crate::Negotiated;
78pub use multistream_select::{NegotiatedComplete, NegotiationError, ProtocolError, Version};
79
80/// Common trait for upgrades that can be applied on inbound substreams, outbound substreams,
81/// or both.
82pub trait UpgradeInfo {
83    /// Opaque type representing a negotiable protocol.
84    type Info: AsRef<str> + Clone;
85    /// Iterator returned by `protocol_info`.
86    type InfoIter: IntoIterator<Item = Self::Info>;
87
88    /// Returns the list of protocols that are supported. Used during the negotiation process.
89    fn protocol_info(&self) -> Self::InfoIter;
90}
91
92/// Possible upgrade on an inbound connection or substream.
93pub trait InboundUpgrade<C>: UpgradeInfo {
94    /// Output after the upgrade has been successfully negotiated and the handshake performed.
95    type Output;
96    /// Possible error during the handshake.
97    type Error;
98    /// Future that performs the handshake with the remote.
99    type Future: Future<Output = Result<Self::Output, Self::Error>>;
100
101    /// After we have determined that the remote supports one of the protocols we support, this
102    /// method is called to start the handshake.
103    ///
104    /// The `info` is the identifier of the protocol, as produced by `protocol_info`.
105    fn upgrade_inbound(self, socket: C, info: Self::Info) -> Self::Future;
106}
107
108/// Possible upgrade on an outbound connection or substream.
109pub trait OutboundUpgrade<C>: UpgradeInfo {
110    /// Output after the upgrade has been successfully negotiated and the handshake performed.
111    type Output;
112    /// Possible error during the handshake.
113    type Error;
114    /// Future that performs the handshake with the remote.
115    type Future: Future<Output = Result<Self::Output, Self::Error>>;
116
117    /// After we have determined that the remote supports one of the protocols we support, this
118    /// method is called to start the handshake.
119    ///
120    /// The `info` is the identifier of the protocol, as produced by `protocol_info`.
121    fn upgrade_outbound(self, socket: C, info: Self::Info) -> Self::Future;
122}
123
124/// Possible upgrade on an inbound connection
125pub trait InboundConnectionUpgrade<T>: UpgradeInfo {
126    /// Output after the upgrade has been successfully negotiated and the handshake performed.
127    type Output;
128    /// Possible error during the handshake.
129    type Error;
130    /// Future that performs the handshake with the remote.
131    type Future: Future<Output = Result<Self::Output, Self::Error>>;
132
133    /// After we have determined that the remote supports one of the protocols we support, this
134    /// method is called to start the handshake.
135    ///
136    /// The `info` is the identifier of the protocol, as produced by `protocol_info`.
137    fn upgrade_inbound(self, socket: T, info: Self::Info) -> Self::Future;
138}
139
140/// Possible upgrade on an outbound connection
141pub trait OutboundConnectionUpgrade<T>: UpgradeInfo {
142    /// Output after the upgrade has been successfully negotiated and the handshake performed.
143    type Output;
144    /// Possible error during the handshake.
145    type Error;
146    /// Future that performs the handshake with the remote.
147    type Future: Future<Output = Result<Self::Output, Self::Error>>;
148
149    /// After we have determined that the remote supports one of the protocols we support, this
150    /// method is called to start the handshake.
151    ///
152    /// The `info` is the identifier of the protocol, as produced by `protocol_info`.
153    fn upgrade_outbound(self, socket: T, info: Self::Info) -> Self::Future;
154}
libp2p_core/upgrade.rs

libp2p_core/
upgrade.rs
