feat: add block API

Author: Alan Shaw

API.md

@@ -7,7 +7,9 @@
 * [addFromURL](#addfromurl) TODO: add docs
 * [bitswap.stat](#bitswapstat) TODO: add docs
 * [bitswap.wantlist](#bitswapwantlist) TODO: add docs
-* [block.get](#blockget) TODO: add docs
+* [block.get](#blockget)
+* [block.put](#blockput)
+* [block.stat](#blockstat)
 * [cat](#cat)
 * [catPullStream](#catpullstream) TODO: add docs
 * [ls](#ls) TODO: add docs
@@ -316,6 +318,129 @@ pull(
 */
 ```
 
+## block.get
+
+Fetch a raw block from the IPFS block store or the network via bitswap if not local.
+
+### `block.get(cid, [options]): Promise<Buffer>`
+
+#### Parameters
+
+* `cid` - CID of the block to fetch
+    * Type: `String`
+* `options` (optional)
+    * Type: `Object`
+    * Default: `null`
+* `options.signal` (optional) - A signal that can be used to abort the request
+    * Type: [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+    * Default: `null`
+
+#### Returns
+
+A buffer containing the raw bytes of the block.
+
+* Type: `Promise<Buffer>`
+
+#### Example
+
+```js
+const data = await ipfs.block.get('zdpuAtpzCB7ma5zNyCN7eh1Vss1dHWuScf91DbE1ix9ZTbjAk')
+console.log(data) // buffer containing block data
+```
+
+## block.put
+
+Put a block into the IPFS block store.
+
+### `block.put(data, [options]): Promise<Object>`
+
+#### Parameters
+
+* `data` - Raw data for this block
+    * Type: `Buffer`/`Blob`/`File`
+* `options` (optional)
+    * Type: `Object`
+    * Default: `null`
+* `options.format` (optional) - Name of the IPLD format this block is encoded with
+    * Type: `String`
+    * Default: `dag-pb`
+* `options.mhtype` (optional) - Name of the multihash hashing algorithm to use
+    * Type: `String`
+    * Default: `sha2-256`
+* `options.mhlen` (optional) - Length of the hash in bits
+    * Type: `Number`
+    * Default: `256`
+* `options.pin` (optional) - Pin this block so it is not garbage collected
+    * Type: `Boolean`
+    * Default: `false`
+* `options.signal` (optional) - A signal that can be used to abort the request
+    * Type: [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+    * Default: `null`
+
+#### Returns
+
+CID and size for the block that was added.
+
+* Type: `Promise<Object>`
+
+The `Object` has the following properties:
+
+* `key` - The CID of the block
+    * Type: `String`
+* `size` - Size of the block in bytes
+    * Type: `Number`
+
+#### Examples
+
+```js
+const data = Buffer.from('blorb')
+const res = await ipfs.block.put(data)
+console.log(res)
+/*
+{ key: 'QmPv52ekjS75L4JmHpXVeuJ5uX2ecSfSZo88NSyxwA3rAQ', size: 5 }
+*/
+```
+
+## block.stat
+
+Get status for a block.
+
+### `block.stat(cid, [options]): Promise<Object>`
+
+#### Parameters
+
+* `cid` - CID of the block
+    * Type: `String`
+* `options` (optional)
+    * Type: `Object`
+    * Default: `null`
+* `options.signal` (optional) - A signal that can be used to abort the request
+    * Type: [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+    * Default: `null`
+
+#### Returns
+
+CID and size of the block.
+
+* Type: `Promise<Object>`
+
+The `Object` has the following properties:
+
+* `key` - The CID of the block
+    * Type: `String`
+* `size` - Size of the block in bytes
+    * Type: `Number`
+
+#### Examples
+
+```js
+const res = await ipfs.block.stat('zb2rhj7crUKTQYRGCRATFaQ6YFLTde2YzdqbbhAASkL9uRDXn')
+console.log(res)
+/*
+{ key: 'zb2rhj7crUKTQYRGCRATFaQ6YFLTde2YzdqbbhAASkL9uRDXn', size: 11 }
+*/
+```
+
 ## `cat`
 
 Read files from IPFS.
@@ -335,6 +460,9 @@ Read files from IPFS.
 * `options.length` (optional) - Number of bytes to read
     * Type: `Number`
     * Default: `null` (read to the end of the file)
+* `options.signal` (optional) - A signal that can be used to abort the request
+    * Type: [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+    * Default: `null`
 
 #### Returns
 

README.md

@@ -145,7 +145,9 @@ This module is in heavy development, not all API methods are available (or docum
 * [addFromURL](./API.md#addfromurl) TODO: add docs
 * [bitswap.stat](./API.md#bitswapstat) TODO: add docs
 * [bitswap.wantlist](./API.md#bitswapwantlist) TODO: add docs
-* [block.get](./API.md#blockget) TODO: add docs
+* [block.get](./API.md#blockget)
+* [block.put](./API.md#blockput)
+* [block.stat](./API.md#blockstat)
 * [cat](./API.md#cat)
 * [catPullStream](./API.md#catpullstream) TODO: add docs
 * [ls](./API.md#ls) TODO: add docs

package.json

@@ -28,6 +28,7 @@
   "dependencies": {
     "async-iterator-to-pull-stream": "^1.3.0",
     "buffer": "^5.2.1",
+    "cids": "^0.7.1",
     "explain-error": "^1.0.4",
     "form-data": "^2.4.0",
     "iterable-ndjson": "^1.1.0",
@@ -42,8 +43,10 @@
     "dirty-chai": "^2.0.1",
     "go-ipfs-dep": "~0.4.21",
     "interface-ipfs-core": "~0.105.1",
+    "ipfs-block": "^0.8.1",
     "ipfsd-ctl": "^0.43.0",
     "multiaddr-to-uri": "^4.0.1",
+    "multihashes": "^0.4.14",
     "pull-stream": "^3.6.12"
   },
   "engines": {

src/add-from-url.js

@@ -3,8 +3,8 @@
 const configure = require('./lib/configure')
 const { ok, toIterable } = require('./lib/fetch')
 
-module.exports = configure(({ fetch, apiUrl, apiPath, signal, headers }) => {
-  const add = require('./add')({ fetch, apiUrl, apiPath, signal, headers })
+module.exports = configure(({ fetch, apiUrl, apiPath, headers }) => {
+  const add = require('./add')({ fetch, apiUrl, apiPath, headers })
 
   return (url, options) => (async function * () {
     options = options || {}

src/add/index.js

@@ -7,7 +7,7 @@ const { ok, toIterable } = require('../lib/fetch')
 const { toFormData } = require('./form-data')
 const toCamel = require('../lib/to-camel')
 
-module.exports = configure(({ fetch, apiUrl, apiPath, signal, headers }) => {
+module.exports = configure(({ fetch, apiUrl, apiPath, headers }) => {
   return (input, options) => (async function * () {
     options = options || {}
 

src/bitswap/stat.js

@@ -4,7 +4,7 @@ const configure = require('../lib/configure')
 const { ok } = require('../lib/fetch')
 const toCamel = require('../lib/to-camel')
 
-module.exports = configure(({ fetch, apiUrl, apiPath, signal, headers }) => {
+module.exports = configure(({ fetch, apiUrl, apiPath, headers }) => {
   return async (options) => {
     options = options || {}
 

src/bitswap/wantlist.js

@@ -4,7 +4,7 @@ const QueryString = require('querystring')
 const configure = require('../lib/configure')
 const { ok } = require('../lib/fetch')
 
-module.exports = configure(({ fetch, apiUrl, apiPath, signal, headers }) => {
+module.exports = configure(({ fetch, apiUrl, apiPath, headers }) => {
   return async (peerId, options) => {
     if (!options && typeof peerId === 'object') {
       options = peerId

src/block/get.js

@@ -1,20 +1,18 @@
 'use strict'
 
-const QueryString = require('querystring')
 const { Buffer } = require('buffer')
 const configure = require('../lib/configure')
 const { ok } = require('../lib/fetch')
 
-module.exports = configure(({ fetch, apiUrl, apiPath, signal, headers }) => {
+module.exports = configure(({ fetch, apiUrl, apiPath, headers }) => {
   return async (cid, options) => {
     options = options || {}
 
-    const qs = { arg: cid }
-    const url = `${apiUrl}${apiPath}/block/get?${QueryString.stringify(qs)}`
+    const url = `${apiUrl}${apiPath}/block/get?arg=${encodeURIComponent(cid)}`
     const res = await ok(fetch(url, {
       signal: options.signal,
       headers: options.headers || headers
     }))
-    return Buffer.from(await res.blob())
+    return Buffer.from(await res.arrayBuffer())
   }
 })

src/block/put.js

@@ -0,0 +1,53 @@
+'use strict'
+
+const QueryString = require('querystring')
+const FormData = require('form-data')
+const configure = require('../lib/configure')
+const { ok } = require('../lib/fetch')
+const toCamel = require('../lib/to-camel')
+
+module.exports = configure(({ fetch, apiUrl, apiPath, headers }) => {
+  const put = async (data, options) => {
+    options = options || {}
+
+    const qs = Object.entries({
+      format: options.format,
+      mhtype: options.mhtype,
+      mhlen: options.mhlen,
+      pin: options.pin
+    }).reduce((obj, [key, value]) => {
+      if (value != null) obj[key] = value
+      return obj
+    }, {})
+
+    const url = `${apiUrl}${apiPath}/block/put?${QueryString.stringify(qs)}`
+
+    const body = new FormData()
+    body.append('file', data)
+
+    let res
+
+    try {
+      res = await ok(fetch(url, {
+        method: 'POST',
+        signal: options.signal,
+        headers: options.headers || headers,
+        body
+      }))
+    } catch (err) {
+      // Retry with "protobuf"/"cbor" format for go-ipfs
+      // TODO: remove when https://github.com/ipfs/go-cid/issues/75 resolved
+      if (options.format === 'dag-pb') {
+        return put(data, { ...options, format: 'protobuf' })
+      } else if (options.format === 'dag-cbor') {
+        return put(data, { ...options, format: 'cbor' })
+      }
+
+      throw err
+    }
+
+    return toCamel(await res.json())
+  }
+
+  return put
+})

src/block/stat.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const configure = require('../lib/configure')
+const { ok } = require('../lib/fetch')
+const toCamel = require('../lib/to-camel')
+
+module.exports = configure(({ fetch, apiUrl, apiPath, headers }) => {
+  return async (cid, options) => {
+    options = options || {}
+
+    const url = `${apiUrl}${apiPath}/block/stat?arg=${encodeURIComponent(cid)}`
+    const res = await ok(fetch(url, {
+      signal: options.signal,
+      headers: options.headers || headers
+    }))
+    return toCamel(await res.json())
+  }
+})