peerstore

README

go-libp2p-peer

An object to manage peers, their addresses, and other metadata about them.

Install

go get github.com/libp2p/go-libp2p-peerstore

Usage

Check out the GoDocs.

Contribute

Feel free to join in. All welcome. Open an issue!

This repository falls under the IPFS Code of Conduct.

Want to hack on IPFS?

License

MIT

Documentation

Index

• Constants
• Variables
• func NewMetrics() *metrics
• func PeerInfoIDs(pis []PeerInfo) []peer.ID
• type AddrBook
• type AddrManager
  • func (mgr *AddrManager) AddAddr(p peer.ID, addr ma.Multiaddr, ttl time.Duration)
  • func (mgr *AddrManager) AddAddrs(p peer.ID, addrs []ma.Multiaddr, ttl time.Duration)
  • func (mgr *AddrManager) AddrStream(ctx context.Context, p peer.ID) <-chan ma.Multiaddr
  • func (mgr *AddrManager) Addrs(p peer.ID) []ma.Multiaddr
  • func (mgr *AddrManager) ClearAddrs(p peer.ID)
  • func (mgr *AddrManager) Peers() []peer.ID
  • func (mgr *AddrManager) SetAddr(p peer.ID, addr ma.Multiaddr, ttl time.Duration)
  • func (mgr *AddrManager) SetAddrs(p peer.ID, addrs []ma.Multiaddr, ttl time.Duration)
• type KeyBook
• type Metrics
• type PeerInfo
  • func PeerInfos(ps Peerstore, peers []peer.ID) []PeerInfo
  • func (pi *PeerInfo) Loggable() map[string]interface{}
  • func (pi *PeerInfo) MarshalJSON() ([]byte, error)
  • func (pi *PeerInfo) UnmarshalJSON(b []byte) error
• type Peerstore
  • func NewPeerstore() Peerstore

Constants

const (

	// TempAddrTTL is the ttl used for a short lived address
	TempAddrTTL = time.Second * 10

	// ProviderAddrTTL is the TTL of an address we've received from a provider.
	// This is also a temporary address, but lasts longer. After this expires,
	// the records we return will require an extra lookup.
	ProviderAddrTTL = time.Minute * 10

	// RecentlyConnectedAddrTTL is used when we recently connected to a peer.
	// It means that we are reasonably certain of the peer's address.
	RecentlyConnectedAddrTTL = time.Minute * 10

	// OwnObservedAddrTTL is used for our own external addresses observed by peers.
	OwnObservedAddrTTL = time.Minute * 10

	// PermanentAddrTTL is the ttl for a "permanent address" (e.g. bootstrap nodes)
	// if we haven't shipped you an update to ipfs in 356 days
	// we probably arent running the same bootstrap nodes...
	PermanentAddrTTL = time.Hour * 24 * 356

	// ConnectedAddrTTL is the ttl used for the addresses of a peer to whom
	// we're connected directly. This is basically permanent, as we will
	// clear them + re-add under a TempAddrTTL after disconnecting.
	ConnectedAddrTTL = PermanentAddrTTL
)

const (
	// AddressTTL is the expiration time of addresses.
	AddressTTL = time.Hour
)

Variables

var ErrNotFound = errors.New("item not found")

var LatencyEWMASmoothing = 0.1

LatencyEWMASmooting governs the decay of the EWMA (the speed at which it changes). This must be a normalized (0-1) value. 1 is 100% change, 0 is no change.

Functions

func NewMetrics

func NewMetrics() *metrics

func PeerInfoIDs

func PeerInfoIDs(pis []PeerInfo) []peer.ID

Types

type AddrBook

type AddrBook interface {

	// AddAddr calls AddAddrs(p, []ma.Multiaddr{addr}, ttl)
	AddAddr(p peer.ID, addr ma.Multiaddr, ttl time.Duration)

	// AddAddrs gives AddrManager addresses to use, with a given ttl
	// (time-to-live), after which the address is no longer valid.
	// If the manager has a longer TTL, the operation is a no-op for that address
	AddAddrs(p peer.ID, addrs []ma.Multiaddr, ttl time.Duration)

	// SetAddr calls mgr.SetAddrs(p, addr, ttl)
	SetAddr(p peer.ID, addr ma.Multiaddr, ttl time.Duration)

	// SetAddrs sets the ttl on addresses. This clears any TTL there previously.
	// This is used when we receive the best estimate of the validity of an address.
	SetAddrs(p peer.ID, addrs []ma.Multiaddr, ttl time.Duration)

	// Addresses returns all known (and valid) addresses for a given peer
	Addrs(p peer.ID) []ma.Multiaddr

	// AddrStream returns a channel that gets all addresses for a given
	// peer sent on it. If new addresses are added after the call is made
	// they will be sent along through the channel as well.
	AddrStream(context.Context, peer.ID) <-chan ma.Multiaddr

	// ClearAddresses removes all previously stored addresses
	ClearAddrs(p peer.ID)
}

