little-network-box

little-network-box

A little toolkit for distributed applications based on Hypercore and Hyperswarm

Installation

$ npm install little-network-box # from github for now

Status

WIP

Example

const { Origin, Sink, storage } = require('little-network-box')
const pump = require('pump')
const path = require('path')
const ram = require('random-access-memory')
const raf = require('random-access-file')
const fs = require('fs')

const video = path.resolve(__dirname, 'video.mp4')
const copy = path.resolve(__dirname, 'copy.mp4')
const origin = new Origin(ram)

origin.ready(() => {
  const input = origin.createWriteStream()
  const video = fs.createReadStream(video, { highWaterMark: 1024 })
  const sink = new Sink(storage.sink(copy), origin.key, {
    encryptionKey: origin.encryptionKey,
    nonce: origin.nonce
  })

  pump(video, input, (err) => {
    sink.on('sync', ()=> {
      if (sink.byteLength === origin.byteLength) {
        console.log('sync')
        sink.close()
        origin.close()
        process.nextTick(process.exit)
      }
    })
  })
})

API

Below is the documentation for the modules, classes, functions, and constants little-network-box exports publically.

const box = new Box(storage, key, options)

The Box class represents a container for a Hypercore feed. Extending classes are provided life cycle callback by implementing various Box symbol methods like Box.codec, Box.storage, and more to customize the configuration, initialization, and encryption of the Hypercore feed.

Usage

const box = new Box(storage[, key[, options]])

Where storage is a random-access-storage factory function, key is an optional Hypercore public keey, and options is an object that is passed directly to the Hypercore constructor and made available to various Symbol methods like Box.options, Box.init, and more.

box.key

Read only accessor for the Hypercore feed's public key.

box.secretKey

Read only accessor for the Hypercore feed's secret key.

box.discoveryKey

Read only accessor for the Hypercore feed's discovery key.

box.stats

Read only accessor for the Hypercore feed's stats object.

box.extensions

Read only accessor for the Hypercore feed's extensions array.

box.live

Read only accessor for the Hypercore feeds' live state.

box.sparse

Read only accessor for the Hypercore feeds' sparse state.

box.readable

Read only accessor for the Hypercore feeds' readable state.

box.writable

Read only accessor for the Hypercore feeds' writable state.

box.opened

Read only accessor for the Hypercore feeds' opened state.

box.closed

Read only accessor for the Hypercore feeds' closed state.

box.length

Read only accessor for the Hypercore feeds' length.

box.byteLength

Read only accessor for the Hypercore feeds' byte length.

box.origin

Read only accessor for the Box's origin state.

const options = Box.defaults(defaults, ...overrides)

Creates an options object that can be passed to the Box constructor.

Usage

const options = Box.defaults(defaults, ...overrides)

Where default options described by the Box class can be overloaded by a given defaults object and subsequently with any number of override objects passed in as rest arguments ...overrides.

Box.options

Classes who extend the Box class who are interested in extending constructor options should implement this Symbol method.

class ExtendedBox extends Box {
  [Box.options](options) {
    // modify `options`
  }
}

Box.init

Classes who extend the Box class who are interested in initializing objects with the options passed into the constructor should implement this Symbol method.

const hyperswarm require('hyperswarm')
const ram = require('random-access-memory')

class ExtendedBox extends Box {
  [Box.init](options) {
    this.swarm = hyperswarm(options.swarm)
  }
}

const box = new ExtendedBox(ram, {
  swarm: { ephemeral: false }
})

box.ready(() => {
  box.swarm.join(box.discoveryKey)
})

Box.codec

Classes who extend the Box class who are interested in providing a codec for the Hypercore's valueEncoding property should implement this Symbol method.

const encoding = require('buffer-json-encoding')
const ram = require('random-access-memory')

class ExtendedBox extends Box {
  [Box.codec](opts) {
    return encoding
  }
}

const box = new ExtendedBox(ram)

box.ready(() => {
  box.append({ hello: 'world' }, (err) => {
    box.head(console.log) // { hello: 'world' }
  })
})

Box.open

Classes who extend the Box class who are interested in opening resources when the instance is "opening" should implement this Symbol method.

