Skip to content

Latest commit

 

History

History
141 lines (106 loc) · 6.04 KB

README.md

File metadata and controls

141 lines (106 loc) · 6.04 KB
Raw

ipfs-message-port-client

Travis CI Codecov branch Dependency Status js-standard-style

A client library for the IPFS API over message channel. This client library provides (subset) of IPFS API enabling applications to work with js-ipfs running in the different JS e.g. SharedWorker.

Table of Contentens

Install

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

Usage

This client library works with IPFS node over the message channel and assumes that IPFS node is provided via ipfs-message-port-server on the other end.

It provides following API subset:

A client can be instantiated from the MessagePort instance. The primary goal of this library is to allow sharing a node across browsing contexts (tabs, iframes) and therefore most likely ipfs-message-port-server will be in a separate JS bundle and loaded in the SharedWorker.

import { IPFSClient } from 'ipfs-message-port-client'
// URL to the script containing ipfs-message-port-server.
const IPFS_SERVER_URL = '/bundle/ipfs-worker.js'

const main = async () => {
  const worker = new SharedWorker(IPFS_SERVER_URL)
  const ipfs = IPFSClient.from(worker.port)
  const data = ipfs.cat('/ipfs/QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n')

  for await (const chunk of data) {
    console.log(chunk)
  }
}

It is also possible to instantiate a detached client, which can be attached to the server later on. This is useful when a server port is received via a message from another JS context (e.g. iframe)

Note: Client will queue all API calls and only execute them once it is attached (unless they time out or are aborted in the meantime).

import { IPFSClient } from 'ipfs-message-port-client'

const ipfs = IPFSClient.detached()

const main = async () => {
  const data = ipfs.cat('/ipfs/QmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n')

  for await (const chunk of data) {
    console.log(chunk)
  }
}

window.onload = main
window.onmessage = ({ports}) => {
  IPFSClient.attach(ports[0])
}

Notes on Performance

Since client works with IPFS node over message channel all the data passed is copied via structured cloning algorithm, which may lead to suboptimal results (especially with large binary data). In order to avoid unnecessary copying all API options have being extended with optional transfer property that can be supplied Transferables which will be used to move corresponding values instead of copying.

Note: Transferring data will empty it on the sender side which can lead to errors if that data is used again later. To avoid these errors transfer option was added so user can explicitly give up reference when it is safe to do so.

/**
 * @param {Uint8Array} data - Large data chunk
 */
const example = async (data) => {
  // Passing `data.buffer` will cause underlying `ArrayBuffer` to be
  // transferred emptying `data` in JS context.
  ipfs.add(data, { transfer: [data.buffer] })
}

It is however recommended to prefer web native Blob / File instances as most web APIs provide them as option & can be send across without copying underlying memory.

const example = async (url) => {
  const request = await fetch(url)
  const blob = await request.blob()
  ipfs.add(blob)
}

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

FOSSA Status