simple-hypercore-protocol

Hypercore protocol state machine

npm install simple-hypercore-protocol

Includes a Noise handshake, and is not backwards compatible with Hypercore <= 7

Usage

const Protocol = require('simple-hypercore-protocol')

const a = new Protocol(true, {
  send (data) { // send hook should send data
    b.recv(data)
  }
})

const b = new Protocol(false, {
  onrequest (channel, message) {
    console.log('got request message', message, 'on channel', channel)
  },
  send (data) {
    a.recv(data)
  }
})

// send a request message on channel 10
a.request(10, {
  index: 42
})

API

This is still a work in progress, so that messages supported might change. See the schema.proto file for the schema for each message.

`p = new Protocol(isInitator, handlers)`

Create a new protocol state machine.

isInitator is a boolean indicating if you are a client or server
handlers is a series of functions handling incoming messages

Everytime a binary message should be sent to another peer, handlers.send(data) is invoked.

If there is a critical error, handlers.destroy(err) is called.

After the initial handshake transport encryption is enabled, to ensure your stream is private.

To disable transport encryption set handlers.encrypted = false.

To disable the NOISE handshake set handlers.noise = false (works only when encrypted is also set to false).

`p.recv(data)`

Call this with incoming data.

`buf = p.remoteCapability(key)`

Create a remote capability for a key. Use this to verify if a remote indeed had a key when you get an open message.

`buf = p.capability(key)`

Create a local capability.

`p.destroy(err)`

Destroy the protocol state machine.

`p.publicKey`

The local public key used for authentication.

`p.remotePublicKey`

The remotes public key.

`p.handshakeHash`

The noise handshake hash which uniquely identifies the noise session.

http://noiseprotocol.org/noise.html#channel-binding

`handlers.onauthenticate(remotePublicKey, done)`

Called when you should authenticate a remote public key.

`handlers.onhandshake()`

Called when the initial protocol handshake has finished.

`p.open(channel, message)`

Send an open message on a channel.

Note that if you message.key the protocol, will turn that into a capability that is sent instead of the key.

Receiving an open message triggers handlers.onopen(channel, message)

`p.options(channel, message)`

Send a options message on a channel.

Receiving a handshake message triggers handlers.onoptions(channel, message)

`p.status(channel, message)`

Send a status message on a channel.

Receiving a info message triggers handlers.onstatus(channel, message)

`p.have(channel, message)`

Send a have message on a channel.

Receiving a have message triggers handlers.onhave(channel, message)

`p.unhave(channel, message)`

Send an unhave message on a channel.

Receiving an unhave message triggers handlers.onunhave(channel, message)

`p.want(channel, message)`

Send a want message on a channel.

Receiving a want message triggers handlers.onwant(channel, message)

`p.unwant(channel, message)`

Send an unwant message on a channel.

Receiving an unwant message triggers handlers.onunwant(channel, message)

`p.request(channel, message)`

Send a request message on a channel.

Receiving a request message triggers handlers.onrequest(channel, message)

`p.cancel(channel, message)`

Send a cancel message on a channel.

Receiving a cancel message triggers handlers.oncancel(channel, message)

`p.data(channel, message)`

Send a data message on a channel.

Receiving a data message triggers handlers.ondata(channel, message)

`keyPair = Protocol.keyPair([seed])`

Static function to generate a Noise key pair, optionally from a seed.

License

MIT

Current Tags

2.1.2 ... latest (3 years ago)

simple-hypercore-protocol

Usage

API

p = new Protocol(isInitator, handlers)

p.recv(data)

buf = p.remoteCapability(key)

buf = p.capability(key)

p.destroy(err)

p.publicKey

p.remotePublicKey

p.handshakeHash

handlers.onauthenticate(remotePublicKey, done)

handlers.onhandshake()

p.open(channel, message)

p.options(channel, message)

p.status(channel, message)

p.have(channel, message)

p.unhave(channel, message)

p.want(channel, message)

p.unwant(channel, message)

p.request(channel, message)

p.cancel(channel, message)

p.data(channel, message)

keyPair = Protocol.keyPair([seed])