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

     1  package network
     2  
     3  import (
     4  	"github.com/onflow/flow-go/model/flow"
     5  	"github.com/onflow/flow-go/module"
     6  	"github.com/onflow/flow-go/network/channels"
     7  )
     8  
     9  // Engine represents an isolated process running across the peer-to-peer network
    10  // as part of the node business logic. It provides the network layer with
    11  // the necessary interface to forward events to engines for processing.
    12  // Deprecated: Use MessageProcessor instead
    13  type Engine interface {
    14  	module.ReadyDoneAware
    15  
    16  	// SubmitLocal submits an event originating on the local node.
    17  	// Deprecated: To asynchronously communicate a local message between components:
    18  	// * Define a message queue on the component receiving the message
    19  	// * Define a function (with a concrete argument type) on the component receiving
    20  	//   the message, which adds the message to the message queue
    21  	SubmitLocal(event interface{})
    22  
    23  	// Submit submits the given event from the node with the given origin ID
    24  	// for processing in a non-blocking manner. It returns instantly and logs
    25  	// a potential processing error internally when done.
    26  	// Deprecated: Only applicable for use by the networking layer, which should use MessageProcessor instead
    27  	Submit(channel channels.Channel, originID flow.Identifier, event interface{})
    28  
    29  	// ProcessLocal processes an event originating on the local node.
    30  	// Deprecated: To synchronously process a local message:
    31  	// * Define a function (with a concrete argument type) on the component receiving
    32  	//   the message, which blocks until the message is processed
    33  	ProcessLocal(event interface{}) error
    34  
    35  	// Process processes the given event from the node with the given origin ID
    36  	// in a blocking manner. It returns the potential processing error when
    37  	// done.
    38  	// Deprecated: Only applicable for use by the networking layer, which should use MessageProcessor instead
    39  	Process(channel channels.Channel, originID flow.Identifier, event interface{}) error
    40  }
    41  
    42  // MessageProcessor represents a component which receives messages from the
    43  // networking layer. Since these messages come from other nodes, which may
    44  // be Byzantine, implementations must expect and handle arbitrary message inputs
    45  // (including invalid message types, malformed messages, etc.). Because of this,
    46  // node-internal messages should NEVER be submitted to a component using Process.
    47  type MessageProcessor interface {
    48  	// Process is exposed by engines to accept messages from the networking layer.
    49  	// Implementations of Process should be non-blocking. In general, Process should
    50  	// only queue the message internally by the engine for later async processing.
    51  	//
    52  	// TODO: This function should not return an error.
    53  	//  The networking layer's responsibility is fulfilled once it delivers a message to an engine.
    54  	//  It does not possess the context required to handle errors that may arise during an engine's processing
    55  	//  of the message, as error handling for message processing falls outside the domain of the networking layer.
    56  	//  Consequently, it is reasonable to remove the error from the Process function's signature,
    57  	//  since returning an error to the networking layer would not be useful in this context.
    58  	Process(channel channels.Channel, originID flow.Identifier, message interface{}) error
    59  }