srv

README

Srv

Go Web Server with graceful termination, configurable health and info endpoints

Documentation

Index

• Variables
• func HealthHandler(metrics *[]HealthMetric) httprouter.Handle
• func InfoHandler(metrics *[]InfoMetric) httprouter.Handle
• func MethodNotAllowedHandler() http.HandlerFunc
• func NotFoundHandler() http.HandlerFunc
• func PanicHandler() func(http.ResponseWriter, *http.Request, interface{})
• func RouteHandler(routes *[]RouteInfo) httprouter.Handle
• type HealthMetric
• type HealthMetricHandler
• type HealthMetricResult
• type HealthResponse
• type InfoMetric
• type InfoMetricHandler
• type InfoResponse
• type InfoResponseGC
• type Option
  • func OptionAppEnv(envName string) Option
  • func OptionContextPath(path string) Option
• type RouteInfo
• type Server
  • func New(opts ...Option) *Server
  • func (s *Server) AddInfoMetric(name string, handler InfoMetricHandler)
  • func (s *Server) AddLivenessCheck(name string, handler HealthMetricHandler)
  • func (s *Server) AddReadinessCheck(name string, handler HealthMetricHandler)
  • func (s *Server) DELETE(path string, handle httprouter.Handle)
  • func (s *Server) GET(path string, handle httprouter.Handle)
  • func (s *Server) HEAD(path string, handle httprouter.Handle)
  • func (s *Server) Handle(method, path string, handle httprouter.Handle)
  • func (s Server) IsRunning() bool
  • func (s *Server) OPTIONS(path string, handle httprouter.Handle)
  • func (s *Server) PATCH(path string, handle httprouter.Handle)
  • func (s *Server) POST(path string, handle httprouter.Handle)
  • func (s *Server) PUT(path string, handle httprouter.Handle)
  • func (s *Server) Run(addr string) error
  • func (s *Server) Shutdown() (err error)

Variables

var ErrServerAlreadyRunning = errors.New("common/server: already running")

ErrServerAlreadyRunning is the error returned when the server is already running

var ErrServerStopped = errors.New("common/server: not running")

ErrServerStopped is the error returned when the server is not running

Functions

func HealthHandler

func HealthHandler(metrics *[]HealthMetric) httprouter.Handle

HealthHandler returns basic system health information

func InfoHandler

func InfoHandler(metrics *[]InfoMetric) httprouter.Handle

InfoHandler returns basic system runtime information

func MethodNotAllowedHandler

func MethodNotAllowedHandler() http.HandlerFunc

MethodNotAllowedHandler returns the handler for a request where the HTTP verb is not allowed. This is used to override the default httprouter handler

func NotFoundHandler

func NotFoundHandler() http.HandlerFunc

NotFoundHandler returns the handler for a not found resource. This is used as the default handler for the httprouter not found interface

func PanicHandler

func PanicHandler() func(http.ResponseWriter, *http.Request, interface{})

PanicHandler returns the handler for an application panic during a request This overrides the default httprouter handler to not expose stacktraces from the application during an exception

func RouteHandler

func RouteHandler(routes *[]RouteInfo) httprouter.Handle

RouteHandler returns the handler for listing out the avaliable routes for the system including their HTTP verbs

Types

type HealthMetric

type HealthMetric struct {
	Name     string
	GetValue HealthMetricHandler
}

HealthMetric is the struct for a health metric

type HealthMetricHandler

type HealthMetricHandler func() HealthMetricResult

HealthMetricHandler is the handler func that needs to be implemented for adding custom health checks.

type HealthMetricResult

type HealthMetricResult struct {
	OK     bool                   `json:"-"`              // if false the service will return an error on the health endpoint
	Status string                 `json:"status"`         // an optional status string to use instead of the default "ok" and "not ok"
	Info   map[string]interface{} `json:"info,omitempty"` // additional information about the health (such as response time, uptime, etc.)
}

HealthMetricResult is the returning struct for calling the HealthMetricHandler

type HealthResponse

type HealthResponse struct {
	Status string `json:"status"`

	Metrics map[string]HealthMetricResult `json:"metrics"`
}

HealthResponse is the response model for the HealthHandler endpoint

type InfoMetric

type InfoMetric struct {
	Name     string
	GetValue InfoMetricHandler
}

InfoMetric is the struct for a info metric

type InfoMetricHandler

type InfoMetricHandler func() interface{}

InfoMetricHandler is the handler func that needs to be implemented for adding custom info metrics.

