validation

package
v0.31.21 Latest Latest
Warning

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

 Go to latest Published: Oct 11, 2023 License: AGPL-3.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// HardThresholdMapKey key used to set the  hard threshold config limit.
	HardThresholdMapKey = "hardthreshold"
	// SafetyThresholdMapKey key used to set the safety threshold config limit.
	SafetyThresholdMapKey = "safetythreshold"
	// RateLimitMapKey key used to set the rate limit config limit.
	RateLimitMapKey = "ratelimit"
	// DefaultGraftHardThreshold upper bound for graft messages, if the RPC control message GRAFTs exceed this threshold  the RPC control message automatically discarded.
	DefaultGraftHardThreshold = 30
	// DefaultGraftSafetyThreshold a lower bound for graft messages, if the amount of GRAFTs in an RPC control message is below this threshold those GRAFTs validation will be bypassed.
	DefaultGraftSafetyThreshold = .5 * DefaultGraftHardThreshold
	// DefaultGraftRateLimit the rate limit for graft control messages.
	// Currently, the default rate limit is equal to the hard threshold amount.
	// This will result in a rate limit of 30 grafts/sec.
	DefaultGraftRateLimit = DefaultGraftHardThreshold

	// DefaultPruneHardThreshold upper bound for prune messages, if the RPC control message PRUNEs exceed this threshold  the RPC control message automatically discarded.
	DefaultPruneHardThreshold = 30
	// DefaultPruneSafetyThreshold a lower bound for prune messages, if the amount of PRUNEs in an RPC control message is below this threshold those GRAFTs validation will be bypassed.
	DefaultPruneSafetyThreshold = .5 * DefaultPruneHardThreshold

	// DefaultClusterPrefixedMsgDropThreshold is the maximum number of cluster-prefixed control messages allowed to be processed
	// when the cluster IDs provider has not been set or a node is behind in the protocol state. If the number of cluster-prefixed
	// control messages in an RPC exceeds this threshold, the entire RPC will be dropped and the node should be penalized.
	DefaultClusterPrefixedMsgDropThreshold = 100
	// DefaultPruneRateLimit the rate limit for prune control messages.
	// Currently, the default rate limit is equal to the hard threshold amount.
	// This will result in a rate limit of 30 prunes/sec.
	DefaultPruneRateLimit = DefaultPruneHardThreshold

	// DefaultIHaveHardThreshold upper bound for ihave messages, the message count for ihave messages
	// exceeds the configured hard threshold only a sample size of the messages will be inspected. This
	// ensures liveness of the network because there is no expected max number of ihave messages than can be
	// received by a node.
	DefaultIHaveHardThreshold = 100
	// DefaultIHaveSafetyThreshold a lower bound for ihave messages, if the amount of iHaves in an RPC control message is below this threshold those GRAFTs validation will be bypassed.
	DefaultIHaveSafetyThreshold = .5 * DefaultIHaveHardThreshold
	// DefaultIHaveRateLimit rate limiting for ihave control messages is disabled.
	DefaultIHaveRateLimit = 0
	// DefaultIHaveSyncInspectSampleSizePercentage the default percentage of ihaves to use as the sample size for synchronous inspection 25%.
	DefaultIHaveSyncInspectSampleSizePercentage = .25
	// DefaultIHaveAsyncInspectSampleSizePercentage the default percentage of ihaves to use as the sample size for asynchronous inspection 10%.
	DefaultIHaveAsyncInspectSampleSizePercentage = .10
	// DefaultIHaveInspectionMaxSampleSize the max number of ihave messages in a sample to be inspected.
	DefaultIHaveInspectionMaxSampleSize = 100
)
View Source 
const (
	// DefaultNumberOfWorkers default number of workers for the inspector component.
	DefaultNumberOfWorkers = 5
	// DefaultControlMsgValidationInspectorQueueCacheSize is the default size of the inspect message queue.
	DefaultControlMsgValidationInspectorQueueCacheSize = 100
	// DefaultClusterPrefixedControlMsgsReceivedCacheSize is the default size of the cluster prefixed topics received record cache.
	DefaultClusterPrefixedControlMsgsReceivedCacheSize = 150
	// DefaultClusterPrefixedControlMsgsReceivedCacheDecay the default cache decay value for cluster prefixed topics received cached counters.
	DefaultClusterPrefixedControlMsgsReceivedCacheDecay = 0.99
)

Variables

This section is empty.

Functions

func IsErrActiveClusterIDsNotSet added in v0.31.0 

func IsErrActiveClusterIDsNotSet(err error) bool

