forked from libp2p/js-libp2p
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request libp2p#10 from diasdavid/revisit
Revisit Swarm - multitransport + upgrades - https://github.com/diasdavid/node-ipfs-swarm/issues/8
- Loading branch information
Showing
10 changed files
with
776 additions
and
491 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,82 +1,69 @@ | ||
| ipfs-swarm Node.js implementation | ||
| libp2p-swarm Node.js implementation | ||
| ================================= | ||
|
|
||
| [](http://ipn.io) [](http://ipfs.io/) [](http://webchat.freenode.net/?channels=%23ipfs) [](https://travis-ci.org/diasdavid/node-ipfs-swarm) | ||
|
|
||
| > IPFS swarm implementation in Node.js | ||
| > libp2p swarm implementation in Node.js | ||
| # Description | ||
|
|
||
| ipfs-swarm is an abstraction for the network layer on IPFS. It offers an API to open streams between peers on a specific protocol. | ||
| libp2p-swarm is a connection abstraction that is able to leverage several transports and connection upgrades, such as congestion control, channel encryption, multiplexing several streams in one connection, and more. It does this by bringing protocol multiplexing to the application level (instead of the traditional Port level) using multicodec and multistream. | ||
|
|
||
| Ref spec (WIP) - https://github.com/diasdavid/specs/blob/protocol-spec/protocol/layers.md#network-layer | ||
| libp2p-swarm is used by libp2p but it can be also used as a standalone module. | ||
|
|
||
| # Usage | ||
|
|
||
| ### Create a new Swarm | ||
| ### Install and create a Swarm | ||
|
|
||
| ```javascript | ||
| var Swarm = require('ipfs-swarm') | ||
| libp2p-swarm is available on npm and so, like any other npm module, just: | ||
|
|
||
| var s = new Swarm([port]) // `port` defalts to 4001 | ||
| ```bash | ||
| $ npm install libp2p-swarm --save | ||
| ``` | ||
|
|
||
| ### Set the swarm to listen for incoming streams | ||
| And use it in your Node.js code as: | ||
|
|
||
| ```javascript | ||
| s.listen([port], [callback]) // `port` defaults to 4001, `callback` gets called when the socket starts listening | ||
| ``` | ||
|
|
||
| ### Close the listener/socket and every open stream that was multiplexed on it | ||
| ```JavaScript | ||
| var Swarm = require('libp2p-swarm') | ||
|
|
||
| ```javascript | ||
| s.closeListener() | ||
| var sw = new Swarm(peerInfoSelf) | ||
| ``` | ||
|
|
||
| ### Register a protocol to be handled by an incoming stream | ||
|
|
||
| ```javascript | ||
| s.registerHandler('/name/protocol/you/want/version', function (stream) {}) | ||
| ``` | ||
| peerInfoSelf is a [PeerInfo](https://github.com/diasdavid/node-peer-info) object that represents the peer creating this swarm instance. | ||
|
|
||
| ### Open a new connection | ||
| ### Support a transport | ||
|
|
||
| Used when we want to make sure we can connect to a given peer, but do not intend to establish a stream with any of the services offered right away. | ||
| libp2p-swarm expects transports that implement [abstract-transport](https://github.com/diasdavid/abstract-transport). For example [libp2p-tcp](https://github.com/diasdavid/node-libp2p-tcp), a simple shim on top of the `net` module to make it work with swarm expectations. | ||
|
|
||
| ``` | ||
| s.openConnection(peerConnection, function (err) {}) | ||
| ```JavaScript | ||
| sw.addTransport(transport, [options, dialOptions, listenOptions]) | ||
| ``` | ||
|
|
||
| ### Add a connection upgrade | ||
|
|
||
| ### Dial a new stream | ||
| A connection upgrade must be able to receive and return something that implements the [abstract-connection](https://github.com/diasdavid/abstract-connection) interface. | ||
|
|
||
| ```JavaScript | ||
| sw.addUpgrade(connUpgrade, [options]) | ||
| ``` | ||
| s.openStream(peerInfo, protocol, function (err, stream) {}) | ||
| ``` | ||
|
|
||
| peerInfo must be a [`ipfs-peer`](https://www.npmjs.com/package/ipfs-peer) object, contaning both peer-id and multiaddrs. | ||
|
|
||
| ## Events emitted | ||
| Upgrading a connection to use a stream muxer is still considered an upgrade, but a special case since once this connection is applied, the returned obj will implement the [abstract-stream-muxer](https://github.com/diasdavid/abstract-stream-muxer) interface. | ||
|
|
||
| ```JavaScript | ||
| sw.addStreamMuxer(streamMuxer, [options]) | ||
| ``` | ||
| .on('error') | ||
|
|
||
| .on('connection') | ||
| .on('connection-unknown') // used by Identify to start the Identify protocol from listener to dialer | ||
| ``` | ||
|
|
||
| ## Identify protocol | ||
|
|
||
| The Identify protocol is an integral part to Swarm. It enables peers to share observedAddrs, identities and other possible address available. This enables us to do better NAT traversal. | ||
|
|
||
| To instantiate Identify: | ||
| ### Dial to another peer | ||
|
|
||
| ```JavaScript | ||
| sw.dial(PeerInfo, options, protocol) | ||
| sw.dial(PeerInfo, options) | ||
| ``` | ||
| var Identify = require('ipfs-swarm/identify') | ||
|
|
||
| var i = new Identify(swarmInstance, peerSelf) | ||
| ``` | ||
| dial uses the best transport (whatever works first, in the future we can have some criteria), and jump starts the connection until the point we have to negotiate the protocol. If a muxer is available, then drop the muxer onto that connection. Good to warm up connections or to check for connectivity. If we have already a muxer for that peerInfo, than do nothing. | ||
|
|
||
| `swarmInstance` must be an Instance of swarm and `peerSelf` must be a instance of `ipfs-peer` that represents the peer that instantiated this Identify | ||
| ### Accept requests on a specific protocol | ||
|
|
||
| Identify emits a `peer-update` event each time it receives information from another peer. | ||
| ```JavaScript | ||
| sw.handleProtocol(protocol, handlerFunction) | ||
| ``` |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| var Swarm = require('./../src') | ||
|
|
||
| var Peer = require('peer-info') | ||
| var Id = require('peer-id') | ||
| var multiaddr = require('multiaddr') | ||
| var tcp = require('libp2p-tcp') | ||
|
|
||
| var mh = multiaddr('/ip4/127.0.0.1/tcp/8010') | ||
| var p = new Peer(Id.create(), []) | ||
| var sw = new Swarm(p) | ||
|
|
||
| sw.addTransport('tcp', tcp, { multiaddr: mh }, {}, {port: 8010}, function () { | ||
| console.log('transport added') | ||
| }) |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.