ipfs-message-port-protocol

ipfs-message-port-protocol

This package serves as a repository code shared between the core ipfs-message-port-client and the ipfs-message-port-server

Lead Maintainer

Alex Potsides

Table of Contentens

• Install
• Usage
  • Wire protocol codecs
  • Block
  • DAGNode
  • AsyncIterable
  • [Callback][#callback]
• Contribute
• License

Install

$ npm install --save ipfs-message-port-protocol

Usage

Wire protocol codecs

Library provides encode / decode functions for types that are not supported by structured cloning algorithm and therefore need to be encoded before posted over message channel and decoded on the other end.

All encoders take optional transfer array. If provided, encoder will add all Transferable fields of the given value so the they could be moved across threads without copying.

CID

Codecs for CID implementation in JavaScript.

const { CID, encodeCID, decodeCID } = require('ipfs-message-port-protocol/src/cid')

const cid = new CID('bafybeig6xv5nwphfmvcnektpnojts33jqcuam7bmye2pb54adnrtccjlsu')

const { port1, port2 } = new MessageChannel()

// Will copy underyling memory
port1.postMessage(encodeCID(cid))

// Will transfer underlying memory (cid is corrupt on this thread)
const transfer = []
port1.postMessage(encodeCID(cid, transfer), transfer)

// On the receiver thread
port2.onmessage = ({data}) => {
  const cid = decodeCID(data)
  data instanceof CID // => true
}

Block

Codecs for IPLD Block implementation in JavaScript.

const { Block, encodeBlock, decodeBlock } = require('ipfs-message-port-protocol/src/block')

const data = Buffer.from('hello')
const cid = new CID('QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n')
const block = new Block(data, cid)

const { port1, port2 } = new MessageChannel()

// Will copy underyling memory
port1.postMessage(encodeBlock(block))

// Will transfer underlying memory (block & cid will be corrupt on this thread)
const transfer = []
port1.postMessage(encodeBlock(block, transfer), transfer)


// On the receiver thread
port2.onmessage = ({data}) => {
  const block = decodeBlock(data)
  block instanceof Block // true
}

DAGNode

Codec for DAGNodes accepted by ipfs.dag.put API.

const { encodeNode, decodeNode } = require('ipfs-message-port-protocol/src/dag')


const cid = CID('QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n')
const dagNode = { hi: 'hello', link: cid }

const { port1, port2 } = new MessageChannel()

// Will copy underyling memory
port1.postMessage(encodeNode(dagNode))

// Will transfer underlying memory (`dagNode.link` will be corrupt on this thread)
const transfer = []
port1.postMessage(encodeNode(dagNode, transfer), transfer)


// On the receiver thread
port2.onmessage = ({data}) => {
  const dagNode = decodeNode(data)
  dagNode.link instanceof CID // true
}

AsyncIterable

Encoder allows producer to encode async iterables such that it can be transferred across threads and decoded by a consumer on the other end and take care of all the IO coordination between two. Unlike other encoders transfer argument is mandatory (because value is encoded to a MessagePort that can only be transferred). Additionally encoder / decoder take item encoder / decoder functions to encode each item of the async iterable.

const { encodeIterable, decodeIterable } = require('ipfs-message-port-protocol/src/core')

const data = ipfs.cat('/ipfs/QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n')

const { port1, port2 } = new MessageChannel()

// Will copy each chunk to the receiver thread
{
  const transfer = []
  port1.postMessage(
    encodeIterable(content, chunk => chunk, transfer),
    transfer
  )
}


// Will transfer each chunk to the reciever thread (corrupting it on this thread)
{
  const transfer = []
  port1.postMessage(
    encodeIterable(
      content,
      (chunk, transfer) => {
        transfer.push(chunk.buffer)
        return chunk
      },
      transfer
    ),
    transfer
  )
}


// On the receiver thread
port2.onmessage = async ({data}) => {
  for await (const chunk of decodeIterable(data)) {
    chunk instanceof Uint8Array
  }
}

Callback

Primitive callbacks that take single parameter supported by structured cloning algorithm like progress callback used across IPFS APIs can be encoded / decoded. Unilke most encoders transfer argument is required (because value is encoded to a MessagePort that can only be transferred)

const { encodeCallback, decodeCallback } = require('ipfs-message-port-protocol/src/core')

const { port1, port2 } = new MessageChannel()

const progress = (value) => console.log(progress)

const transfer = []
port1.postMessage(encodeCallback(progress, transfer))


// On the receiver thread
port2.onmessage = ({data}) => {
  const progress = decodeCallback(data)
  // Invokes `progress` on the other end
  progress(20)
}

Contribute

Contributions welcome. Please check out the issues.

Check out our contributing document for more information on how we work, and about contributing in general. Please be aware that all interactions related to this repo are subject to the IPFS Code of Conduct.

License