Documentation

Overview

    Package router provides a network routing control plane

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var (
    	// AdvertiseEventsTick is time interval in which the router advertises route updates
    	AdvertiseEventsTick = 10 * time.Second
    	// DefaultAdvertTTL is default advertisement TTL
    	DefaultAdvertTTL = 2 * time.Minute
    )
    View Source
    var (
    	// DefaultLink is default network link
    	DefaultLink = "local"
    	// DefaultLocalMetric is default route cost for a local route
    	DefaultLocalMetric int64 = 1
    )
    View Source
    var (
    	// DefaultAddress is default router address
    	DefaultAddress = ":9093"
    	// DefaultName is default router service name
    	DefaultName = "go.micro.router"
    	// DefaultNetwork is default micro network
    	DefaultNetwork = "go.micro"
    	// DefaultRouter is default network router
    	DefaultRouter = NewRouter()
    )
    View Source
    var (
    	// ErrRouteNotFound is returned when no route was found in the routing table
    	ErrRouteNotFound = errors.New("route not found")
    	// ErrDuplicateRoute is returned when the route already exists
    	ErrDuplicateRoute = errors.New("duplicate route")
    )
    View Source
    var (
    	// ErrWatcherStopped is returned when routing table watcher has been stopped
    	ErrWatcherStopped = errors.New("watcher stopped")
    )

    Functions

    This section is empty.

    Types

    type Advert struct {
    	// Id is the router Id
    	Id string
    	// Type is type of advert
    	Type AdvertType
    	// Timestamp marks the time when the update is sent
    	Timestamp time.Time
    	// TTL is Advert TTL
    	TTL time.Duration
    	// Events is a list of routing table events to advertise
    	Events []*Event
    }

      Advert contains a list of events advertised by the router to the network

      type AdvertType

      type AdvertType int

        AdvertType is route advertisement type

        const (
        	// Announce is advertised when the router announces itself
        	Announce AdvertType = iota
        	// RouteUpdate advertises route updates
        	RouteUpdate
        )

        func (AdvertType) String

        func (t AdvertType) String() string

          String returns human readable advertisement type

          type Event

          type Event struct {
          	// Unique id of the event
          	Id string
          	// Type defines type of event
          	Type EventType
          	// Timestamp is event timestamp
          	Timestamp time.Time
          	// Route is table route
          	Route Route
          }

            Event is returned by a call to Next on the watcher.

            type EventType

            type EventType int

              EventType defines routing table event

              const (
              	// Create is emitted when a new route has been created
              	Create EventType = iota
              	// Delete is emitted when an existing route has been deleted
              	Delete
              	// Update is emitted when an existing route has been updated
              	Update
              )

              func (EventType) String

              func (t EventType) String() string

                String returns human readable event type

                type Option

                type Option func(*Options)

                  Option used by the router

                  func Address

                  func Address(a string) Option

                    Address sets router service address

                    func Advertise(a Strategy) Option

                      Strategy sets route advertising strategy

                      func Client

                      func Client(c client.Client) Option

                        Client to call router service

                        func Gateway

                        func Gateway(g string) Option

                          Gateway sets network gateway

                          func Id

                          func Id(id string) Option

                            Id sets Router Id

                            func Network

                            func Network(n string) Option

                              Network sets router network

                              func Registry

                              func Registry(r registry.Registry) Option

                                Registry sets the local registry

                                type Options

                                type Options struct {
                                	// Id is router id
                                	Id string
                                	// Address is router address
                                	Address string
                                	// Gateway is network gateway
                                	Gateway string
                                	// Network is network address
                                	Network string
                                	// Registry is the local registry
                                	Registry registry.Registry
                                	// Advertise is the advertising strategy
                                	Advertise Strategy
                                	// Client for calling router
                                	Client client.Client
                                }

                                  Options are router options

                                  func DefaultOptions

                                  func DefaultOptions() Options

                                    DefaultOptions returns router default options

                                    type QueryOption

                                    type QueryOption func(*QueryOptions)

                                      QueryOption sets routing table query options

                                      func QueryAddress

                                      func QueryAddress(a string) QueryOption

                                        QueryAddress sets service to query

                                        func QueryGateway

                                        func QueryGateway(g string) QueryOption

                                          QueryGateway sets gateway address to query

                                          func QueryNetwork

                                          func QueryNetwork(n string) QueryOption

                                            QueryNetwork sets network name to query

                                            func QueryRouter

                                            func QueryRouter(r string) QueryOption

                                              QueryRouter sets router id to query

                                              func QueryService

                                              func QueryService(s string) QueryOption

                                                QueryService sets service to query

                                                func QueryStrategy

                                                func QueryStrategy(s Strategy) QueryOption

                                                  QueryStrategy sets strategy to query

                                                  type QueryOptions

                                                  type QueryOptions struct {
                                                  	// Service is destination service name
                                                  	Service string
                                                  	// Address of the service
                                                  	Address string
                                                  	// Gateway is route gateway
                                                  	Gateway string
                                                  	// Network is network address
                                                  	Network string
                                                  	// Router is router id
                                                  	Router string
                                                  	// Strategy is routing strategy
                                                  	Strategy Strategy
                                                  }

                                                    QueryOptions are routing table query options

                                                    func NewQuery

                                                    func NewQuery(opts ...QueryOption) QueryOptions

                                                      NewQuery creates new query and returns it

                                                      type Route

                                                      type Route struct {
                                                      	// Service is destination service name
                                                      	Service string
                                                      	// Address is service node address
                                                      	Address string
                                                      	// Gateway is route gateway
                                                      	Gateway string
                                                      	// Network is network address
                                                      	Network string
                                                      	// Router is router id
                                                      	Router string
                                                      	// Link is network link
                                                      	Link string
                                                      	// Metric is the route cost metric
                                                      	Metric int64
                                                      }

                                                        Route is network route

                                                        func (*Route) Hash

                                                        func (r *Route) Hash() uint64

                                                          Hash returns route hash sum.

                                                          type Router

                                                          type Router interface {
                                                          	// Init initializes the router with options
                                                          	Init(...Option) error
                                                          	// Options returns the router options
                                                          	Options() Options
                                                          	// The routing table
                                                          	Table() Table
                                                          	// Advertise advertises routes
                                                          	Advertise() (<-chan *Advert, error)
                                                          	// Process processes incoming adverts
                                                          	Process(*Advert) error
                                                          	// Lookup queries routes in the routing table
                                                          	Lookup(...QueryOption) ([]Route, error)
                                                          	// Watch returns a watcher which tracks updates to the routing table
                                                          	Watch(opts ...WatchOption) (Watcher, error)
                                                          	// Start starts the router
                                                          	Start() error
                                                          	// Stop stops the router
                                                          	Stop() error
                                                          	// Returns the router implementation
                                                          	String() string
                                                          }

                                                            Router is an interface for a routing control plane

                                                            func NewRouter

                                                            func NewRouter(opts ...Option) Router

                                                              NewRouter creates new Router and returns it

                                                              type StatusCode

                                                              type StatusCode int

                                                                StatusCode defines router status

                                                                const (
                                                                	// Running means the router is up and running
                                                                	Running StatusCode = iota
                                                                	// Advertising means the router is advertising
                                                                	Advertising
                                                                	// Stopped means the router has been stopped
                                                                	Stopped
                                                                	// Error means the router has encountered error
                                                                	Error
                                                                )

                                                                type Strategy

                                                                type Strategy int

                                                                  Strategy is route advertisement strategy

                                                                  const (
                                                                  	// AdvertiseAll advertises all routes to the network
                                                                  	AdvertiseAll Strategy = iota
                                                                  	// AdvertiseBest advertises optimal routes to the network
                                                                  	AdvertiseBest
                                                                  	// AdvertiseLocal will only advertise the local routes
                                                                  	AdvertiseLocal
                                                                  	// AdvertiseNone will not advertise any routes
                                                                  	AdvertiseNone
                                                                  )

                                                                    TODO: remove the "Advertise" prefix from these

                                                                    func (Strategy) String

                                                                    func (s Strategy) String() string

                                                                      String returns human readable Strategy

                                                                      type Table

                                                                      type Table interface {
                                                                      	// Create new route in the routing table
                                                                      	Create(Route) error
                                                                      	// Delete existing route from the routing table
                                                                      	Delete(Route) error
                                                                      	// Update route in the routing table
                                                                      	Update(Route) error
                                                                      	// List all routes in the table
                                                                      	List() ([]Route, error)
                                                                      	// Query routes in the routing table
                                                                      	Query(...QueryOption) ([]Route, error)
                                                                      }

                                                                        Table is an interface for routing table

                                                                        type WatchOption

                                                                        type WatchOption func(*WatchOptions)

                                                                          WatchOption is used to define what routes to watch in the table

                                                                          func WatchService

                                                                          func WatchService(s string) WatchOption

                                                                            WatchService sets what service routes to watch Service is the microservice name

                                                                            type WatchOptions

                                                                            type WatchOptions struct {
                                                                            	// Service allows to watch specific service routes
                                                                            	Service string
                                                                            }

                                                                              WatchOptions are table watcher options TODO: expand the options to watch based on other criteria

                                                                              type Watcher

                                                                              type Watcher interface {
                                                                              	// Next is a blocking call that returns watch result
                                                                              	Next() (*Event, error)
                                                                              	// Chan returns event channel
                                                                              	Chan() (<-chan *Event, error)
                                                                              	// Stop stops watcher
                                                                              	Stop()
                                                                              }

                                                                                Watcher defines routing table watcher interface Watcher returns updates to the routing table

                                                                                Directories

                                                                                Path Synopsis