Awesome
ssb-conn-hub
Module that manages active connections to peers. For use with the SSB CONN family of modules.
Visual metaphor: a network switch managing connections to other peers, capable of starting or stopping connections.
Usage
Prerequisites:
- Requires Node.js 6.5 or higher
- Requires
secret-stack@^6.3.0
This module is only used to create an SSB CONN plugin, not used directly by applications. A ConnHub instance should be available on the CONN plugin, with the following API:
API
connHub.connect(address, data?)
: connect to a peer known by itsaddress
(string, must conform to the multiserver address convention). The second argumentdata
is optional, and allows you to attach additional metadata, that can be read later when this connection data is retrieved. Returns a Promise, with the three possible outcomes:- Resolves with an RPC object that represents the successfully connected peer
- Resolves with
false
when the connect was unnecessary, therefore not performed - Rejects with an error indicating why the connection failed
connHub.disconnect(address)
: disconnect from a peer known by itsaddress
(string, must conform to the multiserver address convention). Returns a Promise, with the three possible outcomes:- Resolves with
true
when disconnected successfully - Resolves with
false
when the disconnect was unnecessary, therefore not performed - Rejects with an error indicating why the disconnection failed
- Resolves with
connHub.update(address, data)
: update the metadata of a peer currently in connection with us, where the peer is known by itsaddress
and the new data is indata
. If the peer is not registered in ConnHub, this method performs no operations and returns false. Returns true if the update has succeeded.connHub.reset()
: closes all connections, basically resetting this instance as if it had just been startedconnHub.entries()
: returns a newIterator
object that gives[address, data]
pairs, where data has the state and key of the peerconnHub.liveEntries()
: returns a pull-stream that emits an array of entries (likeconnHub.entries()
, but an array instead of anIterator
) everytime there are updates to connections.connDB.listen()
: returns a pull stream that notifies of connection events, as an object{type, address, key, details}
where:type
is either'connecting'
,'connecting-failed'
,'connected'
,'disconnecting'
,'disconnecting-failed'
,'disconnected'
address
is the original address used for connecting- (maybe present)
key
is the cryptographic public id - (maybe present, see below)
details
is an object with additional info- Present when when
type === 'connected'
and containsdetails.rpc
(the MuxRPC object for the remote peer) anddetails.isClient
(boolean indicating whether we are the client) - Does not exist when
type === 'disconnecting'
- Does not exist when
type === 'disconnected'
- Does not exist when
type === 'connecting'
- Present when
type === 'connecting-failed'
anddetails
is the error object for the connection failure - Present when
type === 'disconnecting-failed'
anddetails
is the error object for the connection failure
- Present when when
connHub.getState(address)
: returns undefined if the peer for that address is disconnected, otherwise returns one of'connecting'
,'connected'
, or'disconnecting'
connHub.close()
: terminates any used resources and listeners, in preparation to destroy this instance.
Recipes
How can I get the RPC object for the remote peer connected with me?
Assuming you're access ConnHub from ssb-conn, listen to connection events on ConnHub, filter
for 'connected'
events, and they should contain the RPC object on the event's details
field:
pull(
ssb.conn.hub().listen(),
pull.filter(event => event.type === 'connected'),
pull.drain(event => {
const rpc = event.details.rpc
// `rpc` object has public methods such as `rpc.createHistoryStream()`
})
)
License
MIT