httputils

README

go-httputils

This package provides some utility wrapper for the HTTP package. The major protagonist ist the Handler object, which wraps the default http.Server with a mux.Router and takes care to measure durations with prometheus for every HTTP call.

Usage example

package main

import (
	"fmt"
	"net/http"
	"time"

	"github.com/sirupsen/logrus"
	"github.com/aklinkert/go-httputils"
)

func main() {
	// handler is based on logrus for logging
	logger := logrus.New()
	httpLogger := logger.WithField("component", "http")

	// first address is the main http listener, second one is for the prometheus endpoint
	// I usually have both on different ports to have the prometheus metrics endpoint not exposed but 
	// only serve internal traffic, e.g. only inside a kubernetes cluster or other private network.
	handler := httputils.NewHandler(httpLogger, ":8080", ":9090")

	// handler provides some useful Handle*() methods that support both http.HandlerFunc http.Handler using
	// Handle() and HandleFunc() respectively. Also HandlePrefix() and HandleFuncPrefix() support a prefixed
	// catch-all approach, e.g. when you wanna do dynamic routes that are not handled by mux (serving images or so)
	handler.HandleFunc("/example", func(rw http.ResponseWriter, r *http.Request) {
		_, err := fmt.Fprintf(rw, "Hello from example, current time is %v", time.Now())
		if err != nil {
			logger.Error(err)
		}
	})

	// default graceful shutdown duration is 2 seconds
	handler.SetGracefulShutdownDuration(10 * time.Second)

	// Serve() is blocking the main routine until a shutdown is received, using https://github.com/aklinkert/go-exitcontext
	// If you want to modify the context behavior use httputils.NewHandlerWithContext(...)
	handler.Serve()
}

License

Apache 2.0 Licence

Documentation

Index

• func NewTimer(logger logrus.FieldLogger, handler http.Handler) http.Handler
• type Handler
  • func NewHandler(logger logrus.FieldLogger, listen, metricsListen string) *Handler
  • func NewHandlerWithContext(ctx context.Context, logger logrus.FieldLogger, listen, metricsListen string) *Handler
  • func (h *Handler) AddOkHandler(path string)
  • func (h *Handler) Handle(path string, handler http.Handler) *mux.Route
  • func (h *Handler) HandleFunc(path string, f func(http.ResponseWriter, *http.Request)) *mux.Route
  • func (h *Handler) HandleFuncPrefix(prefix string, f func(http.ResponseWriter, *http.Request)) *mux.Route
  • func (h *Handler) HandlePrefix(prefix string, handler http.Handler) *mux.Route
  • func (h *Handler) Serve()
  • func (h *Handler) SetGracefulShutdownDuration(duration time.Duration)
• type OkHandler
  • func NewOkHandler(logger logrus.FieldLogger) *OkHandler
  • func (h *OkHandler) ServeHTTP(rw http.ResponseWriter, _ *http.Request)
• type Timer
  • func (h *Timer) ServeHTTP(rw http.ResponseWriter, r *http.Request)

Functions

func NewTimer

func NewTimer(logger logrus.FieldLogger, handler http.Handler) http.Handler

NewTimer returns a new Timer instance

Types

type Handler

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

Handler is a custom wrapper around http.Server that cares about graceful termination.

func NewHandler

func NewHandler(logger logrus.FieldLogger, listen, metricsListen string) *Handler

NewHandler constructs the whole internal HTTP routing / handlers

func NewHandlerWithContext

func NewHandlerWithContext(ctx context.Context, logger logrus.FieldLogger, listen, metricsListen string) *Handler

NewHandlerWithContext constructs the whole internal HTTP routing / handlers and accepts a context

func (*Handler) AddOkHandler

func (h *Handler) AddOkHandler(path string)

AddOkHandler adds an OKHandler to the given path. Useful for custom uptime check or health check URLs.

func (*Handler) Handle

func (h *Handler) Handle(path string, handler http.Handler) *mux.Route

Handle registers a new route with a matcher for the URL path. See Route.Path() and Route.Handler(). Wrapper around mux.router.

func (*Handler) HandleFunc

func (h *Handler) HandleFunc(path string, f func(http.ResponseWriter, *http.Request)) *mux.Route

HandleFunc registers a new route with a matcher for the URL path. See Route.Path() and Route.HandlerFunc(). Wrapper around mux.router.

func (*Handler) HandleFuncPrefix

func (h *Handler) HandleFuncPrefix(prefix string, f func(http.ResponseWriter, *http.Request)) *mux.Route

HandleFuncPrefix registers a new route with a matcher for the URL path. See Route.Prefix() and Route.HandleFunc(). Wrapper around mux.router.

func (*Handler) HandlePrefix

func (h *Handler) HandlePrefix(prefix string, handler http.Handler) *mux.Route

HandlePrefix registers a new route with a matcher for the URL path. See Route.Prefix() and Route.Handler(). Wrapper around mux.router.

func (*Handler) Serve

func (h *Handler) Serve()

Serve starts the server and blocks until the process is terminated by signals

func (*Handler) SetGracefulShutdownDuration

func (h *Handler) SetGracefulShutdownDuration(duration time.Duration)

SetGracefulShutdownDuration overrides the default duration to wait for requests to be finished during graceful shutdown before it is enforced

type OkHandler

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

OkHandler handles http requests and answers with "ok" :)

func NewOkHandler

func NewOkHandler(logger logrus.FieldLogger) *OkHandler

NewOkHandler returns a new OkHandler instance

func (*OkHandler) ServeHTTP

func (h *OkHandler) ServeHTTP(rw http.ResponseWriter, _ *http.Request)

ServeHTTP actually answers the http request. Surprising, isn't it?

type Timer

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

Timer measures request durations for the nested handler

func (*Timer) ServeHTTP

func (h *Timer) ServeHTTP(rw http.ResponseWriter, r *http.Request)

ServeHTTP times the request and collects request infos