github.com/micro/go-micro/v2@v2.9.1/tunnel/tunnel.go (about)

     1  // Package tunnel provides gre network tunnelling
     2  package tunnel
     3  
     4  import (
     5  	"errors"
     6  	"time"
     7  
     8  	"github.com/micro/go-micro/v2/transport"
     9  )
    10  
    11  const (
    12  	// send over one link
    13  	Unicast Mode = iota
    14  	// send to all channel listeners
    15  	Multicast
    16  	// send to all links
    17  	Broadcast
    18  )
    19  
    20  var (
    21  	// DefaultDialTimeout is the dial timeout if none is specified
    22  	DefaultDialTimeout = time.Second * 5
    23  	// ErrDialTimeout is returned by a call to Dial where the timeout occurs
    24  	ErrDialTimeout = errors.New("dial timeout")
    25  	// ErrDiscoverChan is returned when we failed to receive the "announce" back from a discovery
    26  	ErrDiscoverChan = errors.New("failed to discover channel")
    27  	// ErrLinkNotFound is returned when a link is specified at dial time and does not exist
    28  	ErrLinkNotFound = errors.New("link not found")
    29  	// ErrLinkDisconnected is returned when a link we attempt to send to is disconnected
    30  	ErrLinkDisconnected = errors.New("link not connected")
    31  	// ErrLinkLoppback is returned when attempting to send an outbound message over loopback link
    32  	ErrLinkLoopback = errors.New("link is loopback")
    33  	// ErrLinkRemote is returned when attempting to send a loopback message over remote link
    34  	ErrLinkRemote = errors.New("link is remote")
    35  	// ErrReadTimeout is a timeout on session.Recv
    36  	ErrReadTimeout = errors.New("read timeout")
    37  	// ErrDecryptingData is for when theres a nonce error
    38  	ErrDecryptingData = errors.New("error decrypting data")
    39  )
    40  
    41  // Mode of the session
    42  type Mode uint8
    43  
    44  // Tunnel creates a gre tunnel on top of the go-micro/transport.
    45  // It establishes multiple streams using the Micro-Tunnel-Channel header
    46  // and Micro-Tunnel-Session header. The tunnel id is a hash of
    47  // the address being requested.
    48  type Tunnel interface {
    49  	// Init initializes tunnel with options
    50  	Init(opts ...Option) error
    51  	// Address returns the address the tunnel is listening on
    52  	Address() string
    53  	// Connect connects the tunnel
    54  	Connect() error
    55  	// Close closes the tunnel
    56  	Close() error
    57  	// Links returns all the links the tunnel is connected to
    58  	Links() []Link
    59  	// Dial allows a client to connect to a channel
    60  	Dial(channel string, opts ...DialOption) (Session, error)
    61  	// Listen allows to accept connections on a channel
    62  	Listen(channel string, opts ...ListenOption) (Listener, error)
    63  	// String returns the name of the tunnel implementation
    64  	String() string
    65  }
    66  
    67  // Link represents internal links to the tunnel
    68  type Link interface {
    69  	// Id returns the link unique Id
    70  	Id() string
    71  	// Delay is the current load on the link (lower is better)
    72  	Delay() int64
    73  	// Length returns the roundtrip time as nanoseconds (lower is better)
    74  	Length() int64
    75  	// Current transfer rate as bits per second (lower is better)
    76  	Rate() float64
    77  	// Is this a loopback link
    78  	Loopback() bool
    79  	// State of the link: connected/closed/error
    80  	State() string
    81  	// honours transport socket
    82  	transport.Socket
    83  }
    84  
    85  // The listener provides similar constructs to the transport.Listener
    86  type Listener interface {
    87  	Accept() (Session, error)
    88  	Channel() string
    89  	Close() error
    90  }
    91  
    92  // Session is a unique session created when dialling or accepting connections on the tunnel
    93  type Session interface {
    94  	// The unique session id
    95  	Id() string
    96  	// The channel name
    97  	Channel() string
    98  	// The link the session is on
    99  	Link() string
   100  	// a transport socket
   101  	transport.Socket
   102  }
   103  
   104  // NewTunnel creates a new tunnel
   105  func NewTunnel(opts ...Option) Tunnel {
   106  	return newTunnel(opts...)
   107  }