type InfoResponse

type InfoResponse struct {
	Goroutines int            `json:"goroutines"`
	Uptime     string         `json:"uptime"`
	NumCPU     int            `json:"numCpu"`
	MemUsed    string         `json:"memUsed"`
	GC         InfoResponseGC `json:"gc"`

	Metrics map[string]interface{} `json:"metrics"`
}

InfoResponse is the response model for the InfoHandler endpoint

type InfoResponseGC

type InfoResponseGC struct {
	Enabled  bool   `json:"enabled"`
	Runs     uint32 `json:"runs"`
	NextRun  string `json:"nextRun"`
	CPUUsage string `json:"cpuUsage"`
	Time     string `json:"time"`
}

InfoResponseGC is the response model for the GC in the InfoResponse struct

type Option

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

Option is the struct for server based options

func OptionAppEnv

func OptionAppEnv(envName string) Option

OptionAppEnv is used to set specific security runtime environment variables. When value is dev the panic handler is disabled to view stacktraces in the browser and the /_system/routes route is avaliable to show all routes that were registered with the server.

func OptionContextPath

func OptionContextPath(path string) Option

OptionContextPath is used to set a prefix to the path of all requests on the server. This value must be passed in when creating a new instance of the Server. If using the context path you can always set a route to outside of the context path by directly calling one of the Router methods on the Server struct.

type RouteInfo

type RouteInfo struct {
	Method string `json:"method"`
	Path   string `json:"path"`
}

RouteInfo is the response object for a single route info object

type Server

type Server struct {
	*httprouter.Router
	*negroni.Negroni
	// contains filtered or unexported fields
}

Server struct containing the httprouter routing handler and the negroni middleware framework

func New

func New(opts ...Option) *Server

New creates a new instance of the router. Context path is the prefix to all url paths.

func (*Server) AddInfoMetric

func (s *Server) AddInfoMetric(name string, handler InfoMetricHandler)

AddInfoMetric to the list of info metrics used to get info about the running system at the /_system/info endpoint. The name parameter should be camel-case.

func (*Server) AddLivenessCheck

func (s *Server) AddLivenessCheck(name string, handler HealthMetricHandler)

AddLivenessCheck to the list of liveness metrics used to validate the system is running and healthy at the /_system/liveness endpoint. The name parameter should be camel-case. Liveness metrics are defined as the server has moved into a broken state and cannot recover except by being restarted.

func (*Server) AddReadinessCheck

func (s *Server) AddReadinessCheck(name string, handler HealthMetricHandler)

AddReadinessCheck to the list of readiness metrics used to validate the system is running and healthy at the /_system/readiness endpoint. The name parameter should be camel-case. Readiness metrics are used when the server is temporarily unable to serve traffic this is different from liveness in that readiness should not restart the application when it is failing.

func (*Server) DELETE

func (s *Server) DELETE(path string, handle httprouter.Handle)

DELETE is a shortcut for router.Handle("DELETE", path, handle)

func (*Server) GET

func (s *Server) GET(path string, handle httprouter.Handle)

GET is a shortcut for router.Handle("GET", path, handle)

func (*Server) HEAD

func (s *Server) HEAD(path string, handle httprouter.Handle)

HEAD is a shortcut for router.Handle("HEAD", path, handle)

func (*Server) Handle

func (s *Server) Handle(method, path string, handle httprouter.Handle)

Handle is a function that can be registered to a route to handle HTTP requests. Like http.HandlerFunc, but has a third parameter for the values of wildcards (variables).

func (Server) IsRunning

func (s Server) IsRunning() bool

IsRunning tells if the server is currently running

func (*Server) OPTIONS

func (s *Server) OPTIONS(path string, handle httprouter.Handle)

OPTIONS is a shortcut for router.Handle("OPTIONS", path, handle)

func (*Server) PATCH

func (s *Server) PATCH(path string, handle httprouter.Handle)

PATCH is a shortcut for router.Handle("PATCH", path, handle)

func (*Server) POST

func (s *Server) POST(path string, handle httprouter.Handle)

POST is a shortcut for router.Handle("POST", path, handle)

func (*Server) PUT

func (s *Server) PUT(path string, handle httprouter.Handle)

PUT is a shortcut for router.Handle("PUT", path, handle)

func (*Server) Run

func (s *Server) Run(addr string) error

Run the HTTP server on the addr provided with graceful shutdown

func (*Server) Shutdown

func (s *Server) Shutdown() (err error)

Shutdown gracefully stops the HTTP server