bitswap

README

#Welcome to Bitswap ###(The data trading engine)

Bitswap is the module that is responsible for requesting and providing data blocks over the network to and from other ipfs peers. The role of bitswap is to be a merchant in the large global marketplace of data.

##Main Operations Bitswap has three high level operations:

• GetBlocks

  • GetBlocks is a bitswap method used to request multiple blocks that are likely to all be provided by the same set of peers (part of a single file, for example).

• GetBlock

  • GetBlock is a special case of GetBlocks that just requests a single block.

• HasBlock

  • HasBlock registers a local block with bitswap. Bitswap will then send that block to any connected peers who want it (with the strategies approval), record that transaction in the ledger and announce to the DHT that the block is being provided.

##Internal Details All GetBlock requests are relayed into a single for-select loop via channels. Calls to GetBlocks will have FindProviders called for only the first key in the set initially, This is an optimization attempting to cut down on the number of RPCs required. After a timeout (specified by the strategies GetRebroadcastDelay) Bitswap will iterate through all keys still in the local wantlist, perform a find providers call for each, and sent the wantlist out to those providers. This is the fallback behaviour for cases where our initial assumption about one peer potentially having multiple blocks in a set does not hold true.

When receiving messages, Bitswaps ReceiveMessage method is called. A bitswap message may contain the wantlist of the peer who sent the message, and an array of blocks that were on our local wantlist. Any blocks we receive in a bitswap message will be passed to HasBlock, and the other peers wantlist gets updated in the strategy by bs.strategy.MessageReceived. If another peers wantlist is received, Bitswap will call its strategies ShouldSendBlockToPeer method to determine whether or not the other peer will be sent the block they are requesting (if we even have it).

##Outstanding TODOs:

• Ensure only one request active per key
• More involved strategies
• Ensure only wanted blocks are counted in ledgers

Documentation

Overview

package bitswap implements the IPFS Exchange interface with the BitSwap bilateral exchange protocol.

Index

• Constants
• Variables
• func New(parent context.Context, p peer.ID, network bsnet.BitSwapNetwork, ...) exchange.Interface
• type Bitswap
  • func (bs *Bitswap) Close() error
  • func (bs *Bitswap) GetBlock(parent context.Context, k u.Key) (*blocks.Block, error)
  • func (bs *Bitswap) GetBlocks(ctx context.Context, keys []u.Key) (<-chan *blocks.Block, error)
  • func (bs *Bitswap) GetWantlist() []u.Key
  • func (bs *Bitswap) HasBlock(ctx context.Context, blk *blocks.Block) error
  • func (bs *Bitswap) PeerConnected(p peer.ID)
  • func (bs *Bitswap) PeerDisconnected(p peer.ID)
  • func (bs *Bitswap) ReceiveError(err error)
  • func (bs *Bitswap) ReceiveMessage(ctx context.Context, p peer.ID, incoming bsmsg.BitSwapMessage) (peer.ID, bsmsg.BitSwapMessage)
  • func (bs *Bitswap) Stat() (*Stat, error)
  • func (bs *Bitswap) WantlistForPeer(p peer.ID) []u.Key
• type Instance
  • func (i *Instance) Blockstore() blockstore.Blockstore
  • func (i *Instance) SetBlockstoreLatency(t time.Duration) time.Duration
• type SessionGenerator
  • func NewTestSessionGenerator(net tn.Network) SessionGenerator
  • func (g *SessionGenerator) Close() error
  • func (g *SessionGenerator) Instances(n int) []Instance
  • func (g *SessionGenerator) Next() Instance
• type Stat

Constants

const (
	HasBlockBufferSize = 256
)

Variables

var TaskWorkerCount = 8

Functions

func New

func New(parent context.Context, p peer.ID, network bsnet.BitSwapNetwork,
	bstore blockstore.Blockstore, nice bool) exchange.Interface

New initializes a BitSwap instance that communicates over the provided BitSwapNetwork. This function registers the returned instance as the network delegate. Runs until context is cancelled.

Types

type Bitswap

type Bitswap struct {
	// contains filtered or unexported fields
}

Bitswap instances implement the bitswap protocol.

func (*Bitswap) Close

func (bs *Bitswap) Close() error

func (*Bitswap) GetBlock

func (bs *Bitswap) GetBlock(parent context.Context, k u.Key) (*blocks.Block, error)

GetBlock attempts to retrieve a particular block from peers within the deadline enforced by the context.

func (*Bitswap) GetBlocks

func (bs *Bitswap) GetBlocks(ctx context.Context, keys []u.Key) (<-chan *blocks.Block, error)

GetBlocks returns a channel where the caller may receive blocks that correspond to the provided |keys|. Returns an error if BitSwap is unable to begin this request within the deadline enforced by the context.

NB: Your request remains open until the context expires. To conserve resources, provide a context with a reasonably short deadline (ie. not one that lasts throughout the lifetime of the server)

func (*Bitswap) GetWantlist

func (bs *Bitswap) GetWantlist() []u.Key

func (*Bitswap) HasBlock

func (bs *Bitswap) HasBlock(ctx context.Context, blk *blocks.Block) error

HasBlock announces the existance of a block to this bitswap service. The service will potentially notify its peers.

func (*Bitswap) PeerConnected

func (bs *Bitswap) PeerConnected(p peer.ID)

Connected/Disconnected warns bitswap about peer connections

func (*Bitswap) PeerDisconnected

func (bs *Bitswap) PeerDisconnected(p peer.ID)

Connected/Disconnected warns bitswap about peer connections

func (*Bitswap) ReceiveError

func (bs *Bitswap) ReceiveError(err error)

func (*Bitswap) ReceiveMessage

func (bs *Bitswap) ReceiveMessage(ctx context.Context, p peer.ID, incoming bsmsg.BitSwapMessage) (
	peer.ID, bsmsg.BitSwapMessage)

TODO(brian): handle errors

func (*Bitswap) Stat

func (bs *Bitswap) Stat() (*Stat, error)

func (*Bitswap) WantlistForPeer

func (bs *Bitswap) WantlistForPeer(p peer.ID) []u.Key

type Instance

type Instance struct {
	Peer     peer.ID
	Exchange exchange.Interface
	// contains filtered or unexported fields
}

func (*Instance) Blockstore

func (i *Instance) Blockstore() blockstore.Blockstore

func (*Instance) SetBlockstoreLatency

func (i *Instance) SetBlockstoreLatency(t time.Duration) time.Duration

type SessionGenerator

type SessionGenerator struct {
	// contains filtered or unexported fields
}

TODO move this SessionGenerator to the core package and export it as the core generator

func NewTestSessionGenerator

func NewTestSessionGenerator(
	net tn.Network) SessionGenerator

WARNING: this uses RandTestBogusIdentity DO NOT USE for NON TESTS!

func (*SessionGenerator) Close

func (g *SessionGenerator) Close() error

func (*SessionGenerator) Instances

func (g *SessionGenerator) Instances(n int) []Instance

func (*SessionGenerator) Next

func (g *SessionGenerator) Next() Instance

type Stat

type Stat struct {
	ProvideBufLen   int
	Wantlist        []u.Key
	Peers           []string
	BlocksReceived  int
	DupBlksReceived int
}