client

Documentation

Overview

Package bitswap implements the IPFS exchange interface with the BitSwap bilateral exchange protocol.

Index

• type BlockReceivedNotifier
• type Client
  • func New(parent context.Context, network bsnet.BitSwapNetwork, ...) *Client
  • func (bs *Client) Close() error
  • func (bs *Client) GetBlock(ctx context.Context, k cid.Cid) (blocks.Block, error)
  • func (bs *Client) GetBlocks(ctx context.Context, keys []cid.Cid) (<-chan blocks.Block, error)
  • func (bs *Client) GetWantBlocks() []cid.Cid
  • func (bs *Client) GetWantHaves() []cid.Cid
  • func (bs *Client) GetWantlist() []cid.Cid
  • func (bs *Client) IsOnline() bool
  • func (bs *Client) NewSession(ctx context.Context) exchange.Fetcher
  • func (bs *Client) NotifyNewBlocks(ctx context.Context, blks ...blocks.Block) error
  • func (bs *Client) PeerConnected(p peer.ID)
  • func (bs *Client) PeerDisconnected(p peer.ID)
  • func (bs *Client) ReceiveError(err error)
  • func (bs *Client) ReceiveMessage(ctx context.Context, p peer.ID, incoming bsmsg.BitSwapMessage)
  • func (bs *Client) Stat() (st Stat, err error)
• type Option
  • func ProviderSearchDelay(newProvSearchDelay time.Duration) Option
  • func RebroadcastDelay(newRebroadcastDelay delay.D) Option
  • func SetSimulateDontHavesOnTimeout(send bool) Option
  • func WithBlockReceivedNotifier(brn BlockReceivedNotifier) Option
  • func WithDefaultProviderQueryManager(defaultProviderQueryManager bool) Option
  • func WithTracer(tap tracer.Tracer) Option
  • func WithoutDuplicatedBlockStats() Option
• type ProviderFinder
• type Stat

Types

type BlockReceivedNotifier

type BlockReceivedNotifier interface {
	// ReceivedBlocks notifies the decision engine that a peer is well-behaving
	// and gave us useful data, potentially increasing its score and making us
	// send them more data in exchange.
	ReceivedBlocks(peer.ID, []blocks.Block)
}

type Client

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

Client instances implement the bitswap protocol.

func New

func New(parent context.Context, network bsnet.BitSwapNetwork, providerFinder ProviderFinder, bstore blockstore.Blockstore, options ...Option) *Client

New initializes a Bitswap client that runs until client.Close is called. The Content providerFinder paramteter can be nil to disable content-routing lookups for content (rely only on bitswap for discovery).

func (*Client) Close

func (bs *Client) Close() error

Close is called to shutdown the Client

func (*Client) GetBlock

func (bs *Client) GetBlock(ctx context.Context, k cid.Cid) (blocks.Block, error)

GetBlock attempts to retrieve a particular block from peers within the deadline enforced by the context. It returns a github.com/stateless-minds/boxo/bitswap/client/traceability.Block assertable blocks.Block.

func (*Client) GetBlocks