IsErrActiveClusterIDsNotSet returns true if an error is ErrActiveClusterIdsNotSet.

func IsErrDuplicateTopic 

func IsErrDuplicateTopic(err error) bool

IsErrDuplicateTopic returns true if an error is ErrDuplicateTopic.

func IsErrHardThreshold added in v0.31.0 

func IsErrHardThreshold(err error) bool

IsErrHardThreshold returns true if an error is ErrHardThreshold

func IsErrInvalidLimitConfig 

func IsErrInvalidLimitConfig(err error) bool

IsErrInvalidLimitConfig returns whether an error is ErrInvalidLimitConfig.

func IsErrRateLimitedControlMsg 

func IsErrRateLimitedControlMsg(err error) bool

IsErrRateLimitedControlMsg returns whether an error is ErrRateLimitedControlMsg.

func IsErrUnstakedPeer added in v0.31.0 

func IsErrUnstakedPeer(err error) bool

IsErrUnstakedPeer returns true if an error is ErrUnstakedPeer.

Types

type ClusterPrefixedMessageConfig added in v0.31.0 

type ClusterPrefixedMessageConfig struct {
	// ClusterPrefixHardThreshold the upper bound on the amount of cluster prefixed control messages that will be processed
	// before a node starts to get penalized. This allows LN nodes to process some cluster prefixed control messages during startup
	// when the cluster ID's provider is set asynchronously. It also allows processing of some stale messages that may be sent by nodes
	// that fall behind in the protocol. After the amount of cluster prefixed control messages processed exceeds this threshold the node
	// will be pushed to the edge of the network mesh.
	ClusterPrefixHardThreshold float64
	// ClusterPrefixedControlMsgsReceivedCacheSize size of the cache used to track the amount of cluster prefixed topics received by peers.
	ClusterPrefixedControlMsgsReceivedCacheSize uint32
	// ClusterPrefixedControlMsgsReceivedCacheDecay decay val used for the geometric decay of cache counters used to keep track of cluster prefixed topics received by peers.
	ClusterPrefixedControlMsgsReceivedCacheDecay float64
}

ClusterPrefixedMessageConfig configuration values for cluster prefixed control message validation.

type ControlMsgValidationInspector 

type ControlMsgValidationInspector struct {
	component.Component
	events.Noop
	// contains filtered or unexported fields
}

ControlMsgValidationInspector RPC message inspector that inspects control messages and performs some validation on them, when some validation rule is broken feedback is given via the Peer scoring notifier.

func NewControlMsgValidationInspector 

func NewControlMsgValidationInspector(
	logger zerolog.Logger,
	sporkID flow.Identifier,
	config *ControlMsgValidationInspectorConfig,
	distributor p2p.GossipSubInspectorNotifDistributor,
	clusterPrefixedCacheCollector module.HeroCacheMetrics,
	idProvider module.IdentityProvider,
	inspectorMetrics module.GossipSubRpcValidationInspectorMetrics) (*ControlMsgValidationInspector, error)

NewControlMsgValidationInspector returns new ControlMsgValidationInspector Args:

  • logger: the logger used by the inspector.
  • sporkID: the current spork ID.
  • config: inspector configuration.
  • distributor: gossipsub inspector notification distributor.
  • clusterPrefixedCacheCollector: metrics collector for the underlying cluster prefix received tracker cache.
  • idProvider: identity provider is used to get the flow identifier for a peer.

Returns:

  • *ControlMsgValidationInspector: a new control message validation inspector.
  • error: an error if there is any error while creating the inspector. All errors are irrecoverable and unexpected.

func (*ControlMsgValidationInspector) ActiveClustersChanged added in v0.31.0 

func (c *ControlMsgValidationInspector) ActiveClustersChanged(clusterIDList flow.ChainIDList)

ClusterIdsUpdated consumes cluster ID update protocol events.

func (*ControlMsgValidationInspector) Inspect 

func (c *ControlMsgValidationInspector) Inspect(from peer.ID, rpc *pubsub.RPC) error

Inspect is called by gossipsub upon reception of an rpc from a remote node. It examines the provided message to ensure it adheres to the expected format and conventions. If the message passes validation, the method returns a nil error. If an issue is found, the method returns an error detailing the specific issue encountered. The returned error can be of two types:

  1. Expected errors: These are issues that are expected to occur during normal operation, such as invalid messages or messages that don't follow the conventions. These errors should be handled gracefully by the caller.
  2. Exceptions: These are unexpected issues, such as internal system errors or misconfigurations, that may require immediate attention or a change in the system's behavior. The caller should log and handle these errors accordingly.

