netconf

Documentation

Index

• Constants
• func AllFlagNames() []string
• func BuildFlagName(keys ...string) string
• func InitializeNetworkFlags(flags *pflag.FlagSet, config *Config)
• func LoadLibP2PResourceManagerFlags(flags *pflag.FlagSet, config *Config)
• func SetAliases(conf *viper.Viper) error
• type AlspConfig
• type Config
• type ConnectionManager
• type RateLimiter
• type SyncEngineAlspConfig
• type Unicast
• type UnicastManager

Constants

const (
	DryRunKey          = "dry-run"
	LockoutDurationKey = "lockout-duration"

	BandwidthRateLimitKey  = "bandwidth-rate-limit"
	BandwidthBurstLimitKey = "bandwidth-burst-limit"
)

const (
	MessageTimeoutKey = "message-timeout"
)

Functions

func AllFlagNames

func AllFlagNames() []string

func BuildFlagName

func BuildFlagName(keys ...string) string

func InitializeNetworkFlags

func InitializeNetworkFlags(flags *pflag.FlagSet, config *Config)

InitializeNetworkFlags initializes all CLI flags for the Flow network configuration on the provided pflag set. Args:

*pflag.FlagSet: the pflag set of the Flow node.
*Config: the default network config used to set default values on the flags

func LoadLibP2PResourceManagerFlags

func LoadLibP2PResourceManagerFlags(flags *pflag.FlagSet, config *Config)

LoadLibP2PResourceManagerFlags loads all CLI flags for the libp2p resource manager configuration on the provided pflag set. Args: *pflag.FlagSet: the pflag set of the Flow node. *Config: the default network config used to set default values on the flags

func SetAliases

func SetAliases(conf *viper.Viper) error

SetAliases this func sets an aliases for each CLI flag defined for network config overrides to it's corresponding full key in the viper config store. This is required because in our p2pconfig.yml file all configuration values for the Flow network are stored one level down on the network-config property. When the default config is bootstrapped viper will store these values with the "network-p2pconfig." prefix on the config key, because we do not want to use CLI flags like --network-p2pconfig.networking-connection-pruning to override default values we instead use cleans flags like --networking-connection-pruning and create an alias from networking-connection-pruning -> network-p2pconfig.networking-connection-pruning to ensure overrides happen as expected. Args: *viper.Viper: instance of the viper store to register network config aliases on. Returns: error: if a flag does not have a corresponding key in the viper store; all returned errors are fatal.

Types

type AlspConfig

type AlspConfig struct {
	// Size of the cache for spam records. There is at most one spam record per authorized (i.e., staked) node.
	// Recommended size is 10 * number of authorized nodes to allow for churn.
	SpamRecordCacheSize uint32 `mapstructure:"alsp-spam-record-cache-size"`

	// SpamReportQueueSize is the size of the queue for spam records. The queue is used to store spam records
	// temporarily till they are picked by the workers. When the queue is full, new spam records are dropped.
	// Recommended size is 100 * number of authorized nodes to allow for churn.
	SpamReportQueueSize uint32 `mapstructure:"alsp-spam-report-queue-size"`

	// DisablePenalty indicates whether applying the penalty to the misbehaving node is disabled.
	// When disabled, the ALSP module logs the misbehavior reports and updates the metrics, but does not apply the penalty.
	// This is useful for managing production incidents.
	// Note: under normal circumstances, the ALSP module should not be disabled.
	DisablePenalty bool `mapstructure:"alsp-disable-penalty"`

	// HeartBeatInterval is the interval between heartbeats sent by the ALSP module. The heartbeats are recurring
	// events that are used to perform critical ALSP tasks, such as updating the spam records cache.
	HearBeatInterval time.Duration `mapstructure:"alsp-heart-beat-interval"`

	SyncEngine SyncEngineAlspConfig `mapstructure:",squash"`
}

AlspConfig is the config for the Application Layer Spam Prevention (ALSP) protocol.

type Config

