server

Documentation

Overview

Package server implements a minor extension of the standard http.Server struct.

The primary extensions of this implementation over the standard library are:

1. Integration with the base EasyTLS package, to provide a standardized and simpler interface for configuring and utilizing TLS encryption on an HTTP Server.

2. Slightly easier interface for starting and stopping the server, registering routes and middlewares, and a small library of included middlewares for common use-cases.

3. Plugin integration via the easy-tls/plugins package. Client/Server application design can be simplified or broken down from monoliths with an easy enough plugin system, which this is intended to provide. The http.Handler registration process has been simplified in such a way as to allow programmatic registration of Routes by the use of SimpleHandlers. A Server module can easily expose the set of routes it services as an array of SimpleHandlers, which can be iterated over and registered.

Index

• func AddHandlers(verbose bool, s *SimpleServer, r *mux.Router, Handlers ...SimpleHandler)
• func AddMiddlewares(r *mux.Router, middlewares ...MiddlewareHandler)
• func MiddlewareDefaultLogger(next http.Handler) http.Handler
• func MiddlewareLimitConnectionRate(CycleTime time.Duration, Timeout time.Duration, verbose bool) func(http.Handler) http.Handler
• func MiddlewareLimitMaxConnections(ConnectionLimit int, Timeout time.Duration, verbose bool) func(http.Handler) http.Handler
• func NewDefaultRouter() *mux.Router
• func NewRouter(s *SimpleServer, Handlers []SimpleHandler, Middlewares ...MiddlewareHandler) *mux.Router
• type MiddlewareHandler
• type SimpleHandler
• type SimpleServer
  • func NewServerHTTP(Addr ...string) (*SimpleServer, error)
  • func NewServerHTTPS(TLS *easytls.TLSBundle, Addr ...string) (*SimpleServer, error)
  • func (S *SimpleServer) Addr() string
  • func (S *SimpleServer) EnableAboutHandler(r *mux.Router)
  • func (S *SimpleServer) ListenAndServe() error
  • func (S *SimpleServer) RegisterRouter(r http.Handler)
  • func (S *SimpleServer) SetKeepAlives(SetTo bool)
  • func (S *SimpleServer) SetTimeouts(ReadTimeout, ReadHeaderTimeout, WriteTimeout, IdleTimeout time.Duration)
  • func (S *SimpleServer) Shutdown() error

Functions

func AddHandlers

func AddHandlers(verbose bool, s *SimpleServer, r *mux.Router, Handlers ...SimpleHandler)

AddHandlers will add the given handlers to the router, with the verbose flag determining if a log message should be generated for each added route.

func AddMiddlewares

func AddMiddlewares(r *mux.Router, middlewares ...MiddlewareHandler)

AddMiddlewares is a convenience wrapper for the mux.Router "Use" function. This will add the middlewares to the router in the order specified (which also defines their execution order).

func MiddlewareDefaultLogger

func MiddlewareDefaultLogger(next http.Handler) http.Handler

MiddlewareDefaultLogger provides a simple logging middleware, to view incoming connections as they arrive and print a basic set of properties of the request.

func MiddlewareLimitConnectionRate

func MiddlewareLimitConnectionRate(CycleTime time.Duration, Timeout time.Duration, verbose bool) func(http.Handler) http.Handler

MiddlewareLimitConnectionRate will limit the rate at which the Server will process incoming requests. This will process at most 1 request per CycleTime. Verbose mode includes a log message when a request begins processing through this function. If the request is not processed within Timeout, a failed statusCode will be generated and sent back.

func MiddlewareLimitMaxConnections

func MiddlewareLimitMaxConnections(ConnectionLimit int, Timeout time.Duration, verbose bool) func(http.Handler) http.Handler

MiddlewareLimitMaxConnections will provide a mechanism to strictly limit the maximum number of concurrent requests served. Verbose mode includes a log message when a request begins processing through this function. If the request is not processed within Timeout, a failed statusCode will be generated and sent back.

func NewDefaultRouter

func NewDefaultRouter() *mux.Router

NewDefaultRouter will create a new Router, based on the gorilla/mux implementation. This will pre-set the "trailing-slash" behaviour to not be pedantic, as well as initialing the "Not-Found" and "Method-Not-Allowed" behaviours to simply return the corresponding status codes. These can be overridden if desired.

func NewRouter

func NewRouter(s *SimpleServer, Handlers []SimpleHandler, Middlewares ...MiddlewareHandler) *mux.Router

NewRouter will create a new Router with ALL of the specified Routes and Middlewares, and update the SimpleServer with the registration information. This will NOT register the router, as more handlers and/or middlewares can be added following this function if necessary.

Types

type MiddlewareHandler

type MiddlewareHandler func(http.Handler) http.Handler

MiddlewareHandler represents the Type which must be satified by any given function to be used as a middleware function in the Server chain.

type SimpleHandler

type SimpleHandler struct {
	Handler http.HandlerFunc
	Path    string
	Methods []string
}

SimpleHandler represents a simplification to the standard http handlerFuncs, allowing simpler registration and logging with Routers.

type SimpleServer

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

SimpleServer is the extension to the default http.Server this package provides.

func NewServerHTTP

func NewServerHTTP(Addr ...string) (*SimpleServer, error)

NewServerHTTP will create a new HTTP-only server which will serve on the specified IP:Port address. This has NO TLS settings enabled. The server returned from this function only has the default http.ServeMux as the Router, so should have a dedicated router registered.

The default address of ":8080" will be used if none is provided Only the first string will be treated as the address

func NewServerHTTPS

func NewServerHTTPS(TLS *easytls.TLSBundle, Addr ...string) (*SimpleServer, error)

NewServerHTTPS will create a new HTTPS-only server which will serve on the specified IP:Port address. The server returned from this function only has the default http.ServeMux as the Router, so should have a dedicated router registered.

The default address of ":8080" will be used if none is provided

func (*SimpleServer) Addr

func (S *SimpleServer) Addr() string

Addr exposes the underlying IP:Port address of the SimpleServer.

func (*SimpleServer) EnableAboutHandler

func (S *SimpleServer) EnableAboutHandler(r *mux.Router)

EnableAboutHandler will enable and set up the "about" handler, to display the available routes. This must be the last route registered in order for the full set of routes to be displayed.

func (*SimpleServer) ListenAndServe

func (S *SimpleServer) ListenAndServe() error

ListenAndServe will start the SimpleServer, serving HTTPS if enabled, or HTTP if not. This will properly wait for the shutdown to FINISH before returning.

func (*SimpleServer) RegisterRouter

func (S *SimpleServer) RegisterRouter(r http.Handler)

RegisterRouter will register the given Handler (typically an *http.ServeMux or *mux.Router) as the http Handler for the server.

func (*SimpleServer) SetKeepAlives

func (S *SimpleServer) SetKeepAlives(SetTo bool)

SetKeepAlives will configure the server for whether or not it should use Keep-Alives. True implies to use Keep-Alives, and false will disable them.

func (*SimpleServer) SetTimeouts

func (S *SimpleServer) SetTimeouts(ReadTimeout, ReadHeaderTimeout, WriteTimeout, IdleTimeout time.Duration)

SetTimeouts will set the given timeouts of the Server. Set 0 to leave uninitialized.

func (*SimpleServer) Shutdown

func (S *SimpleServer) Shutdown() error

Shutdown will safely shut down the SimpleServer, returning any errors