feat: add WebRTC private to private example (#173)

Restores old example of WebRTC between two browsers

Author: achingbrain

.github/workflows/ci.yml

@@ -27,6 +27,7 @@ jobs:
           - js-libp2p-example-custom-protocols
           - js-libp2p-example-delegated-routing
           - js-libp2p-example-discovery-mechanisms
+          - js-libp2p-example-webrtc-private-to-private
     defaults:
       run:
         working-directory: examples/${{ matrix.project }}
@@ -81,6 +82,7 @@ jobs:
           - js-libp2p-example-custom-protocols
           - js-libp2p-example-delegated-routing
           - js-libp2p-example-discovery-mechanisms
+          - js-libp2p-example-webrtc-private-to-private
     steps:
       - uses: convictional/trigger-workflow-and-wait@f69fa9eedd3c62a599220f4d5745230e237904be
         with:

examples/js-libp2p-example-webrtc-private-to-private/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+# ⚠️ IMPORTANT ⚠️
+
+# Please do not create a Pull Request for this repository
+
+The contents of this repository are automatically synced from the parent [js-libp2p Examples Project](https://github.com/libp2p/js-libp2p-examples) so any changes made to the standalone repository will be lost after the next sync.
+
+Please open a PR against [js-libp2p Examples](https://github.com/libp2p/js-libp2p-examples) instead.
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+
+1. Fork the [js-libp2p Examples Project](https://github.com/libp2p/js-libp2p-examples)
+2. Create your Feature Branch (`git checkout -b feature/amazing-example`)
+3. Commit your Changes (`git commit -a -m 'feat: add some amazing example'`)
+4. Push to the Branch (`git push origin feature/amazing-example`)
+5. Open a Pull Request

examples/js-libp2p-example-webrtc-private-to-private/.github/workflows/sync.yml

@@ -0,0 +1,19 @@
+name: pull
+
+on:
+  workflow_dispatch
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Pull from another repository
+        uses: ipfs-examples/actions-pull-directory-from-repo@main
+        with:
+          source-repo: libp2p/js-libp2p-examples
+          source-folder-path: examples/${{ github.event.repository.name }}
+          source-branch: main
+          target-branch: main
+          git-username: github-actions
+          git-email: [email protected]

examples/js-libp2p-example-webrtc-private-to-private/README.md

@@ -0,0 +1,95 @@
+# @libp2p/example-webrtc-private-to-private
+
+[![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/)
+[![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io)
+[![codecov](https://img.shields.io/codecov/c/github/libp2p/js-libp2p-examples.svg?style=flat-square)](https://codecov.io/gh/libp2p/js-libp2p-examples)
+[![CI](https://img.shields.io/github/actions/workflow/status/libp2p/js-libp2p-examples/ci.yml?branch=main\&style=flat-square)](https://github.com/libp2p/js-libp2p-examples/actions/workflows/ci.yml?query=branch%3Amain)
+
+In libp2p terms a "private" node is one behind a [NAT firewall](https://en.wikipedia.org/wiki/Network_address_translation) that prevents it from being dialed externally.
+
+This could be a browser, a node.js process or something else.
+
+Nodes that support the [libp2p WebRTC transport](https://github.com/libp2p/specs/blob/master/webrtc/webrtc.md) such as browsers can by dialed via this method even if they are behind a NAT.
+
+When establishing a WebRTC connection, the two browsers must first exchange a series of messages that establish the required capabilities of the nodes (we only require RTC data channels, no video or audio), and their internet-facing addresses/ports.
+
+This is referred to as the "SDP handshake". The WebRTC spec requires this to take place out-of-band, so libp2p performs the handshake via a [Circuit Relay Server](https://docs.libp2p.io/concepts/nat/circuit-relay/) - this is another network node that has made some resources available for the good of the network.
+
+When two browsers dial each other the following steps occur:
+
+1. The listener makes a reservation on a relay with a free slot
+2. The dialer obtains the listener's relay address
+3. The dialer dials the relay and specifies the listeners PeerId as part of the Circuit Relay HOP protocol
+4. The relay opens a stream on the listener as part of the Circuit Relay STOP protocol
+5. A virtual connection is created between the dialer and the listener via the relay
+6. The dialer opens a stream on the virtual connection to perform the SDP handshake
+7. SDP messages are exchanged
+8. A direct WebRTC connection is opened between the two browsers
+
+At this point the browsers are directly connected and the relay plays no further part.
+
+## Running the Example
+
+### Build the `@libp2p/example-webrtc-private-to-private` package
+
+Build example by calling `npm i && npm run build` in the repository root.
+
+### Running the Relay Server
+
+For browsers to communicate, we first need to run a relay server:
+
+```shell
+npm run relay
+```
+
+The [multiaddress](https://docs.libp2p.io/concepts/fundamentals/addressing/) the relay is listening on will be printed to the console. Copy one of them to your clipboard.
+
+### Running the Clients
+
+In a separate console tab, start the web server:
+
+```shell
+npm start
+```
+
+A browser window will automatically open.  Let's call this `Browser A`.
+
+Using the copied multiaddrs from the relay server, paste it into the `Remote MultiAddress` input and click the `Connect` button.
+`Browser A` is now connected to the relay server.
+
+Copy the multiaddr located after the `Listening on` message.
+
+Now open a second tab with the url `http://localhost:5173/`, perhaps in a different browser or a private window.  Let's call this `Browser B`.
+
+Using the copied multiaddress from `Listening on` section in `Browser A`, paste it into the `Remote MultiAddress` input and click the `Connect` button.
+
+The peers are now connected to each other.
+
+Enter a message and click the `Send` button in either/both browsers and see the echo'd messages.
+
+The output should look like:
+
+`Browser A`
+```text
+Dialing '/ip4/127.0.0.1/tcp/57708/ws/p2p/12D3KooWRqAUEzPwKMoGstpfJVqr3aoinwKVPu4DLo9nQncbnuLk'
+Listening on /ip4/127.0.0.1/tcp/57708/ws/p2p/12D3KooWRqAUEzPwKMoGstpfJVqr3aoinwKVPu4DLo9nQncbnuLk/p2p-circuit/p2p/12D3KooW9wFiWFELqGJTbzEwtByXsPiHJdHB8n7Kin71VMYyERmC/p2p-circuit/webrtc/p2p/12D3KooW9wFiWFELqGJTbzEwtByXsPiHJdHB8n7Kin71VMYyERmC
+Dialing '/ip4/127.0.0.1/tcp/57708/ws/p2p/12D3KooWRqAUEzPwKMoGstpfJVqr3aoinwKVPu4DLo9nQncbnuLk/p2p-circuit/p2p/12D3KooWBZyVLJfQkofqLK4op9TPkHuUumCZt1ybQrPvNm7TVQV9/p2p-circuit/webrtc/p2p/12D3KooWBZyVLJfQkofqLK4op9TPkHuUumCZt1ybQrPvNm7TVQV9'
+Sending message 'helloa'
+Received message 'helloa'
+Received message 'hellob'
+```
+
+`Browser B`
+```text
+Dialing '/ip4/127.0.0.1/tcp/57708/ws/p2p/12D3KooWRqAUEzPwKMoGstpfJVqr3aoinwKVPu4DLo9nQncbnuLk/p2p-circuit/p2p/12D3KooW9wFiWFELqGJTbzEwtByXsPiHJdHB8n7Kin71VMYyERmC/p2p-circuit/webrtc/p2p/12D3KooW9wFiWFELqGJTbzEwtByXsPiHJdHB8n7Kin71VMYyERmC'
+Listening on /ip4/127.0.0.1/tcp/57708/ws/p2p/12D3KooWRqAUEzPwKMoGstpfJVqr3aoinwKVPu4DLo9nQncbnuLk/p2p-circuit/p2p/12D3KooWBZyVLJfQkofqLK4op9TPkHuUumCZt1ybQrPvNm7TVQV9/p2p-circuit/webrtc/p2p/12D3KooWBZyVLJfQkofqLK4op9TPkHuUumCZt1ybQrPvNm7TVQV9
+Received message 'helloa'
+Sending message 'hellob'
+Received message 'hellob'
+```
+
+## Next steps
+
+The WebRTC transport is not limited to browsers.
+
+Why don't you try to create a Node.js version of the [browser peer script](./index.js)?

examples/js-libp2p-example-webrtc-private-to-private/index.html

@@ -0,0 +1,50 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>js-libp2p WebRTC</title>
+    <style>
+      label,
+      button {
+        display: block;
+        font-weight: bold;
+        margin: 5px 0;
+      }
+      div {
+        margin-bottom: 20px;
+      }
+      #send-section {
+        display: none;
+      }
+      input[type="text"] {
+        width: 800px;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app">
+      <div>
+        <label for="peer">Remote MultiAddress:</label>
+        <input type="text" id="peer" />
+        <button id="connect">Connect</button>
+      </div>
+      <div id="send-section">
+        <label for="message">Message:</label>
+        <input type="text" id="message" value="hello" />
+        <button id="send">Send</button>
+      </div>
+      <div id="connectionsWrapper">
+        <h3>Active Connections:</h3>
+        <ul id="connections"></ul>
+      </div>
+      <div id="listeningAddressesWrapper">
+        <h3>Listening addresses:</h3>
+        <ul id="multiaddrs"></ul>
+      </div>
+      <h3>Output:</h3>
+      <div id="output"></div>
+    </div>
+    <script type="module" src="./index.js"></script>
+  </body>
+</html>

examples/js-libp2p-example-webrtc-private-to-private/index.js

@@ -0,0 +1,173 @@
+import { noise } from '@chainsafe/libp2p-noise'
+import { yamux } from '@chainsafe/libp2p-yamux'
+import { circuitRelayTransport } from '@libp2p/circuit-relay-v2'
+import { identify, identifyPush } from '@libp2p/identify'
+import { ping } from '@libp2p/ping'
+import { webRTC } from '@libp2p/webrtc'
+import { webSockets } from '@libp2p/websockets'
+import * as filters from '@libp2p/websockets/filters'
+import { multiaddr, protocols } from '@multiformats/multiaddr'
+import { byteStream } from 'it-byte-stream'
+import { createLibp2p } from 'libp2p'
+import { fromString, toString } from 'uint8arrays'
+
+const WEBRTC_CODE = protocols('webrtc').code
+
+const output = document.getElementById('output')
+const sendSection = document.getElementById('send-section')
+const appendOutput = (line) => {
+  const div = document.createElement('div')
+  div.appendChild(document.createTextNode(line))
+  output.append(div)
+}
+const CHAT_PROTOCOL = '/libp2p/examples/chat/1.0.0'
+let ma
+let chatStream
+
+const node = await createLibp2p({
+  addresses: {
+    listen: [
+      '/webrtc'
+    ]
+  },
+  transports: [
+    webSockets({
+      filter: filters.all
+    }),
+    webRTC(),
+    circuitRelayTransport({
+      discoverRelays: 1
+    })
+  ],
+  connectionEncrypters: [noise()],
+  streamMuxers: [yamux()],
+  connectionGater: {
+    denyDialMultiaddr: () => {
+      // by default we refuse to dial local addresses from the browser since they
+      // are usually sent by remote peers broadcasting undialable multiaddrs but
+      // here we are explicitly connecting to a local node so do not deny dialing
+      // any discovered address
+      return false
+    }
+  },
+  services: {
+    identify: identify(),
+    identifyPush: identifyPush(),
+    ping: ping()
+  }
+})
+
+await node.start()
+
+function updateConnList () {
+  // Update connections list
+  const connListEls = node.getConnections()
+    .map((connection) => {
+      if (connection.remoteAddr.protoCodes().includes(WEBRTC_CODE)) {
+        ma = connection.remoteAddr
+        sendSection.style.display = 'block'
+      }
+
+      const el = document.createElement('li')
+      el.textContent = connection.remoteAddr.toString()
+      return el
+    })
+  document.getElementById('connections').replaceChildren(...connListEls)
+}
+
+node.addEventListener('connection:open', (event) => {
+  updateConnList()
+})
+node.addEventListener('connection:close', (event) => {
+  updateConnList()
+})
+
+node.addEventListener('self:peer:update', (event) => {
+  // Update multiaddrs list, only show WebRTC addresses
+  const multiaddrs = node.getMultiaddrs()
+    .filter(ma => isWebrtc(ma))
+    .map((ma) => {
+      const el = document.createElement('li')
+      el.textContent = ma.toString()
+      return el
+    })
+  document.getElementById('multiaddrs').replaceChildren(...multiaddrs)
+})
+
+node.handle(CHAT_PROTOCOL, async ({ stream }) => {
+  chatStream = byteStream(stream)
+
+  while (true) {
+    const buf = await chatStream.read()
+    appendOutput(`Received message '${toString(buf.subarray())}'`)
+  }
+})
+
+const isWebrtc = (ma) => {
+  return ma.protoCodes().includes(WEBRTC_CODE)
+}
+
+window.connect.onclick = async () => {
+  ma = multiaddr(window.peer.value)
+  appendOutput(`Dialing '${ma}'`)
+
+  const signal = AbortSignal.timeout(5000)
+
+  try {
+    if (isWebrtc(ma)) {
+      const rtt = await node.services.ping.ping(ma, {
+        signal
+      })
+      appendOutput(`Connected to '${ma}'`)
+      appendOutput(`RTT to ${ma.getPeerId()} was ${rtt}ms`)
+    } else {
+      await node.dial(ma, {
+        signal
+      })
+      appendOutput('Connected to relay')
+    }
+  } catch (err) {
+    if (signal.aborted) {
+      appendOutput(`Timed out connecting to '${ma}'`)
+    } else {
+      appendOutput(`Connecting to '${ma}' failed - ${err.message}`)
+    }
+  }
+}
+
+window.send.onclick = async () => {
+  if (chatStream == null) {
+    appendOutput('Opening chat stream')
+
+    const signal = AbortSignal.timeout(5000)
+
+    try {
+      const stream = await node.dialProtocol(ma, CHAT_PROTOCOL, {
+        signal
+      })
+      chatStream = byteStream(stream)
+
+      Promise.resolve().then(async () => {
+        while (true) {
+          const buf = await chatStream.read()
+          appendOutput(`Received message '${toString(buf.subarray())}'`)
+        }
+      })
+    } catch (err) {
+      if (signal.aborted) {
+        appendOutput('Timed out opening chat stream')
+      } else {
+        appendOutput(`Opening chat stream failed - ${err.message}`)
+      }
+
+      return
+    }
+  }
+
+  const message = window.message.value.toString().trim()
+  appendOutput(`Sending message '${message}'`)
+  chatStream.write(fromString(message))
+    .catch(err => {
+      appendOutput(`Error sending message - ${err.message}`)
+    })
+}