type Config struct {
	Unicast           Unicast                         `mapstructure:"unicast"`
	ResourceManager   p2pconfig.ResourceManagerConfig `mapstructure:"libp2p-resource-manager"`
	ConnectionManager ConnectionManager               `mapstructure:"connection-manager"`
	// GossipSub core gossipsub configuration.
	GossipSub  p2pconfig.GossipSubParameters `mapstructure:"gossipsub"`
	AlspConfig `mapstructure:",squash"`

	// NetworkConnectionPruning determines whether connections to nodes
	// that are not part of protocol state should be trimmed
	// TODO: solely a fallback mechanism, can be removed upon reliable behavior in production.
	NetworkConnectionPruning bool `mapstructure:"networking-connection-pruning"`
	// PreferredUnicastProtocols list of unicast protocols in preferred order
	PreferredUnicastProtocols       []string      `mapstructure:"preferred-unicast-protocols"`
	NetworkReceivedMessageCacheSize uint32        `validate:"gt=0" mapstructure:"received-message-cache-size"`
	PeerUpdateInterval              time.Duration `validate:"gt=0s" mapstructure:"peerupdate-interval"`

	DNSCacheTTL time.Duration `validate:"gt=0s" mapstructure:"dns-cache-ttl"`
	// DisallowListNotificationCacheSize size of the queue for notifications about new peers in the disallow list.
	DisallowListNotificationCacheSize uint32 `validate:"gt=0" mapstructure:"disallow-list-notification-cache-size"`
}

Config encapsulation of configuration structs for all components related to the Flow network.

type ConnectionManager

type ConnectionManager struct {
	// HighWatermark and LowWatermark govern the number of connections are maintained by the ConnManager.
	// When the peer count exceeds the HighWatermark, as many peers will be pruned (and
	// their connections terminated) until LowWatermark peers remain. In other words, whenever the
	// peer count is x > HighWatermark, the ConnManager will prune x - LowWatermark peers.
	// The pruning algorithm is as follows:
	// 1. The ConnManager will not prune any peers that have been connected for less than GracePeriod.
	// 2. The ConnManager will not prune any peers that are protected.
	// 3. The ConnManager will sort the peers based on their number of streams and direction of connections, and
	// prunes the peers with the least number of streams. If there are ties, the peer with the incoming connection
	// will be pruned. If both peers have incoming connections, and there are still ties, one of the peers will be
	// pruned at random.
	// Algorithm implementation is in https://github.com/libp2p/go-libp2p/blob/master/p2p/net/connmgr/connmgr.go#L262-L318
	HighWatermark int `mapstructure:"high-watermark"` // naming from libp2p
	LowWatermark  int `mapstructure:"low-watermark"`  // naming from libp2p

	// SilencePeriod is a regular interval that the connection manager will check for pruning peers if the number of peers exceeds the high-watermark.
	// It is a regular interval.
	SilencePeriod time.Duration `mapstructure:"silence-period"` // naming from libp2p
	// GracePeriod is the time to wait before a new connection is considered for pruning.
	GracePeriod time.Duration `mapstructure:"grace-period"` // naming from libp2p
}

type RateLimiter

type RateLimiter struct {
	// DryRun setting this to true will disable connection disconnects and gating when unicast rate limiters are configured
	DryRun bool `mapstructure:"dry-run"`
	// LockoutDuration the number of seconds a peer will be forced to wait before being allowed to successfully reconnect to the node
	// after being rate limited.
	LockoutDuration time.Duration `validate:"gte=0" mapstructure:"lockout-duration"`
	// MessageRateLimit amount of unicast messages that can be sent by a peer per second.
	MessageRateLimit int `validate:"gte=0" mapstructure:"message-rate-limit"`
	// BandwidthRateLimit bandwidth size in bytes a peer is allowed to send via unicast streams per second.
	BandwidthRateLimit int `validate:"gte=0" mapstructure:"bandwidth-rate-limit"`
	// BandwidthBurstLimit bandwidth size in bytes a peer is allowed to send via unicast streams at once.
	BandwidthBurstLimit int `validate:"gte=0" mapstructure:"bandwidth-burst-limit"`
}

RateLimiter unicast rate limiter configuration for the message and bandwidth rate limiters.

type SyncEngineAlspConfig

