diff --git a/.gitignore b/.gitignore index a589b3fa49..02deb582c6 100644 --- a/.gitignore +++ b/.gitignore @@ -18,9 +18,6 @@ node_modules # Build artefacts dist -# Doc generation -docs - # Deployment files .npmrc diff --git a/packages/ipfs/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md similarity index 84% rename from packages/ipfs/ISSUE_TEMPLATE.md rename to ISSUE_TEMPLATE.md index b4b5720d66..3cf0010c0d 100644 --- a/packages/ipfs/ISSUE_TEMPLATE.md +++ b/ISSUE_TEMPLATE.md @@ -1,13 +1,16 @@ #### Type: - - -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 πŸ‰. +We've come a long way, but this project is still in Alpha, lots of development is happening, APIs might change, beware of πŸ‰.. -**Want to get started?** Check our [examples folder](/examples) to learn how to spawn an IPFS node in Node.js and in the Browser. +## Getting started -🚨 **Please read this** 🚨 The [DHT](https://en.wikipedia.org/wiki/Distributed_hash_table), a fundamental piece for automatic content and peer discovery is not yet complete. There are multiple applications that can be built without this service but nevertheless it is fundamental to getting that magic IPFS experience. The current status is that implementation is done and merged and we're working on performance issues. Expect the DHT to be available in a release very soon. - -[**`Weekly Core Implementations Call`**](https://github.com/ipfs/team-mgmt/issues/992) +* Look into the [examples folder](https://github.com/ipfs/js-ipfs/tree/master/examples) to learn how to spawn an IPFS node in Node.js and in the Browser +* Read the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node +* Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it +* Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs +* Check out https://docs-beta.ipfs.io for tips, how-tos and more ## Tech Lead @@ -43,22 +38,22 @@ We've come a long way, but this project is still in Alpha, lots of development i ## Lead Maintainer -[Alan Shaw](https://github.com/alanshaw) +[Alex Potsides](http://github.com/achingbrain) ## Table of Contents +- [Getting started](#getting-started) +- [Documentation](#documentation) - [Structure](#structure) -- [Development](#development) - - [Clone and install dependencies](#clone-and-install-dependencies) - - [Run tests](#run-tests) - - [Lint](#lint) - - [Build a dist version](#build-a-dist-version) - - [Publishing new versions](#publishing-new-versions) - - [Using prerelease versions](#using-prerelease-versions) -- [Contribute](#contribute) - - [Want to hack on IPFS?](#want-to-hack-on-ipfs) +- [Want to hack on IPFS?](#want-to-hack-on-ipfs) - [License](#license) +## Documentation + +* [Core API](./docs/core-api) +* [Examples](./examples) +* [Development](./docs/DEVELOPMENT.md) + ## Structure This project is broken into several modules, their purposes are: @@ -66,83 +61,25 @@ This project is broken into several modules, their purposes are: * [`/packages/ipfs`](./packages/ipfs) The core implementation * [`/packages/ipfs-http-client`](./packages/ipfs-http-client) A client for the RPC-over-HTTP API presented by both js-ipfs and go-ipfs * [`/packages/interface-ipfs-core`](./packages/interface-ipfs-core) Tests to ensure adherance of an implementation to the spec -* [`/packages/ipfs-utils`](./packages/ipfs-utils) Helpers and utilities common to core and the HTTP RPC API client -* [`/packages/ipfs-mfs`](./packages/ipfs-mfs) The mfs implementation -* [`/packages/ipfs-multipart`](./packages/ipfs-multipart) A module that handles adding files via multipart HTTP requests for core and the mfs - -## Development - -### Clone and install dependencies - -```sh -> git clone https://github.com/ipfs/js-ipfs.git -> cd js-ipfs -> npm install -``` - -This will install [lerna](https://www.npmjs.com/package/lerna) and bootstrap the various packages, deduping and hoisting dependencies into the root folder. - -If later you add new dependencies to submodules or just wish to remove all the `node_modules`/`dist` folders and start again, run `npm run reset && npm install` from the root. - -See the scripts section of the root [`package.json`](./package.json) for more commands. - -### Run tests - -```sh -# run all the unit tests -> npm test - -# run just IPFS tests in Node.js -> npm run test:node +* [`/packages/ipfs-core-utils`](./packages/ipfs-core-utils) Helpers and utilities common to core and the HTTP RPC API client -# run just IPFS tests in a browser -> npm run test:browser +## Want to hack on IPFS? -# run just IPFS tests in a webworker -> npm run test:webworker -``` - -More granular test suites can be run from each submodule. - -Please see the `package.json` in each submodule for available commands. - -### Lint - -Please run the linter before submitting a PR, the build will not pass if it fails: - -```sh -> npm run lint -``` - -### Build a dist version - -```sh -> npm run build -``` - -### Publishing new versions - -1. Ensure you have a `GH_TOKEN` env var containing a GitHub [Personal Access Token](https://github.com/settings/tokens) with `public_repo` permissions -2. From the root of this repo run `npm run release` and follow the on screen prompts. It will use [conventional commits](https://www.conventionalcommits.org) to work out the new package version - -### Using prerelease versions - -Any changed packages from each successful build of master are published to npm as canary builds under the npm tag `next`. +[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) -## Contribute +The IPFS implementation in JavaScript needs your help! There are a few things you can do right now to help out: -IPFS implementation in JavaScript is a work in progress. As such, there's a few things you can do right now to help out: +Read the [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md) and [JavaScript Contributing Guidelines](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md). -- Go through the modules below and **check out existing issues**. This would be especially useful for modules in active development. Some knowledge of IPFS may be required, as well as the infrastructure behind it - for instance, you may need to read up on p2p and more complex operations like muxing to be able to help technically. -- **Perform code reviews**. More eyes will help (a) speed the project along, (b) ensure quality, and (c) reduce possible future bugs. -- Take a look at go-ipfs and some of the planning repositories or issues: for instance, the [libp2p spec](https://github.com/ipfs/specs/pull/19). Contributions here that would be most helpful are **top-level comments** about how it should look based on our understanding. Again, the more eyes the better. +- **Check out existing issues** The [issue list](https://github.com/ipfs/js-ipfs/issues) has many that are marked as ['help wanted'](https://github.com/ipfs/js-ipfs/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) or ['difficulty:easy'](https://github.com/ipfs/js-ipfs/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Adifficulty%3Aeasy) which make great starting points for development, many of which can be tackled with no prior IPFS knowledge +- **Look at the [IPFS Roadmap](https://github.com/ipfs/roadmap)** This are the high priority items being worked on right now +- **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. +- **Join the [Weekly Core Implementations Call](https://github.com/ipfs/team-mgmt/issues/992)** it's where everyone discusses what's going on with IPFS and what's next -### Want to hack on IPFS? - -[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) - -Check out [ipfs/community/CONTRIBUTING_JS.md](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md) for details on coding standards, commit messages and other project conventions ## License diff --git a/packages/ipfs/docs/using-js-ipfs-in-the-browser.md b/docs/BROWSERS.md similarity index 100% rename from packages/ipfs/docs/using-js-ipfs-in-the-browser.md rename to docs/BROWSERS.md diff --git a/packages/ipfs/docs/config.md b/docs/CONFIG.md similarity index 97% rename from packages/ipfs/docs/config.md rename to docs/CONFIG.md index b4bf37c92d..2980292b79 100644 --- a/packages/ipfs/docs/config.md +++ b/docs/CONFIG.md @@ -1,8 +1,32 @@ -# The js-ipfs config file +# The js-ipfs config file The js-ipfs config file is a JSON document located in the root directory of the js-ipfs repository. -#### Profiles +## Table of Contents + +- [Profiles](#profiles) +- [`Addresses`](#addresses) + - [`API`](#api) + - [`Delegates`](#delegates) + - [`Gateway`](#gateway) + - [`Swarm`](#swarm) +- [`Bootstrap`](#bootstrap) +- [`Datastore`](#datastore) + - [`Spec`](#spec) +- [`Discovery`](#discovery) + - [`MDNS`](#mdns) + - [`webRTCStar`](#webrtcstar) +- [`Identity`](#identity) + - [`PeerID`](#peerid) + - [`PrivKey`](#privkey) +- [`Keychain`](#keychain) +- [`Pubsub`](#pubsub) + - [`Router`](#router) + - [`Enabled`](#enabled) +- [`Swarm`](#swarm-1) + - [`ConnMgr`](#connmgr) + +## Profiles Configuration profiles allow to tweak configuration quickly. Profiles can be applied with `--profile` flag to `ipfs init` or with the `ipfs config profile @@ -40,29 +64,8 @@ Available profiles: Inverse of "lowpower" profile. -## Table of Contents - -- [`Addresses`](#addresses) - - [`API`](#api) - - [`Delegates`](#delegates) - - [`Gateway`](#gateway) - - [`Swarm`](#swarm) -- [`Bootstrap`](#bootstrap) -- [`Datastore`](#datastore) - - [`Spec`](#spec) -- [`Discovery`](#discovery) - - [`MDNS`](#mdns) - - [`webRTCStar`](#webrtcstar) -- [`Identity`](#identity) - - [`PeerID`](#peerid) - - [`PrivKey`](#privkey) -- [`Keychain`](#keychain) -- [`Pubsub`](#pubsub) - - [`Router`](#router) -- [`Swarm`](#swarm) - - [`ConnMgr`](#connmgr) - ## `Addresses` + Contains information about various listener addresses to be used by this node. ### `API` diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000000..db55432a0a --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,65 @@ +# Development + +- [Clone and install dependencies](#clone-and-install-dependencies) +- [Run tests](#run-tests) +- [Lint](#lint) +- [Build a dist version](#build-a-dist-version) +- [Publishing new versions](#publishing-new-versions) +- [Using prerelease versions](#using-prerelease-versions) + +## Clone and install dependencies + +```sh +> git clone https://github.com/ipfs/js-ipfs.git +> cd js-ipfs +> npm install +``` + +This will install [lerna](https://www.npmjs.com/package/lerna) and bootstrap the various packages, deduping and hoisting dependencies into the root folder. + +If later you add new dependencies to submodules or just wish to remove all the `node_modules`/`dist` folders and start again, run `npm run reset && npm install` from the root. + +See the scripts section of the root [`package.json`](./package.json) for more commands. + +## Run tests + +```sh +# run all the unit tests +> npm test + +# run just IPFS tests in Node.js +> npm run test:node + +# run just IPFS tests in a browser +> npm run test:browser + +# run just IPFS tests in a webworker +> npm run test:webworker +``` + +More granular test suites can be run from each submodule. + +Please see the `package.json` in each submodule for available commands. + +## Lint + +Please run the linter before submitting a PR, the build will not pass if it fails: + +```sh +> npm run lint +``` + +## Build a dist version + +```sh +> npm run build +``` + +## Publishing new versions + +1. Ensure you have a `GH_TOKEN` env var containing a GitHub [Personal Access Token](https://github.com/settings/tokens) with `public_repo` permissions +2. From the root of this repo run `npm run release` and follow the on screen prompts. It will use [conventional commits](https://www.conventionalcommits.org) to work out the new package version + +## Using prerelease versions + +Any changed packages from each successful build of master are published to npm as canary builds under the npm tag `next`. diff --git a/packages/ipfs/docs/EARLY_TESTERS.md b/docs/EARLY_TESTERS.md similarity index 100% rename from packages/ipfs/docs/EARLY_TESTERS.md rename to docs/EARLY_TESTERS.md diff --git a/docs/IPFS.md b/docs/IPFS.md new file mode 100644 index 0000000000..8ca5ca5b3d --- /dev/null +++ b/docs/IPFS.md @@ -0,0 +1,25 @@ +# IPFS module + +These are functions not in the [Core API](#core-api) but that are specific to [`ipfs`](../packages/ipfs). + +## Table of contents + +- [Constructor](#constructor) + - [`options.repo`](#optionsrepo) + - [`options.repoAutoMigrate`](#optionsrepoautomigrate) + - [`options.init`](#optionsinit) + - [`options.start`](#optionsstart) + - [`options.pass`](#optionspass) + - [`options.silent`](#optionssilent) + - [`options.relay`](#optionsrelay) + - [`options.offline`](#optionsoffline) + - [`options.preload`](#optionspreload) + - [`options.EXPERIMENTAL`](#optionsexperimental) + - [`options.config`](#optionsconfig) + - [`options.ipld`](#optionsipld) + - [`options.libp2p`](#optionslibp2p) + - [`options.connectionManager`](#optionsconnectionmanager) +- [Instance methods](#instance-methods) + - [`node.start()`](#nodestart) + - [`node.stop()`](#nodestop) + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..c982306d68 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,26 @@ +# IPFS Docs + +- [API Docs](#api-docs) +- [How tos and other documentation](#how-tos-and-other-documentation) +- [Development documentation](#development-documentation) + +## API Docs + +`ipfs` can run as part of your program (an in-process node) or as a standalone daemon process that can be communicated with via an HTTP RPC API using the [`ipfs-http-client`](../packages/ipfs-http-api) module. + +Whether accessed directly or over HTTP, both methods support the full [Core API](#core-api). In addition other methods are available to construct instances of each module, etc. + +* [Core API docs](./core-api/README.md) +* [IPFS API](../packages/ipfs/README.md) +* [IPFS-HTTP-CLIENT API](../packages/ipfs-http-client/README.md) + +## How tos and other documentation + +* [How to run js-IPFS in the browser](./BROWSERS.md) +* [js-IPFS configuration options](./CONFIG.md) + +## Development documentation + +* [Release issue template](./RELEASE_ISSUE_TEMPLATE.md) +* [Early testers](./EARLY_TESTERS.md) +* [Releases](./RELEASES.md) diff --git a/packages/ipfs/docs/releases.md b/docs/RELEASES.md similarity index 100% rename from packages/ipfs/docs/releases.md rename to docs/RELEASES.md diff --git a/packages/ipfs/docs/RELEASE_ISSUE_TEMPLATE.md b/docs/RELEASE_ISSUE_TEMPLATE.md similarity index 100% rename from packages/ipfs/docs/RELEASE_ISSUE_TEMPLATE.md rename to docs/RELEASE_ISSUE_TEMPLATE.md diff --git a/packages/interface-ipfs-core/SPEC/BITSWAP.md b/docs/core-api/BITSWAP.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/BITSWAP.md rename to docs/core-api/BITSWAP.md diff --git a/packages/interface-ipfs-core/SPEC/BLOCK.md b/docs/core-api/BLOCK.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/BLOCK.md rename to docs/core-api/BLOCK.md diff --git a/packages/interface-ipfs-core/SPEC/BOOTSTRAP.md b/docs/core-api/BOOTSTRAP.md similarity index 96% rename from packages/interface-ipfs-core/SPEC/BOOTSTRAP.md rename to docs/core-api/BOOTSTRAP.md index dc3fd77717..35d5d59a8a 100644 --- a/packages/interface-ipfs-core/SPEC/BOOTSTRAP.md +++ b/docs/core-api/BOOTSTRAP.md @@ -1,116 +1,116 @@ -# Bootstrap API - -> Manipulates the `bootstrap list`, which contains - the addresses of the bootstrap nodes. These are the trusted peers from - which to learn about other peers in the network. - -> Only edit this list if you understand the risks of adding or removing nodes - -* [bootstrap.add](#bootstrapadd) -* [bootstrap.list](#bootstraplist) -* [bootstrap.rm](#bootstraprm) - -#### `bootstrap.add` - -> Add a peer address to the bootstrap list - -##### `ipfs.bootstrap.add(addr, [options])` - -- `addr` is a [multiaddr](https://github.com/multiformats/js-multiaddr) to a peer node -- `options.default` if true, add the default peers to the list - -Note: If passing the `default` option, `addr` is an optional parameter (may be `undefined`/`null`) and options may be passed as the first argument. i.e. `ipfs.bootstrap.add({ default: true })` - -**Returns** - -| Type | Description | -| -------- | -------- | -| `Promise` | An object that contains an array with all the added addresses | - -example of the returned object: - -```JavaScript -{ - Peers: [address1, address2, ...] -} -``` - -**Example:** - -```JavaScript -const validIp4 = '/ip4/104....9z' - -const res = await ipfs.bootstrap.add(validIp4) -console.log(res.Peers) -// Logs: -// ['/ip4/104....9z'] -``` - -A great source of [examples][] can be found in the tests for this API. - -#### `bootstrap.list` - -> List all peer addresses in the bootstrap list - -##### `ipfs.bootstrap.list()` - -**Returns** - -| Type | Description | -| -------- | -------- | -| `Promise` | An object that contains an array with all the bootstrap addresses | - -example of the returned object: - -```JavaScript -{ - Peers: [address1, address2, ...] -} -``` - -**Example:** - -```JavaScript -const res = await ipfs.bootstrap.list() -console.log(res.Peers) -// Logs: -// [address1, address2, ...] -``` - -A great source of [examples][] can be found in the tests for this API. - -#### `bootstrap.rm` - -> Remove a peer address from the bootstrap list - -##### `ipfs.bootstrap.rm(peer, [options])` - -- `addr` is a [multiaddr](https://github.com/multiformats/js-multiaddr) to a peer node -- `options.all` if true, remove all peers from the list - -Note: If passing the `all` option, `addr` is an optional parameter (may be `undefined`/`null`) and options may be passed as the first argument. i.e. `ipfs.bootstrap.rm({ all: true })` - -**Returns** - -| Type | Description | -| -------- | -------- | -| `Promise` | An object that contains an array with all the removed addresses | - -```JavaScript -{ - Peers: [address1, address2, ...] -} -``` - -**Example:** - -```JavaScript -const res = await ipfs.bootstrap.rm(null, { all: true }) -console.log(res.Peers) -// Logs: -// [address1, address2, ...] -``` - -A great source of [examples][] can be found in the tests for this API. - -[examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/bootstrap +# Bootstrap API + +> Manipulates the `bootstrap list`, which contains + the addresses of the bootstrap nodes. These are the trusted peers from + which to learn about other peers in the network. + +> Only edit this list if you understand the risks of adding or removing nodes + +* [bootstrap.add](#bootstrapadd) +* [bootstrap.list](#bootstraplist) +* [bootstrap.rm](#bootstraprm) + +#### `bootstrap.add` + +> Add a peer address to the bootstrap list + +##### `ipfs.bootstrap.add(addr, [options])` + +- `addr` is a [multiaddr](https://github.com/multiformats/js-multiaddr) to a peer node +- `options.default` if true, add the default peers to the list + +Note: If passing the `default` option, `addr` is an optional parameter (may be `undefined`/`null`) and options may be passed as the first argument. i.e. `ipfs.bootstrap.add({ default: true })` + +**Returns** + +| Type | Description | +| -------- | -------- | +| `Promise` | An object that contains an array with all the added addresses | + +example of the returned object: + +```JavaScript +{ + Peers: [address1, address2, ...] +} +``` + +**Example:** + +```JavaScript +const validIp4 = '/ip4/104....9z' + +const res = await ipfs.bootstrap.add(validIp4) +console.log(res.Peers) +// Logs: +// ['/ip4/104....9z'] +``` + +A great source of [examples][] can be found in the tests for this API. + +#### `bootstrap.list` + +> List all peer addresses in the bootstrap list + +##### `ipfs.bootstrap.list()` + +**Returns** + +| Type | Description | +| -------- | -------- | +| `Promise` | An object that contains an array with all the bootstrap addresses | + +example of the returned object: + +```JavaScript +{ + Peers: [address1, address2, ...] +} +``` + +**Example:** + +```JavaScript +const res = await ipfs.bootstrap.list() +console.log(res.Peers) +// Logs: +// [address1, address2, ...] +``` + +A great source of [examples][] can be found in the tests for this API. + +#### `bootstrap.rm` + +> Remove a peer address from the bootstrap list + +##### `ipfs.bootstrap.rm(peer, [options])` + +- `addr` is a [multiaddr](https://github.com/multiformats/js-multiaddr) to a peer node +- `options.all` if true, remove all peers from the list + +Note: If passing the `all` option, `addr` is an optional parameter (may be `undefined`/`null`) and options may be passed as the first argument. i.e. `ipfs.bootstrap.rm({ all: true })` + +**Returns** + +| Type | Description | +| -------- | -------- | +| `Promise` | An object that contains an array with all the removed addresses | + +```JavaScript +{ + Peers: [address1, address2, ...] +} +``` + +**Example:** + +```JavaScript +const res = await ipfs.bootstrap.rm(null, { all: true }) +console.log(res.Peers) +// Logs: +// [address1, address2, ...] +``` + +A great source of [examples][] can be found in the tests for this API. + +[examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/bootstrap diff --git a/packages/interface-ipfs-core/SPEC/CONFIG.md b/docs/core-api/CONFIG.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/CONFIG.md rename to docs/core-api/CONFIG.md diff --git a/packages/interface-ipfs-core/SPEC/DAG.md b/docs/core-api/DAG.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/DAG.md rename to docs/core-api/DAG.md diff --git a/packages/interface-ipfs-core/SPEC/DHT.md b/docs/core-api/DHT.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/DHT.md rename to docs/core-api/DHT.md diff --git a/packages/interface-ipfs-core/SPEC/FILES.md b/docs/core-api/FILES.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/FILES.md rename to docs/core-api/FILES.md diff --git a/packages/interface-ipfs-core/SPEC/KEY.md b/docs/core-api/KEY.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/KEY.md rename to docs/core-api/KEY.md diff --git a/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md b/docs/core-api/MISCELLANEOUS.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md rename to docs/core-api/MISCELLANEOUS.md diff --git a/packages/interface-ipfs-core/SPEC/NAME.md b/docs/core-api/NAME.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/NAME.md rename to docs/core-api/NAME.md diff --git a/packages/interface-ipfs-core/SPEC/OBJECT.md b/docs/core-api/OBJECT.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/OBJECT.md rename to docs/core-api/OBJECT.md diff --git a/packages/interface-ipfs-core/SPEC/PIN.md b/docs/core-api/PIN.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/PIN.md rename to docs/core-api/PIN.md diff --git a/packages/interface-ipfs-core/SPEC/PUBSUB.md b/docs/core-api/PUBSUB.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/PUBSUB.md rename to docs/core-api/PUBSUB.md diff --git a/docs/core-api/README.md b/docs/core-api/README.md new file mode 100644 index 0000000000..f2321d4fbc --- /dev/null +++ b/docs/core-api/README.md @@ -0,0 +1,22 @@ +# IPFS Core API + +This directory contains the description of the core IPFS API. In order to be considered "valid", an IPFS core implementation must expose the API described here. You can also use this loose spec as documentation for consuming the core APIs. + +It is broken up into the following sections: + +* [BITSWAP.md](BITSWAP.md) +* [BLOCK.md](BLOCK.md) +* [BOOTSTRAP.md](BOOTSTRAP.md) +* [CONFIG.md]([CONFIG.md) +* [DAG.md](DAG.md) +* [DHT.md](DHT.md) +* [FILES.md](FILES.md) +* [KEY.md](KEY.md) +* [MISCELLANEOUS.md](MISCELLANEOUS.md) +* [NAME.md](NAME.md) +* [OBJECT.md](OBJECT.md) +* [PIN.md](PIN.md) +* [PUBSUB.md](PUBSUB.md) +* [REFS.md](REFS.md) +* [STATS.md](STATS.md) +* [SWARM.md](SWARM.md) diff --git a/packages/interface-ipfs-core/SPEC/REFS.md b/docs/core-api/REFS.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/REFS.md rename to docs/core-api/REFS.md diff --git a/packages/interface-ipfs-core/SPEC/REPO.md b/docs/core-api/REPO.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/REPO.md rename to docs/core-api/REPO.md diff --git a/packages/interface-ipfs-core/SPEC/STATS.md b/docs/core-api/STATS.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/STATS.md rename to docs/core-api/STATS.md diff --git a/packages/interface-ipfs-core/SPEC/SWARM.md b/docs/core-api/SWARM.md similarity index 100% rename from packages/interface-ipfs-core/SPEC/SWARM.md rename to docs/core-api/SWARM.md diff --git a/packages/interface-ipfs-core/README.md b/packages/interface-ipfs-core/README.md index 122664348e..fbbc615dfe 100644 --- a/packages/interface-ipfs-core/README.md +++ b/packages/interface-ipfs-core/README.md @@ -1,45 +1,54 @@ -# interface-ipfs-core +# interface-ipfs-core [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io) [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs) [![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/) [![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) +[![Dependency Status](https://david-dm.org/ipfs/js-ipfs/status.svg?style=flat-square&path=packages/interface-ipfs-core)](https://david-dm.org/ipfs/js-ipfs?path=packages/interface-ipfs-core) > A test suite and interface you can use to implement an IPFS core interface. -## Lead Maintainer +## Lead Maintainer -[Alan Shaw](http://github.com/alanshaw). +[Alex Potsides](http://github.com/achingbrain) -## Table of Contents +## Table of Contents - [Background](#background) - - [Modules that implement the interface](#modules-that-implement-the-interface) - - [Badge](#badge) +- [Core API](#core-api) +- [Modules that implement the interface](#modules-that-implement-the-interface) +- [Badge](#badge) - [Install](#install) - [Usage](#usage) - - [JavaScript](#javascript) - - [Go](#go) -- [API](#api) +- [Running tests](#running-tests) + - [Running tests by command](#running-tests-by-command) + - [Running only some tests](#running-only-some-tests) + - [Running only specific tests](#running-only-specific-tests) +- [Skipping tests](#skipping-tests) + - [Skipping specific tests](#skipping-specific-tests) - [Contribute](#contribute) - [Want to hack on IPFS?](#want-to-hack-on-ipfs) - [License](#license) ## Background -The primary goal of this module is to define and ensure that both IPFS core implementations and their respective HTTP client libraries offer the same interface, so that developers can quickly change between a local and a remote node without having to change their applications. In addition to the definition of the expected interface, this module offers a suite of tests that can be run in order to check if the interface is used as described. +The primary goal of this module is to define and ensure that IPFS core implementations and their respective HTTP client libraries offer the same interface, so that developers can quickly change between a local and a remote node without having to change their applications. -The API is presented with both Node.js and Go primitives. However, there are no actual limitations keeping it from being extended for any other language, pushing forward cross compatibility and interoperability through different stacks. +It offers a suite of tests that can be run in order to check if the interface is implemented as described. -### Modules that implement the interface +## Core API -- [JavaScript IPFS implementation](https://github.com/ipfs/js-ipfs) -- [JavaScript IPFS HTTP Client Library](https://github.com/ipfs/js-ipfs-api) +In order to be considered "valid", an IPFS implementation must expose the Core API as described in [/docs/core-api](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api). You can also use this loose spec as documentation for consuming the core APIs. + +## Modules that implement the interface + +- [JavaScript IPFS implementation](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs) +- [JavaScript IPFS HTTP Client Library](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs-http-client) - [JavaScript IPFS postMessage proxy](https://github.com/ipfs-shipyard/ipfs-postmsg-proxy) Send in a PR if you find or write one! -### Badge +## Badge Include this badge in your readme if you make a new module that implements interface-ipfs-core API. @@ -53,16 +62,16 @@ Include this badge in your readme if you make a new module that implements inter In JavaScript land: -```js -npm install interface-ipfs-core +```console +$ npm install interface-ipfs-core ``` If you want to run these tests against a go-ipfs daemon, checkout [ipfs-http-client](https://github.com/ipfs/js-ipfs-http-client) and run test tests: -``` -git clone https://github.com/ipfs/js-ipfs-http-client -npm install -npm test +```console +$ git clone https://github.com/ipfs/js-ipfs-http-client +$ npm install +$ npm test ``` ## Usage @@ -95,84 +104,69 @@ tests.dag(createCommon) // ...etc. (see src/index.js) ``` -#### Running tests by command +## Running tests + +```js +// run all the tests for the repo subsystem +tests.repo(createCommon) +``` + +### Running tests by command ```js tests.repo.version(createCommon) ``` -#### Skipping tests +### Running only some tests ```js -tests.repo.gc(createCommon, { skip: true }) // pass an options object to skip these tests +tests.repo.gc(createCommon, { only: true }) // pass an options object to run only these tests // OR, at the subsystem level -// skips ALL the repo.gc tests -tests.repo(createCommon, { skip: ['gc'] }) -// skips ALL the object.patch.addLink tests -tests.object(createCommon, { skip: ['patch.addLink'] }) +// runs only ALL the repo.gc tests +tests.repo(createCommon, { only: ['gc'] }) +// runs only ALL the object.patch.addLink tests +tests.object(createCommon, { only: ['patch.addLink'] }) ``` -##### Skipping specific tests +### Running only specific tests ```js -tests.repo.gc(createCommon, { skip: ['should do a thing'] }) // named test(s) to skip +tests.repo.gc(createCommon, { only: ['should do a thing'] }) // only run these named test(s) // OR, at the subsystem level - -tests.repo(createCommon, { skip: ['should do a thing'] }) +tests.repo(createCommon, { only: ['should do a thing'] }) ``` -#### Running only some tests +## Skipping tests ```js -tests.repo.gc(createCommon, { only: true }) // pass an options object to run only these tests - -// OR, at the subsystem level +tests.repo.gc(createCommon, { skip: true }) // pass an options object to skip these tests -// runs only ALL the repo.gc tests -tests.repo(createCommon, { only: ['gc'] }) -// runs only ALL the object.patch.addLink tests -tests.object(createCommon, { only: ['patch.addLink'] }) +// skips ALL the repo.gc tests +tests.repo(createCommon, { skip: ['gc'] }) +// skips ALL the object.patch.addLink tests +tests.object(createCommon, { skip: ['patch.addLink'] }) ``` -##### Running only specific tests +### Skipping specific tests ```js -tests.repo.gc(createCommon, { only: ['should do a thing'] }) // only run these named test(s) +tests.repo.gc(createCommon, { skip: ['should do a thing'] }) // named test(s) to skip // OR, at the subsystem level +tests.repo(createCommon, { skip: ['should do a thing'] }) -tests.repo(createCommon, { only: ['should do a thing'] }) +// Optionally specify a reason +tests.repo(createCommon, { + skip: [{ + name: 'should do a thing', + reason: 'Thing is not implemented yet' + }] +}) ``` -## API - -In order to be considered "valid", an IPFS core implementation must expose the API described in [/SPEC](SPEC). You can also use this loose spec as documentation for consuming the core APIs. Here is an outline of the contents of that directory: - -- **Files** - - [files](./SPEC/FILES.md) - - [block](./SPEC/BLOCK.md) - - [repo (not spec'ed yet)](./SPEC/REPO.md) -- **Graph** - - [dag](./SPEC/DAG.md) - - [object](./SPEC/OBJECT.md) - - [pin](./SPEC/PIN.md) -- [**Name**](./SPEC/NAME.md) -- **Network** - - [bootstrap](./SPEC/BOOTSTRAP.md) - - [bitswap](./SPEC/BITSWAP.md) - - [dht](./SPEC/DHT.md) - - [pubsub](./SPEC/PUBSUB.md) - - [swarm](./SPEC/SWARM.md) -- **Node Management** - - [Miscellaneous](./SPEC/MISCELLANEOUS.md) - - [config](./SPEC/CONFIG.md) - - [key](./SPEC/KEY.md) - - [stats](./SPEC/STATS.md) - - [repo](./SPEC/REPO.md) - ## Contribute Feel free to join in. All welcome. Open an [issue](https://github.com/ipfs/js-ipfs/issues)! diff --git a/packages/interface-ipfs-core/SPEC/README.md b/packages/interface-ipfs-core/SPEC/README.md deleted file mode 100644 index 9b487a5bad..0000000000 --- a/packages/interface-ipfs-core/SPEC/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# IPFS Core API - -This directory contains the description of the core IPFS API. In order to be considered "valid", an IPFS core implementation must expose the API described here. You can also use this loose spec as documentation for consuming the core APIs. There is an outline of the contents of that directory in the [API section of this repository's root README file](../README.md#api). diff --git a/packages/ipfs-core-utils/README.md b/packages/ipfs-core-utils/README.md index 93126c9764..f22c48830d 100644 --- a/packages/ipfs-core-utils/README.md +++ b/packages/ipfs-core-utils/README.md @@ -3,9 +3,9 @@ [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://protocol.ai) [![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/) [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs) -[![Travis CI](https://flat.badgen.net/travis/ipfs/js-ipfs-utils)](https://travis-ci.com/ipfs/js-ipfs-utils) -[![Codecov branch](https://img.shields.io/codecov/c/github/ipfs/js-ipfs-utils/master.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-ipfs-utils) -[![Dependency Status](https://david-dm.org/ipfs/js-ipfs-utils.svg?style=flat-square)](https://david-dm.org/ipfs/js-ipfs-utils) +[![Travis CI](https://flat.badgen.net/travis/ipfs/js-ipfs)](https://travis-ci.com/ipfs/js-ipfs) +[![Codecov branch](https://img.shields.io/codecov/c/github/ipfs/js-ipfs/master.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-ipfs) +[![Dependency Status](https://david-dm.org/ipfs/js-ipfs/status.svg?path=packages/ipfs-core-utils)](https://david-dm.org/ipfs/js-ipfs?path=packages/ipfs-core-utils) [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard) > This package serves as a repository code shared between the core `ipfs` core implementation and the `ipfs-http-client` @@ -28,7 +28,7 @@ $ npm install --save ipfs-core-utils ## Contribute -Contributions welcome. Please check out [the issues](https://github.com/ipfs/js-ipfs-utils/issues). +Contributions welcome. Please check out [the issues](https://github.com/ipfs/js-ipfs/issues). Check out our [contributing document](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md) 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](https://github.com/ipfs/community/blob/master/code-of-conduct.md). diff --git a/packages/ipfs-http-client/README.md b/packages/ipfs-http-client/README.md index 3a1b4d9a78..8daf6dc3ff 100644 --- a/packages/ipfs-http-client/README.md +++ b/packages/ipfs-http-client/README.md @@ -5,20 +5,19 @@

