github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/network/p2p/consumers.go (about)

     1  package p2p
     2  
     3  import (
     4  	"github.com/libp2p/go-libp2p/core/peer"
     5  
     6  	p2pmsg "github.com/onflow/flow-go/network/p2p/message"
     7  )
     8  
     9  // CtrlMsgTopicType represents the type of the topic within a control message.
    10  type CtrlMsgTopicType uint64
    11  
    12  const (
    13  	// CtrlMsgNonClusterTopicType represents a non-cluster-prefixed topic.
    14  	CtrlMsgNonClusterTopicType CtrlMsgTopicType = iota
    15  	// CtrlMsgTopicTypeClusterPrefixed represents a cluster-prefixed topic.
    16  	CtrlMsgTopicTypeClusterPrefixed
    17  )
    18  
    19  func (t CtrlMsgTopicType) String() string {
    20  	switch t {
    21  	case CtrlMsgNonClusterTopicType:
    22  		return "non-cluster-prefixed"
    23  	case CtrlMsgTopicTypeClusterPrefixed:
    24  		return "cluster-prefixed"
    25  	default:
    26  		return "unknown"
    27  	}
    28  }
    29  
    30  // InvCtrlMsgNotif is the notification sent to the consumer when an invalid control message is received.
    31  // It models the information that is available to the consumer about a misbehaving peer.
    32  type InvCtrlMsgNotif struct {
    33  	// PeerID is the ID of the peer that sent the invalid control message.
    34  	PeerID peer.ID
    35  	// Error the error that occurred during validation.
    36  	Error error
    37  	// MsgType the control message type.
    38  	MsgType p2pmsg.ControlMessageType
    39  	// Count the number of errors.
    40  	Count uint64
    41  	// TopicType reports whether the error occurred on a cluster-prefixed topic within the control message.
    42  	// Notifications must be explicitly marked as cluster-prefixed or not because the penalty applied to the GossipSub score
    43  	// for an error on a cluster-prefixed topic is more lenient than the penalty applied to a non-cluster-prefixed topic.
    44  	// This distinction ensures that nodes engaged in cluster-prefixed topic communication are not penalized too harshly,
    45  	// as such communication is vital to the progress of the chain.
    46  	TopicType CtrlMsgTopicType
    47  }
    48  
    49  // NewInvalidControlMessageNotification returns a new *InvCtrlMsgNotif
    50  // Args:
    51  //   - peerID: peer id of the offender.
    52  //   - ctlMsgType: the control message type of the rpc message that caused the error.
    53  //   - err: the error that occurred.
    54  //   - count: the number of occurrences of the error.
    55  //
    56  // Returns:
    57  //   - *InvCtlMsgNotif: invalid control message notification.
    58  func NewInvalidControlMessageNotification(peerID peer.ID, ctlMsgType p2pmsg.ControlMessageType, err error, count uint64, topicType CtrlMsgTopicType) *InvCtrlMsgNotif {
    59  	return &InvCtrlMsgNotif{
    60  		PeerID:    peerID,
    61  		Error:     err,
    62  		MsgType:   ctlMsgType,
    63  		Count:     count,
    64  		TopicType: topicType,
    65  	}
    66  }
    67  
    68  // GossipSubInvCtrlMsgNotifConsumer is the interface for the consumer that consumes gossipsub inspector notifications.
    69  // It is used to consume notifications in an asynchronous manner.
    70  // The implementation must be concurrency safe, but can be blocking. This is due to the fact that the consumer is called
    71  // asynchronously by the distributor.
    72  type GossipSubInvCtrlMsgNotifConsumer interface {
    73  	// OnInvalidControlMessageNotification is called when a new invalid control message notification is distributed.
    74  	// Any error on consuming event must handle internally.
    75  	// The implementation must be concurrency safe and non-blocking.
    76  	// Note: there is no real-time guarantee on processing the notification.
    77  	OnInvalidControlMessageNotification(*InvCtrlMsgNotif)
    78  }