httpnet

Documentation

Overview

Package httpnet implements an Exchange network that sends and receives Exchange messages from peers' HTTP endpoints.

Index

• Constants
• Variables
• func New(host host.Host, opts ...Option) network.BitSwapNetwork
• type Network
  • func (ht *Network) Connect(ctx context.Context, p peer.AddrInfo) error
  • func (ht *Network) DisconnectFrom(ctx context.Context, p peer.ID) error
  • func (ht *Network) Latency(p peer.ID) time.Duration
  • func (ht *Network) NewMessageSender(ctx context.Context, p peer.ID, opts *network.MessageSenderOpts) (network.MessageSender, error)
  • func (ht *Network) Ping(ctx context.Context, p peer.ID) ping.Result
  • func (ht *Network) Protect(p peer.ID, tag string)
  • func (ht *Network) Self() peer.ID
  • func (ht *Network) SendMessage(ctx context.Context, p peer.ID, msg bsmsg.BitSwapMessage) error
  • func (ht *Network) Start(receivers ...network.Receiver)
  • func (ht *Network) Stats() network.Stats
  • func (ht *Network) Stop()
  • func (ht *Network) TagPeer(p peer.ID, tag string, w int)
  • func (ht *Network) Unprotect(p peer.ID, tag string) bool
  • func (ht *Network) UntagPeer(p peer.ID, tag string)
• type Option
  • func WithAllowlist(hosts []string) Option
  • func WithDialTimeout(t time.Duration) Option
  • func WithHTTPWorkers(n int) Option
  • func WithIdleConnTimeout(t time.Duration) Option
  • func WithInsecureSkipVerify(b bool) Option
  • func WithMaxBlockSize(size int64) Option
  • func WithMaxHTTPAddressesPerPeer(max int) Option
  • func WithMaxIdleConns(n int) Option
  • func WithResponseHeaderTimeout(t time.Duration) Option
  • func WithUserAgent(agent string) Option

Constants

const (
	DefaultMaxBlockSize            int64 = 2 << 20 // 2MiB: https://specs.ipfs.tech/bitswap-protocol/#block-sizes
	DefaultDialTimeout                   = 5 * time.Second
	DefaultIdleConnTimeout               = 30 * time.Second
	DefaultResponseHeaderTimeout         = 10 * time.Second
	DefaultMaxIdleConns                  = 50
	DefaultInsecureSkipVerify            = false
	DefaultMaxBackoff                    = time.Minute
	DefaultMaxHTTPAddressesPerPeer       = 10
	DefaultHTTPWorkers                   = 64
)

Defaults for the configurable options.

const (
	// DefaultMaxRetries specifies how many requests to make to available
	// HTTP endpoints in case of failure.
	DefaultMaxRetries = 1
	// DefaultSendTimeout specifies sending each individual HTTP
	// request can take.
	DefaultSendTimeout = 5 * time.Second
	// SendErrorBackoff specifies how long to wait between retries to the
	// same endpoint after failure. It is overriden by Retry-After
	// headers and must be at least 50ms.
	DefaultSendErrorBackoff = time.Second
)

MessageSender option defaults.

Variables

var (
	// DefaultUserAgent is sent as a header in all requests.
	DefaultUserAgent = defaultUserAgent() // Usually will result in a "boxo@commitID"
)

var ErrNoHTTPAddresses = errors.New("AddrInfo does not contain any valid HTTP addresses")

var ErrNoSuccess = errors.New("none of the peer HTTP endpoints responded successfully to request")

Functions

func New

func New(host host.Host, opts ...Option) network.BitSwapNetwork

New returns a BitSwapNetwork supported by underlying IPFS host.

Types

type Network

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

func (*Network) Connect

func (ht *Network) Connect(ctx context.Context, p peer.AddrInfo) error

Connect attempts setting up an HTTP connection to the given peer. The given AddrInfo must include at least one HTTP endpoint for the peer. HTTP URLs in AddrInfo will be tried by making an HTTP GET request to "ipfs/bafyqaaa", which is the CID for an empty raw block (inlined). Any completed request, regardless of the HTTP response, is considered a connection success and marks this peer as "connected", setting it up to handle messages and make requests. The peer will be pinged regularly to collect latency measurements until DisconnectFrom() is called.

func (*Network) DisconnectFrom

