github.com/koko1123/flow-go-1@v0.29.6/network/p2p/pubsub.go (about)

     1  package p2p
     2  
     3  import (
     4  	"context"
     5  
     6  	pubsub "github.com/libp2p/go-libp2p-pubsub"
     7  	pb "github.com/libp2p/go-libp2p-pubsub/pb"
     8  	"github.com/libp2p/go-libp2p/core/peer"
     9  	"github.com/libp2p/go-libp2p/core/routing"
    10  )
    11  
    12  type ValidationResult int
    13  
    14  const (
    15  	ValidationAccept ValidationResult = iota
    16  	ValidationIgnore
    17  	ValidationReject
    18  )
    19  
    20  type TopicValidatorFunc func(context.Context, peer.ID, *pubsub.Message) ValidationResult
    21  
    22  // PubSubAdapter is the abstraction of the underlying pubsub logic that is used by the Flow network.
    23  type PubSubAdapter interface {
    24  	// RegisterTopicValidator registers a validator for topic.
    25  	RegisterTopicValidator(topic string, topicValidator TopicValidatorFunc) error
    26  
    27  	// UnregisterTopicValidator removes a validator from a topic.
    28  	// Returns an error if there was no validator registered with the topic.
    29  	UnregisterTopicValidator(topic string) error
    30  
    31  	// Join joins the topic and returns a Topic handle.
    32  	// Only one Topic handle should exist per topic, and Join will error if the Topic handle already exists.
    33  	Join(topic string) (Topic, error)
    34  
    35  	// GetTopics returns all the topics within the pubsub network that the current peer has subscribed to.
    36  	GetTopics() []string
    37  
    38  	// ListPeers returns all the peers subscribed to a topic.
    39  	// Note that the current peer must be subscribed to the topic for it to query for other peers.
    40  	// If the current peer is not subscribed to the topic, an empty list is returned.
    41  	// For example, if current peer has subscribed to topics A and B, then ListPeers only return
    42  	// subscribed peers for topics A and B, and querying for topic C will return an empty list.
    43  	ListPeers(topic string) []peer.ID
    44  }
    45  
    46  // PubSubAdapterConfig abstracts the configuration for the underlying pubsub implementation.
    47  type PubSubAdapterConfig interface {
    48  	WithRoutingDiscovery(routing.ContentRouting)
    49  	WithSubscriptionFilter(SubscriptionFilter)
    50  	WithScoreOption(ScoreOptionBuilder)
    51  	WithMessageIdFunction(f func([]byte) string)
    52  	WithAppSpecificRpcInspector(f func(peer.ID, *pubsub.RPC) error)
    53  }
    54  
    55  // Topic is the abstraction of the underlying pubsub topic that is used by the Flow network.
    56  type Topic interface {
    57  	// String returns the topic name as a string.
    58  	String() string
    59  
    60  	// Close closes the topic.
    61  	Close() error
    62  
    63  	// Publish publishes a message to the topic.
    64  	Publish(context.Context, []byte) error
    65  
    66  	// Subscribe returns a subscription to the topic so that the caller can receive messages from the topic.
    67  	Subscribe() (Subscription, error)
    68  }
    69  
    70  // ScoreOptionBuilder abstracts the configuration for the underlying pubsub score implementation.
    71  type ScoreOptionBuilder interface {
    72  	// BuildFlowPubSubScoreOption builds the pubsub score options as pubsub.Option for the Flow network.
    73  	BuildFlowPubSubScoreOption() pubsub.Option
    74  }
    75  
    76  // Subscription is the abstraction of the underlying pubsub subscription that is used by the Flow network.
    77  type Subscription interface {
    78  	// Cancel cancels the subscription so that the caller will no longer receive messages from the topic.
    79  	Cancel()
    80  
    81  	// Topic returns the topic that the subscription is subscribed to.
    82  	Topic() string
    83  
    84  	// Next returns the next message from the subscription.
    85  	Next(context.Context) (*pubsub.Message, error)
    86  }
    87  
    88  // BasePubSubAdapterConfig is the base configuration for the underlying pubsub implementation.
    89  // These configurations are common to all pubsub implementations and must be observed by all implementations.
    90  type BasePubSubAdapterConfig struct {
    91  	// MaxMessageSize is the maximum size of a message that can be sent on the pubsub network.
    92  	MaxMessageSize int
    93  }
    94  
    95  // SubscriptionFilter is the abstraction of the underlying pubsub subscription filter that is used by the Flow network.
    96  type SubscriptionFilter interface {
    97  	// CanSubscribe returns true if the current peer can subscribe to the topic.
    98  	CanSubscribe(string) bool
    99  
   100  	// FilterIncomingSubscriptions is invoked for all RPCs containing subscription notifications.
   101  	// It filters and returns the subscriptions of interest to the current node.
   102  	FilterIncomingSubscriptions(peer.ID, []*pb.RPC_SubOpts) ([]*pb.RPC_SubOpts, error)
   103  }