|
1 | 1 | # js-libp2p-circuit |
| 2 | + |
| 3 | +[](http://ipn.io) |
| 4 | +[](http://webchat.freenode.net/?channels=%23ipfs) |
| 5 | +[](https://travis-ci.org/libp2p/js-libp2p-circuit) |
| 6 | +[](https://coveralls.io/github/libp2p/js-libp2p-circuit?branch=master) |
| 7 | +[](https://david-dm.org/libp2p/js-libp2p-circuit) |
| 8 | +[](https://github.com/feross/standard) |
| 9 | + |
| 10 | + |
| 11 | + |
| 12 | + |
| 13 | + |
| 14 | + |
| 15 | +> Node.js implementation of the Circuit module that libp2p uses, which implements the [interface-connection](https://github.com/libp2p/interface-connection) interface for dial/listen. |
| 16 | +
|
| 17 | +`libp2p-circuit` implements the circuit-relay mechanism that allows nodes that don't speak the same protocol to communicate using a third _relay_ node. |
| 18 | + |
| 19 | +**Note:** This module uses [pull-streams](https://pull-stream.github.io) for all stream based interfaces. |
| 20 | + |
| 21 | +### Why? |
| 22 | + |
| 23 | +`circuit-relaying` uses additional nodes in order to transfer traffic between two otherwise unreachable nodes. This allows nodes that don't speak the same protocols or are running in limited environments, e.g. browsers and IoT devices, to communicate, which would otherwise be impossible given the fact that for example browsers don't have any socket support and as such cannot be directly dialed. |
| 24 | + |
| 25 | +The applicability of circuit-relaying is not limited to routing traffic between browser nodes, other uses include: |
| 26 | + - routing traffic between private nets |
| 27 | + - circumventing NAT layers |
| 28 | + - route mangling for better privacy (matreshka/shallot dialing). |
| 29 | + |
| 30 | + It's also possible to use it for clients that implement exotic transports such as devices that only have bluetooth radios to be reachable over bluethoot enabled relays and become full p2p nodes. |
| 31 | + |
| 32 | +### libp2p-circuit and IPFS |
| 33 | + |
| 34 | +Prior to `libp2p-circuit` there was a rift in the IPFS network, were IPFS nodes could only access content from nodes that speak the same protocol, for example TCP only nodes could only dial to other TCP only nodes, same for any other protocol combination. In practice, this limitation was most visible in JS-IPFS browser nodes, since they can only dial out but not be dialed in over WebRTC or WebSockets, hence any content that the browser node held was not reachable by the rest of the network even through it was announced on the DHT. Non browser IPFS nodes would usually speak more than one protocol such as TCP, WebSockets and/or WebRTC, this made the problem less severe outside of the browser. `libp2p-circuit` solves this problem completely, as long as there are `relay nodes` capable of routing traffic between those nodes their content should be available to the rest of the IPFS network. |
| 35 | + |
| 36 | +## Table of Contents |
| 37 | + |
| 38 | +- [Install](#install) |
| 39 | + - [npm](#npm) |
| 40 | +- [Usage](#usage) |
| 41 | + - [Example](#example) |
| 42 | + - [This module uses `pull-streams`](#this-module-uses-pull-streams) |
| 43 | + - [Converting `pull-streams` to Node.js Streams](#converting-pull-streams-to-nodejs-streams) |
| 44 | +- [API](#api) |
| 45 | +- [Contribute](#contribute) |
| 46 | +- [License](#license) |
| 47 | + |
| 48 | +## Install |
| 49 | + |
| 50 | +### npm |
| 51 | + |
| 52 | +```sh |
| 53 | +> npm i libp2p-circuit |
| 54 | +``` |
| 55 | + |
| 56 | +## Usage |
| 57 | + |
| 58 | +### Example |
| 59 | + |
| 60 | +#### Create dialer/listener |
| 61 | + |
| 62 | +```js |
| 63 | +const Circuit = require('libp2p-circuit') |
| 64 | +const multiaddr = require('multiaddr') |
| 65 | +const pull = require('pull-stream') |
| 66 | + |
| 67 | +const mh1 = multiaddr('/p2p-circuit/ipfs/QmHash') // dial /ipfs/QmHash over any circuit |
| 68 | + |
| 69 | +const circuit = new Circuit(swarmInstance, options) // pass swarm instance and options |
| 70 | + |
| 71 | +const listener = circuit.createListener(mh1, (connection) => { |
| 72 | + console.log('new connection opened') |
| 73 | + pull( |
| 74 | + pull.values(['hello']), |
| 75 | + socket |
| 76 | + ) |
| 77 | +}) |
| 78 | + |
| 79 | +listener.listen(() => { |
| 80 | + console.log('listening') |
| 81 | + |
| 82 | + pull( |
| 83 | + circuit.dial(mh1), |
| 84 | + pull.log, |
| 85 | + pull.onEnd(() => { |
| 86 | + circuit.close() |
| 87 | + }) |
| 88 | + ) |
| 89 | +}) |
| 90 | +``` |
| 91 | + |
| 92 | +Outputs: |
| 93 | + |
| 94 | +```sh |
| 95 | +listening |
| 96 | +new connection opened |
| 97 | +hello |
| 98 | +``` |
| 99 | + |
| 100 | +#### Create `relay` |
| 101 | + |
| 102 | +```js |
| 103 | +const Relay = require('libp2p-circuit').Realy |
| 104 | + |
| 105 | +const relay = new Relay(options) |
| 106 | + |
| 107 | +relay.mount(swarmInstance) // start relaying traffic |
| 108 | +``` |
| 109 | + |
| 110 | +### This module uses `pull-streams` |
| 111 | + |
| 112 | +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). |
| 113 | + |
| 114 | +You can learn more about pull-streams at: |
| 115 | + |
| 116 | +- [The history of Node.js streams, nodebp April 2014](https://www.youtube.com/watch?v=g5ewQEuXjsQ) |
| 117 | +- [The history of streams, 2016](http://dominictarr.com/post/145135293917/history-of-streams) |
| 118 | +- [pull-streams, the simple streaming primitive](http://dominictarr.com/post/149248845122/pull-streams-pull-streams-are-a-very-simple) |
| 119 | +- [pull-streams documentation](https://pull-stream.github.io/) |
| 120 | + |
| 121 | +#### Converting `pull-streams` to Node.js Streams |
| 122 | + |
| 123 | +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/dominictarr/pull-stream-to-stream), giving you an instance of a Node.js stream that is linked to the pull-stream. For example: |
| 124 | + |
| 125 | +```js |
| 126 | +const pullToStream = require('pull-stream-to-stream') |
| 127 | + |
| 128 | +const nodeStreamInstance = pullToStream(pullStreamInstance) |
| 129 | +// nodeStreamInstance is an instance of a Node.js Stream |
| 130 | +``` |
| 131 | + |
| 132 | +To learn more about this utility, visit https://pull-stream.github.io/#pull-stream-to-stream. |
| 133 | + |
| 134 | +## API |
| 135 | + |
| 136 | +[](https://github.com/libp2p/interface-transport) |
| 137 | + |
| 138 | +`libp2p-circuit` accepts Circuit addresses for both IPFS and non IPFS encapsulated addresses, i.e: |
| 139 | + |
| 140 | +`/p2p-circuit/ip4/127.0.0.1/tcp/4001/ipfs/QmHash` |
| 141 | + |
| 142 | +Both for dialing and listening. |
| 143 | + |
| 144 | +### Implementation rational |
| 145 | + |
| 146 | +This module is not a transport, however it implements `interface-transport` interface in order to allow circuit to be plugged with `libp2p-swarm`. The rational behind it is that, `libp2p-circuit` has a dial and listen flow, which fits nicely with other transports, moreover, it requires the _raw_ connection to be encrypted and muxed just as a regular transport's connection does. All in all, `interface-transport` ended up being the correct level of abstraction for circuit, as well as allowed us to reuse existing integration points in `libp2p-swarm` and `libp2p` without adding any ad-hoc logic. All parts of `interface-transport` are used, including `.getAddr` which returns a list of `/p2p-circuit` addresses that circuit is currently listening. |
| 147 | + |
| 148 | +``` |
| 149 | + |
| 150 | + libp2p libp2p-circuit |
| 151 | ++-------------------------------------------------+ +---------------------------------------------------------+ |
| 152 | +| | | | |
| 153 | +| +---------------------------------+ | | | |
| 154 | +| | | | | +------------------------+ | |
| 155 | +| | | | circuit-relay registers the /hop | | | | |
| 156 | +| | libp2p-swarm |<----------------------------------------------------->| circuit-relay | | |
| 157 | +| | | | multistream handler with the swarm | | | | |
| 158 | +| | | | to handle incomming dial requests | +------------------------+ | |
| 159 | +| +---------------------------------+ | from other nodes | transport | |
| 160 | +| ^ ^ ^ ^ ^ ^ | | +-------------------------------------------+ | |
| 161 | +| | | | | | | | | | +----------------------------------+ | | |
| 162 | +| | | | | | | | dialer uses the swarm to dial to a | | | | | | |
| 163 | +| | | | +------------------------------------------------------------------------------>| dialer | | | |
| 164 | +| | |transports | | relay node listening on the /hop | | | | | | |
| 165 | +| | | | | | | multistream endpoint | | +----------------------------------+ | | |
| 166 | +| | | | | | | | | | | |
| 167 | +| v v | v v | | | | | |
| 168 | +|+------------------|----------------------------+| | | +----------------------------------+ | | |
| 169 | +|| | | | | || | | | | | | |
| 170 | +||libp2p-tcp |libp2p-ws | .... |libp2p-circuit ||listener registers a /stop multistream | | listener | | | |
| 171 | +|| | +-------------------------------------------------------------------------------->| | | | |
| 172 | +|| | | |pluggs in just ||handler with the swarm to handle | | +----------------------------------+ | | |
| 173 | +|| | | |as any other ||incomming relay connections | | | | |
| 174 | +|| | | |transport || | +-------------------------------------------+ | |
| 175 | +|+-----------------------------------------------+| | | |
| 176 | +| | | | |
| 177 | +| | | | |
| 178 | ++-------------------------------------------------+ +---------------------------------------------------------+ |
| 179 | +``` |
| 180 | + |
| 181 | + |
| 182 | + |
| 183 | +## Contribute |
| 184 | + |
| 185 | +Contributions are welcome! The libp2p implementation in JavaScript is a work in progress. As such, there's a few things you can do right now to help out: |
| 186 | + |
| 187 | +- [Check out the existing issues](//github.com/libp2p/js-libp2p-circuit/issues). |
| 188 | +- **Perform code reviews**. |
| 189 | +- **Add tests**. There can never be enough tests. |
| 190 | + |
| 191 | +Please be aware that all interactions related to libp2p are subject to the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). |
| 192 | + |
| 193 | +Small note: If editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification. |
| 194 | + |
| 195 | +## License |
| 196 | + |
| 197 | +[MIT](LICENSE) © 2017 Protocol Labs |
0 commit comments