• This repository has been archived on 10/Mar/2020
  • Stars
    star
    1,050
  • Rank 43,891 (Top 0.9 %)
  • Language
    JavaScript
  • License
    Other
  • Created about 10 years ago
  • Updated over 4 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

[ARCHIVED] now part of the https://github.com/ipfs/js-ipfs repo

πŸ”’ Archived

The contents of this repo have been merged into ipfs/js-ipfs.

Please open issues or submit PRs there.

IPFS http client lib logo

The JavaScript HTTP client library for IPFS implementations.



A client library for the IPFS HTTP API, implemented in JavaScript. This client library implements the interface-ipfs-core enabling applications to change between an embedded js-ipfs node and any remote IPFS node without having to change the code. In addition, this client library implements a set of utility functions.

Lead Maintainer

Alan Shaw.

Table of Contents

Install

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

npm install --save ipfs-http-client

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

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

const ipfsClient = require('ipfs-http-client')

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

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

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

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

Importing a sub-module and usage

const bitswap = require('ipfs-http-client/src/bitswap')('/ip4/127.0.0.1/tcp/5001')

const list = await bitswap.wantlist(key)
// ...

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 js-ipfs-http-client with webpack.

from CDN

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

To always request the latest version, use the following:

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

Note: remove the .min from the URL to get the human-readable (not minified) version.

For maximum security you may also decide to:

  • reference aΒ specific version of IPFSΒ API (to prevent unexpected breakingΒ changes whenΒ aΒ newer latestΒ version isΒ published)
  • generate a SRI hash of thatΒ version andΒ useΒ it toΒ ensureΒ integrity
  • set the CORS settings attribute toΒ make anonymousΒ requests toΒ CDN

Example:

<script src="https://unpkg.com/[email protected]/dist/index.js"
integrity="sha384-5bXRcW9kyxxnSMbOoHzraqa7Z0PQWIao+cgeg327zit1hz5LZCEbIMx/LWKPReuB"
crossorigin="anonymous"></script>

CDN-based IPFS API provides the IpfsHttpClient constructor as a method of the global window object. Example:

