client

package
v0.35.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 6, 2025 License: Apache-2.0, MIT Imports: 29 Imported by: 14

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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 routing.ContentDiscovery, 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.

If WithTraceBlock option is set true, then returns a github.com/ipfs/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.

If WithTraceBlock option is set true, then returns a channel of github.com/ipfs/boxo/bitswap/client/traceability.Block assertable blocks.Block.

When the provided context is canceled, GetBlocks will stop returning blocks and the returned channel will be closed.

This method creates a temporary internal session that is automatically cleaned up when the operation completes. Any retrieval.State attached to the context will be preserved and used for diagnostic tracking throughout the retrieval process.

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.

The context is used for:

  • Automatic session cleanup: when the context is canceled, the session will be closed
  • Retrieval state tracking: any retrieval.State attached to the context will be preserved in the session for diagnostic tracking of provider discovery and data retrieval

The session's lifetime is controlled by the context and requires that the context be canceled for the session to be closed.

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 DontHaveTimeoutConfig added in v0.28.0 

type DontHaveTimeoutConfig = bsmq.DontHaveTimeoutConfig

func DefaultDontHaveTimeoutConfig added in v0.28.0 

func DefaultDontHaveTimeoutConfig() *DontHaveTimeoutConfig

type Option 

type Option func(*Client)

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

func BroadcastControlEnable added in v0.32.0 

func BroadcastControlEnable(enable bool) Option

BroadcastControlEnable enables or disables broadcast reduction logic. Setting this to false restores the previous broadcast behavior of sending broadcasts to all peers, and ignores all other BroadcastControl options. Default is false (disabled).

func BroadcastControlLocalPeers added in v0.32.0 

func BroadcastControlLocalPeers(enable bool) Option

BroadcastControlLocalPeers enables or disables broadcast control for peers on the local network. If false, than always broadcast to peers on the local network. If true, apply broadcast control to local peers. Default is false (always broadcast to local peers).

func BroadcastControlMaxPeers added in v0.32.0 

func BroadcastControlMaxPeers(limit int) Option

BroadcastControlMaxPeers sets a hard limit on the number of peers to send broadcasts to. A value of 0 means no broadcasts are sent. A value of -1 means there is no limit. Default is -1 (unlimited).

func BroadcastControlMaxRandomPeers added in v0.32.0 

func BroadcastControlMaxRandomPeers(n int) Option

BroadcastControlMaxRandomPeers sets the number of peers to broadcast to anyway, even though broadcast control logic has determined that they are not broadcast targets. Setting this to a non-zero value ensures at least this number of random peers receives a broadcast. This may be helpful in cases where peers that are not receiving broadcasts may have wanted blocks. Default is 0 (no random broadcasts).

func BroadcastControlPeeredPeers added in v0.32.0 

func BroadcastControlPeeredPeers(enable bool) Option

BroadcastControlPeeredPeers enables or disables broadcast control for peers configured for peering. If false, than always broadcast to peers configured for peering. If true, apply broadcast control to peered peers. Default is false (always broadcast to peered peers).

func BroadcastControlSendToPendingPeers added in v0.32.0 

func BroadcastControlSendToPendingPeers(enable bool) Option

BroadcastControlSendToPendingPeers, enables or disables sending broadcasts to any peers to which there is a pending message to send. When enabled, this sends broadcasts to many more peers, but does so in a way that does not increase the number of separate broadcast messages. There is still the increased cost of the recipients having to process and respond to the broadcasts. Default is false.

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 time.Duration) 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 added in v0.25.0 

func WithDefaultProviderQueryManager(defaultProviderQueryManager bool) Option

WithDefaultProviderQueryManager indicates whether to use the default ProviderQueryManager as a wrapper of the content Router. The default bitswap ProviderQueryManager provides bounded parallelism and limits for these lookups. The bitswap default ProviderQueryManager uses these options, which may be more conservative than the ProviderQueryManager defaults:

  • WithMaxProviders(defaults.BitswapClientDefaultMaxProviders)

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 WithDontHaveTimeoutConfig added in v0.26.0 

func WithDontHaveTimeoutConfig(cfg *DontHaveTimeoutConfig) Option

func WithPerPeerSendDelay added in v0.27.3 

func WithPerPeerSendDelay(delay time.Duration) Option

WithPerPeerSendDelay determines how long to wait, based on the number of peers, for wants to accumulate before sending a bitswap message to peers. A value of 0 uses bitswap messagequeue default.

func WithTraceBlock added in v0.33.1 

func WithTraceBlock(enable bool) Option

WithTraceBlock, if enabled is true, configures the client's GetBLock and GetBlocks functions to returns a github.com/ipfs/boxo/bitswap/client/traceability.Block assertable blocks.Block.

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 added in v0.14.0 

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

Source Files

View all Source files

Directories

Path Synopsis
blockpresencemanager
getter
messagequeue
Package messagequeue implements a queue of want messages to send to peers.
 Package messagequeue implements a queue of want messages to send to peers.
notifications
peermanager
session
sessioninterestmanager
sessionmanager
sessionpeermanager
Package wantlist implements an object for bitswap that contains the keys that a given peer wants.
 Package wantlist implements an object for bitswap that contains the keys that a given peer wants.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.