misc/multistream-select: Implement simultaneous open extension

core/CHANGELOG.md

@@ -12,7 +12,43 @@
   Introduce `upgrade::read_length_prefixed` and `upgrade::write_length_prefixed`.
   See [PR 2111](https://github.com/libp2p/rust-libp2p/pull/2111).
 
+- Add support for multistream-select [simultaneous open extension] to assign _initiator_ and
+  _responder_ role during authentication protocol negotiation on simultaneously opened connection.
+
+  This is one important component of the greater effort to support hole punching in rust-libp2p.
+
+  - `Transport::upgrade` no longer takes a multistream-select `Version`. Instead the
+     multistream-select `Version`s `V1`, `V1Lazy` and `V1SimultaneousOpen` can be selected when
+     setting the authentication upgrade via `Builder::authenticate_with_version` and the
+     multistream-select `Version`s `V1` and `V1Lazy` can be selected when setting the multiplexing
+     upgrade via `Builder::multiplex_with_version`.
+
+     Users merely wanting to maintain the status quo should use the following call chain depending
+     on which `Version` they previously used:
+
+     - `Version::V1`
+
+       ```rust
+       my_transport.upgrade()
+         .authenticate(my_authentication)
+         .multiplex(my_multiplexer)
+       ```
+     - `Version::V1Lazy`
+
+       ```rust
+       my_transport.upgrade()
+         .authenticate_with_version(my_authentication, Version::V1Lazy)
+         .multiplex_with_version(my_multiplexer, Version::V1Lazy)
+       ```
+
+  - `Builder::multiplex_ext` is removed in favor of the new simultaneous open workflow. Please reach
+    out in case you depend on `Builder::multiplex_ext`.
+
+  See [PR 2066].
+
 [PR 2090]: https://github.com/libp2p/rust-libp2p/pull/2090
+[simultaneous open extension]: https://github.com/libp2p/specs/blob/master/connections/simopen.md
+[PR 2066]: https://github.com/libp2p/rust-libp2p/pull/2066
 
 # 0.28.3 [2021-04-26]
 

core/Cargo.toml

@@ -22,7 +22,7 @@ libsecp256k1 = { version = "0.5.0", optional = true }
 log = "0.4"
 multiaddr = { version = "0.12.0" }
 multihash = { version = "0.13", default-features = false, features = ["std", "multihash-impl", "identity", "sha2"] }
-multistream-select = { version = "0.10", path = "../misc/multistream-select" }
+multistream-select = { version = "0.11", path = "../misc/multistream-select" }
 parking_lot = "0.11.0"
 pin-project = "1.0.0"
 prost = "0.7"

core/src/transport.rs

@@ -46,7 +46,6 @@ pub use self::boxed::Boxed;
 pub use self::choice::OrTransport;
 pub use self::memory::MemoryTransport;
 pub use self::optional::OptionalTransport;
-pub use self::upgrade::Upgrade;
 
 /// A transport provides connection-oriented communication between two peers
 /// through ordered streams of data (i.e. connections).
@@ -196,12 +195,12 @@ pub trait Transport {
 
     /// Begins a series of protocol upgrades via an
     /// [`upgrade::Builder`](upgrade::Builder).
-    fn upgrade(self, version: upgrade::Version) -> upgrade::Builder<Self>
+    fn upgrade(self) -> upgrade::Builder<Self>
     where
         Self: Sized,
         Self::Error: 'static
     {
-        upgrade::Builder::new(self, version)
+        upgrade::Builder::new(self)
     }
 }