feat: Complete revamp! Spawn js/go daemons locally or remote (from th…

…e browser) (#176)

.aegir.js

@@ -0,0 +1,22 @@
+'use strict'
+
+const createServer = require('./src').createServer
+
+const server = createServer()
+module.exports = {
+  karma: {
+    files: [{
+      pattern: 'test/fixtures/**/*',
+      watched: false,
+      served: true,
+      included: false
+    }],
+    singleRun: true
+  },
+  hooks: {
+    browser: {
+      pre: server.start.bind(server),
+      post: server.stop.bind(server)
+    }
+  }
+}

.appveyor.yml

@@ -1,23 +1,28 @@
+version: "{build}"
+
 environment:
   matrix:
     - nodejs_version: "6"
     - nodejs_version: "8"
 
-# cache:
-#  - node_modules
-
-platform:
-  - x64
+matrix:
+  fast_finish: true
 
 install:
-  - ps: Install-Product node $env:nodejs_version $env:platform
+  # Install Node.js
+  - ps: Install-Product node $env:nodejs_version
+
+  # Upgrade npm
+  - npm install -g npm
+
+  # Output our current versions for debugging
   - node --version
   - npm --version
+
+  # Install our package dependencies
   - npm install
 
 test_script:
-  - npm test
+  - npm run test
 
 build: off
-
-version: "{build}"

.gitignore

@@ -36,3 +36,5 @@ node_modules
 
 dist
 docs
+
+.idea

README.md

@@ -10,12 +10,33 @@
 [![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 Node.js
+> Control an IPFS daemon using JavaScript in Node.js or in the Browser.
+
+```
+                                                                    +-----+                                   
+                                                                    |  H  |                                   
+                                                                    |  T  |                                   
+    +-----------------------------+                                 |  T  |                                   
+    |           Node.js           |  +-----------------------+      |  P  |    +-----------------------------+
+    |                             |  |                       |      |     |    |          BROWSER            |
+    | +-----------------------+   |  |       IPFS Daemon     |      |  S  |    |                             |
+    | |   Local Daemon Ctrl   |   |  |                       |      |  E  |    |   +----------------------+  |
+    | |                       +-------                       --------  R  -----|---- Remote Daemon Ctrl   |  |
+    | +-----------------------+   |  +-----|-----------|-----+      |  V  |    |   |                      |  |
+    |                             |        |           |            |  E  |    |   +----------------------+  |
+    | +-----------------------+   |        |           |            |  R  |    |                             |
+    | |       IPFS API        |   |        |           |            +-----+    |   +----------------------+  |
+    | |                       -------------+           |                       |   |     IPFS API         |  |
+    | +-----------------------+   |                    +-----------------------|----                      |  |
+    |                             |                                            |   +----------------------+  |
+    +-----------------------------+                                            +-----------------------------+
+```
 
 ## Table of Contents
 
 - [Install](#install)
 - [Usage](#usage)
+- [API](#api)
 - [Contribute](#contribute)
 - [License](#license)
 
@@ -30,35 +51,210 @@ 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.
 
+### Spawn an IPFS daemon from Node.js
+
 ```js
 // Start a disposable node, and get access to the api
-// print the node id, and kill the temporary daemon
-
-// IPFS_PATH will point to /tmp/ipfs_***** and will be
-// cleaned up when the process exits.
+// print the node id, and stop the temporary daemon
 
-var ipfsd = require('ipfsd-ctl')
+const DaemonFactory = require('ipfsd-ctl')
+const df = DaemonFactory.create()
 
-ipfsd.disposableApi(function (err, ipfs) {
-  ipfs.id(function (err, id) {
+df.spawn(function (err, ipfsd) {
+  if (err) { throw err }
+
+  ipfsd.api.id(function (err, id) {
+    if (err) { throw err }
+
     console.log(id)
-    process.exit()
+    ipfsd.stop()
   })
 })
 ```
 
-If you need want to use an existing ipfs installation you can set `$IPFS_EXEC=/path/to/ipfs` to ensure it uses that.
+### Spawn an IPFS daemon from the Browser using the provided remote endpoint
+
+```js
+// Start a remote disposable node, and get access to the api
+// print the node id, and stop the temporary daemon
+
+const DaemonFactory = require('ipfsd-ctl')
+
+const port = 9999
+const server = DaemonFactory.createServer(port)
+const df = DaemonFactory.create({ remote: true, port: port })
+
+server.start((err) => {
+  if (err) { throw err }
+
+  df.spawn((err, ipfsd) => {
+    if (err) { throw err }
+
+    ipfsd.api.id(function (err, id) {
+      if (err) { throw err }
+
+      console.log(id)
+      ipfsd.stop(server.stop)
+    })
+  })
+})
+```
+
+## Disposable vs non Disposable nodes
+
+`ipfsd-ctl` can create two types of node controllers, `disposable` and `non-disposable`. A disposable node will be created on a temporary repo which will be optionally initialized and started (the default), as well cleaned up on process exit. A non-disposable node on the other hand, requires the user to initialize and start the node, as well as stop and cleanup after wards. Additionally, a non-disposable will allow you to pass a custom repo using the `repoPath` option, if the `repoPath` is not defined, it will use the default repo for the node type (`$HOME/.ipfs` or `$HOME/.jsipfs`). The `repoPath` parameter is ignored for disposable nodes, as there is a risk of deleting a live repo.
+
+## IPFS executables
+
+`ipfsd-ctl` no longer installs go-ipfs nor js-ipfs dependencies, instead it expects them to be provided by the parent project. In order to be able to use both go and js daemons, please make sure that your project includes these two npm packages as dependencies.
+
+- `ipfs` - the js-ipfs implementation
+- `go-ipfs-dep` - the packaged go-ipfs implementation
+
+## API
+
+### Daemon Factory Class
+
+#### `DaemonFactory` - `const df = DaemonFactory.create([options])`
+
+`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
+  - `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.
+
+`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]) `
+
+`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 endpoint.
+
+#### Spawn a new daemon with `df.spawn`
+
+Spawn either a js-ipfs or go-ipfs daemon
+
+`df.spawn([options], callback)`
+
+`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
+
+`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   
+
+### IPFS Daemon Controller (`ipfsd`)
+
+The IPFS daemon controller (`ipfsd`) allows you to interact with the spawned IPFS daemon.
+
+#### `ipfsd.apiAddr` (getter)
+
+Get the address (multiaddr) of connected IPFS API. Returns a multiaddr
+
+#### `ipfsd.gatewayAddr` (getter)
 
-For more details see https://ipfs.github.io/js-ipfsd-ctl/.
+Get the address (multiaddr) of connected IPFS HTTP Gateway. Returns a multiaddr.
 
+#### `ipfsd.repoPath` (getter)
+
+Get the current repo path. Returns string.
+
+#### `ipfsd.started` (getter)
+
+Is the node started. Returns a boolean.
+
+#### `init([initOpts], callback)`
+
+Initialize a repo. 
+
+`initOpts` (optional) is an object with the following properties:
+  - `keysize` (default 2048) - The bit size of the identity key.
+  - `directory` (default IPFS_PATH if defined, or ~/.ipfs for go-ipfs and ~/.jsipfs for js-ipfs) - The location of the repo.
+
+`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.
+
+#### `ipfsd.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(err)`.
+
+#### `ipfsd.start(flags, callback)`
+
+Start the daemon.
+
+`flags` - Flags array to be passed to the `ipfs daemon` command.
+
+`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
+
+
+#### `ipfsd.stop([callback])`
+
+Stop the daemon.
+
+`callback` is a function with the signature `function(err)` callback - function that receives an instance of `Error` on failure
+
+#### `ipfsd.killProcess([callback])`
+
+Kill the `ipfs daemon` process.
+
+First a `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()` called once the process is killed
+
+#### `ipfsd.pid()`
+
+Get the pid of the `ipfs daemon` process. Returns the pid number
+
+#### `ipfsd.getConfig([key], callback)`
+
+Returns the output of an `ipfs config` command. If no `key` is passed, the whole config is returned as an object.
+
+`key` (optional) - A specific config to retrieve.
+
+`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)`
+
+Set a config value.
+
+`key` - the key of the config entry to change/set 
+
+`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
+
+#### `ipfsd.version(callback)`
+
+Get the version of ipfs
+
+`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) 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

circle.yml

@@ -2,6 +2,10 @@
 machine:
   node:
     version: stable
+
+test:
+  post:
+    - npm run coverage -- --upload --providers coveralls
 
 dependencies:
   pre:

examples/electron-asar/app.js

@@ -1,8 +1,13 @@
 /* eslint no-console: 0 */
 'use strict'
 
-const { app, ipcMain, BrowserWindow } = require('electron')
-const ipfsd = require('ipfsd-ctl')
+const electron = require('electron')
+const app = electron.app
+const ipcMain = electron.ipcMain
+const BrowserWindow = electron.BrowserWindow
+
+const DaemonFactory = require('ipfsd-ctl')
+const df = DaemonFactory.create()
 
 app.on('ready', () => {
   const win = new BrowserWindow({
@@ -15,20 +20,22 @@ ipcMain.on('start', ({ sender }) => {
   console.log('starting disposable IPFS')
   sender.send('message', 'starting disposable IPFS')
 
-  ipfsd.disposableApi((err, ipfs) => {
+  df.spawn((err, ipfsd) => {
     if (err) {
       sender.send('error', err)
       throw err
     }
+
     console.log('get id')
     sender.send('message', 'get id')
-    ipfs.id(function (err, id) {
+    ipfsd.api.id((err, id) => {
       if (err) {
         sender.send('error', err)
         throw err
       }
       console.log('got id', id)
       sender.send('id', JSON.stringify(id))
+      ipfsd.stop()
     })
   })
 })