Support bitswap 1.1.0 and bitswap 1.0.0 using CID

README.md

@@ -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
@@ -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)!

img/architecture.txt

@@ -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                       

package.json

@@ -35,14 +35,14 @@
   },
   "homepage": "https://github.com/ipfs/js-ipfs-bitswap#readme",
   "devDependencies": {
-    "aegir": "9.2.1",
+    "aegir": "9.3.0",
     "buffer-loader": "0.0.1",
     "chai": "^3.5.0",
     "fs-pull-blob-store": "^0.4.1",
     "idb-pull-blob-store": "^0.5.1",
     "interface-pull-blob-store": "^0.6.0",
-    "ipfs-repo": "^0.11.1",
-    "libp2p-ipfs-nodejs": "^0.16.4",
+    "ipfs-repo": "^0.11.2",
+    "libp2p-ipfs-nodejs": "^0.17.0",
     "lodash": "^4.17.2",
     "multiaddr": "^2.1.1",
     "ncp": "^2.0.0",
@@ -54,20 +54,20 @@
   },
   "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.1",
+    "ipfs-block": "^0.5.3",
     "lodash.debounce": "^4.0.8",
     "lodash.isequalwith": "^4.4.0",
-    "lodash.isundefined": "^3.0.1",
-    "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 <[email protected]>",
@@ -77,4 +77,4 @@
     "greenkeeperio-bot <[email protected]>",
     "npmcdn-to-unpkg-bot <[email protected]>"
   ]
-}
+}