func (ht *Network) DisconnectFrom(ctx context.Context, p peer.ID) error

DisconnectFrom marks this peer as Disconnected in the connection event manager, stops pinging for latency measurements and removes it from the peerstore.

func (*Network) Latency

func (ht *Network) Latency(p peer.ID) time.Duration

Latency returns the EWMA latency for the given peer.

func (*Network) NewMessageSender

func (ht *Network) NewMessageSender(ctx context.Context, p peer.ID, opts *network.MessageSenderOpts) (network.MessageSender, error)

NewMessageSender returns a MessageSender implementation which sends the given message to the given peer over HTTP. An error is returned of the peer has no known HTTP endpoints.

func (*Network) Ping

func (ht *Network) Ping(ctx context.Context, p peer.ID) ping.Result

Ping triggers a ping to the given peer and returns the latency.

func (*Network) Protect

func (ht *Network) Protect(p peer.ID, tag string)

Protect does nothing. The purpose of Protect is to mantain connections as long as they are used. But our connections are already maintained as long as they are, and closed when not.

func (*Network) Self

func (ht *Network) Self() peer.ID

Self returns the local peer ID.

func (*Network) SendMessage

func (ht *Network) SendMessage(ctx context.Context, p peer.ID, msg bsmsg.BitSwapMessage) error

SendMessage sends the given message to the given peer. It uses NewMessageSender under the hood, with default options.

func (*Network) Start

func (ht *Network) Start(receivers ...network.Receiver)

Start sets up the given receivers to be notified when message responses are received. It also starts the connection event manager. Start must be called before using the Network.

func (*Network) Stats

func (ht *Network) Stats() network.Stats

Stats returns message counts for this peer. Each message sent is an HTTP requests. Each message received is an HTTP response.

func (*Network) Stop

func (ht *Network) Stop()

Stop stops the connect event manager associated with this network. Other methods should no longer be used after calling Stop().

func (*Network) TagPeer

func (ht *Network) TagPeer(p peer.ID, tag string, w int)

TagPeer uses the host's ConnManager to tag a peer.

func (*Network) Unprotect

func (ht *Network) Unprotect(p peer.ID, tag string) bool

Unprotect does nothing. The purpose of Unprotect is to be able to close connections when they are no longer relevant. Our connections are already closed when they are not used. It returns always true as technically our connections are potentially still protected as long as they are used.

func (*Network) UntagPeer

func (ht *Network) UntagPeer(p peer.ID, tag string)

UntagPeer uses the host's ConnManager to untag a peer.

type Option

type Option func(net *Network)

Option allows to configure the Network.

func WithAllowlist

func WithAllowlist(hosts []string) Option

WithAllowlist sets the hostnames that we are allowed to connect to via HTTP. Additionally, http response status metrics are tagged for each of these hosts.

func WithDialTimeout

func WithDialTimeout(t time.Duration) Option

WithDialTimeout sets the maximum time to wait for a connection to be set up.

func WithHTTPWorkers

func WithHTTPWorkers(n int) Option

WithHTTPWorkers controls how many HTTP requests can be done concurrently.

func WithIdleConnTimeout

func WithIdleConnTimeout(t time.Duration) Option

WithIdleConnTimeout sets how long to keep connections alive before closing them when no requests happen.

func WithInsecureSkipVerify

func WithInsecureSkipVerify(b bool) Option

WithInsecureSkipVerify allows making HTTPS connections to test servers. Use for testing.

func WithMaxBlockSize

func WithMaxBlockSize(size int64) Option

WithMaxBlockSize sets the maximum size of an HTTP response (block).

func WithMaxHTTPAddressesPerPeer

func WithMaxHTTPAddressesPerPeer(max int) Option

WithMaxHTTPAddressesPerPeer limits how many http addresses we attempt to connect to per peer.

func WithMaxIdleConns

func WithMaxIdleConns(n int) Option

WithMaxIdleConns sets how many keep-alive connections we can have where no requests are happening.

func WithResponseHeaderTimeout

func WithResponseHeaderTimeout(t time.Duration) Option

WithResponseHeaderTimeout sets how long to wait for a response to start arriving. It is the time given to the provider to find and start sending the block. It does not affect the time it takes to download the request body.

func WithUserAgent

func WithUserAgent(agent string) Option

WithUserAgent sets the user agent when making requests.