httpmw

README

httpmw

A collection of Go HTTP handlers.

Installation

go get github.com/paccolamano/httpmw

Features

• bodylimit blocks requests that have a payload larger than the allowed size
• logger is middleware that allows you to log incoming HTTP requests.
• ratelimit protects your server from excessive requests with configurable algorithms (Token Bucket, Fixed Window)
• recovery intercepts panics raised in handlers before they crash the server
• tracer is middleware that propagates or creates a request ID (AKA correlation ID)

Examples

You can find examples of how middleware can be used in the README files of the sub-packages.

License

MIT

Documentation

Overview

Package httpmw provides utilities for composing HTTP middleware.

Instead of nesting middleware calls like:

mw1(mw2(mw3(handler)))

You can use Chain to compose them:

httpmw.NewChain(mw1, mw2, mw3).Then(handler)

The chain is reusable and can be extended:

base := httpmw.NewChain(logger, tracer)
api := base.Append(auth, rateLimit)

base.Then(publicHandler)
api.Then(protectedHandler)

Works with http.ServeMux and any router that implements http.Handler.

Index

• type Chain
  • func NewChain(middlewares ...Middleware) Chain
  • func (c Chain) Append(middlewares ...Middleware) Chain
  • func (c Chain) Handler() Middleware
  • func (c Chain) Len() int
  • func (c Chain) Then(h http.Handler) http.Handler
  • func (c Chain) ThenFunc(fn http.HandlerFunc) http.Handler
  • func (c Chain) Wrap(h http.Handler) http.Handler
• type Middleware

Types

type Chain

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

Chain holds a sequence of middleware to be applied.

func NewChain

func NewChain(middlewares ...Middleware) Chain

NewChain creates a new Chain with the given middleware. Middleware will be applied in the order they are provided, meaning the first middleware wraps the outermost layer.

Example:

httpmw.NewChain(mw1, mw2, mw3).Then(handler)
// Equivalent to: mw1(mw2(mw3(handler)))
// Request flow: mw1 -> mw2 -> mw3 -> handler

func (Chain) Append

func (c Chain) Append(middlewares ...Middleware) Chain

Append extends the chain with additional middleware, returning a new Chain. The original chain is not modified.

Example:

base := httpmw.NewChain(logger, tracer)
api := base.Append(auth)
// base remains: logger -> tracer
// api becomes: logger -> tracer -> auth

func (Chain) Handler

func (c Chain) Handler() Middleware

Handler returns a middleware function that applies the entire chain. This allows a Chain to be used as a single middleware in another chain or with routers that use the Use() pattern.

Example:

common := httpmw.NewChain(logger, tracer)

mux := http.NewServeMux()
// Use as middleware with a mux wrapper
http.Handle("/", common.Handler()(mux))

// Or combine chains
full := httpmw.NewChain(common.Handler(), auth)

func (Chain) Len

func (c Chain) Len() int

Len returns the number of middleware in the chain.

func (Chain) Then

func (c Chain) Then(h http.Handler) http.Handler

Then applies the chain to the final handler and returns the resulting http.Handler. This is the terminal operation that produces a usable handler.

Example:

handler := httpmw.NewChain(logger, auth).Then(myHandler)
http.Handle("/api", handler)

func (Chain) ThenFunc

func (c Chain) ThenFunc(fn http.HandlerFunc) http.Handler

ThenFunc applies the chain to an http.HandlerFunc. This is a convenience method equivalent to Then(http.HandlerFunc(fn)).

Example:

handler := httpmw.NewChain(logger, auth).ThenFunc(func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Hello"))
})

func (Chain) Wrap

func (c Chain) Wrap(h http.Handler) http.Handler

Wrap applies the chain to a handler and returns it. This is an alias for Then, provided for semantic clarity when wrapping mux/routers.

Example:

mux := http.NewServeMux()
mux.HandleFunc("/", homeHandler)

// Wrap the entire mux with middleware
http.ListenAndServe(":8080", httpmw.NewChain(logger, recovery).Wrap(mux))

type Middleware

type Middleware func(http.Handler) http.Handler

Middleware is a function that wraps an http.Handler.