feat: cancellable api calls (#2993)

Passes a [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
to every API call which emits a `abort` event when the caller is no longer
interested in the result of the operation.

Lower level code that creates resources or has other long-term effects should tear
down those resources early if the `abort` event is received.

Adds support for `timeout` options to every API call that will emit an `abort` event
on the passed signal and throw a Timeout error.

Finally `abort` events are triggered if the current request arrived via the HTTP API
and the request was aborted from the client - that is, a `disconnect` event is fired by Hapi.

- Updates the core-api docs to add these new options.
- Refactors HTTP API to replace custom args parsing with Joi
- Tests all HTTP API endpoints
- Adds pin support to `ipfs.block.put`- fixes #3015

Author: achingbrain

docs/CONFIG.md

@@ -252,7 +252,7 @@ The "basic" connection manager tries to keep between `LowWater` and `HighWater`
 1. Keeping all connections until `HighWater` connections is reached.
 2. Once `HighWater` is reached, it closes connections until `LowWater` is reached.
 
-**Example:**
+### Example
 
 ```json
 {

docs/core-api/BITSWAP.md

@@ -1,21 +1,47 @@
-# Bitswap API
+# Bitswap API <!-- omit in toc -->
+
+- [`ipfs.bitswap.wantlist([peerId,] [options])`](#ipfsbitswapwantlistpeerid-options)
+  - [Parameters](#parameters)
+  - [Options](#options)
+  - [Returns](#returns)
+  - [Example](#example)
+- [`ipfs.bitswap.unwant(cids, [options])`](#ipfsbitswapunwantcids-options)
+  - [Parameters](#parameters-1)
+  - [Options](#options-1)
+  - [Returns](#returns-1)
+  - [Example](#example-1)
+- [`ipfs.bitswap.stat([options])`](#ipfsbitswapstatoptions)
+  - [Parameters](#parameters-2)
+  - [Options](#options-2)
+  - [Returns](#returns-2)
+  - [Example](#example-2)
+
+## `ipfs.bitswap.wantlist([peerId,] [options])`
 
-* [bitswap.wantlist](#bitswapwantlist)
-* [bitswap.stat](#bitswapstat)
+> Returns the wantlist, optionally filtered by peer ID
 
-### `bitswap.wantlist`
+### Parameters
 
-> Returns the wantlist, optionally filtered by peer ID
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| peerId | [PeerId][], [CID][], `String` or `Buffer` | An optional peer ID to return the wantlist for |
+
+### Options
+
+An optional object which may have the following keys:
 
-#### `ipfs.bitswap.wantlist([peerId])`
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| timeout | `Number` | `undefined` | A timeout in ms |
+| signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
 
-**Returns**
+### Returns
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<CID[]>` | An array of [CID][cid]s currently in the wantlist |
+| `Promise<CID[]>` | An array of [CID][]s currently in the wantlist |
 
-**Example:**
+### Example
 
 ```JavaScript
 const list = await ipfs.bitswap.wantlist()
@@ -29,15 +55,67 @@ console.log(list2)
 
 A great source of [examples][] can be found in the tests for this API.
 
-#### `bitswap.stat`
+## `ipfs.bitswap.unwant(cids, [options])`
 
-> Show diagnostic information on the bitswap agent.
+> Removes one or more CIDs from the wantlist
+
+### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| cids | A [CID][] or Array of [CID][]s | The CIDs to remove from the wantlist |
+
+### Options
+
+An optional object which may have the following keys:
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| timeout | `Number` | `undefined` | A timeout in ms |
+| signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
+
+### Returns
+
+| Type | Description |
+| -------- | -------- |
+| `Promise<void>` | A promise that resolves once the request is complete |
+
+### Example
+
+```JavaScript
+let list = await ipfs.bitswap.wantlist()
+console.log(list)
+// [ CID('QmHash') ]
+
+await ipfs.bitswap.unwant(cid)
+
+list = await ipfs.bitswap.wantlist()
+console.log(list)
+// []
+```
+
+A great source of [examples][] can be found in the tests for this API.
+
+## `ipfs.bitswap.stat([options])`
 
-##### `ipfs.bitswap.stat()`
+> Show diagnostic information on the bitswap agent.
 
 Note: `bitswap.stat` and `stats.bitswap` can be used interchangeably.
 
-**Returns**
+### Parameters
+
+None
+
+### Options
+
+An optional object which may have the following keys:
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| timeout | `Number` | `undefined` | A timeout in ms |
+| signal | [AbortSignal][] | `undefined` |  Can be used to cancel any long running requests started as a result of this call |
+
+### Returns
 
 | Type | Description |
 | -------- | -------- |
@@ -55,7 +133,7 @@ The returned object contains the following keys:
 - `dupBlksReceived` is a [BigNumber Int][1]
 - `dupDataReceived` is a [BigNumber Int][1]
 
-**Example:**
+### Example
 
 ```JavaScript
 const stats = await ipfs.bitswap.stat()
@@ -81,3 +159,5 @@ A great source of [examples][] can be found in the tests for this API.
 [1]: https://github.com/MikeMcl/bignumber.js/
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/bitswap
 [cid]: https://www.npmjs.com/package/cids
+[peerid]: https://www.npmjs.com/package/peer-id
+[AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal

docs/core-api/BLOCK.md

@@ -1,29 +1,52 @@
-# Block API
+# Block API <!-- omit in toc -->
+
+- [`ipfs.block.get(cid, [options])`](#ipfsblockgetcid-options)
+  - [Parameters](#parameters)
+  - [Options](#options)
+  - [Returns](#returns)
+  - [Example](#example)
+- [`ipfs.block.put(block, [options])`](#ipfsblockputblock-options)
+  - [Parameters](#parameters-1)
+  - [Options](#options-1)
+  - [Returns](#returns-1)
+  - [Example](#example-1)
+- [`ipfs.block.rm(cid, [options])`](#ipfsblockrmcid-options)
+  - [Parameters](#parameters-2)
+  - [Options](#options-2)
+  - [Returns](#returns-2)
+  - [Example](#example-2)
+- [`ipfs.block.stat(cid, [options])`](#ipfsblockstatcid-options)
+  - [Parameters](#parameters-3)
+  - [Options](#options-3)
+  - [Returns](#returns-3)
+  - [Example](#example-3)
+
+## `ipfs.block.get(cid, [options])`
 
-* [block.get](#blockget)
-* [block.put](#blockput)
-* [block.rm](#blockrm)
-* [block.stat](#blockstat)
+> Get a raw IPFS block.
 
-#### `block.get`
+### Parameters
 
-> Get a raw IPFS block.
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| cid | [CID][], `String` or `Buffer` | A CID that corresponds to the desired block |
 
-##### `ipfs.block.get(cid, [options])`
+### Options
 
-`cid` is a [cid][cid] which can be passed as:
+An optional object which may have the following keys:
 
-- Buffer, the raw Buffer of the cid
-- CID, a CID instance
-- String, the base58 encoded version of the multihash
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| timeout | `Number` | `undefined` | A timeout in ms |
+| signal | [AbortSignal][] | `undefined` |  Can be used to cancel any long running requests started as a result of this call |
 
-**Returns**
+### Returns
 
 | Type | Description |
 | -------- | -------- |
 | `Promise<Block>` | A [Block][block] type object, containing both the data and the hash of the block |
 
-**Example:**
+### Example
 
 ```JavaScript
 const block = await ipfs.block.get(cid)
@@ -32,43 +55,44 @@ console.log(block.data)
 
 A great source of [examples][] can be found in the tests for this API.
 
-#### `block.put`
+## `ipfs.block.put(block, [options])`
 
 > Stores input as an IPFS block.
 
-##### `ipfs.block.put(block, [options])`
-
-Where `block` can be:
+### Parameters
 
-- `Buffer` - the raw bytes of the Block
-- [`Block`][block] instance
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| block | A `Buffer` or [Block][] instance | The block or data to store |
 
-and `options` is an Object that can contain the following properties:
+### Options
 
-- `cid` - a [cid][cid] which can be passed as:
-  - Buffer, the raw Buffer of the cid
-  - CID, a CID instance
-  - String, the base58 encoded version of the multihash
-- format
-- mhtype
-- mhlen
-- version
+An optional object which may have the following keys:
 
-if no options are passed, it defaults to `{ format: 'dag-pb', mhtype: 'sha2-256', version: 0 }`
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| cid  | [CID][] | `undefined` | A CID to store the block under |
+| format | `String` | `'dag-pb'` | The codec to use to create the CID |
+| mhtype | `String` | `sha2-256` | The hashing algorithm to use to create the CID |
+| mhlen | `Number` | | |
+| version | `Number` | 0 |  The version to use to create the CID |
+| pin | `boolean` | false |  If true, pin added blocks recursively |
+| timeout | `Number` | `undefined` | A timeout in ms |
+| signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
 
 **Note:** If you pass a [`Block`][block] instance as the block parameter, you don't need to pass options, as the block instance will carry the CID value as a property.
 
-**Returns**
+### Returns
 
 | Type | Description |
 | -------- | -------- |
 | `Promise<Block>` | A [Block][block] type object, containing both the data and the hash of the block |
 
-**Example:**
+### Example
 
 ```JavaScript
 // Defaults
-const buf = new Buffer('a serialized object')
+const buf = Buffer.from('a serialized object')
 
 const block = await ipfs.block.put(buf)
 
@@ -81,7 +105,7 @@ console.log(block.cid.toString())
 
 // With custom format and hashtype through CID
 const CID = require('cids')
-const buf = new Buffer('another serialized object')
+const buf = Buffer.from('another serialized object')
 const cid = new CID(1, 'dag-pb', multihash)
 
 const block = await ipfs.block.put(blob, cid)
@@ -96,25 +120,28 @@ console.log(block.cid.toString())
 
 A great source of [examples][] can be found in the tests for this API.
 
-#### `block.rm`
+## `ipfs.block.rm(cid, [options])`
 
 > Remove one or more IPFS block(s).
 
-##### `ipfs.block.rm(cid, [options])`
+### Parameters
 
-`cid` is a [cid][cid] which can be passed as:
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| cid | A [CID][] or Array of [CID][]s | Blocks corresponding to the passed CID(s) will be removed |
 
-- Buffer, the raw Buffer of the cid
-- CID, a CID instance
-- String, the base58 encoded version of the multihash
-- Array, list of CIDs in any of the above three formats
+### Options
 
-`options` is an Object that can contain the following properties:
+An optional object which may have the following keys:
 
-- `force` (boolean): Ignores nonexistent blocks.
-- `quiet` (boolean): write minimal output
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| force | `boolean` | `false` | Ignores nonexistent blocks |
+| quiet | `boolean` | `false | Write minimal output |
+| timeout | `Number` | `undefined` | A timeout in ms |
+| signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
 
-**Returns**
+### Returns
 
 | Type | Description |
 | -------- | -------- |
@@ -131,7 +158,7 @@ Each object yielded is of the form:
 
 Note: If an error string is present for a given object, the block with that hash was not removed and the string will contain the reason why, for example if the block was pinned.
 
-**Example:**
+### Example
 
 ```JavaScript
 for await (const result of ipfs.block.rm(cid)) {
@@ -141,19 +168,26 @@ for await (const result of ipfs.block.rm(cid)) {
 
 A great source of [examples][] can be found in the tests for this API.
 
-#### `block.stat`
+## `ipfs.block.stat(cid, [options])`
 
 > Print information of a raw IPFS block.
 
-##### `ipfs.block.stat(cid)`
+### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| cid | A [CID][] or Array of [CID][]s | The stats of the passed CID will be returned |
+
+### Options
 
-`cid` is a [cid][cid] which can be passed as:
+An optional object which may have the following keys:
 
-- `Buffer`, the raw Buffer of the multihash (or of and encoded version)
-- `String`, the toString version of the multihash (or of an encoded version)
-- CID, a CID instance
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| timeout | `Number` | `undefined` | A timeout in ms |
+| signal | [AbortSignal][] | `undefined` | Can be used to cancel any long running requests started as a result of this call |
 
-**Returns**
+### Returns
 
 | Type | Description |
 | -------- | -------- |
@@ -168,7 +202,7 @@ the returned object has the following keys:
 }
 ```
 
-**Example:**
+### Example
 
 ```JavaScript
 const multihashStr = 'QmQULBtTjNcMwMr4VMNknnVv3RpytrLSdgpvMcTnfNhrBJ'
@@ -188,4 +222,5 @@ A great source of [examples][] can be found in the tests for this API.
 [block]: https://github.com/ipfs/js-ipfs-block
 [multihash]: https://github.com/multiformats/multihash
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/block
+[AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
 [cid]: https://www.npmjs.com/package/cids