feat: refs endpoint (#978)

BREAKING CHANGE: ipfs.refs now returns objects with camelCase properties not PascalCase properties. i.e. `{ ref, err }` not `{ Ref, Err }`

README.md

@@ -220,6 +220,14 @@ const ipfs = ipfsClient({
   - [`ipfs.block.put(block, [options], [callback])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/BLOCK.md#blockput)
   - [`ipfs.block.stat(cid, [callback])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/BLOCK.md#blockstat)
 
+- [refs](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/REFS.md)
+  - [`ipfs.refs(ipfsPath, [options], [callback])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/REFS.md#refs)
+  - [`ipfs.refsReadableStream(ipfsPath, [options], [callback])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/REFS.md#refsreadablestream)
+  - [`ipfs.refsPullStream(ipfsPath, [options], [callback])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/REFS.md#refspullstream)
+  - [`ipfs.refs.local([callback])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/REFS.md#refslocal)
+  - [`ipfs.refs.localReadableStream([callback])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/REFS.md#refslocalreadablestream)
+  - [`ipfs.refs.localPullStream([callback])`](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/REFS.md#refslocalpullstream)
+
 #### Graph
 
 - [dag](https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/DAG.md)

src/files-regular/index.js

@@ -20,6 +20,9 @@ module.exports = (arg) => {
     getPullStream: require('../files-regular/get-pull-stream')(send),
     ls: require('../files-regular/ls')(send),
     lsReadableStream: require('../files-regular/ls-readable-stream')(send),
-    lsPullStream: require('../files-regular/ls-pull-stream')(send)
+    lsPullStream: require('../files-regular/ls-pull-stream')(send),
+    refs: require('../files-regular/refs')(send),
+    refsReadableStream: require('../files-regular/refs-readable-stream')(send),
+    refsPullStream: require('../files-regular/refs-pull-stream')(send)
   }
 }

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

@@ -0,0 +1,27 @@
+'use strict'
+
+const pull = require('pull-stream')
+const toPull = require('stream-to-pull-stream')
+const deferred = require('pull-defer')
+const moduleConfig = require('../utils/module-config')
+
+module.exports = (send) => {
+  send = moduleConfig(send)
+
+  return (opts) => {
+    opts = opts || {}
+
+    const p = deferred.source()
+
+    send({ path: 'refs/local', qs: opts }, (err, stream) => {
+      if (err) { return p.resolve(pull.error(err)) }
+
+      p.resolve(pull(
+        toPull.source(stream),
+        pull.map(r => ({ ref: r.Ref, err: r.Err }))
+      ))
+    })
+
+    return p
+  }
+}

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

@@ -0,0 +1,23 @@
+'use strict'
+
+const Stream = require('readable-stream')
+const pump = require('pump')
+const through = require('through2')
+
+module.exports = (send) => {
+  return (opts) => {
+    opts = opts || {}
+
+    const pt = new Stream.PassThrough({ objectMode: true })
+
+    send({ path: 'refs/local', qs: opts }, (err, stream) => {
+      if (err) { return pt.destroy(err) }
+
+      pump(stream, through.obj(function (r, enc, cb) {
+        cb(null, { ref: r.Ref, err: r.Err })
+      }), pt)
+    })
+
+    return pt
+  }
+}

src/files-regular/refs-local.js

@@ -0,0 +1,32 @@
+'use strict'
+
+const promisify = require('promisify-es6')
+const streamToValueWithTransformer = require('../utils/stream-to-value-with-transformer')
+const moduleConfig = require('../utils/module-config')
+
+module.exports = (arg) => {
+  const send = moduleConfig(arg)
+
+  return promisify((opts, callback) => {
+    if (typeof (opts) === 'function') {
+      callback = opts
+      opts = {}
+    }
+
+    const transform = (res, cb) => {
+      cb(null, res.map(r => ({ ref: r.Ref, err: r.Err })))
+    }
+
+    const request = {
+      path: 'refs/local',
+      qs: opts
+    }
+    send(request, (err, result) => {
+      if (err) {
+        return callback(err)
+      }
+
+      streamToValueWithTransformer(result, transform, callback)
+    })
+  })
+}

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

@@ -0,0 +1,34 @@
+'use strict'
+
+const pull = require('pull-stream')
+const toPull = require('stream-to-pull-stream')
+const deferred = require('pull-defer')
+const moduleConfig = require('../utils/module-config')
+const { checkArgs, normalizeOpts } = require('./refs')
+
+module.exports = (send) => {
+  send = moduleConfig(send)
+
+  return (args, opts) => {
+    opts = normalizeOpts(opts)
+
+    const p = deferred.source()
+
+    try {
+      args = checkArgs(args)
+    } catch (err) {
+      return p.end(err)
+    }
+
+    send({ path: 'refs', args, qs: opts }, (err, stream) => {
+      if (err) { return p.resolve(pull.error(err)) }
+
+      p.resolve(pull(
+        toPull.source(stream),
+        pull.map(r => ({ ref: r.Ref, err: r.Err }))
+      ))
+    })
+
+    return p
+  }
+}

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

@@ -0,0 +1,30 @@
+'use strict'
+
+const Stream = require('readable-stream')
+const pump = require('pump')
+const through = require('through2')
+const { checkArgs, normalizeOpts } = require('./refs')
+
+module.exports = (send) => {
+  return (args, opts) => {
+    opts = normalizeOpts(opts)
+
+    const pt = new Stream.PassThrough({ objectMode: true })
+
+    try {
+      args = checkArgs(args)
+    } catch (err) {
+      return pt.destroy(err)
+    }
+
+    send({ path: 'refs', args, qs: opts }, (err, stream) => {
+      if (err) { return pt.destroy(err) }
+
+      pump(stream, through.obj(function (r, enc, cb) {
+        cb(null, { ref: r.Ref, err: r.Err })
+      }), pt)
+    })
+
+    return pt
+  }
+}

src/files-regular/refs.js

@@ -0,0 +1,75 @@
+'use strict'
+
+const IsIpfs = require('is-ipfs')
+const promisify = require('promisify-es6')
+const streamToValueWithTransformer = require('../utils/stream-to-value-with-transformer')
+const moduleConfig = require('../utils/module-config')
+const cleanCID = require('../utils/clean-cid')
+
+module.exports = (arg) => {
+  const send = moduleConfig(arg)
+
+  const refs = promisify((args, opts, callback) => {
+    if (typeof (opts) === 'function') {
+      callback = opts
+      opts = {}
+    }
+    opts = module.exports.normalizeOpts(opts)
+
+    try {
+      args = module.exports.checkArgs(args)
+    } catch (err) {
+      return callback(err)
+    }
+
+    const transform = (res, cb) => {
+      cb(null, res.map(r => ({ ref: r.Ref, err: r.Err })))
+    }
+
+    const request = {
+      args,
+      path: 'refs',
+      qs: opts
+    }
+    send(request, (err, result) => {
+      if (err) {
+        return callback(err)
+      }
+
+      streamToValueWithTransformer(result, transform, callback)
+    })
+  })
+
+  refs.local = require('./refs-local')(arg)
+  refs.localReadableStream = require('./refs-local-readable-stream')(arg)
+  refs.localPullStream = require('./refs-local-pull-stream')(arg)
+
+  return refs
+}
+
+module.exports.checkArgs = (args) => {
+  const isArray = Array.isArray(args)
+  args = isArray ? args : [args]
+
+  const res = []
+  for (let arg of args) {
+    try {
+      arg = cleanCID(arg)
+    } catch (err) {
+      if (!IsIpfs.ipfsPath(arg)) {
+        throw err
+      }
+    }
+    res.push(arg)
+  }
+
+  return isArray ? res : res[0]
+}
+
+module.exports.normalizeOpts = (opts) => {
+  opts = opts || {}
+  if (typeof opts.maxDepth === 'number') {
+    opts['max-depth'] = opts.maxDepth
+  }
+  return opts
+}

src/utils/load-commands.js

@@ -18,6 +18,9 @@ function requireCommands () {
     ls: require('../files-regular/ls'),
     lsReadableStream: require('../files-regular/ls-readable-stream'),
     lsPullStream: require('../files-regular/ls-pull-stream'),
+    refs: require('../files-regular/refs'),
+    refsReadableStream: require('../files-regular/refs-readable-stream'),
+    refsPullStream: require('../files-regular/refs-pull-stream'),
 
     // Files MFS (Mutable Filesystem)
     files: require('../files-mfs'),
@@ -50,7 +53,6 @@ function requireCommands () {
     key: require('../key'),
     log: require('../log'),
     mount: require('../mount'),
-    refs: require('../refs'),
     repo: require('../repo'),
     stop: require('../stop'),
     shutdown: require('../stop'),