Home

Awesome

kubo-rpc-client <!-- omit in toc -->

ipfs.tech Discuss codecov CI

A client library for the Kubo RPC API

Table of contents <!-- omit in toc -->

Install

$ npm i kubo-rpc-client

Browser <script> tag

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

<script src="https://unpkg.com/kubo-rpc-client/dist/index.min.js"></script>

Kubo RPC Client

<h3 align="center">JavaScript client library for the Kubo RPC API</h3> <p align="center"> <a href="https://app.element.io/#/room/#ipfs-chatter:ipfs.io"><img src="https://img.shields.io/badge/matrix-%23ipfs%3Amatrix.org-blue.svg?style=flat" /> </a> <a href="https://discord.gg/ipfs"><img src="https://img.shields.io/discord/806902334369824788?color=blueviolet&label=discord&style=flat" /></a> <a href="https://github.com/ipfs/team-mgmt/blob/master/MGMT_JS_CORE_DEV.md"><img src="https://img.shields.io/badge/team-mgmt-blue.svg?style=flat" /></a> </p> <p align="center"> <a href="https://codecov.io/gh/ipfs/js-kubo-rpc-client"><img src="https://img.shields.io/codecov/c/github/ipfs/js-kubo-rpc-client/master.svg?style=flat-square"></a> <a href="https://bundlephobia.com/result?p=kubo-rpc-client"><img src="https://flat.badgen.net/bundlephobia/minzip/kubo-rpc-client"></a> <br> <a href="https://github.com/feross/standard"><img src="https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square"></a> <a href="https://github.com/RichardLitt/standard-readme"><img src="https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square" /></a> <a href=""><img src="https://img.shields.io/badge/npm-%3E%3D3.0.0-orange.svg?style=flat-square" /></a> <a href=""><img src="https://img.shields.io/badge/Node.js-%3E%3D10.0.0-orange.svg?style=flat-square" /></a> <a href="https://www.npmjs.com/package/kubo-rpc-client"><img src="https://img.shields.io/npm/dm/kubo-rpc-client.svg" /></a> <a href="https://www.jsdelivr.com/package/npm/kubo-rpc-client"><img src="https://data.jsdelivr.com/v1/package/npm/kubo-rpc-client/badge"/></a> <br> </p>

Getting Started

We've come a long way, but this project is still in Alpha, lots of development is happening, APIs might change, beware of 🐉..

npm install --save kubo-rpc-client

Both the Current and Active LTS versions of Node.js are supported. Please see nodejs.org for what these currently are.

Next Steps

