github.com/koko1123/flow-go-1@v0.29.6/network/conduit.go (about)

     1  // (c) 2019 Dapper Labs - ALL RIGHTS RESERVED
     2  
     3  package network
     4  
     5  import (
     6  	"context"
     7  	"errors"
     8  	"fmt"
     9  
    10  	"github.com/koko1123/flow-go-1/model/flow"
    11  	"github.com/koko1123/flow-go-1/network/channels"
    12  )
    13  
    14  // ConduitFactory is an interface type that is utilized by the Network to create conduits for the channels.
    15  type ConduitFactory interface {
    16  	// RegisterAdapter sets the Adapter component of the factory.
    17  	// The Adapter is a wrapper around the Network layer that only exposes the set of methods
    18  	// that are needed by a conduit.
    19  	RegisterAdapter(Adapter) error
    20  
    21  	// NewConduit creates a conduit on the specified channel.
    22  	// Prior to creating any conduit, the factory requires an Adapter to be registered with it.
    23  	NewConduit(context.Context, channels.Channel) (Conduit, error)
    24  }
    25  
    26  // Conduit represents the interface for engines to communicate over the
    27  // peer-to-peer network. Upon registration with the network, each engine is
    28  // assigned a conduit, which it can use to communicate across the network in
    29  // a network-agnostic way. In the background, the network layer connects all
    30  // engines with the same ID over a shared bus, accessible through the conduit.
    31  type Conduit interface {
    32  
    33  	// Publish submits an event to the network layer for unreliable delivery
    34  	// to subscribers of the given event on the network layer. It uses a
    35  	// publish-subscribe layer and can thus not guarantee that the specified
    36  	// recipients received the event.
    37  	// The event is published on the channels of this Conduit and will be received
    38  	// by the nodes specified as part of the targetIDs.
    39  	// TODO: function errors must be documented.
    40  	Publish(event interface{}, targetIDs ...flow.Identifier) error
    41  
    42  	// Unicast sends the event in a reliable way to the given recipient.
    43  	// It uses 1-1 direct messaging over the underlying network to deliver the event.
    44  	// It returns an error if the unicast fails.
    45  	// TODO: function errors must be documented.
    46  	Unicast(event interface{}, targetID flow.Identifier) error
    47  
    48  	// Multicast unreliably sends the specified event over the channel
    49  	// to the specified number of recipients selected from the specified subset.
    50  	// The recipients are selected randomly from the targetIDs.
    51  	// TODO: function errors must be documented.
    52  	Multicast(event interface{}, num uint, targetIDs ...flow.Identifier) error
    53  
    54  	// Close unsubscribes from the channels of this conduit. After calling close,
    55  	// the conduit can no longer be used to send a message.
    56  	Close() error
    57  }
    58  
    59  // PeerUnreachableError is the error when submitting events to target fails due to the
    60  // target peer is unreachable
    61  type PeerUnreachableError struct {
    62  	Err error
    63  }
    64  
    65  // NewPeerUnreachableError creates a PeerUnreachableError instance with an error
    66  func NewPeerUnreachableError(err error) error {
    67  	return PeerUnreachableError{
    68  		Err: err,
    69  	}
    70  }
    71  
    72  // Unwrap returns the wrapped error value
    73  func (e PeerUnreachableError) Unwrap() error {
    74  	return e.Err
    75  }
    76  
    77  func (e PeerUnreachableError) Error() string {
    78  	return fmt.Sprintf("%v", e.Err)
    79  }
    80  
    81  // IsPeerUnreachableError returns whether the given error is PeerUnreachableError
    82  func IsPeerUnreachableError(e error) bool {
    83  	var err PeerUnreachableError
    84  	return errors.As(e, &err)
    85  }
    86  
    87  // AllPeerUnreachableError returns whether all errors are PeerUnreachableError
    88  func AllPeerUnreachableError(errs ...error) bool {
    89  	for _, err := range errs {
    90  		if !IsPeerUnreachableError(err) {
    91  			return false
    92  		}
    93  	}
    94  	return true
    95  }