stargate

README

Report Card

Stargate

A minimal and extensible library to build gateway servers. Stargate aims to be simple while providing niche solutions like several load balancer implementations, middleware, service discovery, etc.

Stargate supports:

• WebSockets
• Hot-reloading of routes
• Middleware

stargatecontrb contains some middleware implementations that are not in the scope of this library, but might be useful for some people.

Getting started

Check the basic example that implements a stargate.ServiceLister to create a static table of routes and uses round-robin approach to load balance the request.

In the same sprits, the WebSockets example shows a simple WebSocket backend.

Customize logging

Stargate uses stargate.Log variable to write its logging output. This variable is an implementation of stargate.Logger. You may write your own implementation of this interface and write stargate.Log = myOwnLogger{} whenever your program starts.

Check the custom logger example.

Using dynamic route tables.

If the stargate.ServiceLister's implementation updates the route table, the stargate.Router instance can be told to update the routing by calling the Reload() method.

Check the reloading routes example.

Eureka service discovery

Check the eureka package in stargatecontrib.

Middleware

Stargate defines middleware as:

type MiddlewareFunc func (http.Handler) http.Handler

Check the middleware example, that counts the number of requests served.

Open TODOs

• Improve logging
• Improve documentation
• Write more tests
• Customizable healthchecks

LoadBalancer implementations

• Priority round-robin

Documentation

Index

• Constants
• type DirectorFunc
• type HealthCheckOptions
• type LoadBalancer
  • func RoundRobin(servers []OriginServer) (LoadBalancer, error)
• type LoadBalancerMaker
• type Logger
• type MiddlewareFunc
• type OriginServer
  • func NewOriginServer(routeOptions *RouteOptions, director DirectorFunc) (OriginServer, error)
• type RouteOptions
• type Router
  • func NewRouter(lister ServiceLister, options ...RouterOption) (*Router, error)
  • func (r *Router) Reload() error
  • func (r *Router) ServeHTTP(rw http.ResponseWriter, req *http.Request)
• type RouterOption
  • func WithLoadBalancer(lb LoadBalancerMaker) RouterOption
  • func WithMiddleware(mw ...MiddlewareFunc) RouterOption
• type ServiceLister

Constants

const (
	DefaultHealthCheckPath     = "/"
	DefaultHealthCheckStatus   = http.StatusOK
	DefaultHealthCheckInterval = 30 * time.Second
	DefaultHealthCheckTimeout  = 10 * time.Second
	DefaultHealthyPings        = 3
	DefaultUnhealthyPings      = 3
)

Types

type DirectorFunc

type DirectorFunc func(*url.URL) func(*http.Request)

type HealthCheckOptions

type HealthCheckOptions struct {
	// Path is the relative path on the origin server that is to be used for health checking. Defaults to "/".
	Path string

	// Interval is the frequency of health checks. Defaults to 30s.
	Interval time.Duration

	// Timeout dictates how long Stargate should wait for a health check ping to finish. Defaults to 10s.
	Timeout time.Duration

	// HealthyStatus is the expected status code of a successful health check ping. Defaults to http.StatusOK.
	HealthyStatus int

	// UnhealthyPings represents the number of unsuccessful healthcheck calls after which the origin server is deemed
	// unhealthy. Once an origin is deemed unhealthy, it must pass UnhealthyPings pings to be considered healthy again.
	UnhealthyPings int
}

HealthCheckOptions defines the behavior of the health checker routine.

type LoadBalancer

type LoadBalancer interface {

	// NextServer returns an instance of *DownstreamServer that should be used to serve and http request.
	NextServer() OriginServer

	// Length returns how many downstream servers are available.
	Length() int

	// Name returns a friendly name of this balancer
	Name() string
}

LoadBalancer is used to determine which downstream service should be invoked next to serve a request.

func RoundRobin

func RoundRobin(servers []OriginServer) (LoadBalancer, error)

RoundRobin creates new instance of LoadBalancer that implements the Round-Robin load balancing algorithm.

type LoadBalancerMaker

type LoadBalancerMaker func([]OriginServer) (LoadBalancer, error)

LoadBalancerMaker creates a LoadBalancer from the input OriginServer slice.

type Logger

type Logger interface {
	Info(format string, args ...interface{})
	Warn(format string, args ...interface{})
	Debug(format string, args ...interface{})
	Error(format string, args ...interface{})
}

Logger is a facade interface that Stargate uses to log its events. By default, Stargate uses a Logger instance that writes to os.Stdout with the prefix `STARGATE>`.

var Log Logger = defaultLogger{log.New(os.Stdout, "STARGATE> ", log.LstdFlags|log.Lshortfile)}

Log is an instance of Logger used by Stargate. It is set to an implementation of stargate.Logger that writes to the standard output. Implementors may update this variable to their own implementation of stargate.Logger.

type MiddlewareFunc

type MiddlewareFunc func(next http.Handler) http.Handler

MiddlewareFunc is a function that takes an http.Handler and returns another http.Handler. The returned http.Handler is a closure that can call the passed in http.Handler to move the HTTP call forward. Optionally the returned closure can do some extra processing - like authentication - with http.ResponseWriter and http.Request it receives.

type OriginServer

type OriginServer interface {
	io.Closer
	http.Handler
	Address() string
	Healthy() bool
	// contains filtered or unexported methods
}

OriginServer is an abstraction for Stargate that represents the server to be reverse proxied. NewDownstreamServer returns an appropriate implementation of this interface.

func NewOriginServer

func NewOriginServer(routeOptions *RouteOptions, director DirectorFunc) (OriginServer, error)

NewOriginServer returns a DownstreamServer implementation backed by HTTP or WebSockets, depending on the RouteOptions' address. The said address must have http, https, ws, or wss protocol. Anything else passed to this function will make it return an "unknown scheme" error.

type RouteOptions

type RouteOptions struct {
	// Address is the absolute address of an origin server.
	Address string

	// HealthCheck indicates that a health checker routine is to spawned, if not nil.
	HealthCheck *HealthCheckOptions
}

RouteOptions defines the configuration of a route.

type Router

type Router struct {
	// contains filtered or unexported fields
}

Router implements http.Handler and handles all requests that are to be reverse-proxied.

func NewRouter

func NewRouter(lister ServiceLister, options ...RouterOption) (*Router, error)

NewRouter creates a Router instance out of the downstream services supplied by ServiceLister parameter.

func (*Router) Reload

func (r *Router) Reload() error

Reload queries the ServiceLister used with NewRouter and creates the internal routing table used by ServeHTTP.

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServeHTTP satisfies http.Handler. It prioritizes full URL matches from the internal routing table, and tries until / is reached. For example, to serve a request to https://somehost.com/some/test/url, ServeHTTP tries to look for URLs in the routing table in this order ; /some/test/url -> /some/test -> /some -> /

The downstream service pertaining to the first matched URL is picked and the request is reverse proxied to that.

type RouterOption

type RouterOption func(r *Router)

RouterOption represents a closure type that can be used to customize the behavior of Router created using NewRouter.

func WithLoadBalancer

func WithLoadBalancer(lb LoadBalancerMaker) RouterOption

WithLoadBalancer lets you set the LoadBalancerMaker of your choice.

func WithMiddleware

func WithMiddleware(mw ...MiddlewareFunc) RouterOption

WithMiddleware takes a middleware chain to be executed before all requests. The order of middleware passed to it is preserved.

type ServiceLister

type ServiceLister interface {
	List(string) ([]*RouteOptions, error)
	ListAll() (map[string][]*RouteOptions, error)
}

ServiceLister provides all available routes and their downstream services