network

type Codec interface {
	NewEncoder(w io.Writer) Encoder
	NewDecoder(r io.Reader) Decoder
	Encode(v interface{}) ([]byte, error)
	Decode(data []byte) (interface{}, error)
}

type Conduit interface {

	// Submit will submit an event to the network layer. The network layer will
	// ensure that the event is delivered to the same engine on the desired target
	// nodes. It's possible that the event traverses other nodes than the target
	// nodes on its path across the network. The network codec needs to be aware
	// of how to encode the given event type, otherwise the send will fail.
	//
	// Note: Submit method is planned for deprecation soon.
	// Alternative methods are recommended, e.g., Publish, Unicast, and Multicast.
	Submit(event interface{}, targetIDs ...flow.Identifier) error

	// Publish submits an event to the network layer for unreliable delivery
	// to subscribers of the given event on the network layer. It uses a
	// publish-subscribe layer and can thus not guarantee that the specified
	// recipients received the event.
	// The event is published on the channel ID of this Conduit and will be received
	// by the nodes specified as part of the targetIDs
	Publish(event interface{}, targetIDs ...flow.Identifier) error

	// Unicast sends the event in a reliable way to the given recipient.
	// It uses 1-1 direct messaging over the underlying network to deliver the event.
	// It returns an error if the unicast fails.
	Unicast(event interface{}, targetID flow.Identifier) error

	// Multicast unreliably sends the specified event over the channelID
	// to the specified number of recipients selected from the specified subset.
	// The recipients are selected randomly from the targetIDs.
	Multicast(event interface{}, num uint, targetIDs ...flow.Identifier) error

	// Close unsubscribes from the channel ID of this conduit. After calling close,
	// the conduit can no longer be used to send a message.
	Close() error
}

type Connection interface {
	Send(msg interface{}) error
	Receive() (interface{}, error)
}

type Decoder interface {
	Decode() (interface{}, error)
}

type Encoder interface {
	Encode(v interface{}) error
}

type Engine interface {

	// SubmitLocal submits an event originating on the local node.
	SubmitLocal(event interface{})

	// Submit submits the given event from the node with the given origin ID
	// for processing in a non-blocking manner. It returns instantly and logs
	// a potential processing error internally when done.
	Submit(originID flow.Identifier, event interface{})

	// ProcessLocal processes an event originating on the local node.
	ProcessLocal(event interface{}) error

	// Process processes the given event from the node with the given origin ID
	// in a blocking manner. It returns the potential processing error when
	// done.
	Process(originID flow.Identifier, event interface{}) error
}

type MessageQueue interface {
	// Insert inserts the message in queue
	Insert(message interface{}) error
	// Remove removes the message from the queue in priority order. If no message is found, this call blocks.
	// If two messages have the same priority, items are de-queued in insertion order
	Remove() interface{}
	// Len gives the current length of the queue
	Len() int
}

type MessageValidator interface {
	// Validate validates the message and returns true if the message is to be retained and false if it needs to be dropped
	Validate(msg message.Message) bool
}

type Middleware interface {
	// Start will start the middleware.
	Start(overlay Overlay) error

	// Stop will end the execution of the middleware and wait for it to end.
	Stop()

	// Send sends the message to the set of target ids
	// If there is only one target NodeID, then a direct 1-1 connection is used by calling middleware.sendDirect
	// Otherwise, middleware.Publish is used, which uses the PubSub method of communication.
	//
	// Deprecated: Send exists for historical compatibility, and should not be used on new
	// developments. It is planned to be cleaned up in near future. Proper utilization of Dispatch or
	// Publish are recommended instead.
	Send(channelID string, msg *message.Message, targetIDs ...flow.Identifier) error

	// Dispatch sends msg on a 1-1 direct connection to the target ID. It models a guaranteed delivery asynchronous
	// direct one-to-one connection on the underlying network. No intermediate node on the overlay is utilized
	// as the router.
	//
	// Dispatch should be used whenever guaranteed delivery to a specific target is required. Otherwise, Publish is
	// a more efficient candidate.
	SendDirect(msg *message.Message, targetID flow.Identifier) error

	// Publish publishes msg on the channel. It models a distributed broadcast where the message is meant for all or
	// a many nodes subscribing to the channel ID. It does not guarantee the delivery though, and operates on a best
	// effort.
	Publish(msg *message.Message, channelID string) error

	// Subscribe will subscribe the middleware for a topic with the fully qualified channel ID name
	Subscribe(channelID string) error

	// Unsubscribe will unsubscribe the middleware for a topic with the fully qualified channel ID name
	Unsubscribe(channelID string) error

	// Ping pings the target node and returns the ping RTT or an error
	Ping(targetID flow.Identifier) (time.Duration, error)

	// UpdateAllowList fetches the most recent identity of the nodes from overlay
	// and updates the underlying libp2p node.
	UpdateAllowList() error
}

type Overlay interface {
	// Topology returns an identity list of nodes which this node should be directly connected to as peers
	Topology() (flow.IdentityList, error)
	// Identity returns a map of all identifier to flow identity
	Identity() (map[flow.Identifier]flow.Identity, error)
	Receive(nodeID flow.Identifier, msg *message.Message) error
}

type PeerUnreachableError struct {
	Err error
}

type SubscriptionManager interface {
	// Register registers an engine on the channel ID into the subscription manager.
	Register(channelID string, engine Engine) error

	// Unregister removes the engine associated with a channel ID
	Unregister(channelID string) error

	// GetEngine returns engine associated with a channel ID.
	GetEngine(channelID string) (Engine, error)

	// GetChannelIDs returns all the channel IDs registered in this subscription manager.
	GetChannelIDs() []string
}

type Topology interface {
	// GenerateFanout receives IdentityList of entire network and constructs the fanout IdentityList
	// of this instance. A node directly communicates with its fanout IdentityList on epidemic dissemination
	// of the messages (i.e., publish and multicast).
	// Independent invocations of GenerateFanout on different nodes collaboratively must construct a cohesive
	// connected graph of nodes that enables them talking to each other.
	GenerateFanout(ids flow.IdentityList) (flow.IdentityList, error)
}