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 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 Query
  • func NewQuery(opts ...QueryOption) Query
• type QueryOption
  • func QueryGateway(g string) QueryOption
  • func QueryNetwork(n string) QueryOption
  • func QueryService(s string) QueryOption
• type QueryOptions
• type Route
  • func (r *Route) Hash() uint64
• type Router
  • func NewRouter(opts ...Option) Router
• type Status
• type StatusCode
  • func (s StatusCode) 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 metric for the local network
	DefaultLocalMetric = 1
	// DefaultNetworkMetric is default route cost metric for the micro network
	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 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
	// Client for calling router
	Client client.Client
}

Options are router options

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns router default options

type Query

type Query interface {
	// Options returns query options
	Options() QueryOptions
}

Query is routing table query

func NewQuery

func NewQuery(opts ...QueryOption) Query

NewQuery creates new query and returns it

type QueryOption

type QueryOption func(*QueryOptions)

QueryOption sets routing table query options

func QueryGateway

func QueryGateway(g string) QueryOption

QueryGateway sets route gateway

func QueryNetwork

func QueryNetwork(n string) QueryOption

QueryNetwork sets route network address

func QueryService

func QueryService(s string) QueryOption

QueryService sets destination address

type QueryOptions

type QueryOptions struct {
	// Service is destination service name
	Service string
	// Gateway is route gateway
	Gateway string
	// Network is network address
	Network string
}

QueryOptions are routing table query options

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
	// 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
	// Lookup queries routes in the routing table
	Lookup(Query) ([]Route, error)
	// Watch returns a watcher which tracks updates to the routing table
	Watch(opts ...WatchOption) (Watcher, 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 {
	// Error is router error
	Error error
	// Code defines router status
	Code StatusCode
}

Status is router 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 Table

type Table interface {
	// Create new route in the routing table
	Create(Route) error
	// Delete deletes existing route from the routing table
	Delete(Route) error
	// Update updates route in the routing table
	Update(Route) error
	// List returns the list of all routes in the table
	List() ([]Route, error)
	// Query queries routes in the routing table
	Query(Query) ([]Route, error)
}

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

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