feat(core): deprecate {In,Out}boundUpgradeExt

These functions were only used for some code in the interop-tests which is easily mitigated and perhaps even easier to understand now. We can thus deprecate these functions and their related types and thereby reduce the API surface of `libp2p-core` and the maintenance burden.

This change is motivated by the work around making protocols always strings which requires/required updates to all these upgrades.

Related #3806.
Related #3271.
Related #3745.

Pull-Request: #3807.

core/CHANGELOG.md

@@ -4,7 +4,11 @@
   If you depend on it, we suggest you vendor it.
   See [PR 3747].
 
+- Deprecate `{In,Out}boundUpgradeExt`, as they are not used in rust-libp2p.
+  See [PR 3807].
+
 [PR 3747]: https://github.com/libp2p/rust-libp2p/pull/3747
+[PR 3807]: https://github.com/libp2p/rust-libp2p/pull/3807
 
 ## 0.39.1
 

core/src/upgrade.rs

@@ -77,7 +77,6 @@ pub use self::{
     apply::{apply, apply_inbound, apply_outbound, InboundUpgradeApply, OutboundUpgradeApply},
     denied::DeniedUpgrade,
     error::UpgradeError,
-    map::{MapInboundUpgrade, MapInboundUpgradeErr, MapOutboundUpgrade, MapOutboundUpgradeErr},
     optional::OptionalUpgrade,
     pending::PendingUpgrade,
     ready::ReadyUpgrade,
@@ -87,6 +86,9 @@ pub use self::{
 pub use crate::Negotiated;
 pub use multistream_select::{NegotiatedComplete, NegotiationError, ProtocolError, Version};
 
+#[allow(deprecated)]
+pub use map::{MapInboundUpgrade, MapInboundUpgradeErr, MapOutboundUpgrade, MapOutboundUpgradeErr};
+
 /// Types serving as protocol names.
 ///
 /// # Context
@@ -164,6 +166,10 @@ pub trait InboundUpgrade<C>: UpgradeInfo {
 
 /// Extension trait for `InboundUpgrade`. Automatically implemented on all types that implement
 /// `InboundUpgrade`.
+#[deprecated(
+    note = "Will be removed without replacement because it is not used within rust-libp2p."
+)]
+#[allow(deprecated)]
 pub trait InboundUpgradeExt<C>: InboundUpgrade<C> {
     /// Returns a new object that wraps around `Self` and applies a closure to the `Output`.
     fn map_inbound<F, T>(self, f: F) -> MapInboundUpgrade<Self, F>
@@ -184,6 +190,7 @@ pub trait InboundUpgradeExt<C>: InboundUpgrade<C> {
     }
 }
 
+#[allow(deprecated)]
 impl<C, U: InboundUpgrade<C>> InboundUpgradeExt<C> for U {}
 
 /// Possible upgrade on an outbound connection or substream.
@@ -204,6 +211,10 @@ pub trait OutboundUpgrade<C>: UpgradeInfo {
 
 /// Extention trait for `OutboundUpgrade`. Automatically implemented on all types that implement
 /// `OutboundUpgrade`.
+#[deprecated(
+    note = "Will be removed without replacement because it is not used within rust-libp2p."
+)]
+#[allow(deprecated)]
 pub trait OutboundUpgradeExt<C>: OutboundUpgrade<C> {
     /// Returns a new object that wraps around `Self` and applies a closure to the `Output`.
     fn map_outbound<F, T>(self, f: F) -> MapOutboundUpgrade<Self, F>
@@ -224,4 +235,5 @@ pub trait OutboundUpgradeExt<C>: OutboundUpgrade<C> {
     }
 }
 
+#[allow(deprecated)]
 impl<C, U: OutboundUpgrade<C>> OutboundUpgradeExt<C> for U {}

core/src/upgrade/map.rs

@@ -18,12 +18,15 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
+#![allow(deprecated)]
+
 use crate::upgrade::{InboundUpgrade, OutboundUpgrade, UpgradeInfo};
 use futures::prelude::*;
 use std::{pin::Pin, task::Context, task::Poll};
 
 /// Wraps around an upgrade and applies a closure to the output.
 #[derive(Debug, Clone)]
