Skip to content

Commit

Permalink
feat: new bitswap
Browse files Browse the repository at this point in the history
  • Loading branch information
@daviddias
daviddias committed Dec 23, 2016
1 parent 27fe1f7 commit dbe80cc
Show file tree
Hide file tree
Showing 45 changed files with 1,989 additions and 1,514 deletions.
82 changes: 0 additions & 82 deletions API.md
View file

This file was deleted.

116 changes: 113 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,21 +31,21 @@
### npm

```sh
> npm i ipfs-bitswap
> npm install ipfs-bitswap --save
```

### Use in Node.js

```js
const bitswap = require('ipfs-bitswap')
const Bitswap = require('ipfs-bitswap')
```

### Use in a browser with browserify, webpack or any other bundler

The code published to npm that gets loaded on require is in fact a ES5 transpiled version with the right shims added. This means that you can require it and use with your favourite bundler without having to adjust asset management process.

```js
const bitswap = require('ipfs-bitswap')
const Bitswap = require('ipfs-bitswap')
```

### Use in a browser using a script tag
Expand All @@ -62,6 +62,116 @@ Loading this module through a script tag will make the `IpfsBitswap` object avai

For the documentation see [API.md](API.md).

### API

#### `new Bitswap(libp2p, blockstore)`

- `libp2p: Libp2p`, instance of the local network stack.
- `blockstore: Blockstore`, instance of the local database (`IpfsRepo.blockstore`)

Create a new instance.

#### `getStream(cid)`

- `cid: CID|Array`

Returns a source `pull-stream`. Values emitted are the received blocks.

Example:

```js
// Single block
pull(
bitswap.getStream(cid),
pull.collect((err, blocks) => {
// blocks === [block]
})
)

// Many blocks
pull(
bitswap.getStream([cid1, cid2, cid3]),
pull.collect((err, blocks) => {
// blocks === [block1, block2, block3]
})
)
```

> Note: This is safe guarded so that the network is not asked
> for blocks that are in the local `datastore`.
#### `unwant(cids)`

- `cids: CID|[]CID`

Cancel previously requested keys, forcefully. That means they are removed from the
wantlist independent of how many other resources requested these keys. Callbacks
attached to `getBlock` are errored with `Error('manual unwant: key')`.

#### `cancelWants(cids)`

- `cid: CID|[]CID`

Cancel previously requested keys.

#### `putStream()`

Returns a duplex `pull-stream` that emits an object `{key: Multihash}` for every written block when it was stored.
Objects passed into here should be of the form `{data: Buffer, key: Multihash}`

#### `put(blockAndCid, callback)`

- `blockAndKey: {data: Buffer, cid: CID}`
- `callback: Function`

Announce that the current node now has the block containing `data`. This will store it
in the local database and attempt to serve it to all peers that are known
to have requested it. The callback is called when we are sure that the block
is stored.

#### `wantlistForPeer(peerId)`

- `peerId: PeerId`

Get the wantlist for a given peer.

#### `stat()`

Get stats about about the current state of the bitswap instance.

## Development

### Structure

![](/img/architecture.png)

```sh
» tree src
src
├── components
│   ├── decision
│   │   ├── engine.js
│   │   ├── index.js
│   │   ├── ledger.js
│   │   ├── peer-request-queue.js
│   │   └── pq.js
│   ├── network # Handles peerSet and open new conns
│   │   └── index.js
│   └── want-manager # Keeps track of all blocks the peer wants (not the others which it is connected)
│   ├── index.js
│   └── msg-queue.js # Messages to send queue, one per peer
├── constants.js
├── index.js
└── types
├── message # (Type) message that is put in the wire
│   ├── entry.js
│   ├── index.js
│   └── message.proto.js
└── wantlist # (Type) track wanted blocks
├── entry.js
└── index.js
```

## Contribute

