Skip to content

docs: review the readme #181

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jan 9, 2018
Merged

docs: review the readme #181

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fa27d42
docs: review the readme
daviddias Jan 6, 2018
4efab07
Update README.md
daviddias Jan 6, 2018
0371dac
doc: updated `init()` docs
dryajov Jan 8, 2018
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
181 changes: 79 additions & 102 deletions README.md
View file
Open in desktop
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.
Copy link
Member Author

Choose a reason for hiding this comment

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

@dryajov seems that you never got to update the README based on the new reviewed API. I've updated it for you, please confirm that these options are correct.


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