network

type AllowListingUpdate struct {
	FlowIds flow.IdentifierList
	Cause   DisallowListedCause
}

type BasicResolver interface {
	LookupIPAddr(context.Context, string) ([]net.IPAddr, error)
	LookupTXT(context.Context, string) ([]string, error)
}

type BlobGetter interface {
	// GetBlob gets the requested blob.
	GetBlob(ctx context.Context, c cid.Cid) (blobs.Blob, error)

	// GetBlobs does a batch request for the given cids, returning blobs as
	// they are found, in no particular order.
	//
	// It may not be able to find all requested blobs (or the context may
	// be canceled). In that case, it will close the channel early. It is up
	// to the consumer to detect this situation and keep track which blobs
	// it has received and which it hasn't.
	GetBlobs(ctx context.Context, ks []cid.Cid) <-chan blobs.Blob
}

type BlobService interface {
	component.Component
	BlobGetter

	// AddBlob puts a given blob to the underlying datastore
	AddBlob(ctx context.Context, b blobs.Blob) error

	// AddBlobs adds a slice of blobs at the same time using batching
	// capabilities of the underlying datastore whenever possible.
	AddBlobs(ctx context.Context, bs []blobs.Blob) error

	// DeleteBlob deletes the given blob from the blobservice.
	DeleteBlob(ctx context.Context, c cid.Cid) error

	// GetSession creates a new session that allows for controlled exchange of wantlists to decrease the bandwidth overhead.
	GetSession(ctx context.Context) BlobGetter

	// TriggerReprovide updates the BlobService's provider entries in the DHT
	TriggerReprovide(ctx context.Context) error
}

type BlobServiceOption func(BlobService)

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

	// Decode decodes a message.
	// Expected error returns during normal operations:
	//  - codec.ErrInvalidEncoding if message encoding is invalid.
	//  - codec.ErrUnknownMsgCode if message code byte does not match any of the configured message codes.
	//  - codec.ErrMsgUnmarshal if the codec fails to unmarshal the data to the message type denoted by the message code.
	Decode(data []byte) (interface{}, error)
}

type Compressor interface {
	NewReader(io.Reader) (io.ReadCloser, error)
	NewWriter(io.Writer) (WriteCloseFlusher, error)
}

