Skip to content
This repository has been archived by the owner on Feb 12, 2024. It is now read-only.

fix: disable WebRTC by default and add how to support it + websocket-star to the FAQ #1111

Merged
merged 5 commits into from
Nov 27, 2017
Merged

fix: disable WebRTC by default and add how to support it + websocket-star to the FAQ #1111

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
31a78e5
fix: disable WebRTC by default
daviddias Nov 26, 2017
825dc2f
add websocket-star to FAQ
daviddias Nov 27, 2017
5e8f328
fix typo
daviddias Nov 27, 2017
cfdf1a2
update exchange files example
daviddias Nov 27, 2017
5513460
chore: update
daviddias Nov 27, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 67 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,10 @@ You can check the development status at the [Waffle Board](https://waffle.io/ipf

[![Throughput Graph](https://graphs.waffle.io/ipfs/js-ipfs/throughput.svg)](https://waffle.io/ipfs/js-ipfs/metrics/throughput)

**Important to note:** DHT and Relay are not finalized yet, you won't have resource discovery happening by default as you get in go-ipfs, we are working actively on these pieces, please follow:
**Please read this:** DHT (automatic content discovery) and Circuit Relay (pierce through NATs and dial between any node in the network) are two fundamental pieces that are not finalized yet. There are multiple applications that can be built without these two services but nevertheless they are fundamental to get that magic IPFS experience. If you want to track progress or contribute, please follow:

- DHT: https://github.com/ipfs/js-ipfs/pull/856
- Relay: https://github.com/ipfs/js-ipfs/pull/830
- Relay: https://github.com/ipfs/js-ipfs/pull/1063

## Table of Contents

Expand All @@ -54,10 +55,10 @@ You can check the development status at the [Waffle Board](https://waffle.io/ipf
- [Through command line tool](#through-command-line-tool)
- [Use in the browser](#use-in-the-browser)
- [Usage](#usage)
- [CLI](#cli)
- [HTTP-API](#http-api)
- [IPFS Core (use IPFS as a module in Node.js or in the Browser)](#ipfs-core-use-ipfs-as-a-module)
- [Create a IPFS node instance](#create-a-ipfs-node-instance)
- [IPFS CLI](#ipfs-cli)
- [IPFS Daemon](#ipfs-daemon)
- [IPFS Module (use IPFS as a module in Node.js or in the Browser)](#ipfs-module)
- [How to create a IPFS node instance](#create-a-ipfs-node-instance)
- [Tutorials and Examples](#tutorials-and-examples)
- [API Docs](#api)
- [Files](#files)
Expand Down Expand Up @@ -124,7 +125,7 @@ Inserting one of the above lines will make an `Ipfs` object available in the glo

## Usage

### CLI
### 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.

Expand All @@ -150,11 +151,13 @@ Commands:
- default Bootstrap is off, to enable it set `IPFS_BOOTSTRAP=1`


### HTTP-API
### IPFS Daemon

The IPFS Daemon exposes the API defined [`http-api-spec`](https://github.com/ipfs/http-api-spec). You can use any of the IPFS HTTP-API client libraries with it, such as: [js-ipfs-api](https://github.com/ipfs/js-ipfs-api).

The HTTP-API exposed by the js-ipfs daemon follows the [`http-api-spec`](https://github.com/ipfs/http-api-spec). You can use any of the IPFS HTTP-API client libraries with it, such as: [js-ipfs-api](https://github.com/ipfs/js-ipfs-api).
### IPFS Module

### IPFS Core (use IPFS as a module)
Use the IPFS Module as a dependency of a project to spawn in process instances of IPFS.

#### Create a IPFS node instance

Expand Down Expand Up @@ -191,14 +194,14 @@ const node = new IPFS({
// init: {
// bits: 1024 // size of the RSA key generated
// },
start: true,
start: true, // default
// start: false,
EXPERIMENTAL: { // enable experimental features
pubsub: true,
sharding: true, // enable dir sharding
dht: true // enable KadDHT, currently not interopable with go-ipfs
},
config: { // overload the default IPFS node config
config: { // overload the default IPFS node config, find defaults at https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime
Addresses: {
Swarm: [
'/ip4/127.0.0.1/tcp/1337'
Expand Down Expand Up @@ -322,6 +325,28 @@ A set of data types are exposed directly from the IPFS instance under `ipfs.type

## 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 = new IPFS({
config: {
Addresses: {
Swarm: [
'/dns4/wrtc-star.discovery.libp2p.io/wss/p2p-webrtc-star'
]
}
}
})

node.on('ready', () => {
// your instance with WebRTC is ready
})
```

**Important:** This transport usage is kind of unstable and several users have experienced crashes. Track development of a solution at https://github.com/ipfs/js-ipfs/issues/1088.

#### Is there WebRTC support for js-ipfs with Node.js?

Yes, however, bare in mind that there isn't a 100% stable solution to use WebRTC in Node.js, use it at your own risk. The most tested options are:
Expand All @@ -344,7 +369,7 @@ const node = new IPFS({
Swarm: [
"/ip4/0.0.0.0/tcp/4002",
"/ip4/127.0.0.1/tcp/4003/ws",
"/dns4/star-signal.cloud.ipfs.team/wss/p2p-webrtc-star"
"/dns4/wrtc-star.discovery.libp2p.io/wss/p2p-webrtc-star"
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Waiting on libp2p/js-libp2p-webrtc-star#126

]
}
},
Expand All @@ -369,15 +394,9 @@ npm install wrtc --global
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/star-signal.cloud.ipfs.team/wss/p2p-webrtc-star"`

#### 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.
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"`

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)

#### How can I configure an IPFS node to use a custom `signaling server`?
#### 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:

Expand All @@ -398,6 +417,33 @@ const node = new IPFS({

The code above assumes you are running a local `signaling server` on port `9090`. Provide the correct values accordingly.

#### Is there a more stable alternative to webrtc-star that offers a similar functionality?

Yes, websocket-star! A WebSockets based transport that uses a Relay to route the messages. To enable it, just do:

```JavaScript
const node = new IPFS({
config: {
Addresses: {
Swarm: [
'/dns4/ws-star.discovery.libp2p.io/wss/p2p-websocket-star'
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Waiting on libp2p/js-libp2p-websocket-star-rendezvous#9

]
}
}
})

node.on('ready', () => {
// your instance with websocket-star is ready
})
```

#### 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)


## Packages

| Package | Version | Deps | DevDeps | Build |
Expand Down
23 changes: 18 additions & 5 deletions examples/exchange-files-in-browser/public/js/app.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,25 @@ function start () {
if (!node) {
updateView('starting', node)

// DEV: To test with latest js-ipfs
const IPFS = require('ipfs')
node = new IPFS({ repo: 'ipfs-' + Math.random() })
const options = {
repo: 'ipfs-' + Math.random(),
config: {
Addresses: {
Swarm: [
// '/dns4/wrtc-star.discovery.libp2p.io/wss/p2p-webrtc-star'
'/dns4/ws-star.discovery.libp2p.io/wss/p2p-websocket-star'
]
}
}
}

// IFDEV: To test with latest js-ipfs
// const IPFS = require('ipfs')
// node = new IPFS(options)
// VEDIF

// EXAMPLE
// node = new self.Ipfs({ repo: 'ipfs-' + Math.random() })
node = new self.Ipfs(options)

node.once('start', () => node.id((err, id) => {
if (err) { return onError(err) }
Expand Down Expand Up @@ -121,7 +134,7 @@ function onDrop (event) {

const files = []
for (let i = 0; i < filesDropped.length; i++) {
files.pUsh(filesDropped[i])
files.push(filesDropped[i])
}

files.forEach((file) => {
Expand Down
1 change: 0 additions & 1 deletion src/core/runtime/config-browser.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
{
"Addresses": {
"Swarm": [
"/dns4/star-signal.cloud.ipfs.team/wss/p2p-webrtc-star"
],
"API": "",
"Gateway": ""
Expand Down