router

Documentation

Overview

Package router provides a network routing control plane

Index

• Constants
• Variables
• type Advert
• type AdvertType
  • func (t AdvertType) String() string
• type Event
• type EventType
  • func (t EventType) String() string
• type Option
  • func Address(a string) Option
  • func Advertise(a Strategy) Option
  • func Client(c client.Client) Option
  • func Gateway(g string) Option
  • func Id(id string) Option
  • func Network(n string) Option
  • func Registry(r registry.Registry) Option
• type Options
  • func DefaultOptions() Options
• type QueryOption
  • func QueryAddress(a string) QueryOption
  • func QueryGateway(g string) QueryOption
  • func QueryNetwork(n string) QueryOption
  • func QueryRouter(r string) QueryOption
  • func QueryService(s string) QueryOption
• type QueryOptions
  • func NewQuery(opts ...QueryOption) QueryOptions
• type Route
  • func (r *Route) Hash() uint64
• type Router
  • func NewRouter(opts ...Option) Router
• type Status
  • func (s Status) String() string
• type StatusCode
  • func (s StatusCode) String() string
• type Strategy
  • func (s Strategy) String() string
• type Table
• type WatchOption
  • func WatchService(s string) WatchOption
• type WatchOptions
• type Watcher

Constants

const (
	// AdvertiseEventsTick is time interval in which the router advertises route updates
	AdvertiseEventsTick = 5 * time.Second
	// AdvertiseTableTick is time interval in which router advertises all routes found in routing table
	AdvertiseTableTick = 1 * time.Minute
	// AdvertiseFlushTick is time the yet unconsumed advertisements are flush i.e. discarded
	AdvertiseFlushTick = 15 * time.Second
	// AdvertSuppress is advert suppression threshold
	AdvertSuppress = 2000.0
	// AdvertRecover is advert recovery threshold
	AdvertRecover = 750.0
	// DefaultAdvertTTL is default advertisement TTL
	DefaultAdvertTTL = 1 * time.Minute
	// DeletePenalty penalises route deletion
	DeletePenalty = 1000.0
	// UpdatePenalty penalises route updates
	UpdatePenalty = 500.0
	// PenaltyHalfLife is the time the advert penalty decays to half its value
	PenaltyHalfLife = 2.0
	// MaxSuppressTime defines time after which the suppressed advert is deleted
	MaxSuppressTime = 5 * time.Minute
)

Variables

var (
	// DefaultLink is default network link
	DefaultLink = "local"
	// DefaultLocalMetric is default route cost for a local route
	DefaultLocalMetric = 1
	// DefaultNetworkMetric is default route cost for a network route
	DefaultNetworkMetric = 10
)

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()
)

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")
)

var (
	// ErrWatcherStopped is returned when routing table watcher has been stopped
	ErrWatcherStopped = errors.New("watcher stopped")
)

var (
	// PenaltyDecay is a coefficient which controls the speed the advert penalty decays
	PenaltyDecay = math.Log(2) / PenaltyHalfLife
)

Types

type Advert

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 {
	// 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

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

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
}

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 int
}

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 to the network
	Advertise() (<-chan *Advert, error)
	// Process processes incoming adverts
	Process(*Advert) error
	// Solicit advertises the whole routing table to the network
	Solicit() 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
	// Status returns router status
	Status() Status
	// 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 Status

type Status struct {
	// Code defines router status
	Code StatusCode
	// Error contains error description
	Error error
}

Status is router status

func (Status) String

func (s Status) String() string

String returns human readable status

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
)

func (StatusCode) String

func (s StatusCode) String() string

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
)

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