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

• type DirectorFunc
• type LoadBalancer
  • func RoundRobin(svc []string, director DirectorFunc) (LoadBalancer, error)
• type LoadBalancerMaker
• type Logger
• type MiddlewareFunc
• type OriginServer
  • func NewOriginServer(address string, director DirectorFunc) (OriginServer, error)
• 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

Types

type DirectorFunc

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

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(svc []string, director DirectorFunc) (LoadBalancer, error)

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

type LoadBalancerMaker

type LoadBalancerMaker func([]string, DirectorFunc) (LoadBalancer, error)

LoadBalancerMaker takes in the addresses of downstream servers in a []string. The func(*http.Request) returned by DirectorFunc is used for the Director of httputil.ReverseProxy.

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 {
	http.Handler
	Address() string
	Healthy(ctx context.Context) error
}

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(address string, director DirectorFunc) (OriginServer, error)

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

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) ([]string, error)
	ListAll() (map[string][]string, error)
}

ServiceLister provides all available routes and their downstream services