const ipfs = window.IpfsHttpClient({ 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.IpfsHttpClient()

CORS

In a web browser IPFSΒ HTTP client (either browserified orΒ CDN-based) might encounter an error saying that the origin is not allowed. This would be a CORS ("Cross Origin Resource Sharing") failure: IPFSΒ servers areΒ designed toΒ reject requests from unknown domains by default. You can whitelist the domain that you are calling from by changing your ipfs config like this:

$ ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin  '["http://example.com"]'
$ ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "POST", "GET"]'

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:

const ipfs = ipfsClient({
  host: 'localhost',
  port: 5001,
  protocol: 'http',
  headers: {
    authorization: 'Bearer ' + TOKEN
  }
})

Global Timeouts

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

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

Usage

API

IPFS Core API Compatible

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.

Files

Graph

Network

Node Management

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.
  • signal - An AbortSignal that can be used to abort the request on demand.
  • 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.

Instance Utils

  • ipfs.getEndpointConfig()

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, ipfs-http-client exports various types and utilities that are included in the bundle:

These can be accessed like this, for example:

const { CID } = require('ipfs-http-client')
// ...or from an es-module:
import { CID } from 'ipfs-http-client'
Glob source

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

globSource(path, [options])
  • path: A path to a single file or directory to glob from
  • options: Optional options
  • options.recursive: If path is a directory, use option { recursive: true } to add the directory and all its sub-directories.
  • options.ignore: To exclude file globs from the directory, use option { ignore: ['ignore/this/folder/**', 'and/this/file'] }.
  • options.hidden: Hidden/dot files (files or folders starting with a ., for example, .git/) are not included by default. To add them, use the option { hidden: true }.

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

Example
const IpfsHttpClient = require('ipfs-http-client')
const { globSource } = IpfsHttpClient
const ipfs = IpfsHttpClient()

for await (const file of ipfs.add(globSource('./docs', { recursive: true }))) {
  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)
  • url: A string URL or URL instance to send HTTP GET request to

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

Example
const IpfsHttpClient = require('ipfs-http-client')
const { urlSource } = IpfsHttpClient
const ipfs = IpfsHttpClient()

for await (const file of ipfs.add(urlSource('https://ipfs.io/images/ipfs-logo.svg'))) {
  console.log(file)
}
/*
{
  path: 'ipfs-logo.svg',
  cid: CID('QmTqZhR6f7jzdhLgPArDPnsbZpvvgxzCZycXK7ywkLxSyU'),
  size: 3243
}
*/

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.

Contribute

The js-ipfs-http-client 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 FAQ repository with any questions you have about IPFS or any of the relevant technology. A good example would be asking, 'What is a merkledag tree?'. If you don't know a term, odds are, someone else doesn't either. Eventually, we should have a good understanding of where we need to improve communications and teaching together to make IPFS and IPNS better.

Want to hack on IPFS?

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

MIT

FOSSA Status

More Repositories

1

research-CRDT

[ARCHIVED] Repo to organize our ideas about research implementations of CRDTs.
484
star
2

reading-list

[ARCHIVED] Moved to https://docs.ipfs.io β€” papers to read to understand IPFS
TeX
225
star
3

interface-js-ipfs-core

[ARCHIVED] now part of the https://github.com/ipfs/js-ipfs repo
JavaScript
192
star
4

examples

[ARCHIVED] DEPRECATED β€” merged into IPFS docs
185
star
5

archives

[ARCHIVED] Repo to coordinate archival efforts with IPFS
183
star
6

website

This repo has been replaced by https://github.com/ipfs/ipfs-website/
Less
182
star
7

faq

[ARCHIVED] DEPRECATED, please use https://discuss.ipfs.io! Frequently Asked Questions
164
star
8

blog

[ARCHIVED] Source for the IPFS Blog
CSS
98
star
9

package-managers

[ARCHIVED] πŸ“¦ IPFS Package Managers Task Force
97
star
10

docs

[ARCHIVED] πŸ€– πŸ“š IPFS documentation working group, plus IPFS docs site code
HTML
87
star
11

kubernetes-ipfs

[ARCHIVED] kubernetes-ipfs
Go
60
star
12

dynamic-data-and-capabilities

[ARCHIVED] Dynamic Data and Capabilities in IPFS Working Group
59
star
13

js-libp2p-ipfs-nodejs

[ARCHIVED] DEPRECATED β€” libp2p build (module) used in js-ipfs
JavaScript
42
star
14

bifrost-gateway

Experimental gateway with delegated backend. No longer maintained, consider migrating to https://github.com/ipfs/rainbow/
Go
41
star
15

http-api-docs

Documentation on IPFS HTTP API endpoints.
Go
39
star
16

js-libp2p-ipfs-browser

[ARCHIVED] DEPRECATED β€” libp2p build (module) used in js-ipfs when running it on the browser
JavaScript
37
star
17

old-js-ipfs-website

The Website for the JavaScript implementation of the IPFS protocol
HTML
35
star
18

ipfs.js

[ARCHIVED] See https://github.com/ipfs/js-ipfs
33
star
19

starlog

[ARCHIVED] [DEPRECATED] logging the development of an interplanetary filesystem
HTML
33
star
20

http-api-spec

[ARCHIVED] DEPRECATED β€” Apiary IPFS HTTP API description
API Blueprint
32
star
21

sig-blockchain-data

[ARCHIVED] Using IPFS for storing data for Blockchain apps.
32
star
22

conf

[ARCHIVED] IPFS Conf [PLACEHOLDER REPOSITORY]
28
star
23

js-ipfs-mfs

[ARCHIVED] now part of the https://github.com/ipfs/js-ipfs repo
JavaScript
28
star
24

POST

[ARCHIVED] POST - a datastructure for human communication
24
star
25

ipfs-postmsg-proxy

[DEPRECATED] Use ipfs-message-port-server/client instead:
JavaScript
24
star
26

ipfs-ui-style-guide

A UI style guide for IPFS Apps
JavaScript
22
star
27

support

[ARCHIVED] For questions on how to get IPFS up and running smoothly
22
star
28

js-ipfs-unixfs-engine

[ARCHIVED] JavaScript implementation of the layout and chunking mechanisms used by IPFS
JavaScript
22
star
29

ipfs-web-app

[ARCHIVED] DEPRECATED β€” ipfs-web-app tool
JavaScript
19
star
30

developer-meetings

[ARCHIVED] 2018 IPFS Developers Meeting in Berlin
17
star
31

npm-go-ipfs-dep

DEPRECATED by https://github.com/ipfs/npm-go-ipfs
JavaScript
16
star
32

file-browser

[ARCHIVED] generic-ipfs-file-browser-ui-thing
JavaScript
16
star
33

research-p2p-video

[ARCHIVED] Repo to organize our ideas about research and implementations Video applications on top of IPFS and libp2p
16
star
34

research-bitswap

[ARCHIVED] repo to organize research on bitswap
15
star
35

research

[ARCHIVED] Moved to https://github.com/ipfs/notes
14
star
36

ipfs-redux-bundle

[DEPRECATED] Use ipfs-provider instead:
JavaScript
13
star
37

logo

[ARCHIVED] IPFS logo
HTML
13
star
38

refs

[ARCHIVED] DMCA notices, and tools for publishing them
Go
12
star
39

2016-IPFS-Workshop-Lisbon

[ARCHIVED] Repo for the 2016 Q3 Workshop, in Lisbon and remote
12
star
40

go-iprs

[ARCHIVED] go-ipfs records
Go
12
star
41

pdd

[ARCHIVED] Protocol Driven Development
12
star
42

archive-format

[ARCHIVED] DEPRECATED β€” car - Certified ARchives
12
star
43

gx-workspace

[ARCHIVED] A gx tool for working with a big bunch of repositories/packages
Go
12
star
44

window.ipfs-fallback

[DEPRECATED] Use ipfs-provider instead:
JavaScript
11
star
45

RFC

[ARCHIVED] RFCs for changes to IPFS and its surrounding projects
11
star
46

user-research

[ARCHIVED] User research for the IPFS Project.
10
star
47

glossary

[ARCHIVED] A collection of descriptions for terms related to ipfs and surrounding techs
10
star
48

pm-test-lab

[ARCHIVED] DEPRECATED β€” check https://github.com/ipfs/testground/ for the latest
10
star
49

fs-stress-test

[ARCHIVED] IPFS Stress tests
Shell
10
star
50

benchmark-js.ipfs.io

[ARCHIVED] Benchmarking interface for js-ipfs
JavaScript
9
star
51

window.ipfs-is-required

Show a download link for IPFS Companion when window.ipfs is not detected.
JavaScript
8
star
52

ipfs-performance-profiling

[ARCHIVED] Benchmarking tests for js-ipfs, using go-ipfs as a baseline.
JavaScript
8
star
53

jenkins

[ARCHIVED] Configuration for IPFS's build system
HCL
8
star
54

project-operations

[ARCHIVED] The IPFS Project Operations Working Group
7
star
55

project-repos

[ARCHIVED] Project health metrics
CoffeeScript
7
star
56

js-ipfs-name

Publishing and resolving IPNS records
JavaScript
6
star
57

connections-globe

[ARCHIVED] An interactive globe to view all your IPFS peers
JavaScript
6
star
58

interface-pull-blob-store

[ARCHIVED] Test suite for pull-blob-stores
JavaScript
6
star
59

websiter

[ARCHIVED] Foundation and tool for managing websites around IPFS
HTML
5
star
60

ops-requests

[ARCHIVED] Requests about infrastructure operations
5
star
61

dweblink-infra

[ARCHIVED] DEPRECATED β€” Infrastructure for dweb.link
HCL
5
star
62

ipfs-pages

[ARCHIVED] Easy publishing of static web content on IPFS
5
star
63

js-ipfs-multipart

[ARCHIVED] A set of utilities to help dealing with IPFS multipart
JavaScript
5
star
64

bitswap-ml

[ARCHIVED] bitswap + ml
5
star
65

go-commands

[ARCHIVED] DEPRECATED β€” Commands library for go-ipfs
Go
5
star
66

go-blocks

[ARCHIVED] DEPRECATED β€” Blockservice and blockstore for go-ipfs
Go
5
star
67

js-ipfs-unixfs-importer

[ARCHIVED] JavaScript implementation of the UnixFs importer used by IPFS
JavaScript
5
star
68

go-ipfs-addr

[ARCHIVED] DEPRECATED - Parsing utility for ipfs multiaddrs
Go
5
star
69

community-call-helper

[ARCHIVED] Schedule a Community Sync Up via Github Issues
Vue
4
star
70

ci-sync

[ARCHIVED] CI dashboard for Protocol Labs projects
Go
4
star
71

js-docker-base

[ARCHIVED] Base image for JS projects
Shell
4
star
72

sprint-helper-bot

[ARCHIVED] A helper for sprints
JavaScript
4
star
73

dev-team-enablement

[ARCHIVED] Dev Team Enablement Working Group
3
star
74

ipfs-mans

[ARCHIVED] DEPRECATED: The IPFS CLI Manuals
JavaScript
3
star
75

ipfs-metrics

[ARCHIVED] ipfs-metrics is a tool for managing ipfs event log streams
Go
3
star
76

conf.ipfs.io

[ARCHIVED] The IPFS Conference & Developer Meetings Website
3
star
77

go-key

[ARCHIVED] DEPRECATED β€” ipfs block keys and related utilities
Go
2
star
78

go-ds-lru

[ARCHIVED] A datastore implementation that uses an lru to cache results from a different backing datastore
Go
2
star
79

ipfs-nodeschool

[ARCHIVED] The workshoper to go InterPlanetary πŸŒπŸš€βœ¨πŸŒŒ
JavaScript
2
star
80

go-waffle

[ARCHIVED] Repo used to create a overview of all the Golang repos in waffle
2
star
81

jest-environment-aegir

[ARCHIVED] Jest Environment used in Aegir
JavaScript
2
star
82

jenkins-libs

[ARCHIVED] Reusable pipelines to be run on Jenkins
Groovy
2
star
83

badgerds-upgrade

[ARCHIVED] Badger datastore upgrade tool
Go
2
star
84

eslint-config-aegir

[ARCHIVED] Eslint Shareable Config for Aegir
JavaScript
2
star
85

node-github-issue-bot

[ARCHIVED] DEPRECATED β€” Automatically schedule and create GitHub issues
JavaScript
2
star
86

js-ipfs-unixfs-exporter

[ARCHIVED] JavaScript implementation of the UnixFs exporter used by IPFS
JavaScript
2
star
87

datatogether

[ARCHIVED] Old website for datatogether.org
HTML
2
star
88

ipfs-sharness-tests

[ARCHIVED] Sharness tests to test IPFS implementations
Shell
2
star
89

community-calls-reminder

[ARCHIVED] A script that reminds folks to sign up for community calls
JavaScript
1
star
90

aegir-test-repo

[ARCHIVED] A clone of js-ipfs-api that we use for testing aegir.
JavaScript
1
star
91

browser-process-platform

[ARCHIVED] Browser shim for Node.js process.platform.
JavaScript
1
star
92

go-ipfs-flags

[ARCHIVED] DEPRECATED - go-ipfs-flags groups go-ipfs configuration options used by several modules
Go
1
star
93

js-waffle

[ARCHIVED] Repo used to create a overview of all the JS repos in waffle
1
star