github.com/onflow/flow-go@v0.33.17/network/engine.go (about)

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