type Conduit interface {
	MisbehaviorReporter
	// 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 channels of this Conduit and will be received
	// by the nodes specified as part of the targetIDs.
	// TODO: function errors must be documented.
	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.
	// TODO: function errors must be documented.
	Unicast(event interface{}, targetID flow.Identifier) error

	// Multicast unreliably sends the specified event over the channel
	// to the specified number of recipients selected from the specified subset.
	// The recipients are selected randomly from the targetIDs.
	// TODO: function errors must be documented.
	Multicast(event interface{}, num uint, targetIDs ...flow.Identifier) error

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

type ConduitAdapter interface {
	MisbehaviorReportConsumer
	// UnicastOnChannel sends the message in a reliable way to the given recipient.
	UnicastOnChannel(channels.Channel, interface{}, flow.Identifier) error

	// PublishOnChannel sends the message in an unreliable way to all the given recipients.
	PublishOnChannel(channels.Channel, interface{}, ...flow.Identifier) error

	// MulticastOnChannel unreliably sends the specified event over the channel to randomly selected number of recipients
	// selected from the specified targetIDs.
	MulticastOnChannel(channels.Channel, interface{}, uint, ...flow.Identifier) error

	// UnRegisterChannel unregisters the engine for the specified channel. The engine will no longer be able to send or
	// receive messages from that channel.
	UnRegisterChannel(channel channels.Channel) error
}

type ConduitFactory interface {
	// RegisterAdapter sets the ConduitAdapter component of the factory.
	// The ConduitAdapter is a wrapper around the Network layer that only exposes the set of methods
	// that are needed by a conduit.
	RegisterAdapter(ConduitAdapter) error

	// NewConduit creates a conduit on the specified channel.
	// Prior to creating any conduit, the factory requires an ConduitAdapter to be registered with it.
	NewConduit(context.Context, channels.Channel) (Conduit, error)
}

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

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

type DisallowListNotificationConsumer interface {
	// OnDisallowListNotification is called when a new disallow list update notification is distributed.
	// Any error on consuming an event must be handled internally.
	// The implementation must be concurrency safe.
	OnDisallowListNotification(*DisallowListingUpdate)

	// OnAllowListNotification is called when a new allow list update notification is distributed.
	// Any error on consuming an event must be handled internally.
	// The implementation must be concurrency safe.
	OnAllowListNotification(*AllowListingUpdate)
}

type DisallowListedCause string

type DisallowListingUpdate struct {
	FlowIds flow.IdentifierList
	Cause   DisallowListedCause
}

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

type Engine interface {
	module.ReadyDoneAware

	// SubmitLocal submits an event originating on the local node.
	// Deprecated: To asynchronously communicate a local message between components:
	// * Define a message queue on the component receiving the message
	// * Define a function (with a concrete argument type) on the component receiving
	//   the message, which adds the message to the message queue
	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.
	// Deprecated: Only applicable for use by the networking layer, which should use MessageProcessor instead
	Submit(channel channels.Channel, originID flow.Identifier, event interface{})

	// ProcessLocal processes an event originating on the local node.
	// Deprecated: To synchronously process a local message:
	// * Define a function (with a concrete argument type) on the component receiving
	//   the message, which blocks until the message is processed
	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.
	// Deprecated: Only applicable for use by the networking layer, which should use MessageProcessor instead
	Process(channel channels.Channel, originID flow.Identifier, event interface{}) error
}

type EngineRegistry interface {
	component.Component
	// Register will subscribe to the channel with the given engine and
	// the engine will be notified with incoming messages on the channel.
	// The returned Conduit can be used to send messages to engines on other nodes subscribed to the same channel
	// On a single node, only one engine can be subscribed to a channel at any given time.
	Register(channel channels.Channel, messageProcessor MessageProcessor) (Conduit, error)

	// RegisterBlobService registers a BlobService on the given channel, using the given datastore to retrieve values.
	// The returned BlobService can be used to request blocks from the network.
	// RegisterBlobService starts the BlobService component using the network's context.
	// TODO: We should return a function that can be called to unregister / close the BlobService
	RegisterBlobService(channel channels.Channel, store datastore.Batching, opts ...BlobServiceOption) (BlobService, error)

	// RegisterPingService registers a ping protocol handler for the given protocol ID
	RegisterPingService(pingProtocolID protocol.ID, pingInfoProvider PingInfoProvider) (PingService, error)
}

type ErrIllegalConnectionState struct {
	// contains filtered or unexported fields
}

type IncomingMessageScope interface {
	// OriginId returns the origin node ID.
	OriginId() flow.Identifier

	// Proto returns the raw message received.
	Proto() *message.Message

	// DecodedPayload returns the decoded payload of the message.
	DecodedPayload() interface{}

	// Protocol returns the type of protocol used to receive the message.
	Protocol() message.ProtocolType

	// Channel returns the channel of the message.
	Channel() channels.Channel

	// Size returns the size of the message.
	Size() int

	// TargetIDs returns the target node IDs, i.e., the intended recipients.
	TargetIDs() flow.IdentifierList

	// EventID returns the hash of the payload and channel.
	EventID() []byte

	// PayloadType returns the type of the decoded payload.
	PayloadType() string
}

type MessageProcessor interface {
	// Process is exposed by engines to accept messages from the networking layer.
	// Implementations of Process should be non-blocking. In general, Process should
	// only queue the message internally by the engine for later async processing.
	//
	// TODO: This function should not return an error.
	//  The networking layer's responsibility is fulfilled once it delivers a message to an engine.
	//  It does not possess the context required to handle errors that may arise during an engine's processing
	//  of the message, as error handling for message processing falls outside the domain of the networking layer.
	//  Consequently, it is reasonable to remove the error from the Process function's signature,
	//  since returning an error to the networking layer would not be useful in this context.
	Process(channel channels.Channel, originID flow.Identifier, message 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 IncomingMessageScope) bool
}

type Misbehavior string

type MisbehaviorReport interface {
	// OriginId returns the ID of the misbehaving node.
	OriginId() flow.Identifier

	// Reason returns the reason of the misbehavior.
	Reason() Misbehavior

	// Penalty returns the penalty value of the misbehavior.
	Penalty() float64
}

type MisbehaviorReportConsumer interface {
	// ReportMisbehaviorOnChannel reports the misbehavior of a node on sending a message to the current node that appears
	// valid based on the networking layer but is considered invalid by the current node based on the Flow protocol.
	// The misbehavior report is sent to the current node's networking layer on the given channel to be processed.
	// Args:
	// - channel: The channel on which the misbehavior report is sent.
	// - report: The misbehavior report to be sent.
	// Returns:
	// none
	ReportMisbehaviorOnChannel(channel channels.Channel, report MisbehaviorReport)
}

type MisbehaviorReportManager interface {
	component.Component
	// HandleMisbehaviorReport handles the misbehavior report that is sent by the engine.
	// The implementation of this function should penalize the misbehaving node and report the node to be
	// disallow-listed if the overall penalty of the misbehaving node drops below the disallow-listing threshold.
	// The implementation of this function should be thread-safe and non-blocking.
	HandleMisbehaviorReport(channels.Channel, MisbehaviorReport)
}

type MisbehaviorReporter interface {
	// ReportMisbehavior reports the misbehavior of a node on sending a message to the current node that appears valid
	// based on the networking layer but is considered invalid by the current node based on the Flow protocol.
	// The misbehavior is reported to the networking layer to penalize the misbehaving node.
	// Implementation must be thread-safe and non-blocking.
	ReportMisbehavior(MisbehaviorReport)
}

type NetworkingType uint8

type OutgoingMessageScope interface {
	// TargetIds returns the target node IDs.
	TargetIds() flow.IdentifierList

	// Size returns the size of the message.
	Size() int

	// PayloadType returns the type of the payload to be sent.
	PayloadType() string

	// Topic returns the topic, i.e., channel-id/spork-id.
	Topic() channels.Topic

	// Proto returns the raw proto message sent on the wire.
	Proto() *message.Message
}

type PeerUnreachableError struct {
	Err error
}

type PingInfoProvider interface {
	SoftwareVersion() string
	SealedBlockHeight() uint64
	HotstuffView() uint64
}

type PingService interface {
	Ping(ctx context.Context, peerID peer.ID) (message.PingResponse, time.Duration, error)
}

type SubscriptionManager interface {
	// Register registers an engine on the channel into the subscription manager.
	Register(channel channels.Channel, engine MessageProcessor) error

	// Unregister removes the engine associated with a channel.
	Unregister(channel channels.Channel) error

	// GetEngine returns engine associated with a channel.
	GetEngine(channel channels.Channel) (MessageProcessor, error)

	// Channels returns all the channels registered in this subscription manager.
	Channels() channels.ChannelList
}

type Topology interface {
	// Fanout receives IdentityList of entire network and constructs the fanout IdentityList of the node.
	// A node directly communicates with its fanout IdentityList on epidemic dissemination
	// of the messages (i.e., publish and multicast).
	//
	// Fanout is not concurrency safe. It is responsibility of caller to lock for it (if needed).
	Fanout(ids flow.IdentityList) flow.IdentityList
}

type TransientError struct {
	Err error
}

type Underlay interface {
	module.ReadyDoneAware
	DisallowListNotificationConsumer

	// Subscribe subscribes the network Underlay to a channel.
	// No errors are expected during normal operation.
	Subscribe(channel channels.Channel) error

	// Unsubscribe unsubscribes the network Underlay from a channel.
	// All errors returned from this function can be considered benign.
	Unsubscribe(channel channels.Channel) error

	// UpdateNodeAddresses fetches and updates the addresses of all the authorized participants
	// in the Flow protocol.
	UpdateNodeAddresses()
}

type Violation struct {
	Identity *flow.Identity
	PeerID   string
	OriginID flow.Identifier
	MsgType  string
	Channel  channels.Channel
	Protocol message.ProtocolType
	Err      error
}

type ViolationsConsumer interface {
	// OnUnAuthorizedSenderError logs an error for unauthorized sender error.
	OnUnAuthorizedSenderError(violation *Violation)

	// OnUnknownMsgTypeError logs an error for unknown message type error.
	OnUnknownMsgTypeError(violation *Violation)

	// OnInvalidMsgError logs an error for messages that contained payloads that could not
	// be unmarshalled into the message type denoted by message code byte.
	OnInvalidMsgError(violation *Violation)

	// OnSenderEjectedError logs an error for sender ejected error.
	OnSenderEjectedError(violation *Violation)

	// OnUnauthorizedUnicastOnChannel logs an error for messages unauthorized to be sent via unicast.
	OnUnauthorizedUnicastOnChannel(violation *Violation)

	// OnUnauthorizedPublishOnChannel logs an error for messages unauthorized to be sent via pubsub.
	OnUnauthorizedPublishOnChannel(violation *Violation)

	// OnUnexpectedError logs an error for unknown errors.
	OnUnexpectedError(violation *Violation)
}

type WriteCloseFlusher interface {
	io.WriteCloser
	Flush() error
}