feat: add custom protocols example (#93)

Adds an example of how to use libp2p to implement your own custom protocol

Author: achingbrain

.github/workflows/ci.yml

@@ -24,6 +24,7 @@ jobs:
           - js-libp2p-example-chat
           - js-libp2p-example-circuit-relay
           - js-libp2p-example-connection-encryption
+          - js-libp2p-example-custom-protocols
           - js-libp2p-example-delegated-routing
           - js-libp2p-example-discovery-mechanisms
     defaults:
@@ -77,6 +78,7 @@ jobs:
           - js-libp2p-example-chat
           - js-libp2p-example-circuit-relay
           - js-libp2p-example-connection-encryption
+          - js-libp2p-example-custom-protocols
           - js-libp2p-example-delegated-routing
           - js-libp2p-example-discovery-mechanisms
     steps:

README.md

@@ -48,10 +48,11 @@ Feel free to jump directly into the examples, however going through the followin
 
 #### Understanding how libp2p works
 
-- [Circuit Relay](./examples/js-libp2p-example-circuit-relay) - configuring Circuit Relay connections
-- [Connection Encryption](./examples/js-libp2p-example-connection-encryption) - how to encrypt connection between libp2p nodes
-- [Delegated routing](./examples/js-libp2p-example-delegated-routing) - how to offload network operations and queries onto more capable nodes
-- [Discovery mechanisms](./examples/js-libp2p-example-discovery-mechanisms) - how libp2p discovers other peers on the network
+- [Circuit Relay](https://github.com/libp2p/js-libp2p-example-circuit-relay) - configuring Circuit Relay connections
+- [Connection Encryption](https://github.com/libp2p/js-libp2p-example-connection-encryption) - how to encrypt connection between libp2p nodes
+- [Delegated routing](https://github.com/libp2p/js-libp2p-example-delegated-routing) - how to offload network operations and queries onto more capable nodes
+- [Discovery mechanisms](https://github.com/libp2p/js-libp2p-example-discovery-mechanisms) - how libp2p discovers other peers on the network
+- [Custom protocols](https://github.com/libp2p/js-libp2p-example-custom-protocols) - how to create a custom protocol for your application
 
 #### Other examples
 

examples/js-libp2p-example-custom-protocols/.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-custom-protocols/.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-custom-protocols/1-echo.js

@@ -0,0 +1,68 @@
+/* eslint-disable no-console */
+
+import { noise } from '@chainsafe/libp2p-noise'
+import { yamux } from '@chainsafe/libp2p-yamux'
+import { tcp } from '@libp2p/tcp'
+import { pipe } from 'it-pipe'
+import { createLibp2p } from 'libp2p'
+
+async function createNode () {
+  return await createLibp2p({
+    addresses: {
+      listen: [
+        '/ip4/0.0.0.0/tcp/0'
+      ]
+    },
+    connectionEncryption: [
+      noise()
+    ],
+    streamMuxers: [
+      yamux()
+    ],
+    transports: [
+      tcp()
+    ]
+  })
+}
+
+// create two nodes
+const remote = await createNode()
+const local = await createNode()
+
+// this is our protocol id
+const ECHO_PROTOCOL = '/echo/1.0.0'
+
+// the remote will handle incoming streams opened on the protocol
+await remote.handle(ECHO_PROTOCOL, ({ stream }) => {
+  // pipe the stream output back to the stream input
+  pipe(stream, stream)
+})
+
+// the local will dial the remote on the protocol stream
+const stream = await local.dialProtocol(remote.getMultiaddrs(), ECHO_PROTOCOL)
+
+// now it will write some data and read it back
+const output = await pipe(
+  async function * () {
+    // the stream input must be bytes
+    yield new TextEncoder().encode('hello world')
+  },
+  stream,
+  async (source) => {
+    let string = ''
+    const decoder = new TextDecoder()
+
+    for await (const buf of source) {
+      // buf is a `Uint8ArrayList` so we must turn it into a `Uint8Array`
+      // before decoding it
+      string += decoder.decode(buf.subarray())
+    }
+
+    return string
+  }
+)
+
+console.info(`Echoed back to us: "${output}"`)
+
+await remote.stop()
+await local.stop()

examples/js-libp2p-example-custom-protocols/2-request-response.js

@@ -0,0 +1,82 @@
+/* eslint-disable no-console */
+
+import { noise } from '@chainsafe/libp2p-noise'
+import { yamux } from '@chainsafe/libp2p-yamux'
+import { tcp } from '@libp2p/tcp'
+import { lpStream } from 'it-length-prefixed-stream'
+import { createLibp2p } from 'libp2p'
+
+async function createNode () {
+  return await createLibp2p({
+    addresses: {
+      listen: [
+        '/ip4/0.0.0.0/tcp/0'
+      ]
+    },
+    connectionEncryption: [
+      noise()
+    ],
+    streamMuxers: [
+      yamux()
+    ],
+    transports: [
+      tcp()
+    ]
+  })
+}
+
+// create two nodes
+const remote = await createNode()
+const local = await createNode()
+
+// this is our protocol id
+const REQ_RESP_PROTOCOL = '/request-response/1.0.0'
+
+// the remote will handle incoming streams opened on the protocol
+await remote.handle(REQ_RESP_PROTOCOL, ({ stream }) => {
+  Promise.resolve().then(async () => {
+    // lpStream lets us read/write in a predetermined order
+    const lp = lpStream(stream)
+
+    // read the incoming request
+    const req = await lp.read()
+
+    // deserialize the query
+    const query = JSON.parse(new TextDecoder().decode(req.subarray()))
+
+    if (query.question === 'What is the air-speed velocity of an unladen swallow?') {
+      // write the response
+      await lp.write(new TextEncoder().encode(JSON.stringify({
+        answer: 'Is that an African or a European swallow?'
+      })))
+    } else {
+      // write the response
+      await lp.write(new TextEncoder().encode(JSON.stringify({
+        error: "What? I don't know?!"
+      })))
+    }
+  })
+    .catch(err => {
+      stream.abort(err)
+    })
+})
+
+// the local will dial the remote on the protocol stream
+const stream = await local.dialProtocol(remote.getMultiaddrs(), REQ_RESP_PROTOCOL)
+
+// lpStream lets us read/write in a predetermined order
+const lp = lpStream(stream)
+
+// send the query
+await lp.write(new TextEncoder().encode(JSON.stringify({
+  question: 'What is the air-speed velocity of an unladen swallow?'
+})))
+
+// read the response
+const res = await lp.read()
+const output = JSON.parse(new TextDecoder().decode(res.subarray()))
+
+console.info(`The answer is: "${output.answer}"`)
+
+await remote.stop()
+await local.stop()

examples/js-libp2p-example-custom-protocols/LICENSE

@@ -0,0 +1,4 @@
+This project is dual licensed under MIT and Apache-2.0.
+
+MIT: https://www.opensource.org/licenses/mit
+Apache-2.0: https://www.apache.org/licenses/license-2.0

examples/js-libp2p-example-custom-protocols/LICENSE-APACHE

@@ -0,0 +1,5 @@
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

examples/js-libp2p-example-custom-protocols/LICENSE-MIT

@@ -0,0 +1,19 @@
+The MIT License (MIT)
+
+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.