From 30e187465dce8cbd5136d1e4701b75ee56ba0950 Mon Sep 17 00:00:00 2001 From: Max Inden Date: Sun, 30 Jan 2022 14:05:43 +0100 Subject: [PATCH 1/7] src/tutorial: Move ping tutorial in tutorials --- src/lib.rs | 5 ++--- src/tutorials.rs | 2 ++ src/{tutorial.rs => tutorials/ping.rs} | 0 3 files changed, 4 insertions(+), 3 deletions(-) create mode 100644 src/tutorials.rs rename src/{tutorial.rs => tutorials/ping.rs} (100%) diff --git a/src/lib.rs b/src/lib.rs index b913a94121e..a9d8c3e9a45 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -24,11 +24,10 @@ //! [libp2p.io](https://libp2p.io/). //! //! To get started with this libp2p implementation in Rust, please take a look -//! at the [`tutorial`](crate::tutorial). Further examples can be found in the +//! at the [`tutorials`](crate::tutorials). Further examples can be found in the //! [examples] directory. //! //! [examples]: https://github.com/libp2p/rust-libp2p/tree/master/examples -//! [ping tutorial]: https://github.com/libp2p/rust-libp2p/tree/master/examples/ping.rs #![doc(html_logo_url = "https://libp2p.io/img/logo_small.png")] #![doc(html_favicon_url = "https://libp2p.io/img/favicon.png")] @@ -147,7 +146,7 @@ pub mod bandwidth; pub mod simple; #[cfg(doc)] -pub mod tutorial; +pub mod tutorials; pub use self::core::{ identity, diff --git a/src/tutorials.rs b/src/tutorials.rs new file mode 100644 index 00000000000..fd7f319fc7e --- /dev/null +++ b/src/tutorials.rs @@ -0,0 +1,2 @@ +pub mod hole_punching; +pub mod ping; diff --git a/src/tutorial.rs b/src/tutorials/ping.rs similarity index 100% rename from src/tutorial.rs rename to src/tutorials/ping.rs From 678cd5cd4649db63cc6fdff6d948697739d6ef95 Mon Sep 17 00:00:00 2001 From: Max Inden Date: Sun, 30 Jan 2022 14:06:03 +0100 Subject: [PATCH 2/7] src/tutorials: Add hole punching tutorial --- src/tutorials/hole_punching.rs | 146 +++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 src/tutorials/hole_punching.rs diff --git a/src/tutorials/hole_punching.rs b/src/tutorials/hole_punching.rs new file mode 100644 index 00000000000..9129d133d88 --- /dev/null +++ b/src/tutorials/hole_punching.rs @@ -0,0 +1,146 @@ +// Copyright 2022 Protocol Labs. +// +// Permission is hereby granted, free of charge, to any person obtaining a +// copy of this software and associated documentation files (the "Software"), +// to deal in the Software without restriction, including without limitation +// the rights to use, copy, modify, merge, publish, distribute, sublicense, +// and/or sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following conditions: +// +// The above copyright notice and this permission notice shall be included in +// all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +// DEALINGS IN THE SOFTWARE. + +//! # Hole Punching Tutorial +//! +//! This tutorial shows hands-on how to overcome firewalls and NATs with libp2p's hole punching +//! mechanism. Before we get started, please read the [blog post](TODO link to IPFS blog post) to +//! familiarize yourself with libp2p's hole punching mechanism on a conceptual level. +//! +//! We will be using the [Circuit Relay v2](crate::relay::v2) and the [Direct Connection +//! Upgrade through Relay (DCUtR)](crate::dcutr) protocol. +//! +//! TODO: What about the Autonat protocol? +//! +//! You will need 3 machines for this tutorial: +//! +//! - A relay server +//! - Any public server will do, e.g. a cloud provider VM. +//! - A listening client. +//! - Any computer connected to the internet, but not reachable from outside its own network, +//! works. +//! - This can e.g. be your friends laptop behind their router (firewall + NAT). +//! - This can e.g. be some cloud provider VM, shielded from incoming connections e.g. via +//! Linux's UFW on the same machine. +//! - Don't use a machine that is in the same network as the dialing client. (This would require +//! NAT hairpinning.) +//! - A dialing client. +//! - Like the above, any computer connected to the internet, but not reachable from the outside. +//! - Your local machine will likely fulfill these requirements. +//! +//! ## Setting up the relay server +//! +//! Hole punching requires a public relay node for the two private nodes to coordinate their hole +//! punch via. For that we need a public server somewhere in the Internet. In case you don't have +//! one already, any cloud provider VM will do. +//! +//! Either on the server directly, or on your local machine, compile the example relay server: +//! +//! ``` bash +//! ## Inside the rust-libp2p repository. +//! cargo build --example relay_v2 -p libp2p-relay +//! ``` +//! +//! You can find the binary at `target/debug/examples/relay_v2`. In case you built it locally, copy +//! it to your server. +//! +//! On your server, start the relay server binary: +//! +//! ``` bash +//! ./relay_v2 --port 4001 --secret-key-seed 0 +//! ``` +//! +//! Now let's make sure that the server is public, in other words let's make sure one can reach it +//! through the Internet. From the dialing client: +//! +//! 1. Test that you can connect on Layer 3 (IP). +//! +//! ``` bash +//! ping $RELAY_SERVER_IP +//! ``` +//! +//! 2. Test that you can connect on Layer 4 (TCP). +//! +//! ``` bash +//! telnet $RELAY_SERVER_IP 4001 +//! ``` +//! +//! 3. Test that you can connect via libp2p using [`libp2p-lookup`](https://github.com/mxinden/libp2p-lookup). +//! +//! ``` bash +//! ## For IPv4 +//! libp2p-lookup direct --address /ip4/$RELAY_SERVER_IP +//! ## For IPv6 +//! libp2p-lookup direct --address /ip6/$RELAY_SERVER_IP +//! ``` +//! +//! ## Setting up the listening client +//! +//! Either on the listening client machine directly, or on your local machine, compile the example +//! DCUtR client: +//! +//! ``` bash +//! ## Inside the rust-libp2p repository. +//! cargo build --example client -p libp2p-dcutr +//! ``` +//! +//! You can find the binary at `target/debug/examples/client`. In case you built it locally, copy +//! it to your listening client machine. +//! +//! On the listening client machine +//! +//! ``` bash +//! RUST_LOG=info ./client --secret-key-seed 1 --mode listen --relay-address /dns4/$RELAY_SERVER_IP/tcp/4001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN +//! ``` +//! +//! Now let's make sure that the listening client is not public, in other words let's make sure one can not reach it +//! through the Internet. From the dialing client test that you can not connect on Layer 4 (TCP): +//! +//! ``` bash +//! telnet $RELAY_SERVER_IP 4001 +//! ``` +//! +//! ## Connecting to the listening client from the dialing client +//! +//! ``` bash +//! RUST_LOG=info ./client --secret-key-seed 2 --mode dial --relay-address /dns4/$RELAY_SERVER_IP/tcp/4001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN --remote-peer-id 12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X +//! ``` +//! +//! You should see the following logs appear: +//! +//! 1. The dialing client establishing a relayed connection to the listening client via the relay +//! server. Note the [`/p2p-circuit` protocol](crate::multiaddr::Protocol::P2pCircuit) in the +//! [`Multiaddr`](crate::Multiaddr). +//! +//! ``` +//! [2022-01-30T12:54:10Z INFO client] Established connection to PeerId("12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X") via Dialer { address: "/ip4/$RELAY_PEER_ID/tcp/4001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN/p2p-circuit/p2p/12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X", role_override: Dialer } +//! ``` +//! +//! 2. The listening client initiating a direct connection upgrade for the new relayed connection. +//! +//! ``` +//! [2022-01-30T12:54:11Z INFO client] RemoteInitiatedDirectConnectionUpgrade { remote_peer_id: PeerId("12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X"), remote_relayed_addr: "/ip4/$RELAY_PEER_ID/tcp/4001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN/p2p-circuit/p2p/12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X" } +//! ``` +//! +//! 3. The direct connection upgrade, also known as hole punch, succeeding. +//! +//! ``` +//! [2022-01-30T12:54:11Z INFO client] DirectConnectionUpgradeSucceeded { remote_peer_id: PeerId("12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X") } +//! ``` From 0b67e1738659684f3c6c5af03cd453ca4fe6808a Mon Sep 17 00:00:00 2001 From: Max Inden Date: Sun, 30 Jan 2022 14:21:15 +0100 Subject: [PATCH 3/7] src/tutorials/hole_punching: Add TODO on type references --- src/tutorials/hole_punching.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/tutorials/hole_punching.rs b/src/tutorials/hole_punching.rs index 9129d133d88..88336c88f54 100644 --- a/src/tutorials/hole_punching.rs +++ b/src/tutorials/hole_punching.rs @@ -125,6 +125,8 @@ //! //! You should see the following logs appear: //! +//! TODO: Link to each concrete to type to make sure the below stays up to date on renames. +//! //! 1. The dialing client establishing a relayed connection to the listening client via the relay //! server. Note the [`/p2p-circuit` protocol](crate::multiaddr::Protocol::P2pCircuit) in the //! [`Multiaddr`](crate::Multiaddr). From 9adc0eb43506f20dec4f8975879b3f423b798000 Mon Sep 17 00:00:00 2001 From: Max Inden Date: Fri, 4 Feb 2022 17:53:57 +0100 Subject: [PATCH 4/7] src/tutorials/hole-punching: Link to DCUtR Event --- src/tutorials/hole_punching.rs | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/tutorials/hole_punching.rs b/src/tutorials/hole_punching.rs index 88336c88f54..c46f3214c0e 100644 --- a/src/tutorials/hole_punching.rs +++ b/src/tutorials/hole_punching.rs @@ -27,8 +27,6 @@ //! We will be using the [Circuit Relay v2](crate::relay::v2) and the [Direct Connection //! Upgrade through Relay (DCUtR)](crate::dcutr) protocol. //! -//! TODO: What about the Autonat protocol? -//! //! You will need 3 machines for this tutorial: //! //! - A relay server @@ -110,8 +108,9 @@ //! RUST_LOG=info ./client --secret-key-seed 1 --mode listen --relay-address /dns4/$RELAY_SERVER_IP/tcp/4001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN //! ``` //! -//! Now let's make sure that the listening client is not public, in other words let's make sure one can not reach it -//! through the Internet. From the dialing client test that you can not connect on Layer 4 (TCP): +//! Now let's make sure that the listening client is not public, in other words let's make sure one +//! can not reach it directly through the Internet. From the dialing client test that you can not +//! connect on Layer 4 (TCP): //! //! ``` bash //! telnet $RELAY_SERVER_IP 4001 @@ -136,12 +135,16 @@ //! ``` //! //! 2. The listening client initiating a direct connection upgrade for the new relayed connection. +//! Reported by [`dcutr`](crate::dcutr) through +//! [`Event::RemoteInitiatedDirectConnectionUpgrade`](crate::dcutr::behaviour::Event::RemoteInitiatedDirectConnectionUpgrade). //! //! ``` //! [2022-01-30T12:54:11Z INFO client] RemoteInitiatedDirectConnectionUpgrade { remote_peer_id: PeerId("12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X"), remote_relayed_addr: "/ip4/$RELAY_PEER_ID/tcp/4001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN/p2p-circuit/p2p/12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X" } //! ``` //! -//! 3. The direct connection upgrade, also known as hole punch, succeeding. +//! 3. The direct connection upgrade, also known as hole punch, succeeding. Reported by +//! [`dcutr`](crate::dcutr) through +//! [`Event::RemoteInitiatedDirectConnectionUpgrade`](crate::dcutr::behaviour::Event::DirectConnectionUpgradeSucceeded). //! //! ``` //! [2022-01-30T12:54:11Z INFO client] DirectConnectionUpgradeSucceeded { remote_peer_id: PeerId("12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X") } From a3dd971ebedde6143b8e06b16c58d4779314d49e Mon Sep 17 00:00:00 2001 From: Max Inden Date: Wed, 9 Feb 2022 16:29:11 +0100 Subject: [PATCH 5/7] .github/: Run cargo doc with all features --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4e6a51d4af0..3bf167db8f5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -101,7 +101,7 @@ jobs: - uses: Swatinem/rust-cache@842ef286fff290e445b90b4002cc9807c3669641 # v1.3.0 - name: Check rustdoc links - run: RUSTDOCFLAGS="--deny broken_intra_doc_links" cargo doc --verbose --workspace --no-deps --document-private-items + run: RUSTDOCFLAGS="--deny broken_intra_doc_links" cargo doc --verbose --workspace --no-deps --document-private-items --all-features check-clippy: runs-on: ubuntu-18.04 From 96a4ee38766911f7f549ef6896e2dfa80af4b78b Mon Sep 17 00:00:00 2001 From: Max Inden Date: Wed, 9 Feb 2022 20:23:03 +0100 Subject: [PATCH 6/7] src/tutorials: Link to IPFS blog post pull request --- src/tutorials/hole_punching.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/tutorials/hole_punching.rs b/src/tutorials/hole_punching.rs index c46f3214c0e..ae1337d7c33 100644 --- a/src/tutorials/hole_punching.rs +++ b/src/tutorials/hole_punching.rs @@ -21,8 +21,9 @@ //! # Hole Punching Tutorial //! //! This tutorial shows hands-on how to overcome firewalls and NATs with libp2p's hole punching -//! mechanism. Before we get started, please read the [blog post](TODO link to IPFS blog post) to -//! familiarize yourself with libp2p's hole punching mechanism on a conceptual level. +//! mechanism. Before we get started, please read the [blog +//! post](https://github.com/ipfs/ipfs-blog/pull/375) to familiarize yourself with libp2p's hole +//! punching mechanism on a conceptual level. //! //! We will be using the [Circuit Relay v2](crate::relay::v2) and the [Direct Connection //! Upgrade through Relay (DCUtR)](crate::dcutr) protocol. @@ -124,8 +125,6 @@ //! //! You should see the following logs appear: //! -//! TODO: Link to each concrete to type to make sure the below stays up to date on renames. -//! //! 1. The dialing client establishing a relayed connection to the listening client via the relay //! server. Note the [`/p2p-circuit` protocol](crate::multiaddr::Protocol::P2pCircuit) in the //! [`Multiaddr`](crate::Multiaddr). From 818d7184bf2394f7e48f92c2482f8acf2fdb7177 Mon Sep 17 00:00:00 2001 From: Max Inden Date: Thu, 10 Feb 2022 13:58:22 +0100 Subject: [PATCH 7/7] src/tutorials: Add ignore to doc codes --- src/tutorials/hole_punching.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/tutorials/hole_punching.rs b/src/tutorials/hole_punching.rs index ae1337d7c33..3c24c61ebf0 100644 --- a/src/tutorials/hole_punching.rs +++ b/src/tutorials/hole_punching.rs @@ -129,7 +129,7 @@ //! server. Note the [`/p2p-circuit` protocol](crate::multiaddr::Protocol::P2pCircuit) in the //! [`Multiaddr`](crate::Multiaddr). //! -//! ``` +//! ``` ignore //! [2022-01-30T12:54:10Z INFO client] Established connection to PeerId("12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X") via Dialer { address: "/ip4/$RELAY_PEER_ID/tcp/4001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN/p2p-circuit/p2p/12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X", role_override: Dialer } //! ``` //! @@ -137,7 +137,7 @@ //! Reported by [`dcutr`](crate::dcutr) through //! [`Event::RemoteInitiatedDirectConnectionUpgrade`](crate::dcutr::behaviour::Event::RemoteInitiatedDirectConnectionUpgrade). //! -//! ``` +//! ``` ignore //! [2022-01-30T12:54:11Z INFO client] RemoteInitiatedDirectConnectionUpgrade { remote_peer_id: PeerId("12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X"), remote_relayed_addr: "/ip4/$RELAY_PEER_ID/tcp/4001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN/p2p-circuit/p2p/12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X" } //! ``` //! @@ -145,6 +145,6 @@ //! [`dcutr`](crate::dcutr) through //! [`Event::RemoteInitiatedDirectConnectionUpgrade`](crate::dcutr::behaviour::Event::DirectConnectionUpgradeSucceeded). //! -//! ``` +//! ``` ignore //! [2022-01-30T12:54:11Z INFO client] DirectConnectionUpgradeSucceeded { remote_peer_id: PeerId("12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X") } //! ```