connmgr

Documentation

Overview

Package connmgr provides connection tracking and management interfaces for libp2p.

The ConnManager interface exported from this package allows libp2p to enforce an upper bound on the total number of open connections. To avoid service disruptions, connections can be tagged with metadata and optionally "protected" to ensure that essential connections are not arbitrarily cut.

Index

• type ConnManager
• type NullConnMgr
  • func (_ NullConnMgr) Close() error
  • func (_ NullConnMgr) GetTagInfo(peer.ID) *TagInfo
  • func (_ NullConnMgr) Notifee() network.Notifiee
  • func (_ NullConnMgr) Protect(peer.ID, string)
  • func (_ NullConnMgr) TagPeer(peer.ID, string, int)
  • func (_ NullConnMgr) TrimOpenConns(ctx context.Context)
  • func (_ NullConnMgr) Unprotect(peer.ID, string) bool
  • func (_ NullConnMgr) UntagPeer(peer.ID, string)
  • func (_ NullConnMgr) UpsertTag(peer.ID, string, func(int) int)
• type TagInfo

Types

type ConnManager

type ConnManager interface {

	// TagPeer tags a peer with a string, associating a weight with the tag.
	TagPeer(peer.ID, string, int)

	// Untag removes the tagged value from the peer.
	UntagPeer(p peer.ID, tag string)

	// UpsertTag updates an existing tag or inserts a new one.
	//
	// The connection manager calls the upsert function supplying the current
	// value of the tag (or zero if inexistent). The return value is used as
	// the new value of the tag.
	UpsertTag(p peer.ID, tag string, upsert func(int) int)

	// GetTagInfo returns the metadata associated with the peer,
	// or nil if no metadata has been recorded for the peer.
	GetTagInfo(p peer.ID) *TagInfo

	// TrimOpenConns terminates open connections based on an implementation-defined
	// heuristic.
	TrimOpenConns(ctx context.Context)

	// Notifee returns an implementation that can be called back to inform of
	// opened and closed connections.
	Notifee() network.Notifiee

	// Protect protects a peer from having its connection(s) pruned.
	//
	// Tagging allows different parts of the system to manage protections without interfering with one another.
	//
	// Calls to Protect() with the same tag are idempotent. They are not refcounted, so after multiple calls
	// to Protect() with the same tag, a single Unprotect() call bearing the same tag will revoke the protection.
	Protect(id peer.ID, tag string)

	// Unprotect removes a protection that may have been placed on a peer, under the specified tag.
	//
	// The return value indicates whether the peer continues to be protected after this call, by way of a different tag.
	// See notes on Protect() for more info.
	Unprotect(id peer.ID, tag string) (protected bool)

	// Close closes the connection manager and stops background processes
	Close() error
}

ConnManager tracks connections to peers, and allows consumers to associate metadata with each peer.

It enables connections to be trimmed based on implementation-defined heuristics. The ConnManager allows libp2p to enforce an upper bound on the total number of open connections.

type NullConnMgr

type NullConnMgr struct{}

NullConnMgr is a ConnMgr that provides no functionality.

func (NullConnMgr) Close

func (_ NullConnMgr) Close() error

func (NullConnMgr) GetTagInfo

func (_ NullConnMgr) GetTagInfo(peer.ID) *TagInfo

func (NullConnMgr) Notifee

func (_ NullConnMgr) Notifee() network.Notifiee

func (NullConnMgr) Protect

func (_ NullConnMgr) Protect(peer.ID, string)

func (NullConnMgr) TagPeer

func (_ NullConnMgr) TagPeer(peer.ID, string, int)

func (NullConnMgr) TrimOpenConns

func (_ NullConnMgr) TrimOpenConns(ctx context.Context)

func (NullConnMgr) Unprotect

func (_ NullConnMgr) Unprotect(peer.ID, string) bool

func (NullConnMgr) UntagPeer

func (_ NullConnMgr) UntagPeer(peer.ID, string)

func (NullConnMgr) UpsertTag

func (_ NullConnMgr) UpsertTag(peer.ID, string, func(int) int)

type TagInfo

type TagInfo struct {
	FirstSeen time.Time
	Value     int

	// Tags maps tag ids to the numerical values.
	Tags map[string]int

	// Conns maps connection ids (such as remote multiaddr) to their creation time.
	Conns map[string]time.Time
}

TagInfo stores metadata associated with a peer.