type SyncEngineAlspConfig struct {
	// BatchRequestBaseProb is the base probability in [0,1] that's used in creating the final probability of creating a
	// misbehavior report for a BatchRequest message. This is why the word "base" is used in the name of this field,
	// since it's not the final probability and there are other factors that determine the final probability.
	// The reason for this is that we want to increase the probability of creating a misbehavior report for a large batch.
	BatchRequestBaseProb float32 `validate:"gte=0,lte=1" mapstructure:"alsp-sync-engine-batch-request-base-prob"`

	// RangeRequestBaseProb is the base probability in [0,1] that's used in creating the final probability of creating a
	// misbehavior report for a RangeRequest message. This is why the word "base" is used in the name of this field,
	// since it's not the final probability and there are other factors that determine the final probability.
	// The reason for this is that we want to increase the probability of creating a misbehavior report for a large range.
	RangeRequestBaseProb float32 `validate:"gte=0,lte=1" mapstructure:"alsp-sync-engine-range-request-base-prob"`

	// SyncRequestProb is the probability in [0,1] of creating a misbehavior report for a SyncRequest message.
	SyncRequestProb float32 `validate:"gte=0,lte=1" mapstructure:"alsp-sync-engine-sync-request-prob"`
}

SyncEngineAlspConfig is the ALSP config for the SyncEngine.

type Unicast

type Unicast struct {
	// RateLimiter configuration for all unicast rate limiters.
	RateLimiter RateLimiter `mapstructure:"rate-limiter"`

	// UnicastManager configuration for the unicast manager. The unicast manager is responsible for establishing unicast streams.
	UnicastManager UnicastManager `mapstructure:"manager"`

	// EnableStreamProtection enables stream protection for unicast streams. When enabled, all connections that are being established or
	// have been already established for unicast streams are protected, meaning that they won't be closed by the connection manager.
	// This is useful for preventing the connection manager from closing unicast streams that are being used by the application layer.
	// However, it may interfere with the resource manager of libp2p, i.e., the connection manager may not be able to close connections
	// that are not being used by the application layer while at the same time the node is running out of resources for new connections.
	EnableStreamProtection bool `mapstructure:"enable-stream-protection"`

	MessageTimeout time.Duration `validate:"gt=0s" mapstructure:"message-timeout"`
}

Unicast configuration parameters for the unicast protocol.

type UnicastManager

type UnicastManager struct {
	// CreateStreamBackoffDelay initial delay used in the exponential backoff for create stream retries.
	CreateStreamBackoffDelay time.Duration `validate:"gt=0s" mapstructure:"create-stream-retry-delay"`
	// StreamZeroRetryResetThreshold is the threshold that determines when to reset the stream creation retry budget to the default value.
	//
	// For example the default value of 100 means that if the stream creation retry budget is decreased to 0, then it will be reset to default value
	// when the number of consecutive successful streams reaches 100.
	//
	// This is to prevent the retry budget from being reset too frequently, as the retry budget is used to gauge the reliability of the stream creation.
	// When the stream creation retry budget is reset to the default value, it means that the stream creation is reliable enough to be trusted again.
	// This parameter mandates when the stream creation is reliable enough to be trusted again; i.e., when the number of consecutive successful streams reaches this threshold.
	// Note that the counter is reset to 0 when the stream creation fails, so the value of for example 100 means that the stream creation is reliable enough that the recent
	// 100 stream creations are all successful.
	StreamZeroRetryResetThreshold uint64 `validate:"gt=0" mapstructure:"stream-zero-retry-reset-threshold"`
	// MaxStreamCreationRetryAttemptTimes is the maximum number of attempts to be made to create a stream to a remote node over a direct unicast (1:1) connection before we give up.
	MaxStreamCreationRetryAttemptTimes uint64 `validate:"gt=1" mapstructure:"max-stream-creation-retry-attempt-times"`
	// ConfigCacheSize is the cache size of the dial config cache that keeps the individual dial config for each peer.
	ConfigCacheSize uint32 `validate:"gt=0" mapstructure:"dial-config-cache-size"`
}

UnicastManager configuration for the unicast manager. The unicast manager is responsible for establishing unicast streams.