The returned error is returned to the gossipsub node which causes the rejection of rpc (for non-nil errors).

func (*ControlMsgValidationInspector) Name 

func (c *ControlMsgValidationInspector) Name() string

Name returns the name of the rpc inspector.

type ControlMsgValidationInspectorConfig 

type ControlMsgValidationInspectorConfig struct {
	*ClusterPrefixedMessageConfig
	// NumberOfWorkers number of component workers to start for processing RPC messages.
	NumberOfWorkers int
	// InspectMsgStoreOpts options used to configure the underlying herocache message store.
	InspectMsgStoreOpts []queue.HeroStoreConfigOption
	// GraftValidationCfg validation configuration for GRAFT control messages.
	GraftValidationCfg *CtrlMsgValidationConfig
	// PruneValidationCfg validation configuration for PRUNE control messages.
	PruneValidationCfg *CtrlMsgValidationConfig
	// IHaveValidationCfg validation configuration for IHAVE control messages.
	IHaveValidationCfg *CtrlMsgValidationConfig
}

ControlMsgValidationInspectorConfig validation configuration for each type of RPC control message.

type CtrlMsgValidationConfig 

type CtrlMsgValidationConfig struct {
	// ControlMsg the type of RPC control message.
	ControlMsg p2p.ControlMessageType
	// HardThreshold specifies the hard limit for the size of an RPC control message.
	// While it is generally expected that RPC messages with a size greater than HardThreshold should be dropped,
	// there are exceptions. For instance, if the message is an 'iHave', blocking processing is performed
	// on a sample of the control message rather than dropping it.
	HardThreshold uint64
	// SafetyThreshold specifies the lower limit for the size of the RPC control message, it is safe to skip validation for any RPC messages
	// with a size < SafetyThreshold. These messages will be processed as soon as possible.
	SafetyThreshold uint64
	// IHaveSyncInspectSampleSizePercentage the percentage of topics to sample for synchronous pre-processing of 'iHave' control messages. 'iHave' control messages
	// don't have an upper bound on the amount of 'iHaves' expected from a peer during normal operation. Due to this fact it is important to validate a sample percentage
	// of 'iHave' messages to ensure liveness of the network.
	IHaveSyncInspectSampleSizePercentage float64
	// IHaveAsyncInspectSampleSizePercentage  the percentage of topics to sample for asynchronous processing of 'iHave' control messages. 'iHave' control messages
	// don't have an upper bound on the amount of 'iHaves' expected from a peer during normal operation. Due to this fact it is important to validate a sample percentage
	// of 'iHave' messages to ensure liveness of the network.
	IHaveAsyncInspectSampleSizePercentage float64
	// IHaveInspectionMaxSampleSize the maximum size of the sample set of 'iHave' messages that will be validated.
	IHaveInspectionMaxSampleSize float64
	// RateLimiter basic limiter without lockout duration.
	RateLimiter p2p.BasicRateLimiter
}

CtrlMsgValidationConfig configuration values for upper, lower threshold and rate limit.

func NewCtrlMsgValidationConfig 

func NewCtrlMsgValidationConfig(controlMsg p2p.ControlMessageType, cfgLimitValues CtrlMsgValidationLimits, opts ...CtrlMsgValidationConfigOption) (*CtrlMsgValidationConfig, error)

NewCtrlMsgValidationConfig validates each config value before returning a new CtrlMsgValidationConfig. errors returned: 

ErrValidationLimit - if any of the validation limits provided are less than 0. This error is non-recoverable
and the node should crash if this error is encountered.

type CtrlMsgValidationConfigOption added in v0.31.0 

type CtrlMsgValidationConfigOption func(*CtrlMsgValidationConfig)

CtrlMsgValidationConfigOption options to set config values for a specific control message type.

func WithIHaveAsyncInspectSampleSizePercentage added in v0.31.0 

func WithIHaveAsyncInspectSampleSizePercentage(percentage float64) CtrlMsgValidationConfigOption

WithIHaveAsyncInspectSampleSizePercentage option to set the IHaveAsyncInspectSampleSizePercentage for ihave control message config.

func WithIHaveInspectionMaxSampleSize added in v0.31.0 

func WithIHaveInspectionMaxSampleSize(maxSampleSize float64) CtrlMsgValidationConfigOption

WithIHaveInspectionMaxSampleSize option to set the IHaveInspectionMaxSampleSize for ihave control message config.

func WithIHaveSyncInspectSampleSizePercentage added in v0.31.0 

func WithIHaveSyncInspectSampleSizePercentage(percentage float64) CtrlMsgValidationConfigOption