AddrBook is an interface that fits the new AddrManager. I'm patching it up in here to avoid changing a ton of the codebase.

type AddrManager

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

AddrManager manages addresses. The zero-value is ready to be used.

func (*AddrManager) AddAddr

func (mgr *AddrManager) AddAddr(p peer.ID, addr ma.Multiaddr, ttl time.Duration)

AddAddr calls AddAddrs(p, []ma.Multiaddr{addr}, ttl)

func (*AddrManager) AddAddrs

func (mgr *AddrManager) AddAddrs(p peer.ID, addrs []ma.Multiaddr, ttl time.Duration)

AddAddrs gives AddrManager addresses to use, with a given ttl (time-to-live), after which the address is no longer valid. If the manager has a longer TTL, the operation is a no-op for that address

func (*AddrManager) AddrStream

func (mgr *AddrManager) AddrStream(ctx context.Context, p peer.ID) <-chan ma.Multiaddr

func (*AddrManager) Addrs

func (mgr *AddrManager) Addrs(p peer.ID) []ma.Multiaddr

Addresses returns all known (and valid) addresses for a given

func (*AddrManager) ClearAddrs

func (mgr *AddrManager) ClearAddrs(p peer.ID)

ClearAddresses removes all previously stored addresses

func (*AddrManager) Peers

func (mgr *AddrManager) Peers() []peer.ID

func (*AddrManager) SetAddr

func (mgr *AddrManager) SetAddr(p peer.ID, addr ma.Multiaddr, ttl time.Duration)

SetAddr calls mgr.SetAddrs(p, addr, ttl)

func (*AddrManager) SetAddrs

func (mgr *AddrManager) SetAddrs(p peer.ID, addrs []ma.Multiaddr, ttl time.Duration)

SetAddrs sets the ttl on addresses. This clears any TTL there previously. This is used when we receive the best estimate of the validity of an address.

type KeyBook

type KeyBook interface {
	PubKey(peer.ID) ic.PubKey
	AddPubKey(peer.ID, ic.PubKey) error

	PrivKey(peer.ID) ic.PrivKey
	AddPrivKey(peer.ID, ic.PrivKey) error
}

KeyBook tracks the Public keys of Peers.

type Metrics

type Metrics interface {

	// RecordLatency records a new latency measurement
	RecordLatency(peer.ID, time.Duration)

	// LatencyEWMA returns an exponentially-weighted moving avg.
	// of all measurements of a peer's latency.
	LatencyEWMA(peer.ID) time.Duration
}

Metrics is just an object that tracks metrics across a set of peers.

type PeerInfo

type PeerInfo struct {
	ID    peer.ID
	Addrs []ma.Multiaddr
}

PeerInfo is a small struct used to pass around a peer with a set of addresses (and later, keys?). This is not meant to be a complete view of the system, but rather to model updates to the peerstore. It is used by things like the routing system.

func PeerInfos

func PeerInfos(ps Peerstore, peers []peer.ID) []PeerInfo

func (*PeerInfo) Loggable

func (pi *PeerInfo) Loggable() map[string]interface{}

func (*PeerInfo) MarshalJSON

func (pi *PeerInfo) MarshalJSON() ([]byte, error)

func (*PeerInfo) UnmarshalJSON

func (pi *PeerInfo) UnmarshalJSON(b []byte) error

type Peerstore

type Peerstore interface {
	AddrBook
	KeyBook
	Metrics

	// Peers returns a list of all peer.IDs in this Peerstore
	Peers() []peer.ID

	// PeerInfo returns a peer.PeerInfo struct for given peer.ID.
	// This is a small slice of the information Peerstore has on
	// that peer, useful to other services.
	PeerInfo(peer.ID) PeerInfo

	// Get/Put is a simple registry for other peer-related key/value pairs.
	// if we find something we use often, it should become its own set of
	// methods. this is a last resort.
	Get(id peer.ID, key string) (interface{}, error)
	Put(id peer.ID, key string, val interface{}) error

	GetProtocols(peer.ID) ([]string, error)
	AddProtocols(peer.ID, ...string) error
	SetProtocols(peer.ID, ...string) error
	SupportsProtocols(peer.ID, ...string) ([]string, error)
}

Peerstore provides a threadsafe store of Peer related information.

func NewPeerstore

func NewPeerstore() Peerstore

NewPeerstore creates a threadsafe collection of peers.