xhandler: github.com/rs/xhandler Index | Examples | Files

package xhandler

import "github.com/rs/xhandler"

Package xhandler provides a bridge between http.Handler and net/context.

xhandler enforces net/context in your handlers without sacrificing compatibility with existing http.Handlers nor imposing a specific router.

Thanks to net/context deadline management, xhandler is able to enforce a per request deadline and will cancel the context in when the client close the connection unexpectedly.

You may create net/context aware middlewares pretty much the same way as you would with http.Handler.

Index

Examples

Package Files

chain.go middleware.go new.go xhandler.go

func If Uses

func If(cond func(ctx context.Context, w http.ResponseWriter, r *http.Request) bool, condNext func(next HandlerC) HandlerC) func(next HandlerC) HandlerC

If is a special handler that will skip insert the condNext handler only if a condition applies at runtime.

Code:

c := xhandler.Chain{}

// Add a timeout handler only if the URL path matches a prefix
c.UseC(xhandler.If(
    func(ctx context.Context, w http.ResponseWriter, r *http.Request) bool {
        return strings.HasPrefix(r.URL.Path, "/with-timeout/")
    },
    xhandler.TimeoutHandler(2*time.Second),
))

http.Handle("/", c.Handler(xhandler.HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, req *http.Request) {
    fmt.Fprintf(w, "Welcome to the home page!")
})))

func New Uses

func New(ctx context.Context, h HandlerC) http.Handler

New creates a conventional http.Handler injecting the provided root context to sub handlers. This handler is used as a bridge between conventional http.Handler and context aware handlers.

func TimeoutHandler Uses

func TimeoutHandler(timeout time.Duration) func(next HandlerC) HandlerC

TimeoutHandler returns a Handler which adds a timeout to the context.

Child handlers have the responsability of obeying the context deadline and to return an appropriate error (or not) response in case of timeout.

type Chain Uses

type Chain []func(next HandlerC) HandlerC

Chain is a helper for chaining middleware handlers together for easier management.

Code:

c := xhandler.Chain{}
// Append a context-aware middleware handler
c.UseC(xhandler.CloseHandler)

// Mix it with a non-context-aware middleware handler
c.Use(cors.Default().Handler)

// Another context-aware middleware handler
c.UseC(xhandler.TimeoutHandler(2 * time.Second))

mux := http.NewServeMux()

// Use c.Handler to terminate the chain with your final handler
mux.Handle("/", c.Handler(xhandler.HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, req *http.Request) {
    fmt.Fprintf(w, "Welcome to the home page!")
})))

// You can reuse the same chain for other handlers
mux.Handle("/api", c.Handler(xhandler.HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, req *http.Request) {
    fmt.Fprintf(w, "Welcome to the API!")
})))

func (*Chain) Add Uses

func (c *Chain) Add(f ...interface{})

Add appends a variable number of additional middleware handlers to the middleware chain. Middleware handlers can either be context-aware or non-context aware handlers with the appropriate function signatures.

func (Chain) Handler Uses

func (c Chain) Handler(xh HandlerC) http.Handler

Handler wraps the provided final handler with all the middleware appended to the chain and returns a new standard http.Handler instance. The context.Background() context is injected automatically.

func (Chain) HandlerC Uses

func (c Chain) HandlerC(xh HandlerC) HandlerC

HandlerC wraps the provided final handler with all the middleware appended to the chain and returns a HandlerC instance.

func (Chain) HandlerCF Uses

func (c Chain) HandlerCF(xhc HandlerFuncC) HandlerC

HandlerCF wraps the provided final handler func with all the middleware appended to the chain and returns a HandlerC instance.

HandlerCF is equivalent to:

c.HandlerC(xhandler.HandlerFuncC(xhc))

func (Chain) HandlerCtx Uses

func (c Chain) HandlerCtx(ctx context.Context, xh HandlerC) http.Handler

HandlerCtx wraps the provided final handler with all the middleware appended to the chain and returns a new standard http.Handler instance.

func (Chain) HandlerF Uses

func (c Chain) HandlerF(hf http.HandlerFunc) http.Handler

HandlerF is a helper to provide a standard http handler function (http.HandlerFunc) to Handler(). Your final handler won't have access to the context though.

func (Chain) HandlerFC Uses

func (c Chain) HandlerFC(xhf HandlerFuncC) http.Handler

HandlerFC is a helper to provide a function (HandlerFuncC) to Handler().

HandlerFC is equivalent to:

c.Handler(xhandler.HandlerFuncC(xhc))

func (Chain) HandlerH Uses

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

HandlerH is a helper to provide a standard http handler (http.HandlerFunc) to Handler(). Your final handler won't have access to the context though.

func (*Chain) Use Uses

func (c *Chain) Use(f func(next http.Handler) http.Handler)

Use appends a standard http.Handler to the middleware chain without losing track of the context when inserted between two context aware handlers.

Caveat: the f function will be called on each request so you are better off putting any initialization sequence outside of this function.

func (*Chain) UseC Uses

func (c *Chain) UseC(f func(next HandlerC) HandlerC)

UseC appends a context-aware handler to the middleware chain.

func (*Chain) With Uses

func (c *Chain) With(f ...interface{}) *Chain

With creates a new middleware chain from an existing chain, extending it with additional middleware. Middleware handlers can either be context-aware or non-context aware handlers with the appropriate function signatures.

type HandlerC Uses

type HandlerC interface {
    ServeHTTPC(context.Context, http.ResponseWriter, *http.Request)
}

HandlerC is a net/context aware http.Handler

func CloseHandler Uses

func CloseHandler(next HandlerC) HandlerC

CloseHandler returns a Handler, cancelling the context when the client connection closes unexpectedly.

type HandlerFuncC Uses

type HandlerFuncC func(context.Context, http.ResponseWriter, *http.Request)

HandlerFuncC type is an adapter to allow the use of ordinary functions as an xhandler.Handler. If f is a function with the appropriate signature, xhandler.HandlerFuncC(f) is a xhandler.Handler object that calls f.

func (HandlerFuncC) ServeHTTPC Uses

func (f HandlerFuncC) ServeHTTPC(ctx context.Context, w http.ResponseWriter, r *http.Request)

ServeHTTPC calls f(ctx, w, r).

Package xhandler imports 3 packages (graph) and is imported by 26 packages. Updated 2017-07-09. Refresh now. Tools for package owners.