http

Documentation

Index

• Constants
• Variables
• func CheckAcceptHeader(acceptType string) func(http.Handler) http.Handler
• func CheckContentHeader(contentType string) func(http.Handler) http.Handler
• func LogRequest(next http.Handler) http.Handler
• func NewClient() *http.Client
• func NotAllowed() http.Handler
• func NotFound() http.Handler
• func RateLimit(clients map[string]Allower) func(next http.Handler) http.Handler
• func RespondWithJSON(w http.ResponseWriter, r *http.Request, code int, data interface{})
• type Allower
• type RateLimiterMw
  • func (mw *RateLimiterMw) RateLimit() func(next http.Handler) http.Handler
• type Server
  • func NewServer(addr string, h http.Handler) *Server
  • func (s *Server) Log(msg string, fields ...interface{}) error
  • func (s *Server) RecoverPanic(next http.Handler) http.Handler
  • func (s *Server) Start(errorChan chan error)

Constants

const (
	DefaultReadTimeout  time.Duration = 5 * time.Second
	DefaultWriteTimeout time.Duration = 10 * time.Second
	DefaultIdleTimeout  time.Duration = 120 * time.Second
	// DefaultClientTimeout is set the same as a server WriteTimeout so the client is not waiting for a
	// response longer than the server is going to take to send one.
	DefaultClientTimeout time.Duration = 10 * time.Second
)

The constants provided are defaults for net/http servers & clients. They are sensible default values for an API server but can and should be adapted by the user according to the use-case, once the object is instantiated. Further reading at https://blog.gopheracademy.com/advent-2016/exposing-go-on-the-internet/.

const (
	DefaultRateLimit  = 2
	DefaultBurstLimit = 4
)

const DefaultShutdownTimeout time.Duration = 10 * time.Second

DefaultShutdown is the maximum time a process should wait for a graceful server shutdown. Should be used for context deadlines.

Variables

var (
	// ErrNotFound is a standard error to return with 404 status code.
	ErrNotFound error = errors.New("http: Hello, is it me you're looking for? Because the page you requested doesn't exist")

	// ErrNotAllowed is a standard error to return with 405 status.
	ErrNotAllowed error = errors.New("http: we don't do that here")

	// ErrInvalidRequest is a standard error to return with 400 status code.
	ErrInvalidRequest error = errors.New("http: invalid request or payload")

	// ErrUnsupportedMedia is a standard error to return with 415 status code.
	ErrUnsupportedMedia error = errors.New("http: unsupported media type")
)

Functions

func CheckAcceptHeader

func CheckAcceptHeader(acceptType string) func(http.Handler) http.Handler

CheckAcceptHeader checks the incoming request Accept header matches a user specified header before handling the request. If false it writes 406 Not Acceptable return header and processing is stopped. If true, or the client does not send a header or will accept all content, execution continues.

func CheckContentHeader

func CheckContentHeader(contentType string) func(http.Handler) http.Handler

CheckContentHeader checks the incoming request Content-Type Header matches a user specified header before handling the request. If false it sets a 415 MediaNotSupported return header and processing is stopped. An empty string is not considered to be false. GET requests are ignored as no content is sent.

func LogRequest

func LogRequest(next http.Handler) http.Handler

LogRequest will log the basic info of an incoming request.

func NewClient

func NewClient() *http.Client

NewClient returns a net/http Client with a pre-configured Timeout, making it safer to use in production environments, as the user cannot forget to set it. The value used is a suggested value only, the user can and should adapt it according to the use-case.

func NotAllowed

func NotAllowed() http.Handler

NotAllowed wraps http.Error and sends a plain text error message with a http.MethodNotAllowed code.

func NotFound

func NotFound() http.Handler

NotFound wraps http.Error and sends a plain text error message with a http.StatusNotFound code. Acts exactly like http.NotFoundHandler() but sends a custom message.

func RateLimit

func RateLimit(clients map[string]Allower) func(next http.Handler) http.Handler

RateLimit will apply a request rate limiter based on the incoming requests IP address.

func RespondWithJSON

func RespondWithJSON(w http.ResponseWriter, r *http.Request, code int, data interface{})

RespondWithJSON is a convenience function to set headers and write a response with a single call. If a response fails, the server panics. It is good practice to wrap handlers in a recovery handler.

Types

type Allower

type Allower interface {
	Allow() bool
}

type RateLimiterMw

type RateLimiterMw struct {
	Limit int
	Burst int
	// contains filtered or unexported fields
}

func (*RateLimiterMw) RateLimit

func (mw *RateLimiterMw) RateLimit() func(next http.Handler) http.Handler

type Server

type Server struct {
	*http.Server
	log.Logger
}

func NewServer

func NewServer(addr string, h http.Handler) *Server

NewServer wraps and returns a net/http Server with pre-configured Timeouts, making it safer to use in production environments, as the user cannot forget to set them. Values used are suggested values only, the user can and should adapt them according to the use-case.

func (*Server) Log

func (s *Server) Log(msg string, fields ...interface{}) error

Log implements the log.Logger interface. Logging will be passed to the servers logger if one is declared, otherwise handled by the log package singleton.

func (*Server) RecoverPanic

func (s *Server) RecoverPanic(next http.Handler) http.Handler

RecoverPanic will attempt to recover from any panics, log the reason for the panic and return an internal server error. This middleware should be applied at the start of any middleware chains.

func (*Server) Start

func (s *Server) Start(errorChan chan error)