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

     1  package p2p
     2  
     3  import (
     4  	"context"
     5  
     6  	pubsub "github.com/libp2p/go-libp2p-pubsub"
     7  	"github.com/libp2p/go-libp2p/core/connmgr"
     8  	"github.com/libp2p/go-libp2p/core/host"
     9  	"github.com/libp2p/go-libp2p/core/network"
    10  	"github.com/libp2p/go-libp2p/core/peer"
    11  	"github.com/libp2p/go-libp2p/core/routing"
    12  	madns "github.com/multiformats/go-multiaddr-dns"
    13  	"github.com/rs/zerolog"
    14  
    15  	"github.com/onflow/flow-go/model/flow"
    16  	"github.com/onflow/flow-go/module"
    17  	"github.com/onflow/flow-go/module/irrecoverable"
    18  	"github.com/onflow/flow-go/module/metrics"
    19  	flownet "github.com/onflow/flow-go/network"
    20  	"github.com/onflow/flow-go/network/channels"
    21  	p2pconfig "github.com/onflow/flow-go/network/p2p/config"
    22  )
    23  
    24  type GossipSubFactoryFunc func(context.Context, zerolog.Logger, host.Host, PubSubAdapterConfig, CollectionClusterChangesConsumer) (PubSubAdapter, error)
    25  
    26  // NodeConstructor is a function that creates a new libp2p node.
    27  // Args:
    28  // - config: configuration for the node
    29  // Returns:
    30  // - LibP2PNode: new libp2p node
    31  // - error: error if any, any returned error is irrecoverable.
    32  type NodeConstructor func(config *NodeConfig) (LibP2PNode, error)
    33  type GossipSubAdapterConfigFunc func(*BasePubSubAdapterConfig) PubSubAdapterConfig
    34  
    35  // GossipSubBuilder provides a builder pattern for creating a GossipSub pubsub system.
    36  type GossipSubBuilder interface {
    37  	// SetHost sets the host of the builder.
    38  	// If the host has already been set, a fatal error is logged.
    39  	SetHost(host.Host)
    40  
    41  	// SetSubscriptionFilter sets the subscription filter of the builder.
    42  	// If the subscription filter has already been set, a fatal error is logged.
    43  	SetSubscriptionFilter(pubsub.SubscriptionFilter)
    44  
    45  	// SetGossipSubFactory sets the gossipsub factory of the builder.
    46  	// We expect the node to initialize with a default gossipsub factory. Hence, this function overrides the default config.
    47  	SetGossipSubFactory(GossipSubFactoryFunc)
    48  
    49  	// SetGossipSubConfigFunc sets the gossipsub config function of the builder.
    50  	// We expect the node to initialize with a default gossipsub config. Hence, this function overrides the default config.
    51  	SetGossipSubConfigFunc(GossipSubAdapterConfigFunc)
    52  
    53  	// EnableGossipSubScoringWithOverride enables peer scoring for the GossipSub pubsub system with the given override.
    54  	// Any existing peer scoring config attribute that is set in the override will override the default peer scoring config.
    55  	// Anything that is left to nil or zero value in the override will be ignored and the default value will be used.
    56  	// Note: it is not recommended to override the default peer scoring config in production unless you know what you are doing.
    57  	// Production Tip: use PeerScoringConfigNoOverride as the argument to this function to enable peer scoring without any override.
    58  	// Args:
    59  	// - PeerScoringConfigOverride: override for the peer scoring config- Recommended to use PeerScoringConfigNoOverride for production.
    60  	// Returns:
    61  	// none
    62  	EnableGossipSubScoringWithOverride(*PeerScoringConfigOverride)
    63  
    64  	// SetRoutingSystem sets the routing system of the builder.
    65  	// If the routing system has already been set, a fatal error is logged.
    66  	SetRoutingSystem(routing.Routing)
    67  
    68  	// OverrideDefaultRpcInspectorFactory overrides the default RPC inspector suite factory of the builder.
    69  	// A default RPC inspector suite factory is provided by the node. This function overrides the default factory.
    70  	// The purpose of override is to allow the node to provide a custom RPC inspector suite factory for sake of testing
    71  	// or experimentation.
    72  	// It is NOT recommended to override the default RPC inspector suite factory in production unless you know what you are doing.
    73  	OverrideDefaultRpcInspectorFactory(GossipSubRpcInspectorFactoryFunc)
    74  
    75  	// Build creates a new GossipSub pubsub system.
    76  	// It returns the newly created GossipSub pubsub system and any errors encountered during its creation.
    77  	//
    78  	// Arguments:
    79  	// - context.Context: the irrecoverable context of the node.
    80  	//
    81  	// Returns:
    82  	// - PubSubAdapter: a GossipSub pubsub system for the libp2p node.
    83  	// - error: if an error occurs during the creation of the GossipSub pubsub system, it is returned. Otherwise, nil is returned.
    84  	// Note that on happy path, the returned error is nil. Any error returned is unexpected and should be handled as irrecoverable.
    85  	Build(irrecoverable.SignalerContext) (PubSubAdapter, error)
    86  }
    87  
    88  // GossipSubRpcInspectorFactoryFunc is a function that creates a new RPC inspector. It is used to create
    89  // an RPC inspector for the gossipsub protocol. The RPC inspectors are used to inspect and validate
    90  // incoming RPC messages before they are processed by the gossipsub protocol.
    91  // Args:
    92  // - logger: logger to use
    93  // - sporkID: spork ID of the node
    94  // - cfg: configuration for the RPC inspectors
    95  // - metrics: metrics to use for the RPC inspectors
    96  // - heroCacheMetricsFactory: metrics factory for the hero cache
    97  // - networkingType: networking type of the node, i.e., public or private
    98  // - identityProvider: identity provider of the node
    99  // Returns:
   100  // - GossipSubRPCInspector: new RPC inspector suite
   101  // - error: error if any, any returned error is irrecoverable.
   102  type GossipSubRpcInspectorFactoryFunc func(
   103  	zerolog.Logger,
   104  	flow.Identifier,
   105  	*p2pconfig.RpcInspectorParameters,
   106  	module.GossipSubMetrics,
   107  	metrics.HeroCacheMetricsFactory,
   108  	flownet.NetworkingType,
   109  	module.IdentityProvider,
   110  	func() TopicProvider,
   111  	GossipSubInvCtrlMsgNotifConsumer,
   112  ) (GossipSubRPCInspector, error)
   113  
   114  // NodeBuilder is a builder pattern for creating a libp2p Node instance.
   115  type NodeBuilder interface {
   116  	SetBasicResolver(madns.BasicResolver) NodeBuilder
   117  	SetSubscriptionFilter(pubsub.SubscriptionFilter) NodeBuilder
   118  	SetResourceManager(network.ResourceManager) NodeBuilder
   119  	SetConnectionManager(connmgr.ConnManager) NodeBuilder
   120  	SetConnectionGater(ConnectionGater) NodeBuilder
   121  	SetRoutingSystem(func(context.Context, host.Host) (routing.Routing, error)) NodeBuilder
   122  
   123  	// OverrideGossipSubScoringConfig overrides the default peer scoring config for the GossipSub protocol.
   124  	// Note that it does not enable peer scoring. The peer scoring is enabled directly by setting the `peer-scoring-enabled` flag to true in `default-config.yaml`, or
   125  	// by setting the `gossipsub-peer-scoring-enabled` runtime flag to true. This function only overrides the default peer scoring config which takes effect
   126  	// only if the peer scoring is enabled (mostly for testing purposes).
   127  	// Any existing peer scoring config attribute that is set in the override will override the default peer scoring config.
   128  	// Anything that is left to nil or zero value in the override will be ignored and the default value will be used.
   129  	// Note: it is not recommended to override the default peer scoring config in production unless you know what you are doing.
   130  	// Args:
   131  	// - PeerScoringConfigOverride: override for the peer scoring config- Recommended to use PeerScoringConfigNoOverride for production.
   132  	// Returns:
   133  	// none
   134  	OverrideGossipSubScoringConfig(*PeerScoringConfigOverride) NodeBuilder
   135  
   136  	// OverrideNodeConstructor overrides the default node constructor, i.e., the function that creates a new libp2p node.
   137  	// The purpose of override is to allow the node to provide a custom node constructor for sake of testing or experimentation.
   138  	// It is NOT recommended to override the default node constructor in production unless you know what you are doing.
   139  	// Args:
   140  	// - NodeConstructor: custom node constructor
   141  	// Returns:
   142  	// none
   143  	OverrideNodeConstructor(NodeConstructor) NodeBuilder
   144  
   145  	// OverrideGossipSubFactory overrides the default gossipsub factory for the GossipSub protocol.
   146  	// The purpose of override is to allow the node to provide a custom gossipsub factory for sake of testing or experimentation.
   147  	// Note: it is not recommended to override the default gossipsub factory in production unless you know what you are doing.
   148  	// Args:
   149  	// - factory: custom gossipsub factory
   150  	// Returns:
   151  	// - NodeBuilder: the node builder
   152  	OverrideGossipSubFactory(GossipSubFactoryFunc, GossipSubAdapterConfigFunc) NodeBuilder
   153  
   154  	// OverrideDefaultRpcInspectorFactory overrides the default rpc inspector factory for the GossipSub protocol.
   155  	// The purpose of override is to allow the node to provide a custom rpc inspector factory for sake of testing or experimentation.
   156  	// Note: it is not recommended to override the default rpc inspector factory in production unless you know what you are doing.
   157  	// Args:
   158  	// - factory: custom rpc inspector factory
   159  	// Returns:
   160  	// - NodeBuilder: the node builder
   161  	OverrideDefaultRpcInspectorFactory(GossipSubRpcInspectorFactoryFunc) NodeBuilder
   162  
   163  	// Build creates a new libp2p node. It returns the newly created libp2p node and any errors encountered during its creation.
   164  	// Args:
   165  	// none
   166  	// Returns:
   167  	// - LibP2PNode: a new libp2p node
   168  	// - error: if an error occurs during the creation of the libp2p node, it is returned. Otherwise, nil is returned. Any error returned is unexpected and should be handled as irrecoverable.
   169  	Build() (LibP2PNode, error)
   170  }
   171  
   172  // PeerScoringConfigOverride is a structure that is used to carry over the override values for peer scoring configuration.
   173  // Any attribute that is set in the override will override the default peer scoring config.
   174  // Typically, we are not recommending to override the default peer scoring config in production unless you know what you are doing.
   175  type PeerScoringConfigOverride struct {
   176  	// TopicScoreParams is a map of topic score parameters for each topic.
   177  	// Override criteria: any topic (i.e., key in the map) will override the default topic score parameters for that topic and
   178  	// the corresponding value in the map will be used instead of the default value.
   179  	// If you don't want to override topic score params for a given topic, simply don't include that topic in the map.
   180  	// If the map is nil, the default topic score parameters are used for all topics.
   181  	TopicScoreParams map[channels.Topic]*pubsub.TopicScoreParams
   182  
   183  	// AppSpecificScoreParams is a function that returns the application specific score parameters for a given peer.
   184  	// Override criteria: if the function is not nil, it will override the default application specific score parameters.
   185  	// If the function is nil, the default application specific score parameters are used.
   186  	AppSpecificScoreParams func(peer.ID) float64
   187  }
   188  
   189  // NodeParameters are the numerical values that are used to configure the libp2p node.
   190  type NodeParameters struct {
   191  	EnableProtectedStreams bool `validate:"required"`
   192  }
   193  
   194  // NodeConfig is the configuration for the libp2p node, it contains the parameters as well as the essential components for setting up the node.
   195  // It is used to create a new libp2p node.
   196  type NodeConfig struct {
   197  	Parameters *NodeParameters `validate:"required"`
   198  	// logger used to provide logging
   199  	Logger zerolog.Logger `validate:"required"`
   200  	// reference to the libp2p host (https://godoc.org/github.com/libp2p/go-libp2p/core/host)
   201  	Host                 host.Host `validate:"required"`
   202  	PeerManager          PeerManager
   203  	DisallowListCacheCfg *DisallowListCacheConfig `validate:"required"`
   204  }