You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Feb 12, 2024. It is now read-only.
We try to frame our ongoing work using a process based on quarterly Objectives and Key Results (OKRs). Objectives reflect outcomes that are challenging, but realistic. Results are tangible and measurable.
4
+
5
+
## 2018 Q2
6
+
7
+
Find the **js-ipfs OKRs** for 2018 Q2 at the [2018 Q2 IPFS OKRs Spreadsheet](https://docs.google.com/spreadsheets/d/1xIhKROxFlsY9M9on37D5rkbSsm4YtjRQvG2unHScApA/edit#gid=274358435)
8
+
9
+
## 2018 Q1
10
+
11
+
Find the **js-ipfs OKRs** for 2018 Q1 at the [2018 Q1 IPFS OKRs Spreadsheet](https://docs.google.com/spreadsheets/u/1/d/1clB-W489rJpbOEs2Q7Q2Jf1WMXHQxXgccBcUJS9QTiI/edit#gid=2079514081)
@@ -58,14 +58,19 @@ You can check the development status at the [Waffle Board](https://waffle.io/ipf
58
58
-[IPFS CLI](#ipfs-cli)
59
59
-[IPFS Daemon](#ipfs-daemon)
60
60
-[IPFS Module (use IPFS as a module in Node.js or in the Browser)](#ipfs-module)
61
-
-[How to create a IPFS node instance](#create-a-ipfs-node-instance)
62
61
-[Tutorials and Examples](#tutorials-and-examples)
63
62
-[API Docs](#api)
64
-
-[Files](#files)
65
-
-[Graph](#graph)
66
-
-[Network](#network)
67
-
-[Node Management](#node-management)
68
-
-[Domain data types](#domain-data-types)
63
+
-[Constructor](#ipfs-constructor)
64
+
-[Events](#events)
65
+
-[start](#nodestartcallback)
66
+
-[stop](#nodestopcallback)
67
+
-[Core API](#core-api)
68
+
-[Files](#files)
69
+
-[Graph](#graph)
70
+
-[Crypto and Key Management](#crypto-and-key-management)
71
+
-[Network](#network)
72
+
-[Node Management](#node-management)
73
+
-[Domain data types](#domain-data-types)
69
74
-[FAQ](#faq)
70
75
-[Running js-ipfs with Docker](#running-js-ipfs-with-docker)
71
76
-[Packages](#packages)
@@ -163,11 +168,7 @@ If you want a programmatic way to spawn a IPFS Daemon using JavaScript, check ou
163
168
164
169
### IPFS Module
165
170
166
-
Use the IPFS Module as a dependency of a project to __spawn in process instances of IPFS__.
167
-
168
-
#### Create a IPFS node instance
169
-
170
-
Creating an IPFS instance couldn't be easier, all you have to do is:
171
+
Use the IPFS Module as a dependency of a project to __spawn in process instances of IPFS__. Create an instance by calling `new IPFS()` and waiting for its `ready` event:
171
172
172
173
```JavaScript
173
174
// Create the IPFS node instance
@@ -183,70 +184,158 @@ node.on('ready', () => {
183
184
})
184
185
```
185
186
186
-
#### Advanced options when creating an IPFS node.
187
+
###[Tutorials and Examples](/examples)
187
188
188
-
When starting a node, you can:
189
+
You can find some examples and tutorials in the [examples](/examples) folder, these exist to help you get started using `js-ipfs`.
189
190
190
-
```JavaScript
191
-
// IPFS will need a repo, it can create one for you or you can pass
192
-
// it a repo instance of the type IPFS Repo
193
-
// https://github.com/ipfs/js-ipfs-repo
194
-
constrepo=<IPFS Repo instance or repo path>
191
+
### API
195
192
196
-
constnode=newIPFS({
197
-
repo: repo,
198
-
init:true, // default
199
-
// init: false, // You will need to set init: false after time you start instantiate a node as
200
-
// // the repo will be already initiated then.
201
-
// init: {
202
-
// bits: 1024 // size of the RSA key generated
203
-
// },
204
-
start:true, // default
205
-
// start: false,
206
-
pass:undefined// default
207
-
// pass: 'pass phrase for key access',
208
-
EXPERIMENTAL: { // enable experimental features
209
-
pubsub:true,
210
-
sharding:true, // enable dir sharding
211
-
dht:true, // enable KadDHT, currently not interopable with go-ipfs
212
-
relay: {
213
-
enabled:true, // enable circuit relay dialer and listener
214
-
hop: {
215
-
enabled:true// enable circuit relay HOP (make this node a relay)
216
-
}
217
-
}
218
-
},
219
-
config: { // overload the default IPFS node config, find defaults at https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime
220
-
Addresses: {
221
-
Swarm: [
222
-
'/ip4/127.0.0.1/tcp/1337'
223
-
]
224
-
}
225
-
},
226
-
libp2p: { // add custom modules to the libp2p stack of your node
227
-
modules: {}
193
+
#### IPFS Constructor
194
+
195
+
```js
196
+
constnode=newIPFS([options])
197
+
```
198
+
199
+
Creates and returns an instance of an IPFS node. Use the `options` argument to specify advanced configuration. It is an object with any of these properties:
200
+
201
+
-`repo` (string or [`ipfs.Repo`](https://github.com/ipfs/js-ipfs-repo) instance): 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. (Default: `'~/.jsipfs'` in Node.js, `'ipfs'` in browsers.)
202
+
203
+
Example:
204
+
205
+
```js
206
+
// Store data outside your user directory
207
+
constnode=newIPFS({ repo:'/var/ipfs/data' })
208
+
```
209
+
210
+
-`init` (boolean or object): Initialize the repo when creating the IPFS node. (Default:`true`)
211
+
212
+
If you have already initialized a repo before creating your IPFSnode (e.g. you are loading a repo that was saved to disk from a previous run of your program), you must make sure to set this to `false`. 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.
213
+
214
+
Instead of a boolean, you may provide an object with custom initialization options.
215
+
216
+
-`start` (boolean): If `false`, do not automatically start the IPFSnode. Instead, you’ll need to manually call `node.start()` yourself. (Default:`true`)
217
+
218
+
-`pass` (string):A passphrase to encrypt your keys.
219
+
220
+
-`EXPERIMENTAL` (object): Enable and configure experimental features.
-`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`)
223
+
-`dht` (boolean): Enable KadDHT. **This is currently not interopable with`go-ipfs`.**
224
+
-`relay` (object): Configure circuit relay (see the [circuit relay tutorial](https://github.com/ipfs/js-ipfs/tree/master/examples/circuit-relaying) to learn more).
225
+
-`enabled` (boolean): Enable circuit relay dialer and listener. (Default:`false`)
226
+
-`hop` (object)
227
+
-`enabled` (boolean): Make this node a relay (other nodes can connect *through* it). (Default:`false`)
228
+
-`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`)
229
+
230
+
-`config` (object) Modify the default IPFS node config. Find the Node.js defaults at [`src/core/runtime/config-nodejs.json`](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/config-nodejs.json) and the browser defaults at [`src/core/runtime/config-browser.json`](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/config-browser.json). This object will be *merged* with the default config; it will not replace it.
231
+
232
+
-`libp2p` (object) add custom modules to the libp2p stack of your node
233
+
-`modules` (object):
234
+
-`transport` (Array<[libp2p.Transport](https://github.com/libp2p/interface-transport)>): An array of additional Libp2p transport instances to use. See [libp2p/interface-transport](https://github.com/libp2p/interface-transport) for details.
235
+
-`discovery` (Array<[libp2p.PeerDiscovery](https://github.com/libp2p/interface-peer-discovery)>): An array of additional Libp2p peer discovery instances to use. See [libp2p/peer-discovery](https://github.com/libp2p/interface-peer-discovery) for details.
236
+
237
+
#### Events
238
+
239
+
IPFS instances are Node.js [EventEmitters](https://nodejs.org/dist/latest-v8.x/docs/api/events.html#events_class_eventemitter). You can listen for events by calling `node.on('event', handler)`:
-`error` is always accompanied by an `Error` object with information about the error that ocurred.
247
+
248
+
```js
249
+
node.on('error', error => {
250
+
console.error(error.message)
251
+
})
252
+
```
253
+
254
+
-`init` is emitted after a newrepo has been initialized. It will not be emitted if you set the `init: false` option on the constructor.
255
+
256
+
- `ready` is emitted when a node is ready to use. This is the final event you will receive when creating a node (after`init`and`start`).
257
+
258
+
When creating a new IPFS node, you should almost always wait for the `ready` event before calling methods or interacting with the node.
259
+
260
+
- `start` is emitted when a node has started listening for connections. It will not be emitted if you set the `start: false` option on the constructor.
261
+
262
+
- `stop` is emitted when a node has closed all connections and released access to its repo. This is usually the result of calling [`node.stop()`](#nodestopcallback).
263
+
264
+
#### `node.start([callback])`
265
+
266
+
Start listening for connections with other IPFS nodes on the network. In most cases, you do not need to call this method — `new IPFS()` will automatically do it for you.
267
+
268
+
This method is asynchronous. There are several ways to be notified when the node has finished starting:
269
+
270
+
1. If you call `node.start()` with no arguments, it returns a promise.
271
+
2. If you pass a function as the final argument, it will be called when the node is started. *(Note: this method will **not** return a promise if you use a callback function.)*
272
+
3. You can listen for the [`start` event](#events).
273
+
274
+
```js
275
+
const node = new IPFS({ start:false })
276
+
277
+
// Use a promise:
278
+
node.start()
279
+
.then(() =>console.log('Node started!'))
280
+
.catch(error=>console.error('Node failed to start!', error))
281
+
282
+
// OR use a callback:
283
+
node.start(error=> {
284
+
if (error) {
285
+
console.error('Node failed to start!', error)
286
+
return
228
287
}
288
+
console.log('Node started!')
229
289
})
230
290
231
-
// Events
291
+
// OR use events:
292
+
node.on('error', error=>console.error('Something went terribly wrong!', error))
node.on('ready', () => {}) // Node is ready to use when you first create it
234
-
node.on('error', (err) => {}) // Node has hit some error while initing/starting
297
+
#### `node.stop([callback])`
235
298
236
-
node.on('init', () => {}) // Node has successfully finished initing the repo
237
-
node.on('start', () => {}) // Node has started
238
-
node.on('stop', () => {}) // Node has stopped
239
-
```
299
+
Close and stop listening for connections with other IPFS nodes, then release access to the node’s repo.
240
300
241
-
### [Tutorials and Examples](/examples)
301
+
This method is asynchronous. There are several ways to be notified when the node has completely stopped:
242
302
243
-
You can find some examples and tutorials in the [examples](/examples) folder, these exist to help you get started using `js-ipfs`.
303
+
1. If you call `node.stop()` with no arguments, it returns a promise.
304
+
2. If you pass a function as the final argument, it will be called when the node is stopped. *(Note: this method will **not** return a promise if you use a callback function.)*
305
+
3. You can listen for the [`stop` event](#events).
244
306
245
-
### API
307
+
```js
308
+
constnode=newIPFS()
309
+
node.on('ready', () => {
310
+
console.log('Node is ready to use!')
311
+
312
+
// Stop with a promise:
313
+
node.stop()
314
+
.then(() =>console.log('Node stopped!'))
315
+
.catch(error=>console.error('Node failed to stop cleanly!', error))
316
+
317
+
// OR use a callback:
318
+
node.stop(error=> {
319
+
if (error) {
320
+
console.error('Node failed to stop cleanly!', error)
321
+
return
322
+
}
323
+
console.log('Node stopped!')
324
+
})
325
+
326
+
// OR use events:
327
+
node.on('error', error=>console.error('Something went terribly wrong!', error))
A complete API definition is in the works. Meanwhile, you can learn how to you use js-ipfs through the standard interface at [](https://github.com/ipfs/interface-ipfs-core).
336
+
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://github.com/ipfs/interface-ipfs-core).
If you find any other issue, please check the [`Electron Support` issue](https://github.com/ipfs/js-ipfs/issues/843).
525
614
615
+
#### Have more questions?
616
+
617
+
Ask for help in our forum at https://discuss.ipfs.io or in IRC (#ipfs on Freenode).
618
+
526
619
## Running js-ipfs with Docker
527
620
528
621
We have automatic Docker builds setup with Docker Hub: https://hub.docker.com/r/ipfs/js-ipfs/
@@ -728,7 +821,6 @@ IPFS implementation in JavaScript is a work in progress. As such, there's a few
728
821
***Perform code reviews**. More eyes will help (a) speed the project along, (b) ensure quality, and (c) reduce possible future bugs.
729
822
* 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.
730
823
***Add tests**. There can never be enough tests.
731
-
***Contribute to the [FAQ repository](https://github.com/ipfs/faq/issues)** with any questions you have about IPFS or any of the relevant technology. A good example would be asking, 'What is a merkledag tree?'. If you don't know a term, odds are, someone else doesn't either. Eventually, we should have a good understanding of where we need to improve communications and teaching together to make IPFS and IPN better.
0 commit comments