opacity-streamable v2.2.1

opacity-streamable

A proof of concept, streamable implementation of the Opacity Protocol (not fully compatible) with a few significant changes:

• CryptoJS replaced with node-forge
• Encryption/decryption key is the SHA-256 hash of the handle, per-chunk IV (see #109)
• Communication with the nodes via IXI module to save bandwidth
• Pipelined processing:
  • File > Encryption > Upload
  • Download > Decryption > Blob

API Reference

opacity-streamable

Importing opacity-streamable

Example (As an ES Module)

import Opacity from 'opacity-streamable'

Example (As a Node Module)

const Opacity = require(`opacity-streamable`)

Example (As a UMD Module)

window.Opacity = Opacity.default

• opacity-streamable
  • .Download
    • .EVENTS
      • "DOWNLOAD_PROGRESS"
      • "FINISH"
      • "METADATA"
    • .toBuffer(handle, options) ⇒ Download
    • .toBlob(handle, options) ⇒ Download
  • .Upload
    • .EVENTS
      • "INVOICE"
      • "CHUNKS_PROGRESS"
      • "UPLOADED"
      • "META_ATTACHED"
      • "UPLOAD_PROGRESS"
      • "FINISH"
    • .EVENTS
      • "INVOICE"
      • "CHUNKS_PROGRESS"
      • "UPLOADED"
      • "META_ATTACHED"
      • "UPLOAD_PROGRESS"
      • "FINISH"
    • .fromFile(file, options) ⇒ Upload
    • .fromData(buffer, filename, options) ⇒ Upload

Opacity.Download

Kind: static class of opacity-streamable
Emits: METADATA, DOWNLOAD_PROGRESS, FINISH

• .Download
  • .EVENTS
    • "DOWNLOAD_PROGRESS"
    • "FINISH"
    • "METADATA"
  • .toBuffer(handle, options) ⇒ Download
  • .toBlob(handle, options) ⇒ Download

Download.EVENTS

Events fired during the download lifecycle

Kind: static constant of Download

• .EVENTS
  • "DOWNLOAD_PROGRESS"
  • "FINISH"
  • "METADATA"

"DOWNLOAD_PROGRESS"

Fired when a successful poll is performed while retrieving a file

Kind: event emitted by EVENTS
Properties

"FINISH"

Fired when the file has been reconstructed and is ready for use

Kind: event emitted by EVENTS
Properties

"METADATA"

Fired when the file metadata has been reconstructed and is ready for use

Kind: event emitted by EVENTS
Properties

Download.toBuffer(handle, options) ⇒ Download

Kind: static method of Download

Example (To Buffer object (node))

const download = Opacity.Download.toBuffer(handle, {
  iotaProviders: [
    { provider: 'https://poll.oysternodes.com:14265/' },
    { provider: 'https://download.oysternodes.com:14265/' }
  ]
})

download.on('meta', metadata => {
  console.log(metadata)
  // {fileName: "opacity.txt", ext: "txt", numberOfChunks: 2}
})
download.on('finish', filedata => {
  console.log(filedata)
  // {file: Buffer(), metadata: {…}, target: Download}
})

Download.toBlob(handle, options) ⇒ Download

Kind: static method of Download

Example (To Blob object (browser))

const download = Opacity.Download.toBlob(handle, {
  iotaProviders: [
    { provider: 'https://poll.oysternodes.com:14265/' },
    { provider: 'https://download.oysternodes.com:14265/' }
  ]
})

download.on('meta', metadata => {
  console.log(metadata)
  // {fileName: "opacity.txt", ext: "txt", numberOfChunks: 2}
})
download.on('finish', filedata => {
  console.log(filedata)
  // {file: Blob(), metadata: {…}, target: Download}
})

Opacity.Upload

Kind: static class of opacity-streamable
Emits: INVOICE, CHUNKS_PROGRESS, UPLOAD_PROGRESS, FINISH

• .Upload
  • .EVENTS
    • "INVOICE"
    • "CHUNKS_PROGRESS"
    • "UPLOADED"
    • "META_ATTACHED"
    • "UPLOAD_PROGRESS"
    • "FINISH"
  • .EVENTS
    • "INVOICE"
    • "CHUNKS_PROGRESS"
    • "UPLOADED"
    • "META_ATTACHED"
    • "UPLOAD_PROGRESS"
    • "FINISH"
  • .fromFile(file, options) ⇒ Upload
  • .fromData(buffer, filename, options) ⇒ Upload

Upload.EVENTS

Events fired during the upload lifecycle

Kind: static constant of Upload

• .EVENTS
  • "INVOICE"
  • "CHUNKS_PROGRESS"
  • "UPLOADED"
  • "META_ATTACHED"
  • "UPLOAD_PROGRESS"
  • "FINISH"

"INVOICE"

Fired when an invoice is recieved from the broker node

Kind: event emitted by EVENTS
Properties

"CHUNKS_PROGRESS"

Fired when a chunk is uploaded to the broker

Kind: event emitted by EVENTS
Properties

"UPLOADED"

Fired all chunks have been uploaded to the brokers.

Kind: event emitted by EVENTS

"META_ATTACHED"

Fired when the meta chunk has been attached. This is needed in order to resume polling for upload progress.

Kind: event emitted by EVENTS
Properties

"UPLOAD_PROGRESS"

Fired when a chunk is attached to the tangle

Kind: event emitted by EVENTS
Properties

"FINISH"

Fired when the file has been completely attached to the tangle

Kind: event emitted by EVENTS
Properties

Upload.EVENTS

Events fired during the upload lifecycle

Kind: static constant of Upload

• .EVENTS
  • "INVOICE"
  • "CHUNKS_PROGRESS"
  • "UPLOADED"
  • "META_ATTACHED"
  • "UPLOAD_PROGRESS"
  • "FINISH"

"INVOICE"

Fired when an invoice is recieved from the broker node

Kind: event emitted by EVENTS
Properties

"CHUNKS_PROGRESS"

Fired when a chunk is uploaded to the broker

Kind: event emitted by EVENTS
Properties

"UPLOADED"

Fired all chunks have been uploaded to the brokers.

Kind: event emitted by EVENTS

"META_ATTACHED"

Fired when the meta chunk has been attached. This is needed in order to resume polling for upload progress.

Kind: event emitted by EVENTS
Properties

"UPLOAD_PROGRESS"

Fired when a chunk is attached to the tangle

Kind: event emitted by EVENTS
Properties

"FINISH"

Fired when the file has been completely attached to the tangle

Kind: event emitted by EVENTS
Properties

Upload.fromFile(file, options) ⇒ Upload

Kind: static method of Upload

Example (From File object (browser))

const file = fileInput.files[0];
const upload = Opacity.Upload.fromFile(file, {
  iotaProvider: { provider: 'https://poll.oysternodes.com:14265/' },
  alpha: 'https://broker-1.oysternodes.com/',
  beta: 'https://broker-2.oysternodes.com/',
  epochs: 1
});

upload.on('invoice', invoice => {
  console.log(invoice)
  // {address: "<ETH_ADDRESS>", cost: 20}
});
upload.on('finish', filedata => {
  console.log(filedata)
  // {handle: "<OPACITY_HANDLE>", metadata: {…}, target: Upload}
});

Upload.fromData(buffer, filename, options) ⇒ Upload

Kind: static method of Upload

Example (From Buffer object (node))

const fs = require('fs');
const path = './path/to/file';
const filename = 'somefile.txt';

fs.readFile(`${path}/${filename}`, (err, data) => {
  if (err) throw err;

  const upload = Opacity.Upload.fromData(data, filename, {
    iotaProvider: { provider: 'https://poll.oysternodes.com:14265/' },
    alpha: 'https://broker-1.oysternodes.com/',
    beta: 'https://broker-2.oysternodes.com/',
    epochs: 1
  });

  upload.on('invoice', invoice => {
    console.log(invoice)
    // {address: "<ETH_ADDRESS>", cost: 20}
  });
  upload.on('finish', filedata => {
    console.log(filedata)
    // {handle: "<OPACITY_HANDLE>", metadata: {…}, target: Upload}
  });
});

What's next?

Possible things to look into:

• Full compatibility
• Pluggable source streams for uploads and target streams for downloads, allowing:
• Node compatability
• Video streams via MediaSource
• Arbitrary size downloads via StreamSaver

Credits

This repo is based on the official opacity/webinterface and shares a fair amount of code with the project where it makes sense.

Big thanks to everyone working on Opacity!