feat: use stream on stats.bw

Author: hacdias

Diff for: SPEC/BITSWAP.md

@@ -17,15 +17,15 @@ Bitswap API
 
 `callback` must follow `function (err, stats) {}` signature, where `err` is an error if the operation was not successful. `stats` is an Object containing the following keys:
 
-- `provideBufLen`
+- `provideBufLen` is an integer.
 - `wantlist` (array)
 - `peers` (array)
-- `blocksReceived`
-- `dataReceived`
-- `blocksSent`
-- `dataSent`
-- `dupBlksReceived`
-- `dupDataReceived`
+- `blocksReceived` is a [Big Int][1]
+- `dataReceived` is a [Big Int][1]
+- `blocksSent` is a [Big Int][1]
+- `dataSent` is a [Big Int][1]
+- `dupBlksReceived` is a [Big Int][1]
+- `dupDataReceived` is a [Big Int][1]
 
 If no `callback` is passed, a promise is returned.
 
@@ -47,3 +47,5 @@ ipfs.stats.bitswap((err, stats) => console.log(stats))
 //   dupBlksReceived: 0,
 //  dupDataReceived: 0 }
 ```
+
+[1]: https://github.com/MikeMcl/big.js/

Diff for: SPEC/REPO.md

@@ -42,11 +42,11 @@ Where:
 
 `callback` must follow `function (err, stats) {}` signature, where `err` is an Error if the operation was not successful and `stats` is an object containing the following keys:
 
-- `numObjects`
-- `repoSize`
-- `repoPath`
-- `version`
-- `storageMax`
+- `numObjects` is a [Big Int][1].
+- `repoSize` is a [Big Int][1], in bytes.
+- `repoPath` is a string.
+- `version` is a string.
+- `storageMax` is a [Big Int][1].
 
 If no `callback` is passed, a promise is returned.
 
@@ -81,3 +81,5 @@ ipfs.repo.version((err, version) => console.log(version))
 
 // "6"
 ```
+
+[1]: https://github.com/MikeMcl/big.js/

Diff for: SPEC/STATS.md

@@ -11,7 +11,7 @@ Stats API
 
 #### `bw`
 