+#[deprecated(note = "Deprecated without replacement because it is not used within rust-libp2p.")]
 pub struct MapInboundUpgrade<U, F> {
     upgrade: U,
     fun: F,
@@ -79,6 +82,7 @@ where
 
 /// Wraps around an upgrade and applies a closure to the output.
 #[derive(Debug, Clone)]
+#[deprecated(note = "Deprecated without replacement because it is not used within rust-libp2p.")]
 pub struct MapOutboundUpgrade<U, F> {
     upgrade: U,
     fun: F,
@@ -134,6 +138,7 @@ where
 
 /// Wraps around an upgrade and applies a closure to the error.
 #[derive(Debug, Clone)]
+#[deprecated(note = "Deprecated without replacement because it is not used within rust-libp2p.")]
 pub struct MapInboundUpgradeErr<U, F> {
     upgrade: U,
     fun: F,
@@ -189,6 +194,7 @@ where
 
 /// Wraps around an upgrade and applies a closure to the error.
 #[derive(Debug, Clone)]
+#[deprecated(note = "Deprecated without replacement because it is not used within rust-libp2p.")]
 pub struct MapOutboundUpgradeErr<U, F> {
     upgrade: U,
     fun: F,

interop-tests/src/bin/ping.rs

@@ -5,16 +5,13 @@ use std::time::{Duration, Instant};
 use anyhow::{bail, Context, Result};
 use either::Either;
 use env_logger::{Env, Target};
-use futures::{future, AsyncRead, AsyncWrite, StreamExt};
+use futures::StreamExt;
 use libp2p::core::muxing::StreamMuxerBox;
-use libp2p::core::upgrade::{MapInboundUpgrade, MapOutboundUpgrade, Version};
-use libp2p::noise::{NoiseOutput, X25519Spec, XX};
+use libp2p::core::upgrade::Version;
 use libp2p::swarm::{keep_alive, NetworkBehaviour, SwarmEvent};
-use libp2p::tls::TlsStream;
 use libp2p::websocket::WsConfig;
 use libp2p::{
-    identity, noise, ping, swarm::SwarmBuilder, tcp, tls, yamux, InboundUpgradeExt, Multiaddr,
-    OutboundUpgradeExt, PeerId, Transport as _,
+    identity, noise, ping, swarm::SwarmBuilder, tcp, tls, yamux, Multiaddr, PeerId, Transport as _,
 };
 use libp2p_mplex as mplex;
 use libp2p_quic as quic;
@@ -45,32 +42,56 @@ async fn main() -> Result<()> {
     let client = redis::Client::open(redis_addr).context("Could not connect to redis")?;
 
     // Build the transport from the passed ENV var.
-    let (boxed_transport, local_addr) = match transport_param {
-        Transport::QuicV1 => (
+    let (boxed_transport, local_addr) = match (transport_param, from_env("security")) {
+        (Transport::QuicV1, _) => (
             quic::tokio::Transport::new(quic::Config::new(&local_key))
                 .map(|(p, c), _| (p, StreamMuxerBox::new(c)))
                 .boxed(),
             format!("/ip4/{ip}/udp/0/quic-v1"),
         ),
-        Transport::Tcp => (
+        (Transport::Tcp, Ok(SecProtocol::Tls)) => (
             tcp::tokio::Transport::new(tcp::Config::new())
                 .upgrade(Version::V1Lazy)
-                .authenticate(secure_channel_protocol_from_env(&local_key)?)
+                .authenticate(tls::Config::new(&local_key).context("failed to initialise tls")?)
                 .multiplex(muxer_protocol_from_env()?)
                 .timeout(Duration::from_secs(5))
                 .boxed(),
             format!("/ip4/{ip}/tcp/0"),
         ),
-        Transport::Ws => (
+        (Transport::Tcp, Ok(SecProtocol::Noise)) => (
+            tcp::tokio::Transport::new(tcp::Config::new())
+                .upgrade(Version::V1Lazy)
+                .authenticate(
+                    noise::NoiseAuthenticated::xx(&local_key)
+                        .context("failed to intialise noise")?,
+                )
+                .multiplex(muxer_protocol_from_env()?)
+                .timeout(Duration::from_secs(5))
+                .boxed(),
+            format!("/ip4/{ip}/tcp/0"),
+        ),
+        (Transport::Ws, Ok(SecProtocol::Tls)) => (
+            WsConfig::new(tcp::tokio::Transport::new(tcp::Config::new()))
+                .upgrade(Version::V1Lazy)
+                .authenticate(tls::Config::new(&local_key).context("failed to initialise tls")?)
+                .multiplex(muxer_protocol_from_env()?)
+                .timeout(Duration::from_secs(5))
+                .boxed(),
+            format!("/ip4/{ip}/tcp/0/ws"),
+        ),
+        (Transport::Ws, Ok(SecProtocol::Noise)) => (
             WsConfig::new(tcp::tokio::Transport::new(tcp::Config::new()))
                 .upgrade(Version::V1Lazy)
-                .authenticate(secure_channel_protocol_from_env(&local_key)?)
+                .authenticate(
+                    noise::NoiseAuthenticated::xx(&local_key)
+                        .context("failed to intialise noise")?,
+                )
                 .multiplex(muxer_protocol_from_env()?)
                 .timeout(Duration::from_secs(5))
                 .boxed(),
             format!("/ip4/{ip}/tcp/0/ws"),
         ),
-        Transport::WebRtcDirect => (
+        (Transport::WebRtcDirect, _) => (
             webrtc::tokio::Transport::new(
                 local_key,
                 webrtc::tokio::Certificate::generate(&mut rand::thread_rng())?,
@@ -79,6 +100,8 @@ async fn main() -> Result<()> {
             .boxed(),
             format!("/ip4/{ip}/udp/0/webrtc-direct"),
         ),
+        (Transport::Tcp, Err(_)) => bail!("Missing security protocol for TCP transport"),
+        (Transport::Ws, Err(_)) => bail!("Missing security protocol for Websocket transport"),
     };
 
     let mut swarm = SwarmBuilder::with_tokio_executor(
@@ -164,43 +187,6 @@ async fn main() -> Result<()> {
     Ok(())
 }
 
-fn secure_channel_protocol_from_env<C: AsyncRead + AsyncWrite + Unpin + Send + 'static>(
-    identity: &identity::Keypair,
-) -> Result<
-    MapOutboundUpgrade<
-        MapInboundUpgrade<
-            Either<noise::NoiseAuthenticated<XX, X25519Spec, ()>, tls::Config>,
-            MapSecOutputFn<C>,
-        >,
-        MapSecOutputFn<C>,
-    >,
-> {
-    let either_sec_upgrade = match from_env("security")? {
-        SecProtocol::Noise => Either::Left(
-            noise::NoiseAuthenticated::xx(identity).context("failed to intialise noise")?,
-        ),
-        SecProtocol::Tls => {
-            Either::Right(tls::Config::new(identity).context("failed to initialise tls")?)
-        }
-    };
-
-    Ok(either_sec_upgrade
-        .map_inbound(factor_peer_id as MapSecOutputFn<C>)
-        .map_outbound(factor_peer_id as MapSecOutputFn<C>))
-}
-
-type SecOutput<C> = future::Either<(PeerId, NoiseOutput<C>), (PeerId, TlsStream<C>)>;
-type MapSecOutputFn<C> = fn(SecOutput<C>) -> (PeerId, future::Either<NoiseOutput<C>, TlsStream<C>>);
-
-fn factor_peer_id<C>(
-    output: SecOutput<C>,
-) -> (PeerId, future::Either<NoiseOutput<C>, TlsStream<C>>) {
-    match output {
-        future::Either::Left((peer, stream)) => (peer, future::Either::Left(stream)),
-        future::Either::Right((peer, stream)) => (peer, future::Either::Right(stream)),
-    }
-}
-
 fn muxer_protocol_from_env() -> Result<Either<yamux::YamuxConfig, mplex::MplexConfig>> {
     Ok(match from_env("muxer")? {
         Muxer::Yamux => Either::Left(yamux::YamuxConfig::default()),

libp2p/src/lib.rs

@@ -167,9 +167,11 @@ pub mod bandwidth;
 #[cfg(doc)]
 pub mod tutorials;
 
+#[allow(deprecated)]
+pub use self::core::upgrade::{InboundUpgradeExt, OutboundUpgradeExt};
 pub use self::core::{
     transport::TransportError,
-    upgrade::{InboundUpgrade, InboundUpgradeExt, OutboundUpgrade, OutboundUpgradeExt},
+    upgrade::{InboundUpgrade, OutboundUpgrade},
     Transport,
 };
 pub use self::multiaddr::{multiaddr as build_multiaddr, Multiaddr};