The JavaScript HTTP client library for IPFS implementations.

- - - - - + + + +

- - + +
- + @@ -28,17 +27,37 @@

-> A client library for the IPFS HTTP API, implemented in JavaScript. This client library implements the [interface-ipfs-core](https://github.com/ipfs/js-ipfs/tree/master/packages/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. +> A client library for the IPFS HTTP API, implemented in JavaScript. This client library implements the IPFS [Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/api) 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. + +## Getting started + +* Look into the [examples folder](https://github.com/ipfs/js-ipfs/tree/master/examples) to learn how to spawn an IPFS node in Node.js and in the Browser +* Read the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node +* Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it +* Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs +* Check out https://docs-beta.ipfs.io for tips, how-tos and more ## Lead Maintainer -[Alan Shaw](http://github.com/alanshaw). +[Alex Potsides](http://github.com/achingbrain) ## Table of Contents +- [Getting started](#getting-started) - [Lead Maintainer](#lead-maintainer) - [Table of Contents](#table-of-contents) - [Install](#install) +- [Usage](#usage) + - [API](#api) + - [Additional Options](#additional-options) + - [Instance Utils](#instance-utils) + - [Static Types and Utils](#static-types-and-utils) + - [Glob source](#glob-source) + - [`globSource(path, [options])`](#globsourcepath-options) + - [Example](#example) + - [URL source](#url-source) + - [`urlSource(url)`](#urlsourceurl) + - [Example](#example-1) - [Running the daemon with the right port](#running-the-daemon-with-the-right-port) - [Importing the module and usage](#importing-the-module-and-usage) - [Importing a sub-module and usage](#importing-a-sub-module-and-usage) @@ -46,17 +65,6 @@ - [CORS](#cors) - [Custom Headers](#custom-headers) - [Global Timeouts](#global-timeouts) -- [Usage](#usage) - - [API](#api) - - [Files](#files) - - [Graph](#graph) - - [Network](#network) - - [Node Management](#node-management) - - [Additional Options](#additional-options) - - [Instance Utils](#instance-utils) - - [Static Types and Utils](#static-types-and-utils) - - [Glob source](#glob-source) - - [URL source](#url-source) - [Development](#development) - [Testing](#testing) - [Contribute](#contribute) @@ -71,7 +79,119 @@ 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](https://nodejs.org/) for what these currently are. +Both the Current and Active LTS versions of Node.js are supported. Please see [nodejs.org](https://nodejs.org/) for what these currently are. + +## Usage + +### API + +[![IPFS Core API Compatible](https://cdn.rawgit.com/ipfs/interface-ipfs-core/master/img/badge.svg)](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core) + +> `js-ipfs-http-client` implements the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) - please follow the previous link to see the the methods available. + +### Additional Options + +All core API methods take _additional_ `options` specific to the HTTP API: + +* `headers` - An object or [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) instance that can be used to set custom HTTP headers. Note that this option can also be [configured globally](#custom-headers) via the constructor options. +* `signal` - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/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`](https://github.com/sindresorhus/ky/blob/2f37c3f999efb36db9108893b8b3d4b3a7f5ec45/index.js#L127-L132) is thrown. If a number is specified it is interpreted as milliseconds, if a string is passed, it is intepreted according to [`parse-duration`](https://www.npmjs.com/package/parse-duration). Note that this option can also be [configured globally](#global-timeouts) via the constructor options. +* `searchParams` - An object or [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/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: + +- [`Buffer`](https://www.npmjs.com/package/buffer) +- [`multiaddr`](https://www.npmjs.com/package/multiaddr) +- [`multibase`](https://www.npmjs.com/package/multibase) +- [`multicodec`](https://www.npmjs.com/package/multicodec) +- [`multihash`](https://www.npmjs.com/package/multihashes) +- [`CID`](https://www.npmjs.com/package/cids) +- [`globSource`](https://github.com/ipfs/js-ipfs-utils/blob/master/src/files/glob-source.js) (not available in the browser) +- [`urlSource`](https://github.com/ipfs/js-ipfs-utils/blob/master/src/files/url-source.js) + +These can be accessed like this, for example: + +```js +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 + +```js +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`](https://developer.mozilla.org/en-US/docs/Web/API/URL) instance to send HTTP GET request to + +Returns an async iterable that yields `{ path, content }` objects suitable for passing to `ipfs.add`. + +##### Example + +```js +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 +} +*/ +``` ### Running the daemon with the right port @@ -204,249 +324,6 @@ const ipfs = ipfsClient({ timeout: '2m' }) // see https://www.npmjs.com/package/parse-duration for valid string values ``` -## Usage - -### API - -[![IPFS Core API Compatible](https://cdn.rawgit.com/ipfs/interface-ipfs-core/master/img/badge.svg)](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core) - -> `js-ipfs-http-client` follows the spec defined by [`interface-ipfs-core`](https://github.com/ipfs/js-ipfs/tree/master/packages/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 - -- [Regular Files API](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md) - - [`ipfs.add(data, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#add) - - [`ipfs.cat(ipfsPath, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#cat) - - [`ipfs.get(ipfsPath, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#get) - - [`ipfs.ls(ipfsPath)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#ls) -- [MFS (mutable file system) specific](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#mutable-file-system) - - [`ipfs.files.cp([from, to])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filescp) - - [`ipfs.files.flush([path])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesflush) - - [`ipfs.files.ls([path], [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesls) - - [`ipfs.files.mkdir(path, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesmkdir) - - [`ipfs.files.mv([from, to])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesmv) - - [`ipfs.files.read(path, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesread) - - [`ipfs.files.rm(path, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesrm) - - [`ipfs.files.stat(path, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesstat) - - [`ipfs.files.write(path, content, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#fileswrite) - _Explore the Mutable File System through interactive coding challenges in our [ProtoSchool tutorial](https://proto.school/#/mutable-file-system/)._ - -- [block](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BLOCK.md) - - [`ipfs.block.get(cid, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BLOCK.md#blockget) - - [`ipfs.block.put(block, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BLOCK.md#blockput) - - [`ipfs.block.stat(cid)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BLOCK.md#blockstat) - -- [refs](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REFS.md) - - [`ipfs.refs(ipfsPath, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REFS.md#refs) - - [`ipfs.refs.local()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REFS.md#refslocal) - -#### Graph - -- [dag](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DAG.md) - - [`ipfs.dag.get(cid, [path], [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DAG.md#dagget) - - [`ipfs.dag.put(dagNode, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DAG.md#dagput) - - [`ipfs.dag.tree(cid, [path], [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DAG.md#dagtree) - _Explore the DAG API through interactive coding challenges in our [ProtoSchool tutorial](https://proto.school/#/basics)._ - -- [object](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md) - - [`ipfs.object.data(multihash, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectdata) - - [`ipfs.object.get(multihash, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectget) - - [`ipfs.object.links(multihash, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectlinks) - - [`ipfs.object.new([template])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectnew) - - [`ipfs.object.patch.addLink(multihash, DAGLink, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectpatchaddlink) - - [`ipfs.object.patch.appendData(multihash, data, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectpatchappenddata) - - [`ipfs.object.patch.rmLink(multihash, DAGLink, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectpatchrmlink) - - [`ipfs.object.patch.setData(multihash, data, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectpatchsetdata) - - [`ipfs.object.put(obj, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectput) - - [`ipfs.object.stat(multihash, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectstat) - -- [pin](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PIN.md) - - [`ipfs.pin.add(hash, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PIN.md#pinadd) - - [`ipfs.pin.ls([hash], [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PIN.md#pinls) - - [`ipfs.pin.rm(hash, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PIN.md#pinrm) - -#### Network - -- [bootstrap](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BOOTSTRAP.md) - - [`ipfs.bootstrap.add(addr, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BOOTSTRAP.md#bootstrapadd) - - [`ipfs.bootstrap.list()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BOOTSTRAP.md#bootstraplist) - - [`ipfs.bootstrap.rm(addr, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BOOTSTRAP.md#bootstraprm) - -- [bitswap](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BITSWAP.md) - - [`ipfs.bitswap.stat()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BITSWAP.md#bitswapstat) - - [`ipfs.bitswap.wantlist([peerId])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BITSWAP.md#bitswapwantlist) - - [`ipfs.bitswap.unwant(cid)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BITSWAP.md#bitswapunwant) - -- [dht](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md) - - [`ipfs.dht.findPeer(peerId)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md#dhtfindpeer) - - [`ipfs.dht.findProvs(hash)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md#dhtfindprovs) - - [`ipfs.dht.get(key)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md#dhtget) - - [`ipfs.dht.provide(cid)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md#dhtprovide) - - [`ipfs.dht.put(key, value)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md#dhtput) - -- [pubsub](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PUBSUB.md) - - [`ipfs.pubsub.ls(topic)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PUBSUB.md#pubsubls) - - [`ipfs.pubsub.peers(topic)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PUBSUB.md#pubsubpeers) - - [`ipfs.pubsub.publish(topic, data)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PUBSUB.md#pubsubpublish) - - [`ipfs.pubsub.subscribe(topic, handler, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PUBSUB.md#pubsubsubscribe) - - [`ipfs.pubsub.unsubscribe(topic, handler)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PUBSUB.md#pubsubunsubscribe) - -- [swarm](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/SWARM.md) - - [`ipfs.swarm.addrs()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/SWARM.md#swarmaddrs) - - [`ipfs.swarm.connect(addr)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/SWARM.md#swarmconnect) - - [`ipfs.swarm.disconnect(addr)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/SWARM.md#swarmdisconnect) - - [`ipfs.swarm.peers([options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/SWARM.md#swarmpeers) - -- [name](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md) - - [`ipfs.name.publish(addr, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md#namepublish) - - [`ipfs.name.pubsub.cancel(arg)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md#namepubsubcancel) - - [`ipfs.name.pubsub.state()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md#namepubsubstate) - - [`ipfs.name.pubsub.subs()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md#namepubsubsubs) - - [`ipfs.name.resolve(addr, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md#nameresolve) - -#### Node Management - -- [miscellaneous operations](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md) - - [`ipfs.dns(domain)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md#dns) - - [`ipfs.id()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md#id) - - [`ipfs.ping(id, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md#ping) - - [`ipfs.stop()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md#stop). Alias to `ipfs.shutdown`. - - [`ipfs.version()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md#version) - -- [config](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/CONFIG.md) - - [`ipfs.config.get([key])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/CONFIG.md#configget) - - [`ipfs.config.replace(config)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/CONFIG.md#configreplace) - - [`ipfs.config.set(key, value)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/CONFIG.md#configset) - - [`ipfs.config.profiles.list()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/CONFIG.md#configprofileslist) - - [`ipfs.config.profiles.apply(name, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/CONFIG.md#configprofilesapply) - -- [stats](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/STATS.md) - - [`ipfs.stats.bitswap()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/STATS.md#statsbitswap) - - [`ipfs.stats.bw([options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/STATS.md#statsbw) - - [`ipfs.stats.repo([options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/STATS.md#statsrepo) - -- log - - `ipfs.log.level(subsystem, level, [options])` - - `ipfs.log.ls()` - - `ipfs.log.tail()` - -- [repo](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REPO.md) - - [`ipfs.repo.gc([options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REPO.md#repogc) - - [`ipfs.repo.stat([options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REPO.md#repostat) - - [`ipfs.repo.version()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REPO.md#repoversion) - -- [key](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md) - - [`ipfs.key.export(name, password)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md#keyexport) - - [`ipfs.key.gen(name, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md#keygen) - - [`ipfs.key.import(name, pem, password)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md#keyimport) - - [`ipfs.key.list([options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md#keylist) - - [`ipfs.key.rename(oldName, newName)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md#keyrename) - - [`ipfs.key.rm(name)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md#keyrm) - -#### Additional Options - -All core API methods take _additional_ `options` specific to the HTTP API: - -* `headers` - An object or [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) instance that can be used to set custom HTTP headers. Note that this option can also be [configured globally](#custom-headers) via the constructor options. -* `signal` - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/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`](https://github.com/sindresorhus/ky/blob/2f37c3f999efb36db9108893b8b3d4b3a7f5ec45/index.js#L127-L132) is thrown. If a number is specified it is interpreted as milliseconds, if a string is passed, it is intepreted according to [`parse-duration`](https://www.npmjs.com/package/parse-duration). Note that this option can also be [configured globally](#global-timeouts) via the constructor options. -* `searchParams` - An object or [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/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: - -- [`Buffer`](https://www.npmjs.com/package/buffer) -- [`multiaddr`](https://www.npmjs.com/package/multiaddr) -- [`multibase`](https://www.npmjs.com/package/multibase) -- [`multicodec`](https://www.npmjs.com/package/multicodec) -- [`multihash`](https://www.npmjs.com/package/multihashes) -- [`CID`](https://www.npmjs.com/package/cids) -- [`globSource`](https://github.com/ipfs/js-ipfs-utils/blob/master/src/files/glob-source.js) (not available in the browser) -- [`urlSource`](https://github.com/ipfs/js-ipfs-utils/blob/master/src/files/url-source.js) - -These can be accessed like this, for example: - -```js -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 - -```js -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`](https://developer.mozilla.org/en-US/docs/Web/API/URL) instance to send HTTP GET request to - -Returns an async iterable that yields `{ path, content }` objects suitable for passing to `ipfs.add`. - -###### Example - -```js -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 diff --git a/packages/ipfs/README.md b/packages/ipfs/README.md index b84f47e3c9..e5c4cb7bd3 100644 --- a/packages/ipfs/README.md +++ b/packages/ipfs/README.md @@ -4,12 +4,7 @@

-

The JavaScript implementation of the IPFS protocol.

- -

- - -

+

The JavaScript implementation of the IPFS protocol

@@ -23,7 +18,7 @@ - + @@ -34,15 +29,15 @@ > **Upgrading from <=0.40 to 0.41?** See the [release notes](https://github.com/ipfs/js-ipfs/issues/2656) for the list of API changes and the [migration guide](https://gist.github.com/alanshaw/04b2ddc35a6fff25c040c011ac6acf26). -### Project status - `Alpha` - -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](/examples) to learn how to spawn an IPFS node in Node.js and in the Browser. +We've come a long way, but this project is still in Alpha, lots of development is happening, APIs might change, beware of πŸ‰.. -**Please read this:** The [DHT](https://en.wikipedia.org/wiki/Distributed_hash_table), a fundamental piece for automatic content and peer discovery is not yet complete. There are multiple applications that can be built without this service but nevertheless it is fundamental to getting that magic IPFS experience. The current status is that implementation is done and merged and we're working on performance issues. Expect the DHT to be available in a release very soon. +## Getting started -[**`Weekly Core Implementations Call`**](https://github.com/ipfs/team-mgmt/issues/992) +* Look into the [examples folder](https://github.com/ipfs/js-ipfs/tree/master/examples) to learn how to spawn an IPFS node in Node.js and in the Browser +* Read the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node +* Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it +* Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs +* Check out https://docs-beta.ipfs.io for tips, how-tos and more ## Tech Lead @@ -50,125 +45,40 @@ We've come a long way, but this project is still in Alpha, lots of development i ## Lead Maintainer -[Alan Shaw](https://github.com/alanshaw) +[Alex Potsides](http://github.com/achingbrain) ## Table of Contents +- [Getting started](#getting-started) - [Install](#install) - - [npm](#npm) - - [Use in Node.js](#use-in-nodejs) - - [Through command line tool](#through-command-line-tool) - - [Use in the browser](#use-in-the-browser) -- [Usage](#usage) - - [IPFS CLI](#ipfs-cli) - - [IPFS Daemon](#ipfs-daemon) - - [IPFS Module](#ipfs-module) - - [Tutorials and Examples](#tutorials-and-examples) - - [API](#api) - - [IPFS Constructor](#ipfs-constructor) - - [`options.repo`](#optionsrepo) - - [`options.repoAutoMigrate`](#optionsrepoautomigrate) - - [`options.init`](#optionsinit) - - [`options.start`](#optionsstart) - - [`options.pass`](#optionspass) - - [`options.silent`](#optionssilent) - - [`options.relay`](#optionsrelay) - - [`options.offline`](#optionsoffline) - - [`options.preload`](#optionspreload) - - [`options.EXPERIMENTAL`](#optionsexperimental) - - [`options.config`](#optionsconfig) - - [Configuring Delegate Routers](#configuring-delegate-routers) - - [`options.ipld`](#optionsipld) - - [`options.libp2p`](#optionslibp2p) - - [`options.connectionManager`](#optionsconnectionmanager) - - [`node.start()`](#nodestart) - - [`node.stop()`](#nodestop) - - [Core API](#core-api) - - [Files](#files) - - [Graph](#graph) - - [Block](#block) - - [Name](#name) - - [Crypto and Key Management](#crypto-and-key-management) - - [Network](#network) - - [Node Management](#node-management) - - [Static types and utils](#static-types-and-utils) - - [Glob source](#glob-source) - - [`globSource(path, [options])`](#globsourcepath-options) - - [Example](#example) - - [URL source](#url-source) - - [`urlSource(url)`](#urlsourceurl) - - [Example](#example-1) -- [FAQ](#faq) - - [How to enable WebRTC support for js-ipfs in the Browser](#how-to-enable-webrtc-support-for-js-ipfs-in-the-browser) - - [Is there WebRTC support for js-ipfs with Node.js?](#is-there-webrtc-support-for-js-ipfs-with-nodejs) - - [How can I configure an IPFS node to use a custom `signaling endpoint` for my WebRTC transport?](#how-can-i-configure-an-ipfs-node-to-use-a-custom-signaling-endpoint-for-my-webrtc-transport) - - [I see some slowness when hopping between tabs Chrome with IPFS nodes, is there a reason why?](#i-see-some-slowness-when-hopping-between-tabs-chrome-with-ipfs-nodes-is-there-a-reason-why) - - [Can I use IPFS in my Electron App?](#can-i-use-ipfs-in-my-electron-app) - - [Have more questions?](#have-more-questions) -- [Running js-ipfs with Docker](#running-js-ipfs-with-docker) + - [Browser CDN](#browser-cdn) + - [Browser bundle](#browser-bundle) +- [Documentation](#documentation) + - [Core API](#core-api) + - [How to run IPFS in various environments](#how-to-run-ipfs-in-various-environments) + - [How to use IPFS in your application](#how-to-use-ipfs-in-your-application) + - [Different topics in detail](#different-topics-in-detail) + - [Questions?](#questions) + - [Need help?](#need-help) +- [Want to hack on IPFS?](#want-to-hack-on-ipfs) - [Packages](#packages) -- [Development](#development) - - [Clone and install dependencies](#clone-and-install-dependencies) - - [Run tests](#run-tests) - - [Run interop tests](#run-interop-tests) - - [Run benchmark tests](#run-benchmark-tests) - - [Lint](#lint) - - [Build a dist version](#build-a-dist-version) - - [Runtime Support](#runtime-support) - - [Code Architecture and folder Structure](#code-architecture-and-folder-structure) - - [Source code](#source-code) - - [Monitoring](#monitoring) - - [IPFS Architecture](#ipfs-architecture) -- [Contribute](#contribute) - - [Want to hack on IPFS?](#want-to-hack-on-ipfs) - [License](#license) ## Install -### npm - -This project is available through [npm](https://www.npmjs.com/). To install, run: - -```bash -> npm install ipfs +```console +$ npm install ipfs ``` -JS IPFS depends on native modules that are installed by [`node-gyp`](https://github.com/nodejs/node-gyp). If you have problems running the command above, it is likely that the [build tools required by `node-gyp`](https://github.com/nodejs/node-gyp#installation) are missing from your system. Please install them and then try again. - -We support both the Current and Active LTS versions of Node.js. Please see [nodejs.org](https://nodejs.org/) for what these currently are. - -This project is tested on macOS, Linux and Windows. - -### Use in Node.js +If you are planning on using js-ipfs on the command line, install it globally: -To create an IPFS node programmatically: - -```js -const IPFS = require('ipfs') -const node = await IPFS.create() - -// Ready to use! -// See https://github.com/ipfs/js-ipfs#core-api +```console +$ npm install -g ipfs ``` -### Through command line tool - -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): - -```bash -npm 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](https://github.com/ipfs/go-ipfs). - -Once installed, please follow the [Getting Started Guide](https://docs.ipfs.io/introduction/usage/) to learn how to initialize your node and run the daemon. - -### Use in the browser - -Learn how to bundle with browserify and webpack in the [`examples`](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs/examples) folder. - -You can also load it using a ` ``` -## Usage - -### IPFS CLI - -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. - -```sh -# Install js-ipfs globally -> npm install ipfs --global -> jsipfs --help -Commands: - bitswap A set of commands to manipulate the bitswap agent. - block Manipulate raw IPFS blocks. - bootstrap Show or edit the list of bootstrap peers. - commands List all available commands - config [value] Get and set IPFS config values - daemon 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: - -- default repo location: `~/.jsipfs` (can be changed with env variable `IPFS_PATH`) -- default swarm port: `4002` -- default API port: `5002` - -### IPFS Daemon - -The IPFS Daemon exposes the API defined in the [HTTP API spec](https://docs.ipfs.io/reference/api/http/). You can use any of the IPFS HTTP-API client libraries with it, such as: [js-ipfs-http-client](https://github.com/ipfs/js-ipfs-http-client). - -If you want a programmatic way to spawn a IPFS Daemon using JavaScript, check out [ipfsd-ctl module](https://github.com/ipfs/js-ipfsd-ctl) - -### IPFS Module - -Use the IPFS Module as a dependency of a project to __spawn in process instances of IPFS__. Create an instance by calling `await IPFS.create()`: - -```js -// Create the IPFS node instance -const node = await IPFS.create() -// Your node is now ready to use \o/ -await node.stop() -// node is now 'offline' -``` - -### [Tutorials and Examples](/examples) - -You can find some examples and tutorials in the [examples](/examples) folder, these exist to help you get started using `js-ipfs`. - -### API - -#### IPFS Constructor - -```js -const node = await IPFS.create([options]) -``` - -Creates and returns a ready to use instance of an IPFS node. - -Use the `options` argument to specify advanced configuration. It is an object with any of these properties: - -##### `options.repo` - -| Type | Default | -|------|---------| -| string or [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo) instance | `'~/.jsipfs'` in Node.js, `'ipfs'` in browsers | - -The file path at which to store the IPFS node’s data. Alternatively, you can set up a customized storage system by providing an [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo) instance. - -Example: - -```js -// Store data outside your user directory -const node = await IPFS.create({ repo: '/var/ipfs/data' }) -``` - -##### `options.repoAutoMigrate` - -| Type | Default | -|------|---------| -| boolean | `true` | - -`js-ipfs` comes bundled with a tool that automatically migrates your IPFS repository when a new version is available. - -**For apps that build on top of `js-ipfs` and run in the browser environment, be aware that disabling automatic -migrations leaves the user with no way to run the migrations because there is no CLI in the browser. In such -a case, you should provide a way to trigger migrations manually.** - -##### `options.init` - -| Type | Default | -|------|---------| -| boolean or object | `true` | - -Perform repo initialization steps when creating the IPFS node. - -Note that *initializing* a repo is different from creating an instance of [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo). The IPFS constructor sets many special properties when initializing a repo, so you should usually not try and call `repoInstance.init()` yourself. - -Instead of a boolean, you may provide an object with custom initialization options. All properties are optional: - -- `emptyRepo` (boolean) Whether to remove built-in assets, like the instructional tour and empty mutable file system, from the repo. (Default: `false`) -- `bits` (number) Number of bits to use in the generated key pair. (Default: `2048`) -- `privateKey` (string/PeerId) A pre-generated private key to use. Can be either a base64 string or a [PeerId](https://github.com/libp2p/js-peer-id) instance. **NOTE: This overrides `bits`.** - ```js - // Generating a Peer ID: - const PeerId = require('peer-id') - // Generates a new Peer ID, complete with public/private keypair - // See https://github.com/libp2p/js-peer-id - const peerId = await PeerId.create({ bits: 2048 }) - ``` -- `pass` (string) A passphrase to encrypt keys. You should generally use the [top-level `pass` option](#optionspass) instead of the `init.pass` option (this one will take its value from the top-level option if not set). -- `profiles` (Array) Apply profile settings to config. -- `allowNew` (boolean, default: `true`) Set to `false` to disallow initialization if the repo does not already exist. - -##### `options.start` - -| Type | Default | -|------|---------| -| boolean | `true` | - - If `false`, do not automatically start the IPFS node. Instead, you’ll need to manually call [`node.start()`](#nodestart) yourself. - -##### `options.pass` - -| Type | Default | -|------|---------| -| string | `null` | - -A passphrase to encrypt/decrypt your keys. - -##### `options.silent` - -| Type | Default | -|------|---------| -| Boolean | `false` | - -Prevents all logging output from the IPFS node. - -##### `options.relay` - -| Type | Default | -|------|---------| -| object | `{ enabled: true, hop: { enabled: false, active: false } }` | - -Configure circuit relay (see the [circuit relay tutorial](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs/examples/circuit-relaying) to learn more). - -- `enabled` (boolean): Enable circuit relay dialer and listener. (Default: `true`) -- `hop` (object) - - `enabled` (boolean): Make this node a relay (other nodes can connect *through* it). (Default: `false`) - - `active` (boolean): Make this an *active* relay node. Active relay nodes will attempt to dial a destination peer even if that peer is not yet connected to the relay. (Default: `false`) - -##### `options.offline` - -| Type | Default | -|------|---------| -| Boolean | `false` | - -Run ipfs node offline. The node does not connect to the rest of the network but provides a local API. - -##### `options.preload` - -| Type | Default | -|------|---------| -| object | `{ enabled: true, addresses: [...] }` | +### Browser bundle -Configure remote preload nodes. The remote will preload content added on this node, and also attempt to preload objects requested by this node. +Learn how to bundle IPFS into your application with webpack, parceljs and browserify in the [examples](https://github.com/ipfs/js-ipfs/tree/master/examples) folder. -- `enabled` (boolean): Enable content preloading (Default: `true`) -- `addresses` (array): Multiaddr API addresses of nodes that should preload content. **NOTE:** nodes specified here should also be added to your node's bootstrap address list at [`config.Boostrap`](#optionsconfig). +## Documentation -##### `options.EXPERIMENTAL` - -| Type | Default | -|------|---------| -| object | `{ ipnsPubsub: false, sharding: false }` | - -Enable and configure experimental features. - -- `ipnsPubsub` (boolean): Enable pub-sub on IPNS. (Default: `false`) -- `sharding` (boolean): Enable directory sharding. Directories that have many child objects will be represented by multiple DAG nodes instead of just one. It can improve lookup performance when a directory has several thousand files or more. (Default: `false`) - -##### `options.config` - -| Type | Default | -|------|---------| -| object | [`config-nodejs.js`](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs/src/core/runtime/config-nodejs.js) in Node.js, [`config-browser.js`](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs/src/core/runtime/config-browser.js) in browsers | - -Modify the default IPFS node config. This object will be *merged* with the default config; it will not replace it. The default config is documented in [the js-ipfs config file docs](docs/config.md). - -###### Configuring Delegate Routers - -If you need to support Delegated Content and/or Peer Routing, you can enable it by specifying the multiaddrs of your delegate nodes in the config via `options.config.Addresses.Delegates`. If you need to run a delegate router we encourage you to run your own, with go-ipfs. You can see instructions for doing so in the [delegated routing example](https://github.com/libp2p/js-libp2p/tree/master/examples/delegated-routing). - -If you are not able to run your own delegate router nodes, we currently have two nodes that support delegated routing. **Important**: As many people may be leveraging these nodes, performance may be affected, which is why we recommend running your own nodes in production. - -Available delegate multiaddrs are: -- `/dns4/node0.delegate.ipfs.io/tcp/443/https` -- `/dns4/node1.delegate.ipfs.io/tcp/443/https` - -**Note**: If more than 1 delegate multiaddr is specified, the actual delegate will be randomly selected on startup. - -**Note**: If you wish to use delegated routing and are creating your node _programmatically_ in Node.js or the browser you must `npm install libp2p-delegated-content-routing` and/or `npm install libp2p-delegated-peer-routing` and provide configured instances of them in [`options.libp2p`](#optionslibp2p). See the module repos for further instructions: - -- https://github.com/libp2p/js-libp2p-delegated-content-routing -- https://github.com/libp2p/js-libp2p-delegated-peer-routing - -##### `options.ipld` - - | Type | Default | -|------|---------| -| object | [`ipld-nodejs.js`](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs/src/core/runtime/ipld-nodejs.js) in Node.js, [`ipld-browser.js`](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs/src/core/runtime/ipld-browser.js) in browsers | - - Modify the default IPLD config. This object will be *merged* with the default config; it will not replace it. Check IPLD [docs](https://github.com/ipld/js-ipld#ipld-constructor) for more information on the available options. - - > Browser config does **NOT** include by default all the IPLD formats. Only `ipld-dag-pb`, `ipld-dag-cbor` and `ipld-raw` are included. - - To add support for other formats we provide two options, one sync and another async. - - Examples for the sync option: - -

ESM Environments - -```js -import ipldGit from 'ipld-git' -import ipldBitcoin from 'ipld-bitcoin' - -const node = await IPFS.create({ - ipld: { - formats: [ipldGit, ipldBitcoin] - } -}) -``` -
-
Commonjs Environments - -```js -const node = await IPFS.create({ - ipld: { - formats: [require('ipld-git'), require('ipld-bitcoin')] - } -}) -``` -
-
Using script tags - -```html - - - - -``` -
- - Examples for the async option: - -
ESM Environments - -```js -const node = await IPFS.create({ - ipld: { - async loadFormat (codec) { - if (codec === multicodec.GIT_RAW) { - return import('ipld-git') // This is a dynamic import - } else { - throw new Error('unable to load format ' + multicodec.print[codec]) - } - } - } -}) -``` -> For more information about dynamic imports please check [webpack docs](https://webpack.js.org/guides/code-splitting/#dynamic-imports) or search your bundler documention. - -Using dynamic imports will tell your bundler to create a separate file (normally called *chunk*) that will **only** be requested by the browser if it's really needed. This strategy will reduce your bundle size and load times without removing any functionality. - -With Webpack IPLD formats can even be grouped together using magic comments `import(/* webpackChunkName: "ipld-formats" */ 'ipld-git')` to produce a single file with all of them. -
- -
Commonjs Environments - -```js -const node = await IPFS.create({ - ipld: { - async loadFormat (codec) { - if (codec === multicodec.GIT_RAW) { - return require('ipld-git') - } else { - throw new Error('unable to load format ' + multicodec.print[codec]) - } - } - } -}) -``` -
- -
Using Script tags - -```js - - -``` -
- - -##### `options.libp2p` - -| Type | Default | -|------|---------| -| object | [`libp2p-nodejs.js`](https://github.com/ipfs/js-ipfs/blob/master/src/core/runtime/libp2p-nodejs.js) in Node.js, [`libp2p-browser.js`](https://github.com/ipfs/js-ipfs/blob/master/src/core/runtime/libp2p-browser.js) in browsers | -| function | [`libp2p bundle`](examples/custom-libp2p) | - -The libp2p option allows you to build your libp2p node by configuration, or via a bundle function. If you are looking to just modify the below options, using the object format is the quickest way to get the default features of libp2p. If you need to create a more customized libp2p node, such as with custom transports or peer/content routers that need some of the ipfs data on startup, a custom bundle is a great way to achieve this. - -You can see the bundle in action in the [custom libp2p example](examples/custom-libp2p). - -- `modules` (object): - - `transport` (Array<[libp2p.Transport](https://github.com/libp2p/js-interfaces/tree/master/src/transport)>): An array of Libp2p transport classes/instances to use _instead_ of the defaults. See [libp2p/js-interfaces/transport](https://github.com/libp2p/js-interfaces/tree/master/src/transport) for details. - - `peerDiscovery` (Array<[libp2p.PeerDiscovery](https://github.com/libp2p/js-interfaces/tree/master/src/peer-discovery)>): An array of Libp2p peer discovery classes/instances to use _instead_ of the defaults. See [libp2p/js-interfaces/peer-discovery](https://github.com/libp2p/js-interfaces/tree/master/src/peer-discovery) for details. If passing a class, configuration can be passed using the config section below under the key corresponding to you module's unique `tag` (a static property on the class) - - `dht` (object): a DHT implementation that enables PeerRouting and ContentRouting. Example [libp2p/js-libp2p-kad-dht](https://github.com/libp2p/js-libp2p-kad-dht) - - `pubsub` (object): a Pubsub implementation on top of [libp2p/js-libp2p-pubsub](https://github.com/libp2p/js-libp2p-pubsub) - - `contentRouting` (Array<[libp2p.ContentRouting](https://github.com/libp2p/js-interfaces/tree/master/src/content-routing)>): An array of Libp2p content routing modules. See [libp2p/js-interfaces/content-routing](https://github.com/libp2p/js-interfaces/tree/master/src/content-routing) for details. - - `peerRouting` (Array<[libp2p.PeerRouting](https://github.com/libp2p/js-interfaces/tree/master/src/peer-routing)>): An array of Libp2p peer routing modules. See [libp2p/js-interfaces/peer-routing](https://github.com/libp2p/js-interfaces/tree/master/src/peer-routing) for details. -- `config` (object): - - `peerDiscovery` (object): - - `autoDial` (boolean): Dial to discovered peers when under the Connection Manager min peer count watermark. (default `true`) - - `[PeerDiscovery.tag]` (object): configuration for a peer discovery module - - `enabled` (boolean): whether this module is enabled or disabled - - `[custom config]` (any): other keys are specific to the module - - `dht` (object): Configuration options for the DHT (WARNING: the current DHT implementation has performance issues, your mileage may vary) - - `enabled` (boolean): whether the DHT is enabled or not (default `false`) - - `kBucketSize` (number): bucket size (default `20`) - - `randomWalk` (object): configuration for random walk - - `enabled` (boolean): whether random DHT walking is enabled (default `false`) - - `pubsub` (object): Configuration options for Pubsub - - `enabled` (boolean): if pubbsub subsystem should be enabled (default: `false`) - - `emitSelf` (boolean): whether the node should emit to self on publish, in the event of the topic being subscribed (default: `true`) - - `signMessages` (boolean): if messages should be signed (default: `true`) - - `strictSigning` (boolean): if message signing should be required (default: `true`) - -##### `options.connectionManager` - -| Type | Default | -|------|---------| -| object | [defaults](https://github.com/libp2p/js-libp2p-connection-manager#create-a-connectionmanager) | - -Configure the libp2p connection manager. - -#### `node.start()` - -Start listening for connections with other IPFS nodes on the network. In most cases, you do not need to call this method β€” `IPFS.create()` will automatically do it for you. - -This method is asynchronous and returns a promise. - -```js -const node = await IPFS.create({ start: false }) -console.log('Node is ready to use but not started!') - -try { - await node.start() - console.log('Node started!') -} catch (error) { - console.error('Node failed to start!', error) -} -``` - -#### `node.stop()` - -Close and stop listening for connections with other IPFS nodes, then release access to the node’s repo. - -This method is asynchronous and returns a promise. - -```js -const node = await IPFS.create() -console.log('Node is ready to use!') - -try { - await node.stop() - console.log('Node stopped!') -} catch (error) { - console.error('Node failed to stop!', error) -} -``` - -#### Core API - -[![](https://github.com/ipfs/js-ipfs/raw/master/packages/interface-ipfs-core/img/badge.png)](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core) +### Core API -The IPFS core API provides all functionality that is not specific to setting up and starting or stopping a node. This API is available directly on an IPFS instance, on the command line (when using the CLI interface), and as an HTTP REST API. For a complete reference, see [![](https://img.shields.io/badge/interface--ipfs--core-API%20Docs-blue.svg)](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core). +* [API Docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) -The core API is grouped into several areas: +### How to run IPFS in various environments -#### Files +* [docs/CLI.md](./docs/CLI.md) +* [docs/DAEMON.md](./docs/DAEMON.md) +* [docs/DOCKER.md](./docs/DOCKER.md) -- [Regular Files API](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md) - - [`ipfs.add(data, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#add) - - [`ipfs.cat(ipfsPath, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#cat) - - [`ipfs.get(ipfsPath, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#get) - - [`ipfs.ls(ipfsPath)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#ls) -- [MFS (mutable file system) specific](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#mutable-file-system) - - [`ipfs.files.chmod(path, mode, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#fileschmod) - - [`ipfs.files.cp([from, to])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filescp) - - [`ipfs.files.flush([path])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesflush) - - [`ipfs.files.ls([path], [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesls) - - [`ipfs.files.mkdir(path, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesmkdir) - - [`ipfs.files.mv([from, to])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesmv) - - [`ipfs.files.read(path, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesread) - - [`ipfs.files.rm(path, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesrm) - - [`ipfs.files.stat(path, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filesstat) - - [`ipfs.files.touch(path, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#filestouch) - - [`ipfs.files.write(path, content, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/FILES.md#fileswrite) +### How to use IPFS in your application -- [refs](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REFS.md) - - [`ipfs.refs(ipfsPath, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REFS.md#refs) - - [`ipfs.refs.local()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REFS.md#refslocal) +* [docs/MODULE.md](./docs/MODULE.md) -#### Graph +### Different topics in detail -- [dag](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DAG.md) - - [`ipfs.dag.put(dagNode, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DAG.md#dagput) - - [`ipfs.dag.get(cid, [path], [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DAG.md#dagget) - - [`ipfs.dag.tree(cid, [path], [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DAG.md#dagtree) +* [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) +* [docs/MONITORING.md](./docs/MONITORING.md) +* [docs/DELEGATE_ROUTERS.md](./docs/DELEGATE_ROUTERS.md) +* [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md) -- [pin](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PIN.md) - - [`ipfs.pin.add(hash, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PIN.md#pinadd) - - [`ipfs.pin.ls([hash], [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PIN.md#pinls) - - [`ipfs.pin.rm(hash, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PIN.md#pinrm) +### Questions? -- [object](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md) - - [`ipfs.object.new([template])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectnew) - - [`ipfs.object.put(obj, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectput) - - [`ipfs.object.get(multihash, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectget) - - [`ipfs.object.data(multihash, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectdata) - - [`ipfs.object.links(multihash, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectlinks) - - [`ipfs.object.stat(multihash, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectstat) - - [`ipfs.object.patch.addLink(multihash, DAGLink, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectpatchaddlink) - - [`ipfs.object.patch.rmLink(multihash, DAGLink, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectpatchrmlink) - - [`ipfs.object.patch.appendData(multihash, data, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectpatchappenddata) - - [`ipfs.object.patch.setData(multihash, data, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/OBJECT.md#objectpatchsetdata) +* [docs/FAQ.md](./docs/FAQ.md) -#### Block +### Need help? -- [block](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BLOCK.md) - - [`ipfs.block.get(cid, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BLOCK.md#blockget) - - [`ipfs.block.put(block, cid)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BLOCK.md#blockput) - - [`ipfs.block.rm(cid)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BLOCK.md#blockrm) - - [`ipfs.block.stat(cid)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BLOCK.md#blockstat) -- [bitswap](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BITSWAP.md) - - [`ipfs.bitswap.wantlist([peerId])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BITSWAP.md#bitswapwantlist) - - [`ipfs.bitswap.stat()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BITSWAP.md#bitswapstat) +Please ask 'How do I?' questions on https://discuss.ipfs.io -#### Name +## Want to hack on IPFS? -- [name](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md) - - [`ipfs.name.publish(value, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md#namepublish) - - [`ipfs.name.pubsub.cancel(arg)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md#namepubsubcancel) - - [`ipfs.name.pubsub.state()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md#namepubsubstate) - - [`ipfs.name.pubsub.subs()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md#namepubsubsubs) - - [`ipfs.name.resolve(value, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/NAME.md#nameresolve) - -#### Crypto and Key Management - -- [key](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md) - - [`ipfs.key.export(name, password)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md#keyexport) - - [`ipfs.key.gen(name, options)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md#keygen) - - [`ipfs.key.import(name, pem, password)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md#keyimport) - - [`ipfs.key.list()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md#keylist) - - [`ipfs.key.rename(oldName, newName)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md#keyrename) - - [`ipfs.key.rm(name)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/KEY.md#keyrm) - -- crypto (not implemented yet) - -#### Network - -- [bootstrap](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BOOTSTRAP.md) - - [`ipfs.bootstrap.list()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BOOTSTRAP.md#bootstraplist) - - [`ipfs.bootstrap.add(addr, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BOOTSTRAP.md#bootstrapadd) - - [`ipfs.bootstrap.rm(peer, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/BOOTSTRAP.md#bootstraprm) - -- [dht](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md) - - [`ipfs.dht.findPeer(peerId)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md#dhtfindpeer) - - [`ipfs.dht.findProvs(multihash)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md#dhtfindprovs) - - [`ipfs.dht.get(key)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md#dhtget) - - [`ipfs.dht.provide(cid)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md#dhtprovide) - - [`ipfs.dht.put(key, value)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md#dhtput) - - [`ipfs.dht.query(peerId)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/DHT.md#dhtquery) - -- [pubsub](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PUBSUB.md) - - [`ipfs.pubsub.subscribe(topic, handler, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PUBSUB.md#pubsubsubscribe) - - [`ipfs.pubsub.unsubscribe(topic, handler)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PUBSUB.md#pubsubunsubscribe) - - [`ipfs.pubsub.publish(topic, data)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PUBSUB.md#pubsubpublish) - - [`ipfs.pubsub.ls(topic)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PUBSUB.md#pubsubls) - - [`ipfs.pubsub.peers(topic)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/PUBSUB.md#pubsubpeers) - -- [libp2p](https://github.com/libp2p/interface-libp2p). Every IPFS instance also exposes the libp2p SPEC at `ipfs.libp2p`. The formal interface for this SPEC hasn't been defined but you can find documentation at its implementations: - - [Node.js bundle](./src/core/runtime/libp2p-nodejs.js) - - [Browser Bundle](./src/core/runtime/libp2p-browser.js) - - [libp2p baseclass](https://github.com/libp2p/js-libp2p) - -- [swarm](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/SWARM.md) - - [`ipfs.swarm.addrs()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/SWARM.md#swarmaddrs) - - [`ipfs.swarm.connect(addr)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/SWARM.md#swarmconnect) - - [`ipfs.swarm.disconnect(addr)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/SWARM.md#swarmdisconnect) - - [`ipfs.swarm.peers([options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/SWARM.md#swarmpeers) - -#### Node Management - -- [miscellaneous operations](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md) - - [`ipfs.id()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md#id) - - [`ipfs.version()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md#version) - - [`ipfs.ping(peerId, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md#ping) - - `ipfs.init([options])` - - `ipfs.start()` - - [`ipfs.stop()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md#stop) - - `ipfs.isOnline()` - - [`ipfs.resolve(name, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md#resolve) - - [`ipfs.dns(name, [options]`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/MISCELLANEOUS.md#dns) - -- [repo](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REPO.md) - - `ipfs.repo.init` - - [`ipfs.repo.stat([options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REPO.md#repostat) - - [`ipfs.repo.version()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REPO.md#repoversion) - - [`ipfs.repo.gc([options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/REPO.md#repogc) - -- [stats](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/STATS.md) - - [`ipfs.stats.bitswap()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/STATS.md#statsbitswap) - - [`ipfs.stats.bw([options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/STATS.md#statsbw) - - [`ipfs.stats.repo([options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/STATS.md#statsrepo) - -- [config](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/CONFIG.md) - - [`ipfs.config.get([key])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/CONFIG.md#configget) - - [`ipfs.config.set(key, value)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/CONFIG.md#configset) - - [`ipfs.config.replace(config)`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/CONFIG.md#configreplace) - - [`ipfs.config.profiles.list()`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/CONFIG.md#configprofileslist) - - [`ipfs.config.profiles.apply(name, [options])`](https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/SPEC/CONFIG.md#configprofilesapply) - -#### Static types and utils - -Aside from the default export, `ipfs` exports various types and utilities that are included in the bundle: - -- [`crypto`](https://www.npmjs.com/package/libp2p-crypto) -- [`isIPFS`](https://www.npmjs.com/package/is-ipfs) -- [`Buffer`](https://www.npmjs.com/package/buffer) -- [`PeerId`](https://www.npmjs.com/package/peer-id) -- [`PeerInfo`](https://www.npmjs.com/package/peer-info) -- [`multiaddr`](https://www.npmjs.com/package/multiaddr) -- [`multibase`](https://www.npmjs.com/package/multibase) -- [`multihash`](https://www.npmjs.com/package/multihashes) -- [`multihashing`](https://www.npmjs.com/package/multihashing-async) -- [`multicodec`](https://www.npmjs.com/package/multicodec) -- [`CID`](https://www.npmjs.com/package/cids) - -These can be accessed like this, for example: - -```js -const { CID } = require('ipfs') -// ...or from an es-module: -import { CID } from 'ipfs' -``` - -##### 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 - -```js -const IPFS = require('ipfs') -const { globSource } = IPFS -const ipfs = await IPFS.create() -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`](https://developer.mozilla.org/en-US/docs/Web/API/URL) instance to send HTTP GET request to - -Returns an async iterable that yields `{ path, content }` objects suitable for passing to `ipfs.add`. - -###### Example - -```js -const IPFS = require('ipfs') -const { urlSource } = IPFS -const ipfs = await IPFS.create() -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 -} -*/ -``` - -## FAQ - -#### How to enable WebRTC support for js-ipfs in the Browser - -To 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: - -```JavaScript -const node = await IPFS.create({ - config: { - Addresses: { - Swarm: [ - '/dns4/wrtc-star.discovery.libp2p.io/tcp/443/wss/p2p-webrtc-star' - ] - } - } -}) - -// 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. - -#### Is there WebRTC support for js-ipfs with Node.js? - -Yes, however, bear 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: - -- [wrtc](https://npmjs.org/wrtc) - Follow the install instructions. -- [electron-webrtc](https://npmjs.org/electron-webrtc) - -To add WebRTC support in a IPFS node instance, do: - -```JavaScript -const wrtc = require('wrtc') // or require('electron-webrtc')() -const WStar = require('libp2p-webrtc-star') -const wstar = new WStar({ wrtc }) - -const node = await IPFS.create({ - repo: 'your-repo-path', - // start: false, - config: { - Addresses: { - Swarm: [ - "/ip4/0.0.0.0/tcp/4002", - "/ip4/127.0.0.1/tcp/4003/ws", - "/dns4/wrtc-star.discovery.libp2p.io/tcp/443/wss/p2p-webrtc-star" - ] - } - }, - libp2p: { - modules: { - transport: [wstar], - peerDiscovery: [wstar.discovery] - } - } -}) - -// 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: - -```bash -npm install wrtc --global -# or -npm 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"` - -#### How can I configure an IPFS node to use a custom `signaling endpoint` for my WebRTC transport? - -You'll need to execute a compatible `signaling server` ([libp2p-webrtc-star](https://github.com/libp2p/js-libp2p-webrtc-star) works) and include the correct configuration param for your IPFS node: - -- provide the [`multiaddr`](https://github.com/multiformats/multiaddr) for the `signaling server` - -```JavaScript -const node = await IPFS.create({ - repo: 'your-repo-path', - config: { - 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. - -#### I see some slowness when hopping between tabs Chrome with IPFS nodes, is there a reason why? - -Yes, unfortunately, due to [Chrome aggressive resource throttling policy](https://github.com/ipfs/js-ipfs/issues/611), 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](https://github.com/ipfs/ipfs-service-worker) - -#### Can I use IPFS in my Electron App? - -Yes you can and in many ways. Read https://github.com/ipfs/notes/issues/256 for the multiple options. - -We now support Electron v5.0.0 without the need to rebuilt native modules. -Still if you run into problems with native modules follow these instructions [here](https://electronjs.org/docs/tutorial/using-native-node-modules). - -#### Have more questions? - -Ask for help in our forum at https://discuss.ipfs.io or in IRC (#ipfs on Freenode). - -## Running js-ipfs with Docker - -We have automatic Docker builds setup with Docker Hub: https://hub.docker.com/r/ipfs/js-ipfs/ - -All branches in the Github repository maps to a tag in Docker Hub, except `master` Git branch which is mapped to `latest` Docker tag. - -You can run js-ipfs like this: - -``` -$ docker run -it -p 4002:4002 -p 4003:4003 -p 5002:5002 -p 9090:9090 ipfs/js-ipfs:latest - -initializing ipfs node at /root/.jsipfs -generating 2048-bit RSA keypair...done -peer identity: Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS -to get started, enter: - - jsipfs files cat /ipfs/QmfGBRT6BbWJd7yUc2uYdaUZJBbnEFvTqehPFoSMQ6wgdr/readme +[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) -Initializing daemon... -Using wrtc for webrtc support -Swarm listening on /ip4/127.0.0.1/tcp/4003/ws/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS -Swarm listening on /ip4/172.17.0.2/tcp/4003/ws/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS -Swarm listening on /ip4/127.0.0.1/tcp/4002/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS -Swarm listening on /ip4/172.17.0.2/tcp/4002/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS -API is listening on: /ip4/0.0.0.0/tcp/5002 -Gateway (readonly) is listening on: /ip4/0.0.0.0/tcp/9090 -Daemon is ready +The IPFS implementation in JavaScript needs your help! There are a few things you can do right now to help out: -$ curl --silent localhost:5002/api/v0/id | jq .ID -"Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS" -``` +Read the [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md) and [JavaScript Contributing Guidelines](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md). +- **Check out existing issues** The [issue list](https://github.com/ipfs/js-ipfs/issues) has many that are marked as ['help wanted'](https://github.com/ipfs/js-ipfs/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) or ['difficulty:easy'](https://github.com/ipfs/js-ipfs/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Adifficulty%3Aeasy) which make great starting points for development, many of which can be tackled with no prior IPFS knowledge +- **Look at the [IPFS Roadmap](https://github.com/ipfs/roadmap)** This are the high priority items being worked on right now +- **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. +- **Join the [Weekly Core Implementations Call](https://github.com/ipfs/team-mgmt/issues/992)** it's where everyone discusses what's going on with IPFS and what's next ## Packages -Listing of the main packages used in the IPFS ecosystem. There are also three specifications worth linking here: - -- [`interface-ipfs-core`](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core) -- [`HTTP API spec`](https://docs.ipfs.io/reference/api/http) -- [`cli spec`](https://github.com/ipfs/specs/tree/master/public-api/cli) - -> This table is generated using the module [`package-table`](https://www.npmjs.com/package/package-table) with `package-table --data=package-list.json`. +List of the main packages that make up the IPFS ecosystem. | Package | Version | Deps | CI/Travis | Coverage | Lead Maintainer | | ---------|---------|---------|---------|---------|--------- | | **Files** | | [`ipfs-unixfs-exporter`](//github.com/ipfs/js-ipfs-unixfs) | [![npm](https://img.shields.io/npm/v/ipfs-unixfs-exporter.svg?maxAge=86400&style=flat-square)](//github.com/ipfs/js-ipfs-unixfs/releases) | [![Deps](https://david-dm.org/ipfs/js-ipfs-unixfs.svg?style=flat-square)](https://david-dm.org/ipfs/js-ipfs-unixfs) | [![Travis CI](https://flat.badgen.net/travis/ipfs/js-ipfs-unixfs/master)](https://travis-ci.com/ipfs/js-ipfs-unixfs) | [![codecov](https://codecov.io/gh/ipfs/js-ipfs-unixfs/branch/master/graph/badge.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-ipfs-unixfs) | [Alex Potsides](mailto:alex.potsides@protocol.ai) | | [`ipfs-unixfs-importer`](//github.com/ipfs/js-ipfs-unixfs) | [![npm](https://img.shields.io/npm/v/ipfs-unixfs-importer.svg?maxAge=86400&style=flat-square)](//github.com/ipfs/js-ipfs-unixfs/releases) | [![Deps](https://david-dm.org/ipfs/js-ipfs-unixfs.svg?style=flat-square)](https://david-dm.org/ipfs/js-ipfs-unixfs) | [![Travis CI](https://flat.badgen.net/travis/ipfs/js-ipfs-unixfs/master)](https://travis-ci.com/ipfs/js-ipfs-unixfs) | [![codecov](https://codecov.io/gh/ipfs/js-ipfs-unixfs/branch/master/graph/badge.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-ipfs-unixfs) | [Alex Potsides](mailto:alex.potsides@protocol.ai) | -| [`ipfs-mfs`](//github.com/ipfs/js-ipfs-mfs) | [![npm](https://img.shields.io/npm/v/ipfs-mfs.svg?maxAge=86400&style=flat-square)](//github.com/ipfs/js-ipfs-mfs/releases) | [![Deps](https://david-dm.org/ipfs/js-ipfs-mfs.svg?style=flat-square)](https://david-dm.org/ipfs/js-ipfs-mfs) | [![Travis CI](https://flat.badgen.net/travis/ipfs/js-ipfs-mfs/master)](https://travis-ci.com/ipfs/js-ipfs-mfs) | [![codecov](https://codecov.io/gh/ipfs/js-ipfs-mfs/branch/master/graph/badge.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-ipfs-mfs) | [Alex Potsides](mailto:alex.potsides@protocol.ai) | | [`ipfs-unixfs`](//github.com/ipfs/js-ipfs-unixfs) | [![npm](https://img.shields.io/npm/v/ipfs-unixfs.svg?maxAge=86400&style=flat-square)](//github.com/ipfs/js-ipfs-unixfs/releases) | [![Deps](https://david-dm.org/ipfs/js-ipfs-unixfs.svg?style=flat-square)](https://david-dm.org/ipfs/js-ipfs-unixfs) | [![Travis CI](https://flat.badgen.net/travis/ipfs/js-ipfs-unixfs/master)](https://travis-ci.com/ipfs/js-ipfs-unixfs) | [![codecov](https://codecov.io/gh/ipfs/js-ipfs-unixfs/branch/master/graph/badge.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-ipfs-unixfs) | [Alex Potsides](mailto:alex.potsides@protocol.ai) | | **Repo** | | [`ipfs-repo`](//github.com/ipfs/js-ipfs-repo) | [![npm](https://img.shields.io/npm/v/ipfs-repo.svg?maxAge=86400&style=flat-square)](//github.com/ipfs/js-ipfs-repo/releases) | [![Deps](https://david-dm.org/ipfs/js-ipfs-repo.svg?style=flat-square)](https://david-dm.org/ipfs/js-ipfs-repo) | [![Travis CI](https://flat.badgen.net/travis/ipfs/js-ipfs-repo/master)](https://travis-ci.com/ipfs/js-ipfs-repo) | [![codecov](https://codecov.io/gh/ipfs/js-ipfs-repo/branch/master/graph/badge.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-ipfs-repo) | [Alex Potsides](mailto:alex@achingbrain.net) | @@ -1047,149 +207,10 @@ Listing of the main packages used in the IPFS ecosystem. There are also three sp | [`multiaddr`](//github.com/multiformats/js-multiaddr) | [![npm](https://img.shields.io/npm/v/multiaddr.svg?maxAge=86400&style=flat-square)](//github.com/multiformats/js-multiaddr/releases) | [![Deps](https://david-dm.org/multiformats/js-multiaddr.svg?style=flat-square)](https://david-dm.org/multiformats/js-multiaddr) | [![Travis CI](https://flat.badgen.net/travis/multiformats/js-multiaddr/master)](https://travis-ci.com/multiformats/js-multiaddr) | [![codecov](https://codecov.io/gh/multiformats/js-multiaddr/branch/master/graph/badge.svg?style=flat-square)](https://codecov.io/gh/multiformats/js-multiaddr) | [Jacob Heun](mailto:jacobheun@gmail.com) | | [`multihashes`](//github.com/multiformats/js-multihash) | [![npm](https://img.shields.io/npm/v/multihashes.svg?maxAge=86400&style=flat-square)](//github.com/multiformats/js-multihash/releases) | [![Deps](https://david-dm.org/multiformats/js-multihash.svg?style=flat-square)](https://david-dm.org/multiformats/js-multihash) | [![Travis CI](https://flat.badgen.net/travis/multiformats/js-multihash/master)](https://travis-ci.com/multiformats/js-multihash) | [![codecov](https://codecov.io/gh/multiformats/js-multihash/branch/master/graph/badge.svg?style=flat-square)](https://codecov.io/gh/multiformats/js-multihash) | [David Dias](mailto:daviddias@ipfs.io) | -## Development - -### Clone and install dependencies - -```sh -> git clone https://github.com/ipfs/js-ipfs.git -> cd js-ipfs -> npm install -``` - -### Run tests - -```sh -# run all the unit tests -> npm test - -# run individual tests (findprovs) -> npm run test -- --grep findprovs - -# run just IPFS tests in Node.js -> npm run test:node - -# run just IPFS core tests -> npm run test:node:core - -# run just IPFS HTTP-API tests -> npm run test:node:http - -# run just IPFS CLI tests -> npm run test:cli - -# run just IPFS core tests in the Browser (Chrome) -> npm run test:browser - -# run some interface tests (block API) on Node.js -> npm run test:node:interface -- --grep '.block' -``` - -### Run interop tests - - -```sh -# run the interop tests with the default go-IPFS -> npm run test:interop - -#Β run the interop tests with a different go-IPFS -> IPFS_EXEC_GO=/path/to/ipfs npm run test:interop -``` - -### Run benchmark tests - -```sh -# run all the benchmark tests -> npm run benchmark - -# run just IPFS benchmarks in Node.js -> npm run benchmark:node - -# run just IPFS benchmarks in Node.js for an IPFS instance -> npm run benchmark:node:core - -# run just IPFS benchmarks in Node.js for an IPFS daemon -> npm run benchmark:node:http - -# run just IPFS benchmarks in the browser (Chrome) -> npm run benchmark:browser -``` - -### Lint - -**Conforming to linting rules is a prerequisite to commit to js-ipfs.** - -```sh -> npm run lint -``` - -### Build a dist version - -```sh -> npm run build -``` - -### [Runtime Support](https://github.com/ipfs/js-ipfs/issues/536) - -### Code Architecture and folder Structure - -![](/img/overview.png) - -##### Source code - -```Bash -> tree src -L 2 -src # Main source code folder -β”œβ”€β”€ cli # Implementation of the IPFS CLI -β”‚ └── ... -β”œβ”€β”€ http # 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 -β”‚ └── ... -└── ... -``` - -### Monitoring - -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: - -``` -http://localhost:5002/debug/metrics/prometheus -``` - -### IPFS Architecture - -![](/img/architecture.png) - -[Annotated version](https://user-images.githubusercontent.com/1211152/47606420-b6265780-da13-11e8-923b-b365a8534e0e.png) - -What does this image explain? - -- IPFS uses `ipfs-repo` which picks `fs` or `indexeddb` as its storage drivers, depending if it is running in Node.js or in the Browser. -- The exchange protocol, `bitswap`, uses the Block Service which in turn uses the Repo, offering a get and put of blocks to the IPFS implementation. -- The DAG API (previously Object) comes from the IPLD Resolver, it can support several IPLD Formats (i.e: dag-pb, dag-cbor, etc). -- The Files API uses `ipfs-unixfs-engine` to import and export files to and from IPFS. -- libp2p, the network stack of IPFS, uses libp2p to dial and listen for connections, to use the DHT, for discovery mechanisms, and more. - -## Contribute - -IPFS implementation in JavaScript is a work in progress. As such, there's a few things you can do right now to help out: - -- Go through the modules below and **check out existing issues**. This would be especially useful for modules in active development. Some knowledge of IPFS may be required, as well as the infrastructure behind it - for instance, you may need to read up on p2p and more complex operations like muxing to be able to help technically. -- **Perform code reviews**. More eyes will help (a) speed the project along, (b) ensure quality, and (c) reduce possible future bugs. -- Take a look at go-ipfs and some of the planning repositories or issues: for instance, the [libp2p spec](https://github.com/ipfs/specs/pull/19). Contributions here that would be most helpful are **top-level comments** about how it should look based on our understanding. Again, the more eyes the better. -- **Add tests**. There can never be enough tests. - -### Want to hack on IPFS? - -[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) +> This table is generated using the module [`package-table`](https://www.npmjs.com/package/package-table) with `package-table --data=package-list.json`. ## License [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fipfs%2Fjs-ipfs.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fipfs%2Fjs-ipfs?ref=badge_large) + +[![](https://github.com/ipfs/js-ipfs/raw/master/packages/interface-ipfs-core/img/badge.png)](https://github.com/ipfs/js-ipfs/tree/master/packages/interface-ipfs-core) diff --git a/packages/ipfs/docs/ARCHITECTURE.md b/packages/ipfs/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..94b4b72e22 --- /dev/null +++ b/packages/ipfs/docs/ARCHITECTURE.md @@ -0,0 +1,31 @@ +# IPFS Architecture + +![](../img/architecture.png) + +[Annotated version](https://user-images.githubusercontent.com/1211152/47606420-b6265780-da13-11e8-923b-b365a8534e0e.png) + +What does this image explain? + +- IPFS uses `ipfs-repo` which picks `fs` or `indexeddb` as its storage drivers, depending if it is running in Node.js or in the Browser. +- The exchange protocol, `bitswap`, uses the Block Service which in turn uses the Repo, offering a get and put of blocks to the IPFS implementation. +- The DAG API (previously Object) comes from the IPLD Resolver, it can support several IPLD Formats (i.e: dag-pb, dag-cbor, etc). +- The Files API uses `ipfs-unixfs-engine` to import and export files to and from IPFS. +- libp2p, the network stack of IPFS, uses libp2p to dial and listen for connections, to use the DHT, for discovery mechanisms, and more. + +## Code Architecture and folder Structure + +![](img/overview.png) + +### Source code + +```Bash +> tree src -L 2 +src # Main source code folder +β”œβ”€β”€ cli # Implementation of the IPFS CLI +β”‚ └── ... +β”œβ”€β”€ http # 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 +β”‚ └── ... +└── ... +``` diff --git a/packages/ipfs/docs/CLI.md b/packages/ipfs/docs/CLI.md new file mode 100644 index 0000000000..fb1b15c94d --- /dev/null +++ b/packages/ipfs/docs/CLI.md @@ -0,0 +1,39 @@ +# IPFS CLI + +##Β Table of contents + +- [Overview](#overview) +- [Configuration](#configuration) + +## Overview + +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): + +```bash +npm 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](https://github.com/ipfs/go-ipfs). + +Once installed, please follow the [Getting Started Guide](https://docs.ipfs.io/introduction/usage/) to learn how to initialize your node and run the daemon. + +```sh +# Install js-ipfs globally +> jsipfs --help +Commands: + bitswap A set of commands to manipulate the bitswap agent. + block Manipulate raw IPFS blocks. + bootstrap Show or edit the list of bootstrap peers. + commands List all available commands + config [value] Get and set IPFS config values + daemon Start a long-running daemon process +# ... +``` + +## Configuration + +`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: + +- default repo location: `~/.jsipfs` (can be changed with env variable `IPFS_PATH`) +- default swarm port: `4002` +- default API port: `5002` diff --git a/packages/ipfs/docs/DAEMON.md b/packages/ipfs/docs/DAEMON.md new file mode 100644 index 0000000000..35e7346a45 --- /dev/null +++ b/packages/ipfs/docs/DAEMON.md @@ -0,0 +1,35 @@ + +# Running IPFS as a daemon + +> How to run a long-lived IPFS process + +##Β Table of contents + +- [CLI](#cli) +- [Programmatic](#programmatic) + +## CLI + +To start a daemon on the CLI, use the `daemon` command: + +```console +jsipfs daemon +``` + +The IPFS Daemon exposes the API defined in the [HTTP API spec](https://docs.ipfs.io/reference/api/http/). You can use any of the IPFS HTTP-API client libraries with it, such as: [ipfs-http-client](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs-http-client). + +## Programmatic + +If you want a programmatic way to spawn a IPFS Daemon using JavaScript, check out the [ipfsd-ctl](https://github.com/ipfs/js-ipfsd-ctl) module. + +```javascript +const { createFactory } = require('ipfsd-ctl') +const factory = createFactory({ + type: 'proc' // or 'js' to run in a separate process +}) + +const node = await factory.create() + +// print the node ide +console.info(await node.id()) +``` diff --git a/packages/ipfs/docs/DELEGATE_ROUTERS.md b/packages/ipfs/docs/DELEGATE_ROUTERS.md new file mode 100644 index 0000000000..2d8f83f2e4 --- /dev/null +++ b/packages/ipfs/docs/DELEGATE_ROUTERS.md @@ -0,0 +1,16 @@ +# Configuring Delegate Routers + +If you need to support Delegated Content and/or Peer Routing, you can enable it by specifying the multiaddrs of your delegate nodes in the config via `options.config.Addresses.Delegates`. If you need to run a delegate router we encourage you to run your own, with go-ipfs. You can see instructions for doing so in the [delegated routing example](https://github.com/libp2p/js-libp2p/tree/master/examples/delegated-routing). + +If you are not able to run your own delegate router nodes, we currently have two nodes that support delegated routing. **Important**: As many people may be leveraging these nodes, performance may be affected, which is why we recommend running your own nodes in production. + +Available delegate multiaddrs are: +- `/dns4/node0.delegate.ipfs.io/tcp/443/https` +- `/dns4/node1.delegate.ipfs.io/tcp/443/https` + +**Note**: If more than 1 delegate multiaddr is specified, the actual delegate will be randomly selected on startup. + +**Note**: If you wish to use delegated routing and are creating your node _programmatically_ in Node.js or the browser you must `npm install libp2p-delegated-content-routing` and/or `npm install libp2p-delegated-peer-routing` and provide configured instances of them in [`options.libp2p`](#optionslibp2p). See the module repos for further instructions: + +- https://github.com/libp2p/js-libp2p-delegated-content-routing +- https://github.com/libp2p/js-libp2p-delegated-peer-routing diff --git a/packages/ipfs/docs/DEVELOPMENT.md b/packages/ipfs/docs/DEVELOPMENT.md new file mode 100644 index 0000000000..8eb2411e10 --- /dev/null +++ b/packages/ipfs/docs/DEVELOPMENT.md @@ -0,0 +1,92 @@ +# Development + +> Getting started with development on IPFS + +## Table of contents + +- [Clone and install dependencies](#clone-and-install-dependencies) +- [Run tests](#run-tests) + - [Run interop tests](#run-interop-tests) + - [Run benchmark tests](#run-benchmark-tests) +- [Lint](#lint) +- [Build a dist version](#build-a-dist-version) + +## Clone and install dependencies + +```sh +> git clone https://github.com/ipfs/js-ipfs.git +> cd js-ipfs +> npm install +``` + +## Run tests + +```sh +# run all the unit tests +> npm test + +# run individual tests (findprovs) +> npm run test -- --grep findprovs + +# run just IPFS tests in Node.js +> npm run test:node + +# run just IPFS core tests +> npm run test:node:core + +# run just IPFS HTTP-API tests +> npm run test:node:http + +# run just IPFS CLI tests +> npm run test:cli + +# run just IPFS core tests in the Browser (Chrome) +> npm run test:browser + +# run some interface tests (block API) on Node.js +> npm run test:node:interface -- --grep '.block' +``` + +### Run interop tests + + +```sh +# run the interop tests with the default go-IPFS +> npm run test:interop + +#Β run the interop tests with a different go-IPFS +> IPFS_EXEC_GO=/path/to/ipfs npm run test:interop +``` + +### Run benchmark tests + +```sh +# run all the benchmark tests +> npm run benchmark + +# run just IPFS benchmarks in Node.js +> npm run benchmark:node + +# run just IPFS benchmarks in Node.js for an IPFS instance +> npm run benchmark:node:core + +# run just IPFS benchmarks in Node.js for an IPFS daemon +> npm run benchmark:node:http + +# run just IPFS benchmarks in the browser (Chrome) +> npm run benchmark:browser +``` + +## Lint + +**Conforming to linting rules is a prerequisite to commit to js-ipfs.** + +```sh +> npm run lint +``` + +## Build a dist version + +```sh +> npm run build +``` diff --git a/packages/ipfs/docs/DOCKER.md b/packages/ipfs/docs/DOCKER.md new file mode 100644 index 0000000000..551336c05b --- /dev/null +++ b/packages/ipfs/docs/DOCKER.md @@ -0,0 +1,32 @@ + +# Running js-ipfs with Docker + +We have automatic Docker builds setup with Docker Hub: https://hub.docker.com/r/ipfs/js-ipfs/ + +All branches in the Github repository maps to a tag in Docker Hub, except `master` Git branch which is mapped to `latest` Docker tag. + +You can run js-ipfs like this: + +``` +$ docker run -it -p 4002:4002 -p 4003:4003 -p 5002:5002 -p 9090:9090 ipfs/js-ipfs:latest + +initializing ipfs node at /root/.jsipfs +generating 2048-bit RSA keypair...done +peer identity: Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS +to get started, enter: + + jsipfs files cat /ipfs/QmfGBRT6BbWJd7yUc2uYdaUZJBbnEFvTqehPFoSMQ6wgdr/readme + +Initializing daemon... +Using wrtc for webrtc support +Swarm listening on /ip4/127.0.0.1/tcp/4003/ws/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS +Swarm listening on /ip4/172.17.0.2/tcp/4003/ws/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS +Swarm listening on /ip4/127.0.0.1/tcp/4002/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS +Swarm listening on /ip4/172.17.0.2/tcp/4002/ipfs/Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS +API is listening on: /ip4/0.0.0.0/tcp/5002 +Gateway (readonly) is listening on: /ip4/0.0.0.0/tcp/9090 +Daemon is ready + +$ curl --silent localhost:5002/api/v0/id | jq .ID +"Qmbd5jx8YF1QLhvwfLbCTWXGyZLyEJHrPbtbpRESvYs4FS" +``` diff --git a/packages/ipfs/docs/FAQ.md b/packages/ipfs/docs/FAQ.md new file mode 100644 index 0000000000..1b15b5abf8 --- /dev/null +++ b/packages/ipfs/docs/FAQ.md @@ -0,0 +1,125 @@ +# FAQ + +- [FAQ](#faq) + - [Why isn't there DHT support in js-IPFS?](#why-isnt-there-dht-support-in-js-ipfs) + - [How to enable WebRTC support for js-ipfs in the Browser](#how-to-enable-webrtc-support-for-js-ipfs-in-the-browser) + - [Is there WebRTC support for js-ipfs with Node.js?](#is-there-webrtc-support-for-js-ipfs-with-nodejs) + - [How can I configure an IPFS node to use a custom `signaling endpoint` for my WebRTC transport?](#how-can-i-configure-an-ipfs-node-to-use-a-custom-signaling-endpoint-for-my-webrtc-transport) + - [I see some slowness when hopping between tabs Chrome with IPFS nodes, is there a reason why?](#i-see-some-slowness-when-hopping-between-tabs-chrome-with-ipfs-nodes-is-there-a-reason-why) + - [Can I use IPFS in my Electron App?](#can-i-use-ipfs-in-my-electron-app) + - [Have more questions?](#have-more-questions) + +## Why isn't there DHT support in js-IPFS? + +There is DHT support for js-IPFS in the form of [libp2p/js-libp2p-kad-dht](https://github.com/libp2p/js-libp2p-kad-dht) but it is not finished yet, and may not be the right solution to the problem. + +Historically js-IPFS has targeted browser environments. The constraints imposed by browsers do not typically make for good DHT participants - people do not tend to stay on a page for long enough to make or answer DHT queries, and even if they did, most nodes on the network talk TCP - the browser can neither open TCP ports on remote hosts nor accept TCP connections. + +A better approach may be to set up [Delegate Routing](./DELEGATE_ROUTERS.md) to use remote go-IPFS to make queries on the browsers' behalf as these do not have the same constraints. + +Of course, there's no reason why js on the server should not be a fully fledged DHT participant, please help out on the [libp2p/js-libp2p-kad-dht](https://github.com/libp2p/js-libp2p-kad-dht) repo to make this a reality! + +## How to enable WebRTC support for js-ipfs in the Browser + +To 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: + +```JavaScript +const node = await IPFS.create({ + config: { + Addresses: { + Swarm: [ + '/dns4/wrtc-star.discovery.libp2p.io/tcp/443/wss/p2p-webrtc-star' + ] + } + } +}) + +// 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. + +## Is there WebRTC support for js-ipfs with Node.js? + +Yes, however, bear 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: + +- [wrtc](https://npmjs.org/wrtc) - Follow the install instructions. +- [electron-webrtc](https://npmjs.org/electron-webrtc) + +To add WebRTC support in a IPFS node instance, do: + +```JavaScript +const wrtc = require('wrtc') // or require('electron-webrtc')() +const WStar = require('libp2p-webrtc-star') +const wstar = new WStar({ wrtc }) + +const node = await IPFS.create({ + repo: 'your-repo-path', + // start: false, + config: { + Addresses: { + Swarm: [ + "/ip4/0.0.0.0/tcp/4002", + "/ip4/127.0.0.1/tcp/4003/ws", + "/dns4/wrtc-star.discovery.libp2p.io/tcp/443/wss/p2p-webrtc-star" + ] + } + }, + libp2p: { + modules: { + transport: [wstar], + peerDiscovery: [wstar.discovery] + } + } +}) + +// 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: + +```bash +npm install wrtc --global +# or +npm 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"` + +## How can I configure an IPFS node to use a custom `signaling endpoint` for my WebRTC transport? + +You'll need to execute a compatible `signaling server` ([libp2p-webrtc-star](https://github.com/libp2p/js-libp2p-webrtc-star) works) and include the correct configuration param for your IPFS node: + +- provide the [`multiaddr`](https://github.com/multiformats/multiaddr) for the `signaling server` + +```JavaScript +const node = await IPFS.create({ + repo: 'your-repo-path', + config: { + 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. + +## I see some slowness when hopping between tabs Chrome with IPFS nodes, is there a reason why? + +Yes, unfortunately, due to [Chrome aggressive resource throttling policy](https://github.com/ipfs/js-ipfs/issues/611), 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](https://github.com/ipfs/ipfs-service-worker) + +## Can I use IPFS in my Electron App? + +Yes you can and in many ways. Read https://github.com/ipfs/notes/issues/256 for the multiple options. + +We now support Electron v5.0.0 without the need to rebuilt native modules. +Still if you run into problems with native modules follow these instructions [here](https://electronjs.org/docs/tutorial/using-native-node-modules). + +## Have more questions? + +Ask for help in our forum at https://discuss.ipfs.io or in IRC (#ipfs on Freenode). \ No newline at end of file diff --git a/packages/ipfs/docs/MODULE.md b/packages/ipfs/docs/MODULE.md new file mode 100644 index 0000000000..27f53e50e3 --- /dev/null +++ b/packages/ipfs/docs/MODULE.md @@ -0,0 +1,454 @@ +# IPFS Module + +Use the IPFS module as a dependency of your project to spawn in process instances of IPFS in node.js, the browser, electron, etc. + +## Table of contents + +- [Getting started](#getting-started) +- [IPFS.create([options])](#ipfscreateoptions) + - [`options.repo`](#optionsrepo) + - [`options.repoAutoMigrate`](#optionsrepoautomigrate) + - [`options.init`](#optionsinit) + - [`options.start`](#optionsstart) + - [`options.pass`](#optionspass) + - [`options.silent`](#optionssilent) + - [`options.relay`](#optionsrelay) + - [`options.offline`](#optionsoffline) + - [`options.preload`](#optionspreload) + - [`options.EXPERIMENTAL`](#optionsexperimental) + - [`options.config`](#optionsconfig) + - [`options.ipld`](#optionsipld) + - [`options.libp2p`](#optionslibp2p) + - [Instance methods](#instance-methods) + - [`node.start()`](#nodestart) + - [`node.stop()`](#nodestop) +- [Static types and utils](#static-types-and-utils) + - [Glob source](#glob-source) + - [`globSource(path, [options])`](#globsourcepath-options) + - [Example](#example) + - [URL source](#url-source) + - [`urlSource(url)`](#urlsourceurl) + - [Example](#example-1) + +## Getting started + +Create a running node with: + +```javascript +// Create the IPFS node instance +const node = await IPFS.create() +// Your node is now ready to use \o/ + +await node.stop() +// node is now 'offline' +``` + +The node returned from `IPFS.create()` supports the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api), along with some additional methods documented below. + +## IPFS.create([options]) + +```js +const node = await IPFS.create([options]) +``` + +Creates and returns a ready to use instance of an IPFS node. + +Use the `options` argument to specify advanced configuration. It is an object with any of these properties: + +### `options.repo` + +| Type | Default | +|------|---------| +| string or [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo) instance | `'~/.jsipfs'` in Node.js, `'ipfs'` in browsers | + +The file path at which to store the IPFS node’s data. Alternatively, you can set up a customized storage system by providing an [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo) instance. + +Example: + +```js +// Store data outside your user directory +const node = await IPFS.create({ repo: '/var/ipfs/data' }) +``` + +### `options.repoAutoMigrate` + +| Type | Default | +|------|---------| +| boolean | `true` | + +`js-ipfs` comes bundled with a tool that automatically migrates your IPFS repository when a new version is available. + +**For apps that build on top of `js-ipfs` and run in the browser environment, be aware that disabling automatic +migrations leaves the user with no way to run the migrations because there is no CLI in the browser. In such +a case, you should provide a way to trigger migrations manually.** + +### `options.init` + +| Type | Default | +|------|---------| +| boolean or object | `true` | + +Perform repo initialization steps when creating the IPFS node. + +Note that *initializing* a repo is different from creating an instance of [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo). The IPFS constructor sets many special properties when initializing a repo, so you should usually not try and call `repoInstance.init()` yourself. + +Instead of a boolean, you may provide an object with custom initialization options. All properties are optional: + +- `emptyRepo` (boolean) Whether to remove built-in assets, like the instructional tour and empty mutable file system, from the repo. (Default: `false`) +- `bits` (number) Number of bits to use in the generated key pair. (Default: `2048`) +- `privateKey` (string/PeerId) A pre-generated private key to use. Can be either a base64 string or a [PeerId](https://github.com/libp2p/js-peer-id) instance. **NOTE: This overrides `bits`.** + ```js + // Generating a Peer ID: + const PeerId = require('peer-id') + // Generates a new Peer ID, complete with public/private keypair + // See https://github.com/libp2p/js-peer-id + const peerId = await PeerId.create({ bits: 2048 }) + ``` +- `pass` (string) A passphrase to encrypt keys. You should generally use the [top-level `pass` option](#optionspass) instead of the `init.pass` option (this one will take its value from the top-level option if not set). +- `profiles` (Array) Apply profile settings to config. +- `allowNew` (boolean, default: `true`) Set to `false` to disallow initialization if the repo does not already exist. + +### `options.start` + +| Type | Default | +|------|---------| +| boolean | `true` | + + If `false`, do not automatically start the IPFS node. Instead, you’ll need to manually call [`node.start()`](#nodestart) yourself. + +### `options.pass` + +| Type | Default | +|------|---------| +| string | `null` | + +A passphrase to encrypt/decrypt your keys. + +### `options.silent` + +| Type | Default | +|------|---------| +| Boolean | `false` | + +Prevents all logging output from the IPFS node. + +### `options.relay` + +| Type | Default | +|------|---------| +| object | `{ enabled: true, hop: { enabled: false, active: false } }` | + +Configure circuit relay (see the [circuit relay tutorial](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs/examples/circuit-relaying) to learn more). + +- `enabled` (boolean): Enable circuit relay dialer and listener. (Default: `true`) +- `hop` (object) + - `enabled` (boolean): Make this node a relay (other nodes can connect *through* it). (Default: `false`) + - `active` (boolean): Make this an *active* relay node. Active relay nodes will attempt to dial a destination peer even if that peer is not yet connected to the relay. (Default: `false`) + +### `options.offline` + +| Type | Default | +|------|---------| +| Boolean | `false` | + +Run ipfs node offline. The node does not connect to the rest of the network but provides a local API. + +### `options.preload` + +| Type | Default | +|------|---------| +| object | `{ enabled: true, addresses: [...] }` | + +Configure remote preload nodes. The remote will preload content added on this node, and also attempt to preload objects requested by this node. + +- `enabled` (boolean): Enable content preloading (Default: `true`) +- `addresses` (array): Multiaddr API addresses of nodes that should preload content. **NOTE:** nodes specified here should also be added to your node's bootstrap address list at [`config.Boostrap`](#optionsconfig). + +### `options.EXPERIMENTAL` + +| Type | Default | +|------|---------| +| object | `{ ipnsPubsub: false, sharding: false }` | + +Enable and configure experimental features. + +- `ipnsPubsub` (boolean): Enable pub-sub on IPNS. (Default: `false`) +- `sharding` (boolean): Enable directory sharding. Directories that have many child objects will be represented by multiple DAG nodes instead of just one. It can improve lookup performance when a directory has several thousand files or more. (Default: `false`) + +### `options.config` + +| Type | Default | +|------|---------| +| object | [`config-nodejs.js`](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs/src/core/runtime/config-nodejs.js) in Node.js, [`config-browser.js`](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs/src/core/runtime/config-browser.js) in browsers | + +Modify the default IPFS node config. This object will be *merged* with the default config; it will not replace it. The default config is documented in [the js-ipfs config file docs](docs/config.md). + +### `options.ipld` + + | Type | Default | +|------|---------| +| object | [`ipld-nodejs.js`](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs/src/core/runtime/ipld-nodejs.js) in Node.js, [`ipld-browser.js`](https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs/src/core/runtime/ipld-browser.js) in browsers | + + Modify the default IPLD config. This object will be *merged* with the default config; it will not replace it. Check IPLD [docs](https://github.com/ipld/js-ipld#ipld-constructor) for more information on the available options. + + > Browser config does **NOT** include by default all the IPLD formats. Only `ipld-dag-pb`, `ipld-dag-cbor` and `ipld-raw` are included. + + To add support for other formats we provide two options, one sync and another async. + + Examples for the sync option: + +
ESM Environments + +```js +import ipldGit from 'ipld-git' +import ipldBitcoin from 'ipld-bitcoin' + +const node = await IPFS.create({ + ipld: { + formats: [ipldGit, ipldBitcoin] + } +}) +``` +
+
Commonjs Environments + +```js +const node = await IPFS.create({ + ipld: { + formats: [require('ipld-git'), require('ipld-bitcoin')] + } +}) +``` +
+
Using script tags + +```html + + + + +``` +
+ + Examples for the async option: + +
ESM Environments + +```js +const node = await IPFS.create({ + ipld: { + async loadFormat (codec) { + if (codec === multicodec.GIT_RAW) { + return import('ipld-git') // This is a dynamic import + } else { + throw new Error('unable to load format ' + multicodec.print[codec]) + } + } + } +}) +``` +> For more information about dynamic imports please check [webpack docs](https://webpack.js.org/guides/code-splitting/#dynamic-imports) or search your bundler documention. + +Using dynamic imports will tell your bundler to create a separate file (normally called *chunk*) that will **only** be requested by the browser if it's really needed. This strategy will reduce your bundle size and load times without removing any functionality. + +With Webpack IPLD formats can even be grouped together using magic comments `import(/* webpackChunkName: "ipld-formats" */ 'ipld-git')` to produce a single file with all of them. +
+ +
Commonjs Environments + +```js +const node = await IPFS.create({ + ipld: { + async loadFormat (codec) { + if (codec === multicodec.GIT_RAW) { + return require('ipld-git') + } else { + throw new Error('unable to load format ' + multicodec.print[codec]) + } + } + } +}) +``` +
+ +
Using Script tags + +```js + + +``` +
+ + +### `options.libp2p` + +| Type | Default | +|------|---------| +| object | [`libp2p-nodejs.js`](../src/core/runtime/libp2p-nodejs.js) in Node.js, [`libp2p-browser.js`](../src/core/runtime/libp2p-browser.js) in browsers | +| function | [`libp2p bundle`](https://github.com/ipfs/js-ipfs/tree/master/examples/custom-libp2p) | + +The libp2p option allows you to build your libp2p node by configuration, or via a bundle function. If you are looking to just modify the below options, using the object format is the quickest way to get the default features of libp2p. If you need to create a more customized libp2p node, such as with custom transports or peer/content routers that need some of the ipfs data on startup, a custom bundle is a great way to achieve this. + +You can see the bundle in action in the [custom libp2p example](https://github.com/ipfs/js-ipfs/tree/master/examples/custom-libp2p). + +Please see [libp2p/docs/CONFIGURATION.md](https://github.com/libp2p/js-libp2p/blob/master/doc/CONFIGURATION.md) for the list of options libp2p supports. + +### Instance methods + +#### `node.start()` + +Start listening for connections with other IPFS nodes on the network. In most cases, you do not need to call this method β€” `IPFS.create()` will automatically do it for you. + +This method is asynchronous and returns a promise. + +```js +const node = await IPFS.create({ start: false }) +console.log('Node is ready to use but not started!') + +try { + await node.start() + console.log('Node started!') +} catch (error) { + console.error('Node failed to start!', error) +} +``` + +#### `node.stop()` + +Close and stop listening for connections with other IPFS nodes, then release access to the node’s repo. + +This method is asynchronous and returns a promise. + +```js +const node = await IPFS.create() +console.log('Node is ready to use!') + +try { + await node.stop() + console.log('Node stopped!') +} catch (error) { + console.error('Node failed to stop!', error) +} +``` + +## Static types and utils + +Aside from the default export, `ipfs` exports various types and utilities that are included in the bundle: + +- [`crypto`](https://www.npmjs.com/package/libp2p-crypto) +- [`isIPFS`](https://www.npmjs.com/package/is-ipfs) +- [`Buffer`](https://www.npmjs.com/package/buffer) +- [`PeerId`](https://www.npmjs.com/package/peer-id) +- [`PeerInfo`](https://www.npmjs.com/package/peer-info) +- [`multiaddr`](https://www.npmjs.com/package/multiaddr) +- [`multibase`](https://www.npmjs.com/package/multibase) +- [`multihash`](https://www.npmjs.com/package/multihashes) +- [`multihashing`](https://www.npmjs.com/package/multihashing-async) +- [`multicodec`](https://www.npmjs.com/package/multicodec) +- [`CID`](https://www.npmjs.com/package/cids) + +These can be accessed like this, for example: + +```js +const { CID } = require('ipfs') +// ...or from an es-module: +import { CID } from 'ipfs' +``` + +##### 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 + +```js +const IPFS = require('ipfs') +const { globSource } = IPFS +const ipfs = await IPFS.create() +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`](https://developer.mozilla.org/en-US/docs/Web/API/URL) instance to send HTTP GET request to + +Returns an async iterable that yields `{ path, content }` objects suitable for passing to `ipfs.add`. + +###### Example + +```js +const IPFS = require('ipfs') +const { urlSource } = IPFS +const ipfs = await IPFS.create() +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 +} +*/ +``` diff --git a/packages/ipfs/docs/MONITORING.md b/packages/ipfs/docs/MONITORING.md new file mode 100644 index 0000000000..1b0cc29cfa --- /dev/null +++ b/packages/ipfs/docs/MONITORING.md @@ -0,0 +1,15 @@ +# Monitoring + +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). E.g. + +```console +$ IPFS_MONITORING=true jsipfs daemon +``` + +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: + +``` +http://localhost:5002/debug/metrics/prometheus +``` diff --git a/packages/ipfs/package-list.json b/packages/ipfs/package-list.json index 845b9af40f..e21c128e8f 100644 --- a/packages/ipfs/package-list.json +++ b/packages/ipfs/package-list.json @@ -11,7 +11,6 @@ "Files", ["ipfs/js-ipfs-unixfs", "ipfs-unixfs-exporter"], ["ipfs/js-ipfs-unixfs", "ipfs-unixfs-importer"], - ["ipfs/js-ipfs-mfs", "ipfs-mfs"], ["ipfs/js-ipfs-unixfs", "ipfs-unixfs"], "Repo",