<!-- TODO: currently useless - Read the [docs](https://ipfs.github.io/js-kubo-rpc-client) -->

Usage

create([options])

create an instance of the HTTP API client

Parameters

None

Options

options can be a String, a URL or a Multiaddr which will be interpreted as the address of the IPFS node we wish to use the API of.

Alternatively it can be an object which may have the following keys:

NameTypeDefaultDescription
urlString or URL or Multiaddr'http://localhost:5001/api/v0'A URL that resolves to a running instance of the IPFS HTTP RPC API
protocolString'http'The protocol to used (ignored if url is specified)
hostString'localhost'The host to used (ignored if url is specified)
portnumber5001The port to used (ignored if url is specified)
pathString'api/v0'The path to used (ignored if url is specified)
agenthttp.Agenthttp.Agent({ keepAlive: true, maxSockets: 6 })An http.Agent used to control client behaviour (node.js only)

Returns

TypeDescription
ObjectAn object that conforms to the IPFS Core API

Example

import { create } from 'kubo-rpc-client'

// connect to the default API address http://localhost:5001
const client = create()

// connect to a different API
const client = create({ url: "http://127.0.0.1:5002/api/v0" });

// connect using a URL
const client = create(new URL('http://127.0.0.1:5002'))

// call Core API methods
const { cid } = await client.add('Hello world!')

Do you use Kubo's API.Authorizations? Check the Custom Headers section.

API

kubo-rpc-client will not implement the IPFS Core API. Please see https://github.com/ipfs/kubo/issues/9125 for more information.

Additional Options

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

Instance Utils

Call this on your client instance to return an object containing the host, port, protocol and api-path.

Static Types and Utils

Aside from the default export, kubo-rpc-client exports various types and utilities that are included in the bundle:

These can be accessed like this, for example:

import { CID } from 'kubo-rpc-client'

Glob source

A utility to allow files on the file system to be easily added to IPFS.

globSource(path, pattern, [options])

Returns an async iterable that yields { path, content } objects suitable for passing to ipfs.add.

Example
import { create, globSource } from 'ipfs'

const ipfs = await create()

for await (const file of ipfs.addAll(globSource('./docs', '**/*'))) {
  console.log(file)
}
/*
{
  path: 'docs/assets/anchor.js',
  cid: CID('QmVHxRocoWgUChLEvfEyDuuD6qJ4PhdDL2dTLcpUy3dSC2'),
  size: 15347
}
{
  path: 'docs/assets/bass-addons.css',
  cid: CID('QmPiLWKd6yseMWDTgHegb8T7wVS7zWGYgyvfj7dGNt2viQ'),
  size: 232
}
...
*/

URL source

A utility to allow content from the internet to be easily added to IPFS.

urlSource(url)

Returns an async iterable that yields { path, content } objects suitable for passing to ipfs.add.

Example
import { create, urlSource } from 'kubo-rpc-client'
const ipfs = create()

const file = await ipfs.add(urlSource('https://ipfs.io/images/ipfs-logo.svg'))
console.log(file)

/*
{
  path: 'ipfs-logo.svg',
  cid: CID('QmTqZhR6f7jzdhLgPArDPnsbZpvvgxzCZycXK7ywkLxSyU'),
  size: 3243
}
*/

Running the daemon with the right port

To interact with the API, you need to have a local daemon running. It needs to be open on the right port. 5001 is the default, and is used in the examples below, but it can be set to whatever you need.

# Show the ipfs config API port to check it is correct
> ipfs config Addresses.API
/ip4/127.0.0.1/tcp/5001
# Set it if it does not match the above output
> ipfs config Addresses.API /ip4/127.0.0.1/tcp/5001
# Restart the daemon after changing the config

# Run the daemon
> ipfs daemon

Importing the module and usage

import { create } from 'kubo-rpc-client'

// connect to ipfs daemon API server
const ipfs = create('http://localhost:5001') // (the default in Node.js)

// or connect with multiaddr
const ipfs = create('/ip4/127.0.0.1/tcp/5001')

// or using options
const ipfs = create({ host: 'localhost', port: '5001', protocol: 'http' })

// or specifying a specific API path
const ipfs = create({ host: '1.1.1.1', port: '80', apiPath: '/ipfs/api/v0' })

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 in the examples folder to get a boilerplate.

through webpack

See the example in the examples folder to get an idea on how to use kubo-rpc-client with webpack.

from CDN

Instead of a local installation (and browserification) you may request a remote copy of IPFS API from jsDelivr.

To always request the latest version, use one of the following examples:

<!-- loading the minified version using jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/kubo-rpc-client/dist/index.min.js"></script>

For maximum security you may also decide to:

Example:

<script
  src="https://www.jsdelivr.com/package/npm/kubo-rpc-client"
  integrity="sha384-5bXRcW9kyxxnSMbOoHzraqa7Z0PQWIao+cgeg327zit1hz5LZCEbIMx/LWKPReuB"
  crossorigin="anonymous"
></script>

CDN-based IPFS API provides the KuboRpcClient object of the global window object. Example:

const ipfs = window.KuboRpcClient.create({ host: 'localhost', port: 5001 })

If you omit the host and port, the client will parse window.host, and use this information. This also works, and can be useful if you want to write apps that can be run from multiple different gateways:

const ipfs = window.KuboRpcClient.create()

Custom Headers

If you wish to send custom headers with each request made by this library, for example, the Authorization header. This can be useful if your Kubo node has keys defined in API.Authorizations.

If you're using bearer:token, where token is abc123:

const ipfs = create({
  host: 'localhost',
  port: 5001,
  protocol: 'http',
  headers: {
    authorization: 'Bearer abc123'
  }
})

If you're using basic:user:password, where user:password is alice:secret:

const ipfs = create({
  host: 'localhost',
  port: 5001,
  protocol: 'http',
  headers: {
    // For Node.js, using:
    //    Buffer.from('alice:secret').toString('base64')
    // is preferred over using `btoa`.
    authorization: 'Basic ' + btoa('alice:secret')
  }
})

Global Timeouts

To set a global timeout for all requests pass a value for the timeout option:

// Timeout after 10 seconds
const ipfs = create({ timeout: 10000 })
// Timeout after 2 minutes
const ipfs = create({ timeout: '2m' })
// see https://www.npmjs.com/package/parse-duration for valid string values

Development

Testing

We run tests by executing npm test in a terminal window. This will run both Node.js and Browser tests, both in Chrome and PhantomJS. To ensure that the module conforms with the interface-ipfs-core spec, we run the batch of tests provided by the interface module, which can be found here.

Historical context

This module started as a direct mapping from the go-ipfs cli to a JavaScript implementation, although this was useful and familiar to a lot of developers that were coming to IPFS for the first time, it also created some confusion on how to operate the core of IPFS and have access to the full capacity of the protocol. After much consideration, we decided to create interface-ipfs-core with the goal of standardizing the interface of a core implementation of IPFS, and keep the utility functions the IPFS community learned to use and love, such as reading files from disk and storing them directly to IPFS.

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.