-> Adds an IPFS object to the pinset and also stores it to the IPFS repo. pinset is the set of hashes currently pinned (not gc'able).
+> Get IPFS bandwidth information as an object.
 
 ##### `Go` **WIP**
 
@@ -25,12 +25,14 @@ Where:
   - `poll` is used to print bandwidth at an interval.
   - `interval` is the time interval to wait between updating output, if `poll` is true.
 
-`callback` must follow `function (err, stats) {}` signature, where `err` is an error if the operation was not successful. `stats` is an Object containing the following keys:
+`callback` must follow `function (err, stat) {}` signature, where `err` is an Error if the operation was not successful.
 
-- `totalIn`
-- `totalOut`
-- `rateIn`
-- `rateOut`
+`stat` is, in both cases, an Object containing the following keys:
+
+- `totalIn` - is a [Big Int][big], in bytes.
+- `totalOut` - is a [Big Int][big], in bytes.
+- `rateIn` - is a [Big Int][big], in bytes.
+- `rateOut` - is a [Big Int][big], in bytes.
 
 If no `callback` is passed, a promise is returned.
 
@@ -39,8 +41,71 @@ If no `callback` is passed, a promise is returned.
 ```JavaScript
 ipfs.stats.bw((err, stats) => console.log(stats))
 
-// { totalIn: 15456,
-//   totalOut: 15420,
-//   rateIn: 905.0873512246716,
-//   rateOut: 893.7400053359125 }
+// { totalIn: Big {...},
+//   totalOut: Big {...},
+//   rateIn: Big {...},
+//   rateOut: Big {...} }
+```
+
+#### `bwPullStream`
+
+> Get IPFS bandwidth information as a [Pull Stream][ps].
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.stats.bwPullStream([options]) -> [Pull Stream][ps]
+
+Options are described on [`ipfs.stats.bw`](#bw).
+
+**Example:**
+
+```JavaScript
+const pull = require('pull-stream')
+const log = require('pull-stream/sinks/log')
+
+const stream = ipfs.stats.bwReadableStream({ poll: true })
+
+pull(
+  stream,
+  log()
+)
+
+// { totalIn: Big {...},
+//   totalOut: Big {...},
+//   rateIn: Big {...},
+//   rateOut: Big {...} }
+// ...
+// Ad infinitum
 ```
+
+#### `bwReadableStream`
+
+> Get IPFS bandwidth information as a [Readable Stream][rs].
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.stats.bwReadableStream([options]) -> [Readable Stream][rs]
+
+Options are described on [`ipfs.stats.bw`](#bw).
+
+**Examples:**
+
+```JavaScript
+const stream = ipfs.stats.bwReadableStream({ poll: true })
+const bl = require('bl')
+
+stream.pipe(bl((err, data) => {
+  console.log(data)
+}))
+
+// { totalIn: Big {...},
+//   totalOut: Big {...},
+//   rateIn: Big {...},
+//   rateOut: Big {...} }
+// ...
+// Ad infinitum
+```
+
+[big]: https://github.com/MikeMcl/big.js/
+[rs]: https://www.npmjs.com/package/readable-stream
+[ps]: https://www.npmjs.com/package/pull-stream

Diff for: js/src/repo.js

@@ -5,6 +5,7 @@
 
 const chai = require('chai')
 const dirtyChai = require('dirty-chai')
+const statsTests = require('./utils/stats')
 const expect = chai.expect
 chai.use(dirtyChai)
 
@@ -46,26 +47,15 @@ module.exports = (common) => {
     })
 
     it('.stat', (done) => {
-      ipfs.repo.stat((err, stat) => {
-        expect(err).to.not.exist()
-        expect(stat).to.exist()
-        expect(stat).to.have.property('numObjects')
-        expect(stat).to.have.property('repoSize')
-        expect(stat).to.have.property('repoPath')
-        expect(stat).to.have.property('version')
-        expect(stat).to.have.property('storageMax')
+      ipfs.repo.stat((err, res) => {
+        statsTests.expectIsRepo(err, res)
         done()
       })
     })
 
     it('.stat Promise', () => {
-      return ipfs.repo.stat().then((stat) => {
-        expect(stat).to.exist()
-        expect(stat).to.have.property('numObjects')
-        expect(stat).to.have.property('repoSize')
-        expect(stat).to.have.property('repoPath')
-        expect(stat).to.have.property('version')
-        expect(stat).to.have.property('storageMax')
+      return ipfs.repo.stat().then((res) => {
+        statsTests.expectIsRepo(null, res)
       })
     })
 

Diff for: js/src/stats.js

@@ -5,6 +5,7 @@
 
 const chai = require('chai')
 const dirtyChai = require('dirty-chai')
+const statsTests = require('./utils/stats')
 const expect = chai.expect
 chai.use(dirtyChai)
 
@@ -43,17 +44,7 @@ module.exports = (common) => {
       }
 
       ipfs.stats.bitswap((err, res) => {
-        expect(err).to.not.exist()
-        expect(res).to.exist()
-        expect(res).to.have.a.property('provideBufLen')
-        expect(res).to.have.a.property('wantlist')
-        expect(res).to.have.a.property('peers')
-        expect(res).to.have.a.property('blocksReceived')
-        expect(res).to.have.a.property('dataReceived')
-        expect(res).to.have.a.property('blocksSent')
-        expect(res).to.have.a.property('dataSent')
-        expect(res).to.have.a.property('dupBlksReceived')
-        expect(res).to.have.a.property('dupDataReceived')
+        statsTests.expectIsBitswap(err, res)
         done()
       })
     })
@@ -65,16 +56,7 @@ module.exports = (common) => {
       }
 
       return ipfs.stats.bitswap().then((res) => {
-        expect(res).to.exist()
-        expect(res).to.have.a.property('provideBufLen')
-        expect(res).to.have.a.property('wantlist')
-        expect(res).to.have.a.property('peers')
-        expect(res).to.have.a.property('blocksReceived')
-        expect(res).to.have.a.property('dataReceived')
-        expect(res).to.have.a.property('blocksSent')
-        expect(res).to.have.a.property('dataSent')
-        expect(res).to.have.a.property('dupBlksReceived')
-        expect(res).to.have.a.property('dupDataReceived')
+        statsTests.expectIsBitswap(null, res)
       })
     })
 
@@ -85,13 +67,26 @@ module.exports = (common) => {
       }
 
       ipfs.stats.bw((err, res) => {
+        statsTests.expectIsBandwidth(err, res)
+        done()
+      })
+    })
+
+    it('.bw Poll', (done) => {
+      if (!withGo) {
+        console.log('Not supported in js-ipfs yet')
+        return done()
+      }
+
+      ipfs.stats.bw({poll: true}, (err, res) => {
         expect(err).to.not.exist()
         expect(res).to.exist()
-        expect(res).to.have.a.property('totalIn')
-        expect(res).to.have.a.property('totalOut')
-        expect(res).to.have.a.property('rateIn')
-        expect(res).to.have.a.property('rateOut')
-        done()
+
+        res.once('data', (data) => {
+          statsTests.expectIsBandwidth(null, data)
+          done()
+          res.destroy()
+        })
       })
     })
 
@@ -102,28 +97,35 @@ module.exports = (common) => {
       }
 
       return ipfs.stats.bw().then((res) => {
-        expect(res).to.exist()
-        expect(res).to.have.a.property('totalIn')
-        expect(res).to.have.a.property('totalOut')
-        expect(res).to.have.a.property('rateIn')
-        expect(res).to.have.a.property('rateOut')
+        statsTests.expectIsBandwidth(null, res)
       })
     })
 
+    it('.bw Promise Poll', (done) => {
+      if (!withGo) {
+        console.log('Not supported in js-ipfs yet')
+        return
+      }
+
+      ipfs.stats.bw({poll: true}).then((res) => {
+        expect(res).to.exist()
+
+        res.once('data', (data) => {
+          statsTests.expectIsBandwidth(null, data)
+          done()
+          res.destroy()
+        })
+      }).catch(done)
+    })
+
     it('.repo', (done) => {
       if (!withGo) {
         console.log('Not supported in js-ipfs yet')
         return done()
       }
 
       ipfs.stats.repo((err, res) => {
-        expect(err).to.not.exist()
-        expect(res).to.exist()
-        expect(res).to.have.a.property('numObjects')
-        expect(res).to.have.a.property('repoSize')
-        expect(res).to.have.a.property('repoPath')
-        expect(res).to.have.a.property('version')
-        expect(res).to.have.a.property('storageMax')
+        statsTests.expectIsRepo(err, res)
         done()
       })
     })
@@ -135,12 +137,7 @@ module.exports = (common) => {
       }
 
       return ipfs.stats.repo().then((res) => {
-        expect(res).to.exist()
-        expect(res).to.have.a.property('numObjects')
-        expect(res).to.have.a.property('repoSize')
-        expect(res).to.have.a.property('repoPath')
-        expect(res).to.have.a.property('version')
-        expect(res).to.have.a.property('storageMax')
+        statsTests.expectIsRepo(null, res)
       })
     })
   })