Name: js-ipfs
Owner: TABLEFLIP
Description: IPFS implementation in JavaScript
Forked from: ipfs/js-ipfs
Created: 2017-08-30 10:47:29.0
Updated: 2017-08-30 10:47:31.0
Pushed: 2017-09-08 15:58:01.0
Homepage: https://ipfs.io
Size: 3382
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.
Important to note: DHT and Relay are not finalized yet, you won't have resource discovery happening by default as you get in go-ipfs, we are working actively on these pieces, 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. Inserting one of the following lines will make a Ipfs
object available in the global namespace.
ipt src="https://unpkg.com/ipfs/dist/index.min.js"></script> <!-- loading the minified version -->
ipt src="https://unpkg.com/ipfs/dist/index.js"></script> <!-- loading the human-readable (not minified) version -->
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
)4002
5002
IPFS_BOOTSTRAP=1
The HTTP-API exposed by the js-ipfs daemon follows the http-api-spec
. You can use any of the IPFS HTTP-API client libraries with it, such as: js-ipfs-api.
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,
start: false,
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
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 .
ipfs.files.add(data, [options], [callback])
ipfs.files.createAddStream([options], [callback])
ipfs.files.cat(multihash, [callback])
ipfs.files.get(hash, [callback])
ipfs.dag.put(dagNode, options, callback)
ipfs.dag.get(cid [, path, options], callback)
ipfs.dag.tree(cid [, path, options], callback)
ipfs.pubsub.subscribe(topic, options, handler, callback)
ipfs.pubsub.unsubscribe(topic, handler)
ipfs.pubsub.publish(topic, data, callback)
ipfs.pubsub.ls(topic, callback)
ipfs.pubsub.peers(topic, callback)
Every IPFS instance also exposes the libp2p API at ipfs.libp2p
. The formal interface for this API hasn't been defined by you can find documentation at its implementations:
ipfs.id([callback])
ipfs.version([callback])
ipfs.ping()
ipfs.init([options], callback)
ipfs.start([callback])
ipfs.stop([callback])
ipfs.isOnline()
ipfs.bitswap.wantlist()
ipfs.bitswap.stat()
ipfs.bitswap.unwant()
ipfs.block.get(cid, [options, callback])
ipfs.block.put(block, cid, [callback])
ipfs.block.stat(cid, [callback])
ipfs.config.get([key, callback])
ipfs.config.set(key, value, [callback])
ipfs.config.replace(config, [callback])
ipfs.bootstrap.list
ipfs.bootstrap.add
ipfs.bootstrap.rm
ipfs.repo.init
ipfs.repo.version
ipfs.repo.gc
(not implemented, yet!)ipfs.swarm.addrs([callback])
ipfs.swarm.connect(addr, [callback])
ipfs.swarm.disconnect(addr, [callback])
ipfs.swarm.peers([opts] [, callback])
Consider using the dag API API instead.
ipfs.object.new([template][, callback])
ipfs.object.put(obj, [options, callback])
ipfs.object.get(multihash, [options, callback])
ipfs.object.data(multihash, [options, callback])
ipfs.object.links(multihash, [options, callback])
ipfs.object.stat(multihash, [options, callback])
ipfs.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])
A 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.Buffer
ipfs.types.PeerId
ipfs.types.PeerInfo
ipfs.types.multiaddr
ipfs.types.multihash
ipfs.types.CID
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/star-signal.cloud.ipfs.team/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/star-signal.cloud.ipfs.team/wss/p2p-webrtc-star"
| Package | Version | Deps | DevDeps | Build |
|———|———|————–|—————–|———–|
| 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
| | | | |
| Swarm/libp2p |
| js-libp2p
| | | | |
| Data Types |
| ipfs-block
| | | | |
| ipfs-unixfs
| | | | |
| peer-id
| | | | |
| peer-info
| | | | |
| multiaddr
| | | | |
| multihashes
| | | | |
| Generics/Utils |
| ipfs-api
| | | | |
| ipfs-multipart
| | | | |
| multihashing
| | | | |
| mafmt
| | | | |
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:unit:node:core
n just IPFS core tests
m run test:unit:node:core
n just IPFS HTTP-API tests
m run test:unit:node:http
n just IPFS CLI tests
m run test:unit:node:cli
n just IPFS core tests in the Browser (Chrome)
m run test:unit:browser
n all the interop tsts
m run test:interop
n just IPFS interop tests in Node.js using one go-ipfs daemon and one js-ipfs daemon
m run test:interop:node
n just IPFS interop testsin the Browser (Chrome) using one instance in the browser and one go-ipfs daemon
m run test:interop:browser
n all the benchmark tests
m run test:benchmark
n just IPFS benchmarks in Node.js
m run test:benchmark:node
n just IPFS benchmarks in Node.js for an IPFS instance
m run test:benchmark:node:core
n just IPFS benchmarks in Node.js for an IPFS daemon
m run test:benchmark:node:http
n just IPFS benchmarks in the browser (Chrome)
m run test: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 nodejs metrics.
To enable it, you need to set the environment variable IPFS_MONITORING
(any value)
Once 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: