stargate

README

Stargate

A minimal and extensible library to build gateway servers.

Stargate supports:

• Hot-reloading of routes
• Eureka service registry
• 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.

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

stargate.EurekaLister(string) returns a ServiceLister instance that queries the specified eureka server for registered applications. Calling the Reload() method on stargate.Proxy instance causes the Eureka lister to query eureka server and update the routes.

el := listers.Eureka("http://localhost:8761/eureka")

Check the eureka service discovery example.

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 tests
• WebSockets

ServiceLister implementations

• Etcd
• Consuul

LoadBalancer implementations

• Priority round robin

Documentation

Index

• type DirectorFunc
• type DownstreamServer
  • func (d DownstreamServer) IsAlive() bool
• type LoadBalancer
  • func RoundRobin(svc []string, director DirectorFunc) (LoadBalancer, error)
• type LoadBalancerMaker
• type Logger
• type MiddlewareFunc
• 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 DownstreamServer

type DownstreamServer struct {
	BaseURL string
	Backend *httputil.ReverseProxy
	Alive   bool
	// contains filtered or unexported fields
}

DownstreamServer is a backend service to connect downstream

func (DownstreamServer) IsAlive

func (d DownstreamServer) IsAlive() bool

IsAlive performs a healthcheck on the server and returns true if the server responds back. If a server responds to an initial healthcheck request, next request is made after 30 seconds. TODO: Make healthcheck configurable.

type LoadBalancer

type LoadBalancer interface {

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

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

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