func (bs *Client) GetBlocks(ctx context.Context, keys []cid.Cid) (<-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. It returns a github.com/stateless-minds/boxo/bitswap/client/traceability.Block assertable blocks.Block.

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 (*Client) GetWantBlocks

func (bs *Client) GetWantBlocks() []cid.Cid

GetWantBlocks returns the current list of want-blocks.

func (*Client) GetWantHaves

func (bs *Client) GetWantHaves() []cid.Cid

GetWanthaves returns the current list of want-haves.

func (*Client) GetWantlist

func (bs *Client) GetWantlist() []cid.Cid

GetWantlist returns the current local wantlist (both want-blocks and want-haves).

func (*Client) IsOnline

func (bs *Client) IsOnline() bool

IsOnline is needed to match go-ipfs-exchange-interface

func (*Client) NewSession

func (bs *Client) NewSession(ctx context.Context) exchange.Fetcher

NewSession generates a new Bitswap session. You should use this, rather that calling Client.GetBlocks, any time you intend to do several related block requests in a row. The session returned will have it's own GetBlocks method, but the session will use the fact that the requests are related to be more efficient in its requests to peers. If you are using a session from blockservice, it will create a bitswap session automatically.

func (*Client) NotifyNewBlocks

func (bs *Client) NotifyNewBlocks(ctx context.Context, blks ...blocks.Block) error

NotifyNewBlocks announces the existence of blocks to this bitswap service. Bitswap itself doesn't store new blocks. It's the caller responsibility to ensure that those blocks are available in the blockstore before calling this function.

func (*Client) PeerConnected

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

PeerConnected is called by the network interface when a peer initiates a new connection to bitswap.

func (*Client) PeerDisconnected

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

PeerDisconnected is called by the network interface when a peer closes a connection

func (*Client) ReceiveError

func (bs *Client) ReceiveError(err error)

ReceiveError is called by the network interface when an error happens at the network layer. Currently just logs error.

func (*Client) ReceiveMessage

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

ReceiveMessage is called by the network interface when a new message is received.

func (*Client) Stat

func (bs *Client) Stat() (st Stat, err error)

Stat returns aggregated statistics about bitswap operations

type Option

type Option func(*Client)

Option defines the functional option type that can be used to configure bitswap instances

func ProviderSearchDelay

func ProviderSearchDelay(newProvSearchDelay time.Duration) Option

ProviderSearchDelay sets the initial dely before triggering a provider search to find more peers and broadcast the want list. It also partially controls re-broadcasts delay when the session idles (does not receive any blocks), but these have back-off logic to increase the interval. See defaults.ProvSearchDelay for the default.

func RebroadcastDelay

func RebroadcastDelay(newRebroadcastDelay delay.D) Option

RebroadcastDelay sets a custom delay for periodic search of a random want. When the value ellapses, a random CID from the wantlist is chosen and the client attempts to find more peers for it and sends them the single want. defaults.RebroadcastDelay for the default.

func SetSimulateDontHavesOnTimeout

func SetSimulateDontHavesOnTimeout(send bool) Option

func WithBlockReceivedNotifier

func WithBlockReceivedNotifier(brn BlockReceivedNotifier) Option

func WithDefaultProviderQueryManager

func WithDefaultProviderQueryManager(defaultProviderQueryManager bool) Option

WithDefaultProviderQueryManager indicates wether we should use a the default ProviderQueryManager, a wrapper of the content Router which provides bounded paralelism and limits for these lookups. The ProviderQueryManager setup by default uses maxInProcessRequests = 6 and maxProviders = 10. To use a custom ProviderQueryManager, set to false and wrap directly the content router provided with the WithContentRouting() option. Only takes effect if WithContentRouting is set.

func WithTracer

func WithTracer(tap tracer.Tracer) Option

Configures the Client to use given tracer. This provides methods to access all messages sent and received by the Client. This interface can be used to implement various statistics (this is original intent).

func WithoutDuplicatedBlockStats

func WithoutDuplicatedBlockStats() Option

WithoutDuplicatedBlockStats disable collecting counts of duplicated blocks received. This counter requires triggering a blockstore.Has() call for every block received by launching goroutines in parallel. In the worst case (no caching/blooms etc), this is an expensive call for the datastore to answer. In a normal case (caching), this has the power of evicting a different block from intermediary caches. In the best case, it doesn't affect performance. Use if this stat is not relevant.

type ProviderFinder

type ProviderFinder interface {
	FindProvidersAsync(context.Context, cid.Cid, int) <-chan peer.AddrInfo
}

ProviderFinder is a subset of https://pkg.go.dev/github.com/libp2p/go-libp2p@v0.37.0/core/routing#ContentRouting

type Stat

type Stat struct {
	Wantlist         []cid.Cid
	BlocksReceived   uint64
	DataReceived     uint64
	DupBlksReceived  uint64
	DupDataReceived  uint64
	MessagesReceived uint64
}

Stat is a struct that provides various statistics on bitswap operations