WithIHaveSyncInspectSampleSizePercentage option to set the IHaveSyncInspectSampleSizePercentage for ihave control message config.

type CtrlMsgValidationConfigs 

type CtrlMsgValidationConfigs []*CtrlMsgValidationConfig

CtrlMsgValidationConfigs list of *CtrlMsgValidationConfig

type CtrlMsgValidationLimits 

type CtrlMsgValidationLimits map[string]int

CtrlMsgValidationLimits limits used to construct control message validation configuration.

func (CtrlMsgValidationLimits) HardThreshold added in v0.31.0 

func (c CtrlMsgValidationLimits) HardThreshold() uint64

func (CtrlMsgValidationLimits) RateLimit 

func (c CtrlMsgValidationLimits) RateLimit() int

func (CtrlMsgValidationLimits) SafetyThreshold 

func (c CtrlMsgValidationLimits) SafetyThreshold() uint64

type ErrActiveClusterIdsNotSet added in v0.31.0 

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

ErrActiveClusterIdsNotSet error that indicates a cluster prefixed control message has been received but the cluster IDs have not been set yet.

func NewActiveClusterIdsNotSetErr added in v0.31.0 

func NewActiveClusterIdsNotSetErr(topic channels.Topic) ErrActiveClusterIdsNotSet

NewActiveClusterIdsNotSetErr returns a new ErrActiveClusterIdsNotSet.

func (ErrActiveClusterIdsNotSet) Error added in v0.31.0 

func (e ErrActiveClusterIdsNotSet) Error() string

type ErrDuplicateTopic 

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

ErrDuplicateTopic error that indicates a duplicate topic in control message has been detected.

func NewDuplicateTopicErr added in v0.31.0 

func NewDuplicateTopicErr(topic channels.Topic) ErrDuplicateTopic

NewDuplicateTopicErr returns a new ErrDuplicateTopic.

func (ErrDuplicateTopic) Error 

func (e ErrDuplicateTopic) Error() string

type ErrHardThreshold added in v0.31.0 

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

ErrHardThreshold indicates that the amount of RPC messages received exceeds hard threshold.

func NewHardThresholdErr added in v0.31.0 

func NewHardThresholdErr(controlMsg p2p.ControlMessageType, amount, hardThreshold uint64) ErrHardThreshold

NewHardThresholdErr returns a new ErrHardThreshold.

func (ErrHardThreshold) Error added in v0.31.0 

func (e ErrHardThreshold) Error() string

type ErrInvalidLimitConfig 

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

ErrInvalidLimitConfig indicates the validation limit is < 0.

func NewInvalidLimitConfigErr 

func NewInvalidLimitConfigErr(controlMsg p2p.ControlMessageType, limitStr string, limit uint64) ErrInvalidLimitConfig

NewInvalidLimitConfigErr returns a new ErrValidationLimit.

func (ErrInvalidLimitConfig) Error 

func (e ErrInvalidLimitConfig) Error() string

type ErrRateLimitedControlMsg 

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

ErrRateLimitedControlMsg indicates the specified RPC control message is rate limited for the specified peer.

func NewRateLimitedControlMsgErr 

func NewRateLimitedControlMsgErr(controlMsg p2p.ControlMessageType) ErrRateLimitedControlMsg

NewRateLimitedControlMsgErr returns a new ErrValidationLimit.

func (ErrRateLimitedControlMsg) Error 

func (e ErrRateLimitedControlMsg) Error() string

type ErrUnstakedPeer added in v0.31.0 

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

ErrUnstakedPeer error that indicates a cluster prefixed control message has been from an unstaked peer.

func NewUnstakedPeerErr added in v0.31.0 

func NewUnstakedPeerErr(err error) ErrUnstakedPeer

NewUnstakedPeerErr returns a new ErrUnstakedPeer.

func (ErrUnstakedPeer) Error added in v0.31.0 

func (e ErrUnstakedPeer) Error() string

type InspectMsgRequest 

type InspectMsgRequest struct {
	// Nonce adds random value so that when msg req is stored on hero store a unique ID can be created from the struct fields.
	Nonce []byte
	// Peer sender of the message.
	Peer peer.ID
	// contains filtered or unexported fields
}

InspectMsgRequest represents a short digest of an RPC control message. It is used for further message inspection by component workers.

func NewInspectMsgRequest 

func NewInspectMsgRequest(from peer.ID, validationConfig *CtrlMsgValidationConfig, ctrlMsg *pubsub_pb.ControlMessage) (*InspectMsgRequest, error)

NewInspectMsgRequest returns a new *InspectMsgRequest.

Source Files

View all Source files

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.