class ExtendedBox extends Box {
  [Box.open](opts) {
    this.socket = net.connect(opts)
    this.socket.on('connect', () => this.emit('connect', this.socket)
  }
}

const box = new ExtendedBox(ram)
box.on('connect', (socket) => {
  // handle socket connection
})

Box.close

Classes who extend the Box class who are interested in closing resources when the instance is "closing" should implement this Symbol method.

class ExtendedBox extends Box {
  [Box.open](opts) {
    this.socket = net.connect(opts)
    this.socket.on('connect', () => this.emit('connect', this.socket)
  }

  [Box.close](opts) {
    if (this.socket) {
      this.socket.destroy()
      this.socket = null
    }
  }
}

const box = new ExtendedBox(ram)
box.on('connect', (socket) => {
  // handle socket connection then close
  box.close()
})

Box.write

Classes who extend the Box class who are interested in modifying data as after verification but before being written to storage should implement this Symbol method.

const replicate = require('little-network-box/replicate')
const encoding = require('xsalsa20-encoding')
const xsalsa20 = require('xsalsa20')
const crypto = require('crypto')

const nonce = crypto.randomBytes(24)

// encrypts plaintext into ciphertext before writing
// to storage
class EncryptedBox extends Box {
  [Box.codec](opts) {
    return encoding(nonce, opts.key)
  }
}

// decrypts data before writing to storage so
// `get()`, `head()`, etc return plaintext
class DecryptedBox extends Box {
  [Box.write](index, data, peer, done) {
    try {
      const xor = xsalsa20(nonce, this.key)
      xor.update(data, data)
      xor.finalize()
      done(null)
    } catch (err) {
      done(err)
    }
  }
}

const encrypted = new EncryptedBox(ram)
encrypted.ready(() => {
  const decrypted = new DecryptedBox(ram, encrypted.key)
  decrypted.ready(() => {
    replicate(encrypted, decrypted, (err) => {
      decrypted.head(console.log) // hello world
    })
  })
})

Box.ready

Classes who extend the Box class who are interested in adding work to the "ready queue" should extend this Symbol method.

// waits for super to be ready, then waits 5000ms before calling
// `done()` signaling that the instance is ready.
class DelayedReadyBox extends Box {
  [Box.ready](opts, done) {
    super[Box.ready](opts, (err) => {
        setTimeout(done, 5000)
    })
  }
}

const box = new DelayedReadyBox(ram)
box.ready(() => {
  // called after 5000ms
})

Box.storage

Classes who extend the Box class who are interested in providing a custom random-access-storage interface based on constructor input should implement this Symbol method.

const pump = require('pump')
const ram = require('random-access-memory')
const raf = require('random-access-file')
const fs = require('fs')

// indexes a file by passing the contents of the file,
// block by block, (fs.createReadStream()) through the hypercore
// feed generating a merkle tree and signed roots.
class IndexedBox extends Box {
  [Box.options](opts) {
    opts.indexing = true
  }

  [Box.init](opts) {
    this.filename = opts.filename
  }

  // treats the file as the data storage
  [Box.storage](storage, opts) {
    return (filename) => {
      if ('data' === filename) {
        return raf(this.filename)
      } else {
        return ram()
      }
    }
  }

  [Box.ready](opts, done) {
    super[Box.ready](opts, (err) => {
      const reader = fs.createReadStream(this.filename)
      const writer = this.createWriteStream()
      pump(reader, writer, done)
    })
  }
}

const indexed = new IndexedBox(ram, { filename: './video.mp4' })
indexed.ready(() => {
  indexed.audit(console.log) // should report 0 invalid
})

Box.origin

Classes who extend the Box class who are interested in affecting the value of the box.isOrigin predicate accessor should implement this Symbol method.

const ram = require('random-access-memory')

class Origin extends Box {
  get [Box.origin]() {
    return true
  }
}

const origin = new Origin(ram)
console.log(origin.isOrigin) // true

Box.hypercore

Classes who extend the Box class who are interested in providing a hypercore factory should implement this Symbol method.

const hypertrie = require('hypertrie')
const xsalsa20 = require('xsalsa20-encoding')
const crypto = require('crypto')

class EncryptedOriginTrieBox extends Box {
  [Box.hypercore](opts) {
    return hypertrie
  }

  [Box.codec](opts) {
    return xsalsa20(opts.nonce, opts.key)
  }

  get [Box.origin]() {
    return true
  }
}

const nonce = crypto.randomBytes(24)
const trie = new EncryptedOriginTrieBox(ram, { nonce })
trie.put('hello', 'world', (err) => {
  trie.get('hello', console.log) // { ..., key: 'hello', value: 'world' }
})

License

MIT