Feel free to join in. All welcome. Open an [issue](https://github.com/ipfs/js-ipfs-bitswap/issues)!
Expand Down
8 changes: 5 additions & 3 deletions benchmarks/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ const Block = require('ipfs-block')
const pull = require('pull-stream')
const assert = require('assert')
const crypto = require('crypto')
const CID = require('cids')

const utils = require('../test/utils')

Expand Down Expand Up @@ -54,6 +55,7 @@ function round (nodeArr, blockFactor, n, cb) {
if (err) {
return cb(err)
}
const cids = keys.map((k) => new CID(k))
let d
series([
// put blockFactor amount of blocks per node
Expand All @@ -63,8 +65,8 @@ function round (nodeArr, blockFactor, n, cb) {
const data = _.map(_.range(blockFactor), (j) => {
const index = i * blockFactor + j
return {
data: blocks[index].data,
key: keys[index]
block: blocks[index],
cid: cids[index]
}
})
each(
Expand All @@ -80,7 +82,7 @@ function round (nodeArr, blockFactor, n, cb) {
// fetch all blocks on every node
(cb) => parallel(_.map(nodeArr, (node, i) => (callback) => {
pull(
node.bitswap.getStream(keys),
node.bitswap.getStream(cids),
pull.collect((err, res) => {
if (err) {
return callback(err)
Expand Down
6 changes: 4 additions & 2 deletions benchmarks/put-get.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ const assert = require('assert')
const pull = require('pull-stream')
const series = require('async/series')
const crypto = require('crypto')
const CID = require('cids')

const utils = require('../test/utils')

const suite = new Benchmark.Suite('put-get')
Expand Down Expand Up @@ -64,7 +66,7 @@ function put (blocks, bs, callback) {
if (err) {
return cb(err)
}
cb(null, {key: key, data: b.data})
cb(null, {cid: new CID(key), block: b})
})
}),
bs.putStream(),
Expand All @@ -76,7 +78,7 @@ function get (blocks, bs, callback) {
pull(
pull.values(blocks),
pull.asyncMap((b, cb) => b.key(cb)),
pull.map((k) => bs.getStream(k)),
pull.map((k) => bs.getStream(new CID(k))),
pull.flatten(),
pull.collect((err, res) => {
if (err) {
Expand Down
Binary file added img/architecture.monopic
View file
Binary file not shown.
Binary file added img/architecture.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
51 changes: 51 additions & 0 deletions img/architecture.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@

┌────────────────────────────────────────────────────────────────────────────┐
│ Bitswap API │
└────────────────────────────────────────────────────────────────────────────┘
│ ▲
│register wants │yields the
│and unwants │received
│ │blocks
│ │
│ send block to other nodes┌───────────────────────────┐
│ by adding them to their │ Decision Engine │
│ buckets │ │
│ ┌─────────◀├ ─ ─ ─ │
│ │ │Ledger│ │
│ │ └───────────────────────────┘
│ │ ▲
▼ │ │
┌────────────────────┐ │ │
│ │ │ │
│ Want Manager │ │ │
│ │ │ │
├───────────┬──┬─────┘ │ │
│my wantlist│ │ │ │
└───────────┘ │update wantlist │ │
│messages │ receive a block │
└─────┬───────┬───────┤ │
│ │ │ │
▼ ▼ ▼ │
┌───────┬───────┬───────┐ │
│Message│Message│... │ │
│Queue/ │Queue/ │ │ │
│peer │peer │ │ │
└───────┴───────┴───────┘ │
│ │ │ │
│ │ │ │
│ │ │ │
└───────┴───────┴─┐ │
│ │
│ │
▼ │
┌────────────────────────────────────────┐
│ Network │
└────────────────────────────────────────┘
│ ▲ │ ▲
▼ │ │ │
┌─────────┐ ▼ │
│Transform│ /ipfs/bitswap/1.1.0
└─────────┘
│ ▲
▼ │
/ipfs/bitswap/1.0.0
11 changes: 6 additions & 5 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
},
"homepage": "https://github.com/ipfs/js-ipfs-bitswap#readme",
"devDependencies": {
"aegir": "9.2.2",
"aegir": "9.3.0",
"benchmark": "^2.1.2",
"buffer-loader": "0.0.1",
"chai": "^3.5.0",
Expand All @@ -56,8 +56,8 @@
},
"dependencies": {
"async": "^2.1.4",
"cids": "^0.3.4",
"debug": "^2.3.3",
"cids": "^0.3.5",
"debug": "^2.4.4",
"heap": "^0.2.6",
"ipfs-block": "^0.5.3",
"lodash.debounce": "^4.0.8",
Expand All @@ -68,13 +68,14 @@
"lodash.pullallwith": "^4.7.0",
"lodash.uniqwith": "^4.5.0",
"lodash.values": "^4.3.0",
"multihashes": "^0.3.0",
"multihashes": "^0.3.1",
"protocol-buffers": "^3.2.1",
"pull-defer": "^0.2.2",
"pull-length-prefixed": "^1.2.0",
"pull-paramap": "^1.2.1",
"pull-pushable": "^2.0.1",
"pull-stream": "^3.5.0"
"pull-stream": "^3.5.0",
"varint-decoder": "^0.1.1"
},
"contributors": [
"David Dias <daviddias.p@gmail.com>",
Expand Down
Loading

0 comments on commit dbe80cc

Please sign in to comment.