From dbe6b371bc42febe5f83db8db88c1de51cf16dd4 Mon Sep 17 00:00:00 2001 From: David Dias Date: Tue, 9 Jan 2018 17:00:51 +0000 Subject: [PATCH] docs: review the readme (#181) * docs: review the readme * Update README.md * doc: updated `init()` docs --- README.md | 181 ++++++++++++++++++++++++------------------------------ 1 file changed, 79 insertions(+), 102 deletions(-) diff --git a/README.md b/README.md index b53605cd..cefa9c2f 100644 --- a/README.md +++ b/README.md @@ -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. ``` +-----+ @@ -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 @@ -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 @@ -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) }) @@ -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