Rtcbeam-core NPM

rtcbeam-core

Peer-to-peer end-to-end encrypted file and data transfer module using PeerJS. Provides core functionality for rtcbeam. Can be used to send any kind of data between two peers. Designed for, but not limited to, file transfer.

Usage

IMPORTANT NOTE

rtcbeam-core is built with PeerJS, a peer-to-peer library that (unfortunately) will not function outside of a browser. As a result, rtcbeam-core will only work if run in a browser.

Installation

npm i rtcbeam-core

import { Rtcbeam } from 'rtcbeam-core'

`Rtcbeam([host, options])`

Create a new instance of the Rtcbeam class with const rtcbeam = new Rtcbeam(host)

Parameters:

const rtcbeam = new Rtcbeam('0.peerjs.com', { pingInterval: 10000 })

rtcbeam.getVersion()

Returns version number.

console.log(rtcbeam.getVersion())
// 1.2.3

rtcbeam.createPeer(host)

Creates new PeerJS peer. Can be called on an existing rtcbeam instance to reconnect to another connection broker server.

Parameters:

Returns:

PeerJS peer object.

const rtcbeam = new Rtcbeam('0.peerjs.com')
console.log(rtcbeam.peer.options.host)
// 0.peerjs.com

rtcbeam.createPeer('server.example.com')
console.log(rtcbeam.peer.options.host)
// server.example.com

const newPeer = rtcbeam.createPeer('server.example.com')
console.log(newPeer.options.host)
// server.example.com

rtcbeam.serveData(blob, name, isFile)

Serve new data from your rtcbeam client that can be requested by other clients. Maximum size for single blob is about 800 megabytes.

Parameters:

Returns:

Content ID of the served data. CID will be used by other peers to request this data.

const cid = rtcbeam.serveData(new Blob(['Hello world!']), 'hello', false)

/* -- or -- */

const cid = rtcbeam.serveData(new Blob(['data-read-from-file']), 'file.txt', true)

console.log(cid)
// CID of served data, for example
// 9907f5ca-ee52-44ac-abc1-74e31ceb6a95

rtcbeam.removeData(cid)

Removes served data and makes it no longer available.

Parameters:

const cid = rtcbeam.serveData(new Blob(['Hello world!']))
// Served.

rtcbeam.removeData(cid)
// Gone, reduced to atoms.

rtcbeam.requestData(id, cid, encrypt)

Requests data from another client by client's ID and data CID.

Parameters:

rtcbeam.requestData('other-peer-id', 'some-cid')

rtcbeam.on('transfer-completed', (blob) => {
  blob.text().then(t => console.log(t))
  // Writes requested data as text.
})

rtcbeam.createStatusMessageSet(name, values)

Creates a new status message set with user defined status messages. These messages will be passed on to the status event.

Parameters:

Available status messages and their default values:

networkConnecting: 📡 Establishing connection...

networkConnected: ✅ Connected to network.

error: ❌ An error has occured.

peerConnecting: 💻 Connecting to peer...

requestingData: ❔ Requesting file...

encryptingData: 🔐 Encrypting file...

sendingData: 📡 Sending file...

decryptingData: 🔐 Decrypting file...

transferCompleted: ✅ File transfer completed.

receivingData: 📨 Receiving file...

dataNotAvailable: ❌ File is no longer available.

// Default behaviour:
rtcbeam.on('status', status => {
  console.log(status)
  // When connected to network: ✅ Connected to network.
  // When sending data: 📡 Sending file...
  // etc...
})

/* --- */

// With custom status messages:
// Create a new set
rtcbeam.createStatusMessageSet('newMessageSet', {
  networkConnected: 'Hello world!',
  sendingData: 'Hello world, again!'
  // Other messages that are not specified will use default values.
})
// Use the new set.
rtcbeam.statusMessageSet = 'newMessageSet'

rtcbeam.on('status', status => {
  console.log(status)
  // When connected to network: Hello world!
  // When sending data: Hello world, again!
})

// To use default messages again:
rtcbeam.statusMessageSet = 'default'

Events:

Listen to with rtcbeam.on('event', (param1, param2...) => { ... })

