Skip to content

Commit

Permalink
docs: review the readme (#181)
Browse files Browse the repository at this point in the history 
* docs: review the readme

* Update README.md

* doc: updated `init()` docs
  • Loading branch information
@daviddias
daviddias authored Jan 9, 2018
1 parent c60dece commit dbe6b37
Showing 1 changed file with 79 additions and 102 deletions.
181 changes: 79 additions & 102 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
[![Appveyor CI](https://ci.appveyor.com/api/projects/status/4p9r12ch0jtthnha?svg=true)](https://ci.appveyor.com/project/wubalubadubdub/js-ipfsd-ctl-a9ywu)
[![Dependency Status](https://david-dm.org/ipfs/js-ipfsd-ctl.svg?style=flat-square)](https://david-dm.org/ipfs/js-ipfsd-ctl) [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)

> Control an ipfs node daemon using either Node.js or the browser
> Control an IPFS daemon using JavaScript in Node.js or in the Browser.
```
+-----+
Expand Down Expand Up @@ -51,7 +51,7 @@ npm install --save ipfsd-ctl

IPFS daemons are already easy to start and stop, but this module is here to do it from JavaScript itself.

### Local daemon (_Spawn from from Node.js_)
### Spawn an IPFS daemon from Node.js

```js
// Start a disposable node, and get access to the api
Expand All @@ -61,14 +61,18 @@ const DaemonFactory = require('ipfsd-ctl')
const df = DaemonFactory.create()

df.spawn(function (err, ipfsd) {
if (err) { throw err }

ipfsd.api.id(function (err, id) {
if (err) { throw err }

console.log(id)
ipfsd.stop()
})
})
```

### Remote node _(Spawn from a Browser or from a remote machine))
### Spawn an IPFS daemon from the Browser using the provided remote endpoint

```js
// Start a remote disposable node, and get access to the api
Expand All @@ -78,18 +82,17 @@ const DaemonFactory = require('ipfsd-ctl')

const port = 9999
const server = DaemonFactory.createServer(port)
const df = DaemonFactory.create({ remote: true, port })
const df = DaemonFactory.create({ remote: true, port: port })

server.start((err) => {
if (err) {
throw err
}
if (err) { throw err }

df.spawn((err, ipfsd) => {
if (err) {
throw err
}
if (err) { throw err }

ipfsd.api.id(function (err, id) {
if (err) { throw err }

console.log(id)
ipfsd.stop(server.stop)
})
Expand All @@ -110,174 +113,148 @@ server.start((err) => {

## API

### Daemon Factory
### Daemon Factory Class

#### Create a `DaemonFactory` - `const df = DaemonFactory.create([options])`
#### `DaemonFactory` - `const df = DaemonFactory.create([options])`

> `DaemonFactory.create([options])` returns an object that will expose the `df.spawn` method
`DaemonFactory.create([options])` returns an object that will expose the `df.spawn` method

- `options` - an optional object with the following properties
- `remote` bool - indicates if the factory should spawn local or remote nodes. By default, local nodes are spawned in Node.js and remote nodes are spawned in Browser environments.
- `port` number - the port number to use for the remote factory. It should match the port on which `DaemonFactory.server` was started. Defaults to 9999.
- type - the daemon type to create with this factory. See the section bellow for the supported types
- `type` - the daemon type to create with this factory. See the section bellow for the supported types
- `exec` - path to the desired IPFS executable to spawn, otherwise `ipfsd-ctl` will try to locate the correct one based on the `type`. In the case of `proc` type, exec is required and expects an IPFS coderef.

##### IPFS executable types

`ipfsd-ctl` allows spawning different types of executables, such as:

> `go`
Invoking `df.create({type: 'go'})` will spawn a `go-ipfs` node.

> `js`
Invoking `df.create({type: 'js'})` will spawn a `js-ipfs` node.

> `proc`
Invoking `df.create({type: 'proc'})` will spawn an `in-process-ipfs` node using the provided code reference that implements the core IPFS API. Note that, `exec` option to `df.spawn()` is required if `type: 'proc'` is used.
`ipfsd-ctl` allows spawning different IPFS implementations, such as:

- **`go`** - calling `DaemonFactory.create({type: 'go'})` will spawn a `go-ipfs` daemon.
- **`js`** - calling `DaemonFactory.create({type: 'js'})` will spawn a `js-ipfs` daemon.
- **`proc`** - calling `DaemonFactory.create({type: 'proc', exec: require('ipfs') })` will spawn an `in process js-ipfs node` using the provided code reference that implements the core IPFS API. Note that, `exec` option to `df.spawn()` is required if `type: 'proc'` is used.

#### DaemonFactory endpoint for remote spawning - `const server = DaemonFactory.createServer([options]) `

#### Create a DaemonFactory Endpoint - `const server = DaemonFactory.createServer([options]) `

> `DaemonFactory.createServer` create an instance of the bundled REST API used by the remote controller.
`DaemonFactory.createServer` create an instance of the bundled REST API used by the remote controller.

- exposes `start` and `stop` methods to start and stop the http server.
- exposes `start` and `stop` methods to start and stop the http server endpoint.

#### Spawn a new daemon with `df.spawn`

> Spawn either a js-ipfs or go-ipfs node
Spawn either a js-ipfs or go-ipfs daemon

`spawn([options], callback)`
`df.spawn([options], callback)`

- `options` - is an optional object the following properties
`options` is an optional object the following properties:
- `init` bool (default true) - should the node be initialized
- `start` bool (default true) - should the node be started
- `repoPath` string - the repository path to use for this node, ignored if node is disposable
- `disposable` bool (default false) - a new repo is created and initialized for each invocation, as well as cleaned up automatically once the process exits
- `args` - array of cmd line arguments to be passed to ipfs daemon
- `config` - ipfs configuration options
- `exec` - path to the desired IPFS executable to spawn, otherwise `ipfsd-ctl` will try to locate the correct one based on the `type`. In the case of `proc` type, exec is required and expects an IPFS coderef

- `callback` - is a function with the signature `cb(err, ipfsd)` where:
- `err` - is the error set if spawning the node is unsuccessful
- `ipfsd` - is the daemon controller instance:
- `api` - a property of `ipfsd`, an instance of [ipfs-api](https://github.com/ipfs/js-ipfs-api) attached to the newly created ipfs node

### IPFS Daemon Controller (ipfsd)

> The IPFS daemon controller that allows interacting with the spawned IPFS process

#### `apiAddr` (getter)
`callback` - is a function with the signature `function (err, ipfsd)` where:
- `err` - is the error set if spawning the node is unsuccessful
- `ipfsd` - is the daemon controller instance:
- `api` - a property of `ipfsd`, an instance of [ipfs-api](https://github.com/ipfs/js-ipfs-api) attached to the newly created ipfs node

> Get the address (multiaddr) of connected IPFS API.
### IPFS Daemon Controller (`ipfsd`)

- returns multiaddr
The IPFS daemon controller (`ipfsd`) allows you to interact with the spawned IPFS daemon.

#### `gatewayAddr` (getter)
#### `ipfsd.apiAddr` (getter)

> Get the address (multiaddr) of connected IPFS HTTP Gateway.
Get the address (multiaddr) of connected IPFS API. Returns a multiaddr,

- returns multiaddr
#### `ipfsd.gatewayAddr` (getter)

#### `repoPath` (getter)
Get the address (multiaddr) of connected IPFS HTTP Gateway. Returns a multiaddr.

> Get the current repo path.
#### `ipfsd.repoPath` (getter)

- returns string
Get the current repo path. Returns string

#### `started` (getter)
#### `ipfsd.started` (getter)

> Is the node started.
- returns boolean
Is the node started. Returns a boolean.

#### `init ([initOpts], callback)`
#### `init([initOpts], callback)`

> Initialize a repo.
Initialize a repo.

- `initOpts` (optional) - options object with the following entries
`initOpts` (optional) is an object with the following properties:
- `keysize` (default 2048) - The bit size of the identiy key.
- `directory` (default IPFS_PATH if defined, or ~/.ipfs for go-ipfs and ~/.jsipfs for js-ipfs) - The location of the repo.
- `function (Error, Node)` callback - receives an instance of this Node on success or an instance of `Error` on failure


#### `cleanup (callback)`

> Delete the repo that was being used. If the node was marked as `disposable` this will be called automatically when the process is exited.

`callback` is a function with the signature `function (Error, ipfsd)` where `err` is an Error in case something goes wrong and `ipfsd` is the daemon controller instance.

- `function(Error)` callback
#### `ipfsd.cleanup(callback)`

#### `start (flags, callback)`
Delete the repo that was being used. If the node was marked as `disposable` this will be called automatically when the process is exited.

> Start the daemon.
`callback` is a function with the signature `function(err)`.

- `flags` - Flags array to be passed to the `ipfs daemon` command.
- `function(Error, IpfsApi)}` callback - function that receives an instance of `ipfs-api` on success or an instance of `Error` on failure
#### `ipfsd.start(flags, callback)`

Start the daemon.

#### `stop (callback)`
`flags` - Flags array to be passed to the `ipfs daemon` command.

> Stop the daemon.
`callback` is a function with the signature `function(err, ipfsApi)}` that receives an instance of `ipfs-api` on success or an instance of `Error` on failure

- `function(Error)` callback - function that receives an instance of `Error` on failure

#### `killProcess (callback)`
#### `ipfsd.stop(callback)`

> Kill the `ipfs daemon` process.
Stop the daemon.

First `SIGTERM` is sent, after 10.5 seconds `SIGKILL` is sent if the process hasn't exited yet.
`callback` is a function with the signature `function(err)` callback - function that receives an instance of `Error` on failure

- `function()` callback - Called once the process is killed
#### `ipfsd.killProcess (callback)`

Kill the `ipfs daemon` process.

#### `pid ()`
First a `SIGTERM` is sent, after 10.5 seconds `SIGKILL` is sent if the process hasn't exited yet.

> Get the pid of the `ipfs daemon` process.
`callback` is a function with the signature `function()` called once the process is killed

- returns the pid number
#### `ipfsd.pid ()`

Get the pid of the `ipfs daemon` process. Returns the pid number

#### `getConfig (key, callback)`
#### `ipfsd.getConfig(key, callback)`

> Call `ipfs config`
Returns the output of an `ipfs config` command. If no `key` is passed, the whole config is returned as an object.

If no `key` is passed, the whole config is returned as an object.
`key` (optional) - A specific config to retrieve.

- `key` (optional) - A specific config to retrieve.
- `function(Error, (Object|string)` callback - function that receives an object or string on success or an `Error` instance on failure
`callback` is a function with the signature `function(err, (Object|string)` that receives an object or string on success or an `Error` instance on failure

#### `ipfsd.setConfig (key, value, callback)`

#### `setConfig (key, value, callback)`
Set a config value.

> Set a config value.
`key` - the key of the config entry to change/set

- `key` - the key of the config entry to change/set
- `value` - the config value to change/set
- `function(Error)` callback - function that receives an `Error` instance on failure
`value` - the config value to change/set

`callback` is a function with the signature `function(err)` callback - function that receives an `Error` instance on failure

#### `version (callback)`
#### `ipfsd.version(callback)`

> Get the version of ipfs
Get the version of ipfs

- `function(Error, string)` callback
`callback` is a function with the signature `function(err, version)`

### IPFS Client (`ipfsd.api`)

> An instance of [ipfs-api](https://github.com/ipfs/js-ipfs-api#api)
An instance of [ipfs-api](https://github.com/ipfs/js-ipfs-api#api) that is used to interact with the daemon.

This instance is returned for each successfully started IPFS daemon, when either `df.spawn({start: true})` (the default) is called, or `ipfsd.start()` is invoked in the case of nodes that were spawned with `df.spawn({start: false})`.

### Packaging

`ipfsd-ctl` can be packaged in Electron applications, but the ipfs binary
has to be excluded from asar (Electron Archives),
`ipfsd-ctl` can be packaged in Electron applications, but the ipfs binary has to be excluded from asar (Electron Archives),
[read more about unpack files from asar](https://electron.atom.io/docs/tutorial/application-packaging/#adding-unpacked-files-in-asar-archive).
`ipfsd-ctl` will try to detect if used from within an `app.asar` archive
and tries to resolve ipfs from `app.asar.unpacked`. The ipfs binary is part of
the `go-ipfs-dep` module.

`ipfsd-ctl` will try to detect if used from within an `app.asar` archive and tries to resolve ipfs from `app.asar.unpacked`. The ipfs binary is part of the `go-ipfs-dep` module.

```bash
electron-packager ./ --asar.unpackDir=node_modules/go-ipfs-dep
Expand Down

0 comments on commit dbe6b37

Please sign in to comment.