IPFS Multiplexer Library

A multiplexer library, built on top of js-ipfs-http-client and implementing the interface-ipfs-core.

Lead Maintainer

Iñaki Arango.

Table of Contents

• IPFS Multiplexer Library
  • Lead Maintainer
  • Table of Contents
  • Install
    • Importing the module and usage
    • Importing helper functions
    • In a web browser
    • Custom Headers
  • Usage
    • API
      • Files
      • Graph
      • Additional Options
  • Development
    • Testing
  • Contribute
  • Historical context

Install

This module uses node.js, and can be installed through npm:

npm install --save ipfs-multiplexer

We support both the Current and Active LTS versions of Node.js. Please see nodejs.org for what these currently are.

Importing the module and usage

import IpfsMultiplexer from 'ipfs-multiplexer';

const ipfsMultiplexer = new IpfsMultiplexer();

// Optionally, you can add your own nodes to the list of available nodes
ipfsMultiplexer.addGateway({
  host: 'localhost',
  port: 5001,
  protocol: 'http',
});

ipfsMultiplexer.get('Qmaisz6NMhDB51cCvNWa1GMS7LU1pAxdF4Ld6Ft9kZEP2a')
  .then(console.log)
  .catch(console.error);

Importing helper functions

import { testGateway } from 'ipfs-multiplexer';

testGateway({
    host: 'localhost',
    port: 5001,
    protocol: 'http',  
  })
  .then(() => {
    // Everything went fine
    console.log('The gateway is up');
  })
  .catch(err => {
    // The error thrown by the gateway during test request
    console.error(err);
  });

In a web browser

through Browserify

Same as in Node.js, you just have to browserify the code before serving it. See the browserify repo for how to do that.

See the example provided by js-ipfs-http-client in the examples folder to get a boilerplate.

through webpack

See the example provided by js-ipfs-http-client in the examples folder to get an idea on how to use a package with webpack.

Custom Headers

If you wish to send custom headers with each request made by this library, for example, the Authorization header. You can use the config to do so:

ipfsMultiplexer.addGateway({
  host: 'localhost',
  port: 5001,
  protocol: 'http',
  headers: {
    authorization: 'Bearer ' + TOKEN,
  },
});

Usage

API

js-ipfs-http-client follows the spec defined by interface-ipfs-core, which concerns the interface to expect from IPFS implementations. This interface is a currently active endeavor. You can use it today to consult the methods available.

IMPORTANTE NOTE: Due to the nature of a multiplexer, the commands from the Network and Node Management categories are not available. Please refere to these links to see which part of the API is not available.

Files

• Regular Files API

  • ipfs.add(data, [options])
  • ipfs.addPullStream([options])
  • ipfs.addReadableStream([options])
  • ipfs.addFromStream(stream)
  • ipfs.addFromFs(path, [options])
  • ipfs.addFromURL(url, [options])
  • ipfs.cat(ipfsPath, [options])
  • ipfs.catPullStream(ipfsPath, [options])
  • ipfs.catReadableStream(ipfsPath, [options])
  • ipfs.get(ipfsPath, [options])
  • ipfs.getPullStream(ipfsPath, [options])
  • ipfs.getReadableStream(ipfsPath, [options])
  • ipfs.ls(ipfsPath)
  • ipfs.lsPullStream(ipfsPath)
  • ipfs.lsReadableStream(ipfsPath)

• MFS (mutable file system) specific

  Explore the Mutable File System through interactive coding challenges in our ProtoSchool tutorial.

  • ipfs.files.cp([from, to])
  • ipfs.files.flush([path])
  • ipfs.files.ls([path], [options])
  • ipfs.files.mkdir(path, [options])
  • ipfs.files.mv([from, to])
  • ipfs.files.read(path, [options])
  • ipfs.files.readPullStream(path, [options])
  • ipfs.files.readReadableStream(path, [options])
  • ipfs.files.rm(path, [options])
  • ipfs.files.stat(path, [options])
  • ipfs.files.write(path, content, [options])

• block

  • ipfs.block.get(cid, [options])
  • ipfs.block.put(block, [options])
  • ipfs.block.stat(cid)

• refs

  • ipfs.refs(ipfsPath, [options])
  • ipfs.refsReadableStream(ipfsPath, [options])
  • ipfs.refsPullStream(ipfsPath, [options])
  • ipfs.refs.local()
  • ipfs.refs.localReadableStream()
  • ipfs.refs.localPullStream()

Graph

• dag

  Explore the DAG API through interactive coding challenges in our ProtoSchool tutorial.

  • ipfs.dag.get(cid, [path], [options])
  • ipfs.dag.put(dagNode, [options])
  • ipfs.dag.tree(cid, [path], [options])

• object

  • ipfs.object.data(multihash, [options])
  • ipfs.object.get(multihash, [options])
  • ipfs.object.links(multihash, [options])
  • ipfs.object.new([template])
  • ipfs.object.patch.addLink(multihash, DAGLink, [options])
  • ipfs.object.patch.appendData(multihash, data, [options])
  • ipfs.object.patch.rmLink(multihash, DAGLink, [options])
  • ipfs.object.patch.setData(multihash, data, [options])
  • ipfs.object.put(obj, [options])
  • ipfs.object.stat(multihash, [options])

• pin

  • ipfs.pin.add(hash, [options])
  • ipfs.pin.ls([hash], [options])
  • ipfs.pin.rm(hash, [options])

• refs

  • ipfs.refs.local()

Additional Options

All core API methods take additional options specific to the HTTP API:

• headers - An object or Headers instance that can be used to set custom HTTP headers. Note that this option can also be configured globally via the constructor options.
• timeout - A number or string specifying a timeout for the request. If the timeout is reached before data is received a TimeoutError is thrown. If a number is specified it is interpreted as milliseconds, if a string is passed, it is intepreted according to parse-duration. Note that this option can also be configured globally via the constructor options.
• searchParams - An object or URLSearchParams instance that can be used to add additional query parameters to the query string sent with each request.

NOTE: The signal property thas is described here is not available with this package, because it is used to abort the requests that have not arrived by the time where the multiplexer already has a valid response.

Development

Testing

We run tests by executing npm test in a terminal window. This will run Node.js test.

NOTE: While because the package conforms with the interface-ipfs-core spec because it extends js-ipfs-http-client, the tests provided by the interface module are yet to be added to this package's tests.

Contribute

ipfs-multiplexer is a work in progress. As such, there's a few things you can do right now to help out:

• Check out the existing issues!
• Perform code reviews. More eyes will help a) speed the project along b) ensure quality and c) reduce possible future bugs.
• Add tests. There can never be enough tests. Note that interface tests exist inside interface-ipfs-core.
• Contribute to the js-ipfs-http-client repository by checking out issues, performing code reviews, adding tests or by contributing to their FAQ repository. Remember ipfs-multiplexer is based on js-ipfs-http-client, so every improvement it gets, helps make this package better.

Historical context

This module started as part of docsit-client when we tried to speed up the IPFS operations of our documents, but we realized that it had so much more potential as an independent package.