.on('ready', () => { })

Emitted when rtcbeam client is ready and has connected to the provided PeerServer after initialization. Client can now be used for data transfer.

.on('status', (status) => { })

Emitted when the app status changes.

Parameters:

.on('connection', (conn) => { })

Emitted when a new connection to this client has been established.

Parameters:

.on('send-start', () => { })

Emitted when client has started sending data.

.on('send-finish', () => { })

Emitted when client has finished sending data.

.on('send-progress', (progress, cid) => { })

Emitted repeatedly while sending data.

Parameters:

.on('receive-start', () => { })

Emitted when client has started recieving data.

.on('receive-progress', (progress, cid) => { })

Emitted repeatedly while sending data.

Parameters:

.on('transfer-completed', (blob, metadata) => { })

Emitted when client has finished recieving data.

Parameters:

name\ Name of the data.

type\ MIME type of the data

cid\ Content ID of the data.

isFile\ True if the data should be interpreted as a file, false otherwise.

.on('not-found', (cid) => { })

Emitted when data has been requested from another peer but was not found by other peer.

Parameters:

Values:

Various values accessible within an instance of the Rtcbeam class.

.appStatus

String describing the current state of the app.

.peer

PeerJS peer used by the client.

.inboundData

Contains data being transferred to this client from others. Data structure:

.inboundData
│
├ .cid-of-some-data
│  ├ .body      < blob containing data
│  ├ .name      < data name
│  ├ .type      < data MIME type
│  ├ .nonce     < encryption nonce
│  └ .secretKey < encryption secret key
│
├ .cid-of-some-other-data
...

.outboundData

Contains data being served by this client and that can be transferred from this client to others. Data structure:

.outboundData
│
├ .cid-of-some-data
│  ├ .body      < blob containing data
│  ├ .name      < data name
│  ├ .type      < data MIME type
│  ├ .nonce     < encryption nonce
│  └ .secretKey < encryption secret key
│
├ .cid-of-some-other-data
...

.version

rtcbeam-core version. Identical to .getVersion()

.statusMessageSet

The name of the status message set that is being used. See .createStatusMessageSet(). Value for default set is default.

.statusMessages

This object stores different status message sets. Can be written to directly to change status messages, or to create a new message set. See .createStatusMessageSet(). Data structure:

.statusMessages
│
├ .name-of-message-set
│  ├ .networkConnecting: string
│  ├ .networkConnected: string
│  ├ .error: string
│  ...
│  └ .dataNotAvailable: string
│
├ .name-of-some-other-message-set
...

Internal functions that are publicly accessible but are mostly useless:

deliverData (request, conn)

Delivers data to another client.

Parameters:

rtcbeam.on('connection', (conn) => {
  conn.on('data', (data) => {
    const request = JSON.parse(data)
    if (data.action === 'request-data') {
      rtcbeam.deliverData(request, conn)
    }
  })
})

receiveData(data, conn)

receives data from other peer. Data is written to rtcbeam.inboundData[cid], where cid is Content ID of transferred data. Parameters and usage are identical to deliverData()

handleIncomingData(data, conn)

Handles incoming requests and responds accordingly. Parameters are identical to deliverData()

confirmTransferFinish()

Called when data has been sent to other client.

notifyTransferStart()

Called when data is being received from other client.

dataNotFound(cid)

Called when data was requested but not found by other client.

Parameters:

Example

// As noted above, bundle with Webpack, etc. and run in a browser.

import { Rtcbeam } from 'rtcbeam-core'

// Create a new client.
const firstClient = new Rtcbeam()

// Wait for client to be ready.
firstClient.on('ready', () => {
  // Create some data.
  const data = new Blob(['Hello world!'])

  // Serve that data and save cid.
  const cid = firstClient.serveData(data)

  // Create a second client to receive that data.
  const secondClient = new Rtcbeam()
  secondClient.on('ready', () => {
    // Handle incoming data.
    secondClient.on('transfer-completed', (blob, metadata) => {
      blob.text().then(t => {
        console.log(t)
        // Hello world!
      })
    })
    // Request served data.
    secondClient.requestData(firstClient.peer.id, cid)
  })
})