|
| 1 | +# libp2p-websocket-star-rendezvous |
| 2 | + |
| 3 | +[](http://ipn.io) |
| 4 | +[](http://libp2p.io/) |
| 5 | +[](http://webchat.freenode.net/?channels=%23libp2p) |
| 6 | +[](https://discuss.libp2p.io) |
| 7 | +[](https://codecov.io/gh/libp2p/js-libp2p-websocket-star-rendezvous) |
| 8 | +[](https://travis-ci.com/libp2p/js-libp2p-websocket-star-rendezvous) |
| 9 | +[](https://david-dm.org/libp2p/js-libp2p-websocket-star-rendezvous) |
| 10 | +[](https://github.com/feross/standard) |
| 11 | + |
| 12 | +> The rendezvous service for [libp2p-websocket-star](https://github.com/libp2p/js-libp2p-websocket-star). |
| 13 | +
|
| 14 | +## Lead Maintainer |
| 15 | + |
| 16 | +[Jacob Heun](https://github.com/jacobheun) |
| 17 | + |
| 18 | +## Descriptions |
| 19 | + |
| 20 | +Nodes using `libp2p-websocket-star` will connect to a known point in the network, a rendezvous point where they can learn about other nodes (Discovery) and route their messages to other nodes (2 hop message routing, also known as relay). |
| 21 | + |
| 22 | +## Usage |
| 23 | + |
| 24 | +`libp2p-websocket-star-rendezvous` is the rendezvous server required for `libp2p-websocket-star` and can be used to start a rendezvous server for development. To do that, first install the module globally in your machine with: |
| 25 | + |
| 26 | +```bash |
| 27 | +> npm install --global libp2p-websocket-star-rendezvous |
| 28 | +``` |
| 29 | + |
| 30 | +This will install a `rendezvous` CLI tool. Now you can spawn the server with: |
| 31 | + |
| 32 | +```bash |
| 33 | +> rendezvous --port=9090 --host=127.0.0.1 |
| 34 | +``` |
| 35 | + |
| 36 | +Defaults: |
| 37 | + |
| 38 | +- `port` - 9090 |
| 39 | +- `host` - '0.0.0.0' |
| 40 | + |
| 41 | +## Docker |
| 42 | + |
| 43 | +A docker image is offered for running this service in production |
| 44 | + |
| 45 | +``` |
| 46 | +docker pull libp2p/websocket-star-rendezvous:release |
| 47 | +docker run -d -p 9090:9090 --name rendezvous libp2p/websocket-star-rendezvous:release |
| 48 | +``` |
| 49 | + |
| 50 | +To disable prometheus metrics run the server with `-e DISABLE_METRICS=1` |
| 51 | + |
| 52 | +``` |
| 53 | +docker run -d -p 9090:9090 --name rendezvous -e DISABLE_METRICS=1 libp2p/websocket-star-rendezvous:release |
| 54 | +``` |
| 55 | + |
| 56 | +## Hosted Rendezvous server |
| 57 | + |
| 58 | +We host a rendezvous server at `ws-star.discovery.libp2p.io` that can be used for practical demos and experimentation, it **should not be used for apps in production**. |
| 59 | + |
| 60 | +A libp2p-websocket-star address, using the signalling server we provide, looks like: |
| 61 | + |
| 62 | +`/dns4/ws-star.discovery.libp2p.io/wss/p2p-websocket-star/ipfs/<your-peer-id>` |
| 63 | + |
| 64 | +Note: The address above indicates WebSockets Secure, which can be accessed from both http and https. |
| 65 | + |
| 66 | + |
| 67 | +### Using WSS |
| 68 | + |
| 69 | +To be able to interact with a rendezvous server from an HTTPS site, you will need to use websocket secure. To host a secure websocket server, you must provide a keypair to the server. |
| 70 | + |
| 71 | +#### Using key and certificate |
| 72 | + |
| 73 | +```bash |
| 74 | +> rendezvous --key="path/to/key.key" --cert="path/to/cert.cert" |
| 75 | +``` |
| 76 | + |
| 77 | +#### Using PFX with passphrase |
| 78 | + |
| 79 | +```bash |
| 80 | +> rendezvous --pfx="path/to/pair.pfx" --passphrase="passphrase" |
| 81 | +``` |
| 82 | + |
| 83 | + |
| 84 | +### This module uses `pull-streams` |
| 85 | + |
| 86 | +We expose a streaming interface based on `pull-streams`, rather then on the Node.js core streams implementation (aka Node.js streams). `pull-streams` offers us a better mechanism for error handling and flow control guarantees. If you would like to know more about why we did this, see the discussion at this [issue](https://github.com/ipfs/js-ipfs/issues/362). |
| 87 | + |
| 88 | +You can learn more about pull-streams at: |
| 89 | + |
| 90 | +- [The history of Node.js streams, nodebp April 2014](https://www.youtube.com/watch?v=g5ewQEuXjsQ) |
| 91 | +- [The history of streams, 2016](http://dominictarr.com/post/145135293917/history-of-streams) |
| 92 | +- [pull-streams, the simple streaming primitive](http://dominictarr.com/post/149248845122/pull-streams-pull-streams-are-a-very-simple) |
| 93 | +- [pull-streams documentation](https://pull-stream.github.io/) |
| 94 | + |
| 95 | +#### Converting `pull-streams` to Node.js Streams |
| 96 | + |
| 97 | +If you are a Node.js streams user, you can convert a pull-stream to a Node.js stream using the module [`pull-stream-to-stream`](https://github.com/pull-stream/pull-stream-to-stream), giving you an instance of a Node.js stream that is linked to the pull-stream. For example: |
| 98 | + |
| 99 | +```js |
| 100 | +const pullToStream = require('pull-stream-to-stream') |
| 101 | + |
| 102 | +const nodeStreamInstance = pullToStream(pullStreamInstance) |
| 103 | +// nodeStreamInstance is an instance of a Node.js Stream |
| 104 | +``` |
| 105 | + |
| 106 | +To learn more about this utility, visit https://pull-stream.github.io/#pull-stream-to-stream. |
| 107 | + |
| 108 | +LICENSE MIT |
0 commit comments