test: add tests for refs endpoint (#460)

* feat: refs endpoint

* test: add tests for refs local

* test: add tests for refs local pull / streamable

* test: use expect.includes()

* fix: async.map -> map

* fix: ref -> Ref

* chore: add tests for multiple refs, CBOR

* chore: add REFS spec

* test: add test for Object.links with CBOR

Author: dirkmc

SPEC/REFS.md

@@ -0,0 +1,181 @@
+# Refs API
+
+* [refs](#refs)
+* [refsReadableStream](#refsreadablestream)
+* [refsPullStream](#refspullstream)
+* [refs.local](#refslocal)
+* [refs.localReadableStream](#refslocalreadablestream)
+* [refs.localPullStream](#refslocalpullstream)
+
+#### `refs`
+
+> Get links (references) from an object.
+
+##### `ipfs.refs(ipfsPath, [options], [callback])`
+
+`ipfsPath` can be of type:
+
+- [`cid`][cid] of type:
+  - a [CID](https://github.com/ipfs/js-cid) instance
+  - [Buffer][b], the raw Buffer of the cid
+  - String, the base58 encoded version of the cid
+- String, including the ipfs handler, a cid and a path to traverse to, ie:
+  - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66'
+  - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
+  - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
+
+`options` is an optional object that may contain the following keys:
+  - `recursive (false)`: recursively list references of child nodes
+  - `unique (false)`: omit duplicate references from output
+  - `format ("<dst>")`: output edges with given format. Available tokens: `<src>`, `<dst>`, `<linkname>`
+  - `edges (false)`: output references in edge format: `"<src> -> <dst>"`
+  - `maxDepth (1)`: only for recursive refs, limits fetch and listing to the given depth
+
+`callback` must follow `function (err, refs) {}` signature, where `err` is an error if the operation was not successful and `refs` is an array of `{ ref: "myref", err: "error msg" }`
+
+If no `callback` is passed, a promise is returned.
+
+**Example:**
+
+```JavaScript
+ipfs.refs(ipfsPath, { recursive: true }, function (err, refs) {
+  if (err) {
+    throw err
+  }
+
+  for (const ref of refs) {
+    if (ref.err) {
+      console.error(ref.err)
+    } else {
+      console.log(ref.ref)
+      // output: "QmHash"
+    }
+  }
+})
+```
+
+#### `refsReadableStream`
+
+> Output references using a [Readable Stream][rs]
+
+##### `ipfs.refsReadableStream(ipfsPath, [options])` -> [Readable Stream][rs]
+
+`options` is an optional object argument identical to the options for [ipfs.refs](#refs)
+
+**Example:**
+
+```JavaScript
+const stream = ipfs.refsReadableStream(ipfsPath, { recursive: true })
+stream.on('data', function (ref) {
+  // 'ref' will be of the form
+  // {
+  //   ref: 'QmHash',
+  //   err: 'err message'
+  // }
+})
+```
+
+#### `refsPullStream`
+
+> Output references using a [Pull Stream][ps].
+
+##### `ipfs.refsReadableStream(ipfsPath, [options])` -> [Pull Stream][ps]
+
+`options` is an optional object argument identical to the options for [ipfs.refs](#refs)
+
+**Example:**
+
+```JavaScript
+const stream = ipfs.refsPullStream(ipfsPath, { recursive: true })
+
+pull(
+  stream,
+  pull.collect((err, values) => {
+    // values will be an array of objects, each one of the form
+    // {
+    //   ref: 'QmHash',
+    //   err: 'err message'
+    // }
+  })
+)
+```
+
+#### `refs.local`
+
+> Output all local references (CIDs of all blocks in the blockstore)
+
+##### `ipfs.refs.local([callback])`
+
+`callback` must follow `function (err, refs) {}` signature, where `err` is an error if the operation was not successful and `refs` is an array of `{ ref: "myref", err: "error msg" }`
+
+If no `callback` is passed, a promise is returned.
+
+**Example:**
+
+```JavaScript
+ipfs.refs.local(function (err, refs) {
+  if (err) {
+    throw err
+  }
+
+  for (const ref of refs) {
+    if (ref.err) {
+      console.error(ref.err)
+    } else {
+      console.log(ref.ref)
+      // output: "QmHash"
+    }
+  }
+})
+```
+
+#### `refs.localReadableStream`
+
+> Output all local references using a [Readable Stream][rs]
+
+##### `ipfs.localReadableStream()` -> [Readable Stream][rs]
+
+**Example:**
+
+```JavaScript
+const stream = ipfs.refs.localReadableStream()
+stream.on('data', function (ref) {
+  // 'ref' will be of the form
+  // {
+  //   ref: 'QmHash',
+  //   err: 'err message'
+  // }
+})
+```
+
+#### `refs.localPullStream`
+
+> Output all local references using a [Pull Stream][ps].
+
+##### `ipfs.refs.localReadableStream()` -> [Pull Stream][ps]
+
+**Example:**
+
+```JavaScript
+const stream = ipfs.refs.localPullStream()
+
+pull(
+  stream,
+  pull.collect((err, values) => {
+    // values will be an array of objects, each one of the form
+    // {
+    //   ref: 'QmHash',
+    //   err: 'err message'
+    // }
+  })
+)
+```
+
+A great source of [examples][] can be found in the tests for this API.
+
+[examples]: https://github.com/ipfs/interface-ipfs-core/blob/master/src/files-regular
+[b]: https://www.npmjs.com/package/buffer
+[rs]: https://www.npmjs.com/package/readable-stream
+[ps]: https://www.npmjs.com/package/pull-stream
+[cid]: https://www.npmjs.com/package/cids
+[blob]: https://developer.mozilla.org/en-US/docs/Web/API/Blob

src/files-regular/index.js

@@ -17,7 +17,13 @@ const tests = {
   getPullStream: require('./get-pull-stream'),
   ls: require('./ls'),
   lsReadableStream: require('./ls-readable-stream'),
-  lsPullStream: require('./ls-pull-stream')
+  lsPullStream: require('./ls-pull-stream'),
+  refs: require('./refs'),
+  refsReadableStream: require('./refs-readable-stream'),
+  refsPullStream: require('./refs-pull-stream'),
+  refsLocal: require('./refs-local'),
+  refsLocalPullStream: require('./refs-local-pull-stream'),
+  refsLocalReadableStream: require('./refs-local-readable-stream')
 }
 
 module.exports = createSuite(tests)

src/files-regular/refs-local-pull-stream.js

@@ -0,0 +1,14 @@
+/* eslint-env mocha */
+'use strict'
+
+const pull = require('pull-stream')
+
+module.exports = (createCommon, options) => {
+  const ipfsRefsLocal = (ipfs) => {
+    return (cb) => {
+      const stream = ipfs.refs.localPullStream()
+      pull(stream, pull.collect(cb))
+    }
+  }
+  require('./refs-local-tests')(createCommon, '.refs.localPullStream', ipfsRefsLocal, options)
+}

src/files-regular/refs-local-readable-stream.js

@@ -0,0 +1,15 @@
+/* eslint-env mocha */
+'use strict'
+
+const concat = require('concat-stream')
+
+module.exports = (createCommon, options) => {
+  const ipfsRefsLocal = (ipfs) => {
+    return (cb) => {
+      const stream = ipfs.refs.localReadableStream()
+      stream.on('error', cb)
+      stream.pipe(concat((refs) => cb(null, refs)))
+    }
+  }
+  require('./refs-local-tests')(createCommon, '.refs.localReadableStream', ipfsRefsLocal, options)
+}

src/files-regular/refs-local-tests.js

@@ -0,0 +1,60 @@
+/* eslint-env mocha */
+'use strict'
+
+const { fixtures } = require('./utils')
+const { getDescribe, getIt, expect } = require('../utils/mocha')
+
+module.exports = (createCommon, suiteName, ipfsRefsLocal, options) => {
+  const describe = getDescribe(options)
+  const it = getIt(options)
+  const common = createCommon()
+
+  describe(suiteName, function () {
+    this.timeout(40 * 1000)
+
+    let ipfs
+
+    before(function (done) {
+      // CI takes longer to instantiate the daemon, so we need to increase the
+      // timeout for the before step
+      this.timeout(60 * 1000)
+
+      common.setup((err, factory) => {
+        expect(err).to.not.exist()
+        factory.spawnNode((err, node) => {
+          expect(err).to.not.exist()
+          ipfs = node
+          done()
+        })
+      })
+    })
+
+    after((done) => common.teardown(done))
+
+    it('should get local refs', function (done) {
+      const content = (name) => ({
+        path: `test-folder/${name}`,
+        content: fixtures.directory.files[name]
+      })
+
+      const dirs = [
+        content('pp.txt'),
+        content('holmes.txt')
+      ]
+
+      ipfs.add(dirs, (err, res) => {
+        expect(err).to.not.exist()
+
+        ipfsRefsLocal(ipfs)((err, refs) => {
+          expect(err).to.not.exist()
+
+          const cids = refs.map(r => r.ref)
+          expect(cids).to.include('QmVwdDCY4SPGVFnNCiZnX5CtzwWDn6kAM98JXzKxE3kCmn')
+          expect(cids).to.include('QmR4nFjTu18TyANgC65ArNWp5Yaab1gPzQ4D8zp7Kx3vhr')
+
+          done()
+        })
+      })
+    })
+  })
+}

src/files-regular/refs-local.js

@@ -0,0 +1,7 @@
+/* eslint-env mocha */
+'use strict'
+
+module.exports = (createCommon, options) => {
+  const ipfsRefsLocal = (ipfs) => (cb) => ipfs.refs.local(cb)
+  require('./refs-local-tests')(createCommon, '.refs.local', ipfsRefsLocal, options)
+}

src/files-regular/refs-pull-stream.js

@@ -0,0 +1,14 @@
+/* eslint-env mocha */
+'use strict'
+
+const pull = require('pull-stream')
+
+module.exports = (createCommon, options) => {
+  const ipfsRefs = (ipfs) => {
+    return (path, params, cb) => {
+      const stream = ipfs.refsPullStream(path, params)
+      pull(stream, pull.collect(cb))
+    }
+  }
+  require('./refs-tests')(createCommon, '.refsPullStream', ipfsRefs, options)
+}

src/files-regular/refs-readable-stream.js

@@ -0,0 +1,15 @@
+/* eslint-env mocha */
+'use strict'
+
+const concat = require('concat-stream')
+
+module.exports = (createCommon, options) => {
+  const ipfsRefs = (ipfs) => {
+    return (path, params, cb) => {
+      const stream = ipfs.refsReadableStream(path, params)
+      stream.on('error', cb)
+      stream.pipe(concat((refs) => cb(null, refs)))
+    }
+  }
+  require('./refs-tests')(createCommon, '.refsReadableStream', ipfsRefs, options)
+}