status-swarm

A very simple (secure) replication protocol.

status-swarm replicates a single value per node, where the node's public key is the id, and the value may be updated, but new values always win. status-swarm is intended for relatively long lived connections.

When reconnecting to a node, overhead is small, you only send the last time stamp from that peer.

However, you may receive the same message multiple times if connected to more than one peer, and upon connecting to a new peer for the first time, you may re-receive messages you have already seen.

API

swarm = Swarm(keys, cap)

create a new instance with a given ssb-keys keypair. if cap is provided, it is used as the hmac_key value in ssb-keys's signObj and verifyObj

If cap is not provided, the sha256 hash of the string: "A very simple, secure, eventually consistent, replication protocol" will be used.

hmacs are used before signing, so that signatures created via status-swarm cannot be reused in other parts of the ssb protocol.

swarm.update(value)

update your status. the value will be wrapped and signed:

{
  id: <your_id>,
  ts: <localtimestamp>,
  data: <value>,
  signature: <sig>
}

swarm.get(id)

return the current value for this id (or undefined)

swarm.last(id)

get the timestamp that you last received something from a given node. This is their local time, which may be skewed from yours, but you need to know their time, because you will use this to request they have received since this time.

swarm.data()

return {} of all current data. contains {: ,...}

swarm.send(since), swarm.recv(id)

Set up replication between two peers. note that it's not implemented as a duplex stream, but as a separate source and a sink. This method makes for a more symmetrical protocol. on connecting, each peer requests the remote's swarm.send(ts||0) over rpc

send can be exposed over muxrpc, but recv can be a private api. your code might look something like this:

//this code should exist on both ends.
sbot.on('rpc:connect', function (rpc) {
  var id = rpc.id
  pull(rpc.send(swarm.last(id)), swarm.recv(id))
})
 
//advertise your network location, for example.
rpc.update({host: HOST, port: PORT})

TODO

To stop the replication data growing too large, implement filtering (say, filter ids you don't care about) expire messages that are too old (say, to represent only peers that are online, say within the last few hours)

License

MIT