Name: js-ipfs
Owner: IPFS
Description: IPFS implementation in JavaScript
Created: 2014-05-30 00:31:06.0
Updated: 2018-01-17 18:59:21.0
Pushed: 2018-01-16 15:44:59.0
Homepage: https://ipfs.io
Size: 4215
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
We've come a long way, but this project is still in Alpha, lots of development is happening, API might change, beware of the Dragons ?..
Want to get started? Check our examples folder to learn how to spawn an IPFS node in Node.js and in the Browser.
You can check the development status at the Waffle Board.
Please read this: DHT (automatic content discovery) and Circuit Relay (pierce through NATs and dial between any node in the network) are two fundamental pieces that are not finalized yet. There are multiple applications that can be built without these two services but nevertheless they are fundamental to get that magic IPFS experience. If you want to track progress or contribute, please follow:
This project is available through npm. To install run
m install ipfs --save
Requires npm@3 and node@6 or above, tested on OSX & Linux, expected to work on Windows.
To include this project programmatically:
t IPFS = require('ipfs')
t node = new IPFS()
In order to use js-ipfs as a CLI, you must install it with the global flag. Run the following (even if you have ipfs installed locally):
m install ipfs --global
The CLI is available by using the command jsipfs in your terminal. This is aliased, instead of using ipfs, to make sure it does not conflict with the Go implementation.
Learn how to bundle with browserify and webpack in the examples folder.
You can also load it using a <script> using the unpkg CDN or the jsDelivr CDN. Inserting one of the following lines will make a Ipfs object available in the global namespace.
loading the minified version -->
ipt src="https://unpkg.com/ipfs/dist/index.min.js"></script>
ipt src="https://cdn.jsdelivr.net/npm/ipfs/dist/index.min.js"></script>
loading the human-readable (not minified) version -->
ipt src="https://unpkg.com/ipfs/dist/index.js"></script>
ipt src="https://cdn.jsdelivr.net/npm/ipfs/dist/index.js"></script>
Inserting one of the above lines will make an Ipfs object available in the global namespace.
The jsipfs CLI, available when js-ipfs is installed globally, follows(should, it is a WIP) the same interface defined by go-ipfs, you can always use the help command for help menus.
stall js-ipfs globally
m install ipfs --global
ipfs --help
ands:
tswap A set of commands to manipulate the bitswap agent.
ock Manipulate raw IPFS blocks.
otstrap Show or edit the list of bootstrap peers.
mmands List all available commands
nfig <key> [value] Get and set IPFS config values
emon Start a long-running daemon process
.
js-ipfs uses some different default config values, so that they don't clash directly with a go-ipfs node running in the same machine. These are:
~/.jsipfs (can be changed with env variable IPFS_PATH)40025002IPFS_BOOTSTRAP=1The IPFS Daemon exposes the API defined http-api-spec. You can use any of the IPFS HTTP-API client libraries with it, such as: js-ipfs-api.
If you want a programmatic way to spawn a IPFS Daemon using JavaScript, check out ipfsd-ctl module
Use the IPFS Module as a dependency of a project to spawn in process instances of IPFS.
Creating an IPFS instance couldn't be easier, all you have to do is:
reate the IPFS node instance
t node = new IPFS()
.on('ready', () => {
Your node is now ready to use \o/
stopping a node
de.stop(() => {
// node is now 'offline'
When starting a node, you can:
PFS will need a repo, it can create one for you or you can pass
t a repo instance of the type IPFS Repo
ttps://github.com/ipfs/js-ipfs-repo
t repo = <IPFS Repo instance or repo path>
t node = new IPFS({
po: repo,
it: true, // default
init: false,
init: {
bits: 1024 // size of the RSA key generated
},
art: true, // default
start: false,
ss: undefined // default
pass: 'pass phrase for key access',
PERIMENTAL: { // enable experimental features
pubsub: true,
sharding: true, // enable dir sharding
dht: true // enable KadDHT, currently not interopable with go-ipfs
nfig: { // overload the default IPFS node config, find defaults at https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime
Addresses: {
Swarm: [
'/ip4/127.0.0.1/tcp/1337'
]
}
bp2p: { // add custom modules to the libp2p stack of your node
modules: {}
vents
.on('ready', () => {}) // Node is ready to use when you first create it
.on('error', (err) => {}) // Node has hit some error while initing/starting
.on('init', () => {}) // Node has successfully finished initing the repo
.on('start', () => {}) // Node has started
.on('stop', () => {}) // Node has stopped
You can find some examples and tutorials in the examples folder, these exist to help you get started using js-ipfs.
A complete API definition is in the works. Meanwhile, you can learn how to you use js-ipfs through the standard interface at .
Filesipfs.repo.init
ipfs.repo.version
ipfs.repo.gc (not implemented, yet!)
Graphipfs.object.patch.addLink(multihash, DAGLink, [options, callback])
ipfs.object.patch.rmLink(multihash, DAGLink, [options, callback])
ipfs.object.patch.appendData(multihash, data, [options, callback])
ipfs.object.patch.setData(multihash, data, [options, callback])
Crypto and Key Managementipfs.key.export(name, password, [callback])ipfs.key.gen(name, options, [callback])ipfs.key.import(name, pem, password, [callback])ipfs.key.list([callback])ipfs.key.rename(oldName, newName, [callback])ipfs.key.rm(name, [callback])Networkipfs.bootstrap.list
ipfs.bootstrap.add
ipfs.bootstrap.rm
ipfs.bitswap.wantlist()
ipfs.bitswap.stat()
ipfs.bitswap.unwant()
libp2p. Every IPFS instance also exposes the libp2p SPEC at ipfs.libp2p. The formal interface for this SPEC hasn't been defined by you can find documentation at its implementations:
Node Managementipfs.ping()
ipfs.init([options], callback)
ipfs.start([callback])
ipfs.stop([callback])
ipfs.isOnline()
Domain data typesA set of data types are exposed directly from the IPFS instance under ipfs.types. That way you're not required to import/require the following.
ipfs.types.Bufferipfs.types.PeerIdipfs.types.PeerInfoipfs.types.multiaddripfs.types.multihashipfs.types.CIDTo add a WebRTC transport to your js-ipfs node, you must add a WebRTC multiaddr. To do that, simple override the config.Addresses.Swarm array which contains all the multiaddrs which the IPFS node will use. See below:
t node = new IPFS({
nfig: {
Addresses: {
Swarm: [
'/dns4/wrtc-star.discovery.libp2p.io/tcp/443/wss/p2p-webrtc-star'
]
}
.on('ready', () => {
your instance with WebRTC is ready
Important: This transport usage is kind of unstable and several users have experienced crashes. Track development of a solution at https://github.com/ipfs/js-ipfs/issues/1088.
Yes, however, bare in mind that there isn't a 100% stable solution to use WebRTC in Node.js, use it at your own risk. The most tested options are:
To add WebRTC support in a IPFS node instance, do:
t wrtc = require('wrtc') // or require('electron-webrtc')()
t WStar = require('libp2p-webrtc-star')
t wstar = new WStar({ wrtc: wrtc })
t node = new IPFS({
po: 'your-repo-path',
start: false,
nfig: {
Addresses: {
Swarm: [
"/ip4/0.0.0.0/tcp/4002",
"/ip4/127.0.0.1/tcp/4003/ws",
"/dns4/wrtc-star.discovery.libp2p.io/tcp/433/wss/p2p-webrtc-star"
]
}
bp2p: {
modules: {
transport: [wstar],
discovery: [wstar.discovery]
}
.on('ready', () => {
your instance with WebRTC is ready
To add WebRTC support to the IPFS daemon, you only need to install one of the WebRTC modules globally:
install wrtc --global
install electron-webrtc --global
Then, update your IPFS Daemon config to include the multiaddr for this new transport on the Addresses.Swarm array. Add: "/dns4/wrtc-star.discovery.libp2p.io/wss/p2p-webrtc-star"
signaling endpoint for my WebRTC transport?You'll need to execute a compatible signaling server (libp2p-webrtc-star works) and include the correct configuration param for your IPFS node:
multiaddr for the signaling servert node = new IPFS({
po: 'your-repo-path',
nfig: {
Addresses: {
Swarm: [
'/ip4/127.0.0.1/tcp/9090/ws/p2p-webrtc-star'
]
}
The code above assumes you are running a local signaling server on port 9090. Provide the correct values accordingly.
Yes, websocket-star! A WebSockets based transport that uses a Relay to route the messages. To enable it, just do:
t node = new IPFS({
nfig: {
Addresses: {
Swarm: [
'/dns4/ws-star.discovery.libp2p.io/tcp/443/wss/p2p-websocket-star'
]
}
.on('ready', () => {
your instance with websocket-star is ready
Yes, unfortunately, due to Chrome aggressive resource throttling policy, it cuts freezes the execution of any background tab, turning an IPFS node that was running on that webpage into a vegetable state.
A way to mitigate this in Chrome, is to run your IPFS node inside a Service Worker, so that the IPFS instance runs in a background process. You can learn how to install an IPFS node as a service worker in here the repo ipfs-service-worker
Yes you can and in many ways. Read https://github.com/ipfs/notes/issues/256 for the multiple options.
If your electron-rebuild step is failing, all you need to do is:
ectron's version.
rt npm_config_target=1.7.6
e architecture of Electron, can be ia32 or x64.
rt npm_config_arch=x64
rt npm_config_target_arch=x64
wnload headers for Electron.
rt npm_config_disturl=https://atom.io/download/electron
ll node-pre-gyp that we are building for Electron.
rt npm_config_runtime=electron
ll node-pre-gyp to build module from source code.
rt npm_config_build_from_source=true
stall all dependencies, and store cache to ~/.electron-gyp.
=~/.electron-gyp npm install
If you find any other issue, please check the Electron Support issue.
| Package | Version | Deps | DevDeps | Travis | Circle | AppVeyor | Coverage |
|———|———|——|———|——–|——–|———-|———-|
| API Specs |
| interface-ipfs-core | 
| 
| 
| 
| | | |
| http-api-spec | | |
| cli spec | | | |
| Repo |
| ipfs-repo | 
| 
| 
| 
| 
| |
|
| DAG |
| ipld-resolver | 
| 
| 
| 
| 
| |
|
| ipld-dag-pb | 
| 
| 
| 
| 
| |
|
| ipld-dag-cbor | 
| 
| 
| 
| 
| |
|
| Files |
| ipfs-unixfs-engine | 
| 
| 
| 
| 
| |
|
| Exchange |
| ipfs-block-service | 
| 
| 
| 
| 
| |
|
| ipfs-bitswap | 
| 
| 
| 
| 
| |
|
| Swarm/libp2p |
| js-libp2p | 
| 
| 
| 
| 
| |
|
| js-libp2p-circuit | 
| 
| 
| 
| 
| |
|
| js-libp2p-floodsub | 
| 
| 
| 
| 
| |
|
| js-libp2p-kad-dht | 
| 
| 
| 
| 
| |
|
| js-libp2p-mdns | 
| 
| 
| 
| 
| |
|
| js-libp2p-multiplex | 
| 
| 
| 
| 
| |
|
| js-libp2p-railing | 
| 
| 
| 
| 
| |
|
| js-libp2p-secio | 
| 
| 
| 
| 
| |
|
| js-libp2p-tcp | 
| 
| 
| 
| 
| |
|
| js-libp2p-webrtc-star | 
| 
| 
| 
| 
| |
|
| js-libp2p-websocket-star | 
| 
| 
| 
| 
| |
|
| js-libp2p-websockets | 
| 
| 
| 
| 
| |
|
| Data Types |
| ipfs-block | 
| 
| 
| 
| 
| |
|
| ipfs-unixfs | 
| 
| 
| 
| 
| |
|
| peer-id | 
| 
| 
| 
| 
| |
|
| peer-info | 
| 
| 
| 
| 
| |
|
| multiaddr | 
| 
| 
| 
| 
| |
|
| multihashes | 
| 
| 
| 
| 
| |
|
| Generics/Utils |
| ipfs-api | 
| 
| 
| 
| 
| |
|
| ipfs-multipart | 
| 
| 
| 
| | |
|
| is-ipfs | 
| 
| 
| 
| | |
|
| multihashing | 
| 
| 
| 
| 
| |
|
| mafmt | 
| 
| 
| 
| 
| |
|
| Crypto
| libp2p-crypto | 
| 
| 
| 
| 
| |
|
| libp2p-keychain | 
| 
| 
| 
| 
| |
|
t clone https://github.com/ipfs/js-ipfs.git
js-ipfs
m install
n all the unit tsts
m test
n just IPFS tests in Node.js
m run test:node:core
n just IPFS core tests
m run test:node:core
n just IPFS HTTP-API tests
m run test:node:http
n just IPFS CLI tests
m run test:node:cli
n just IPFS core tests in the Browser (Chrome)
m run test:browser
Run the interop tests with https://github.com/ipfs/interop
n all the benchmark tests
m run benchmark
n just IPFS benchmarks in Node.js
m run benchmark:node
n just IPFS benchmarks in Node.js for an IPFS instance
m run benchmark:node:core
n just IPFS benchmarks in Node.js for an IPFS daemon
m run benchmark:node:http
n just IPFS benchmarks in the browser (Chrome)
m run benchmark:browser
Conforming to linting rules is a prerequisite to commit to js-ipfs.
m run lint
m run build
ee src -L 2
# Main source code folder
cli # Implementation of the IPFS CLI
??? ...
http-api # The HTTP-API implementation of IPFS as defined by http-api-spec
core # IPFS implementation, the core (what gets loaded in browser)
??? components # Each of IPFS subcomponent
??? ...
...
The HTTP API exposed with js-ipfs can also be used for exposing metrics about the running js-ipfs node and other Node.js metrics.
To enable it, you need to set the environment variable IPFS_MONITORING (any value)
Once the environment variable is set and the js-ipfs daemon is running, you can get the metrics (in prometheus format) by making a GET request to the following endpoint:
://localhost:5002/debug/metrics/prometheus
What does this image explain?
ipfs-repo which picks fs or indexeddb as its storage drivers, depending if it is running in Node.js or in the Browser.bitswap, uses the Block Service which in turn uses the Repo, offering a get and put of blocks to the IPFS implementation.ipfs-unixfs-engine to import and export files to and from IPFS.IPFS implementation in JavaScript is a work in progress. As such, there's a few things you can do right now to help out:
