bitswap

package
v0.21.0 Latest Latest
Warning

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

 Go to latest Published: Jun 21, 2024 License: Apache-2.0, MIT Imports: 18 Imported by: 31

README

go-bitswap

An implementation of the bitswap protocol in go!

Table of Contents

Background

Bitswap is the data trading module for ipfs. It manages requesting and sending blocks to and from other peers in the network. Bitswap has two main jobs:

  • to acquire blocks requested by the client from the network
  • to judiciously send blocks in its possession to other peers who want them

Bitswap is a message based protocol, as opposed to request-response. All messages contain wantlists or blocks.

A node sends a wantlist to tell peers which blocks it wants. When a node receives a wantlist it should check which blocks it has from the wantlist, and consider sending the matching blocks to the requestor.

When a node receives blocks that it asked for, the node should send out a notification called a 'Cancel' to tell its peers that the node no longer wants those blocks.

go-bitswap provides an implementation of the Bitswap protocol in go.

Learn more about how Bitswap works

Usage

Initializing a Bitswap Exchange
import (
  "context"
  bitswap "github.com/ipfs/boxo/bitswap"
  bsnet "github.com/ipfs/boxo/bitswap/network"
  blockstore "github.com/ipfs/go-ipfs-blockstore"
  "github.com/libp2p/go-libp2p-core/routing"
  "github.com/libp2p/go-libp2p-core/host"
)

var ctx context.Context
var host host.Host
var router routing.ContentRouting
var bstore blockstore.Blockstore

network := bsnet.NewFromIpfsHost(host, router)
exchange := bitswap.New(ctx, network, bstore)

Parameter Notes:

  1. ctx is just the parent context for all of Bitswap
  2. network is a network abstraction provided to Bitswap on top of libp2p & content routing.
  3. bstore is an IPFS blockstore
Get A Block Synchronously
var c cid.Cid
var ctx context.Context
var exchange bitswap.Bitswap

block, err := exchange.GetBlock(ctx, c)

Parameter Notes:

  1. ctx is the context for this request, which can be cancelled to cancel the request
  2. c is the content ID of the block you're requesting
Get Several Blocks Asynchronously
var cids []cid.Cid
var ctx context.Context
var exchange bitswap.Bitswap

blockChannel, err := exchange.GetBlocks(ctx, cids)

Parameter Notes:

  1. ctx is the context for this request, which can be cancelled to cancel the request
  2. cids is a slice of content IDs for the blocks you're requesting

In IPFS, content blocks are often connected to each other through a MerkleDAG. If you know ahead of time that block requests are related, Bitswap can make several optimizations internally in how it requests those blocks in order to get them faster. Bitswap provides a mechanism called a Bitswap Session to manage a series of block requests as part of a single higher level operation. You should initialize a Bitswap Session any time you intend to make a series of block requests that are related -- and whose responses are likely to come from the same peers.

var ctx context.Context
var cids []cids.cid
var exchange bitswap.Bitswap

session := exchange.NewSession(ctx)
blocksChannel, err := session.GetBlocks(ctx, cids)
// later
var relatedCids []cids.cid
relatedBlocksChannel, err := session.GetBlocks(ctx, relatedCids)

Note that NewSession returns an interface with GetBlock and GetBlocks methods that have the same signature as the overall Bitswap exchange.

Tell bitswap a new block was added to the local datastore
var blk blocks.Block
var exchange bitswap.Bitswap

err := exchange.HasBlock(blk)

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	HasBlockBufferSize = defaults.HasBlockBufferSize
)

Functions

This section is empty.

Types

type Bitswap 

type Bitswap struct {
	*client.Client
	*server.Server
	// contains filtered or unexported fields
}

func New 

func New(ctx context.Context, net network.BitSwapNetwork, bstore blockstore.Blockstore, options ...Option) *Bitswap

func (*Bitswap) Close 

func (bs *Bitswap) Close() error

func (*Bitswap) NotifyNewBlocks 

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

func (*Bitswap) PeerConnected 

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

func (*Bitswap) PeerDisconnected 

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

func (*Bitswap) ReceiveError 

func (bs *Bitswap) ReceiveError(err error)

func (*Bitswap) ReceiveMessage 

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

func (*Bitswap) Stat 

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

func (*Bitswap) WantlistForPeer 

func (bs *Bitswap) WantlistForPeer(p peer.ID) []cid.Cid

type Option 

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

Option is interface{} of server.Option or client.Option or func(*Bitswap) wrapped in a struct to gain strong type checking.

func EngineBlockstoreWorkerCount 

func EngineBlockstoreWorkerCount(count int) Option

func EngineTaskWorkerCount 

func EngineTaskWorkerCount(count int) Option

func MaxCidSize 

func MaxCidSize(n uint) Option

MaxCidSize only affects the server. If it is 0 no limit is applied.

func MaxOutstandingBytesPerPeer 

func MaxOutstandingBytesPerPeer(count int) Option

func MaxQueuedWantlistEntriesPerPeer 

func MaxQueuedWantlistEntriesPerPeer(count uint) Option

func ProvideEnabled 

func ProvideEnabled(enabled bool) Option

func ProviderSearchDelay 

func ProviderSearchDelay(newProvSearchDelay time.Duration) Option

func RebroadcastDelay 

func RebroadcastDelay(newRebroadcastDelay delay.D) Option

func SetSendDontHaves 

func SetSendDontHaves(send bool) Option

func SetSimulateDontHavesOnTimeout 

func SetSimulateDontHavesOnTimeout(send bool) Option

func TaskWorkerCount 

func TaskWorkerCount(count int) Option

func WithBlockReceivedNotifier added in v0.19.0 

func WithBlockReceivedNotifier(brn client.BlockReceivedNotifier) Option

func WithPeerBlockRequestFilter 

func WithPeerBlockRequestFilter(pbrf server.PeerBlockRequestFilter) Option

func WithPeerLedger added in v0.20.0 

func WithPeerLedger(peerLedger server.PeerLedger) Option

func WithScoreLedger 

func WithScoreLedger(scoreLedger server.ScoreLedger) Option

func WithTargetMessageSize 

func WithTargetMessageSize(tms int) Option

func WithTaskComparator 

func WithTaskComparator(comparator server.TaskComparator) Option

func WithTracer 

func WithTracer(tap tracer.Tracer) Option

func WithoutDuplicatedBlockStats added in v0.19.0 

func WithoutDuplicatedBlockStats() Option

type PeerBlockRequestFilter 

type PeerBlockRequestFilter = server.PeerBlockRequestFilter

DEPRECATED

type Stat 

type Stat struct {
	Wantlist         []cid.Cid
	Peers            []string
	BlocksReceived   uint64
	DataReceived     uint64
	DupBlksReceived  uint64
	DupDataReceived  uint64
	MessagesReceived uint64
	BlocksSent       uint64
	DataSent         uint64
	ProvideBufLen    int
}

type TaskComparator 

type TaskComparator = server.TaskComparator

DEPRECATED

type TaskInfo 

type TaskInfo = server.TaskInfo

DEPRECATED

type Tracer 

type Tracer = tracer.Tracer

DEPRECATED

Source Files

View all Source files

Directories

Path Synopsis
Package bitswap implements the IPFS exchange interface with the BitSwap bilateral exchange protocol.
 Package bitswap implements the IPFS exchange interface with the BitSwap bilateral exchange protocol.
internal
internal/blockpresencemanager
internal/getter
internal/messagequeue
internal/notifications
internal/peermanager
internal/providerquerymanager
internal/session
internal/sessioninterestmanager
internal/sessionmanager
internal/sessionpeermanager
traceability
wantlist
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.
defaults
testutil
pb
internal
internal/decision
Package decision implements the decision engine for the bitswap service.
 Package decision implements the decision engine for the bitswap service.

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.