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

     1  package p2p
     2  
     3  import (
     4  	"errors"
     5  	"fmt"
     6  
     7  	"github.com/libp2p/go-libp2p/core/peer"
     8  
     9  	"github.com/onflow/flow-go/model/flow"
    10  	"github.com/onflow/flow-go/module/component"
    11  )
    12  
    13  // SubscriptionProvider provides a list of topics a peer is subscribed to.
    14  type SubscriptionProvider interface {
    15  	component.Component
    16  	// GetSubscribedTopics returns all the subscriptions of a peer within the pubsub network.
    17  	// Note that the current peer must be subscribed to the topic for it to the same topics in order
    18  	// to query for other peers, e.g., if current peer has subscribed to topics A and B, and peer1
    19  	// has subscribed to topics A, B, and C, then GetSubscribedTopics(peer1) will return A and B. Since this peer
    20  	// has not subscribed to topic C, it will not be able to query for other peers subscribed to topic C.
    21  	GetSubscribedTopics(pid peer.ID) []string
    22  }
    23  
    24  // SubscriptionValidator validates the subscription of a peer to a topic.
    25  // It is used to ensure that a peer is only subscribed to topics that it is allowed to subscribe to.
    26  type SubscriptionValidator interface {
    27  	component.Component
    28  	// CheckSubscribedToAllowedTopics checks if a peer is subscribed to topics that it is allowed to subscribe to.
    29  	// Args:
    30  	// 	pid: the peer ID of the peer to check
    31  	//  role: the role of the peer to check
    32  	// Returns:
    33  	// error: if the peer is subscribed to topics that it is not allowed to subscribe to, an InvalidSubscriptionError is returned.
    34  	// The error is benign, i.e., it does not indicate an illegal state in the execution of the code. We expect this error
    35  	// when there are malicious peers in the network. But such errors should not lead to a crash of the node.
    36  	CheckSubscribedToAllowedTopics(pid peer.ID, role flow.Role) error
    37  }
    38  
    39  // TopicProvider provides a low-level abstraction for pubsub to perform topic-related queries.
    40  // This abstraction is provided to encapsulate the pubsub implementation details from the rest of the codebase.
    41  type TopicProvider interface {
    42  	// GetTopics returns all the topics within the pubsub network that the current peer has subscribed to.
    43  	GetTopics() []string
    44  
    45  	// ListPeers returns all the peers subscribed to a topic.
    46  	// Note that the current peer must be subscribed to the topic for it to query for other peers.
    47  	// If the current peer is not subscribed to the topic, an empty list is returned.
    48  	// For example, if current peer has subscribed to topics A and B, then ListPeers only return
    49  	// subscribed peers for topics A and B, and querying for topic C will return an empty list.
    50  	ListPeers(topic string) []peer.ID
    51  }
    52  
    53  // InvalidSubscriptionError indicates that a peer has subscribed to a topic that is not allowed for its role.
    54  // This error is benign, i.e., it does not indicate an illegal state in the execution of the code. We expect this error
    55  // when there are malicious peers in the network. But such errors should not lead to a crash of the node.32
    56  type InvalidSubscriptionError struct {
    57  	topic string // the topic that the peer is subscribed to, but not allowed to.
    58  }
    59  
    60  func NewInvalidSubscriptionError(topic string) error {
    61  	return InvalidSubscriptionError{
    62  		topic: topic,
    63  	}
    64  }
    65  
    66  func (e InvalidSubscriptionError) Error() string {
    67  	return fmt.Sprintf("unauthorized subscription: %s", e.topic)
    68  }
    69  
    70  func IsInvalidSubscriptionError(this error) bool {
    71  	var e InvalidSubscriptionError
    72  	return errors.As(this, &e)
    73  }