Adds new api endpoint api/retrieval-client/retrieve-piece

API.md

@@ -48,7 +48,7 @@
 * paych.redeem
 * paych.voucher
 * [ping](#ping)
-* retrievalClient.retrievePiece
+* [retrievalClient.retrievePiece](#retrievalclientretrievepiece)
 * [show.block](#showblock)
 * [stats.bandwidth](#statsbandwidth)
 * [swarm.connect](#swarmconnect)
@@ -847,6 +847,40 @@ After first iteration:
 */
 ```
 
+## `retrievalClient.retrievePiece`
+
+> Read out piece data stored by a miner on the network
+
+### `retrievalClient.retrievePiece(miner, cid, [options])`
+
+#### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| miner | `String` | Retrieval miner actor address |
+| cid | `CID`\|`String` | Content identifier of piece to read |
+| options | `Object` | Optional options |
+| options.signal | [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) | A signal that can be used to abort the request |
+
+#### Returns
+
+| Type | Description |
+|------|-------------|
+| `AsyncIterable<Buffer\|UInt8Array>` | Content of the file, yields `Buffer` objects in Node.js and `UInt8Array` objects in the browser |
+
+#### Example
+
+```js
+const pieceData = fc.retrievalClient.retrievePiece(
+  't2u2r6nyaxdspozci5t2i2xtfw23lxa35rvkul7di',
+  'QmSB6t4fVfE4fZ46EFBodtK89RJaCRTtPRaEYFx8EQxh8a'
+)
+
+let data = Buffer.alloc(0)
+for await (const chunk of pieceData)
+  data = Buffer.concat([data, chunk])
+```
+
 ## `show.block`
 
 > Show a filecoin block by its CID

README.md

@@ -97,7 +97,7 @@ $ filecoin config api.accessControlAllowOrigin '["http://example.com"]'
 * paych.redeem
 * paych.voucher
 * [ping](API.md#ping)
-* retrievalClient.retrievePiece
+* [retrievalClient.retrievePiece](API.md#retrievalclientretrievepiece)
 * [show.block](API.md#showblock)
 * [stats.bandwidth](API.md#statsbandwidth)
 * [swarm.connect](API.md#swarmconnect)

src/cmd/retrieval-client/retrieve-piece.js

@@ -0,0 +1,16 @@
+const toUri = require('../../lib/multiaddr-to-uri')
+const { ok, toIterable } = require('../../lib/fetch')
+
+module.exports = (fetch, config) => {
+  return (minerAddr, cid, options) => (async function * () {
+    options = options || {}
+
+    minerAddr = encodeURIComponent(minerAddr)
+    cid = encodeURIComponent(cid)
+
+    const url = `${toUri(config.apiAddr)}/api/retrieval-client/retrieve-piece?arg=${minerAddr}&arg=${cid}`
+    const res = await ok(fetch(url, { signal: options.signal }))
+
+    yield * toIterable(res.body)
+  })()
+}

src/index.js

@@ -52,6 +52,9 @@ module.exports = (fetch, config) => {
       stop: require('./cmd/mining/stop')(fetch, config)
     },
     ping: require('./cmd/ping')(fetch, config),
+    retrievalClient: {
+      retrievePiece: require('./cmd/retrieval-client/retrieve-piece')(fetch, config)
+    },
     show: {
       block: require('./cmd/show/block')(fetch, config)
     },

test/unit/cmd/retrieval-client/retrieve-piece.test.js

@@ -0,0 +1,19 @@
+const test = require('ava')
+const { randomBytes } = require('crypto')
+const Filecoin = require('../../../../src')
+const { toAsyncIterable } = require('../../../helpers/iterable')
+
+test('should read out piece data stored by a miner on the network', async t => {
+  const cid = 'QmZPUUg1QVMciR1yYnC2HSFrXyAUwRvpnbx4haYefB2KY3'
+  const miner = 'fcq5y65n23xdkcx2ymakflxpxqhkvewnwswp0me52'
+  const chunks = [randomBytes(2048), randomBytes(512), randomBytes(256)]
+  const fetch = () => ({ ok: true, body: toAsyncIterable(chunks) })
+  const fc = Filecoin(fetch)
+
+  const data = []
+  for await (const chunk of fc.retrievalClient.retrievePiece(miner, cid)) {
+    data.push(chunk)
+  }
+
+  t.deepEqual(Buffer.concat(data), Buffer.concat(chunks))
+})