Skip to content

Latest commit

 

History

History
152 lines (109 loc) · 5.99 KB

README.md

File metadata and controls

152 lines (109 loc) · 5.99 KB
Raw

ipfs-message-port-client

ipfs.io IRC Discord codecov CI

IPFS client library for accessing IPFS node over message port

Table of contents

Install

$ npm i 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)
}

License

Licensed under either of

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.