fixup the bitswap readme
Juan Batiz-Benet committed
May 21, 2015 at 01:11 UTC
2eac921e1d27403539589a8abe684a6e43fb2f35
1 file changed
+36
-46
exchange/bitswap/README.md
+36
-46
@@ -1,47 +1,37 @@
1
-#Welcome to Bitswap
2
-###(The data trading engine)
1
+# Bitswap
2
+
3
+## Protocol
4
+Bitswap is the data trading module for ipfs, it manages requesting and sending
5
+blocks to and from other peers in the network. Bitswap has two main jobs, the
6
+first is to acquire blocks requested by the client from the network. The second
7
+is to judiciously send blocks in its posession to other peers who want them.
8
+
9
+Bitswap is a message based protocol, as opposed to response-reply. All messages
10
+contain wantlists, or blocks. Upon receiving a wantlist, a node should consider
11
+sending out wanted blocks if they have them. Upon receiving blocks, the node
12
+should send out a notification called a 'Cancel' signifying that they no longer
13
+want the block. At a protocol level, bitswap is very simple.
14
+
15
+## go-ipfs Implementation
16
+Internally, when a message with a wantlist is received, it is sent to the
17
+decision engine to be considered, and blocks that we have that are wanted are
18
+placed into the peer request queue. Any block we possess that is wanted by
19
+another peer has a task in the peer request queue created for it. The peer
20
+request queue is a priority queue that sorts available tasks by some metric,
21
+currently, that metric is very simple and aims to fairly address the tasks
22
+of each other peer. More advanced decision logic will be implemented in the
23
+future. Task workers pull tasks to be done off of the queue, retreive the block
24
+to be sent, and send it off. The number of task workers is limited by a constant
25
+factor.
26
+
27
+Client requests for new blocks are handled by the want manager, for every new
28
+block (or set of blocks) wanted, the 'WantBlocks' method is invoked. The want
29
+manager then ensures that connected peers are notified of the new block that we
30
+want by sending the new entries to a message queue for each peer. The message
31
+queue will loop while there is work available and do the following: 1) Ensure it
32
+has a connection to its peer, 2) grab the message to be sent, and 3) send it.
33
+If new messages are added while the loop is in steps 1 or 3, the messages are
34
+combined into one to avoid having to keep an actual queue and send multiple
35
+messages. The same process occurs when the client receives a block and sends a
36
+cancel message for it.
37
4
-Bitswap is the module that is responsible for requesting and providing data
5
-blocks over the network to and from other ipfs peers. The role of bitswap is
6
-to be a merchant in the large global marketplace of data.
7
-
8
-##Main Operations
9
-Bitswap has three high level operations:
10
-
11
-- **GetBlocks**
12
- - `GetBlocks` is a bitswap method used to request multiple blocks that are likely
13
-to all be provided by the same set of peers (part of a single file, for example).
14
-
15
-- **GetBlock**
16
- - `GetBlock` is a special case of `GetBlocks` that just requests a single block.
17
-
18
-- **HasBlock**
19
- - `HasBlock` registers a local block with bitswap. Bitswap will then send that
20
-block to any connected peers who want it (with the strategies approval), record
21
-that transaction in the ledger and announce to the DHT that the block is being
22
-provided.
23
-
24
-##Internal Details
25
-All `GetBlock` requests are relayed into a single for-select loop via channels.
26
-Calls to `GetBlocks` will have `FindProviders` called for only the first key in
27
-the set initially, This is an optimization attempting to cut down on the number
28
-of RPCs required. After a timeout (specified by the strategies
29
-`GetRebroadcastDelay`) Bitswap will iterate through all keys still in the local
30
-wantlist, perform a find providers call for each, and sent the wantlist out to
31
-those providers. This is the fallback behaviour for cases where our initial
32
-assumption about one peer potentially having multiple blocks in a set does not
33
-hold true.
34
-
35
-When receiving messages, Bitswaps `ReceiveMessage` method is called. A bitswap
36
-message may contain the wantlist of the peer who sent the message, and an array
37
-of blocks that were on our local wantlist. Any blocks we receive in a bitswap
38
-message will be passed to `HasBlock`, and the other peers wantlist gets updated
39
-in the strategy by `bs.strategy.MessageReceived`.
40
-If another peers wantlist is received, Bitswap will call its strategies
41
-`ShouldSendBlockToPeer` method to determine whether or not the other peer will
42
-be sent the block they are requesting (if we even have it).
43
-
44
-##Outstanding TODOs:
45
-- [ ] Ensure only one request active per key
46
-- [ ] More involved strategies
47
-- [ ] Ensure only wanted blocks are counted in ledgers