ipfs-message-port-protocol

⛔️ DEPRECATED: js-IPFS has been superseded by Helia

📚 Learn more about this deprecation or how to migrate

⚠️ If you continue using this repo, please note that security fixes will not be provided

ipfs-message-port-protocol

IPFS client/server protocol over message port

Table of contents

• Install
  • Browser <script> tag
• Usage
• Wire protocol codecs
  • CID
  • DAGNode
  • AsyncIterable
  • Callback
• License
• Contribute

Install

$ npm i ipfs-message-port-protocol

Browser <script> tag

Loading this module through a script tag will make it's exports available as IpfsMessagePortProtocol in the global namespace.

<script src="https://unpkg.com/ipfs-message-port-protocol/dist/index.min.js"></script>

Usage

Wire protocol codecs

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

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

CID

Codecs for CID implementation in JavaScript.

import { CID, encodeCID, decodeCID } from 'ipfs-message-port-protocol/cid'

const cid = CID.parse('bafybeig6xv5nwphfmvcnektpnojts33jqcuam7bmye2pb54adnrtccjlsu')

const { port1, port2 } = new MessageChannel()

// Will copy underlying 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
}

DAGNode

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

import { encodeNode, decodeNode } from 'ipfs-message-port-protocol/dag'

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

const { port1, port2 } = new MessageChannel()

// Will copy underlying 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

This encoder encodes async iterables such that they can be transferred across threads and decoded by a consumer on the other end while taking care of all the IO coordination between two. It needs to be provided encoder / decoder function to encode / decode each yielded item of the async iterable. Unlike other encoders the transfer argument is mandatory (because async iterable is encoded to a MessagePort that can only be transferred).

import { encodeIterable, decodeIterable } from 'ipfs-message-port-protocol/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 receiver 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. Unlike most encoders transfer argument is required (because value is encoded to a MessagePort that can only be transferred)

import { encodeCallback, decodeCallback } from 'ipfs-message-port-protocol/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)
}

License

Licensed under either of

• Apache 2.0, (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)
• MIT (LICENSE-MIT / http://opensource.org/licenses/MIT)

Contribute

Contributions welcome! Please check out the issues.

Also see 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.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.