Extend Chain API, fix typos (#13)

Extend Chain API with 'Add' and 'With' methods.

Author: DeepAnchor

chain.go

@@ -6,19 +6,47 @@ import (
 	"golang.org/x/net/context"
 )
 
-// Chain is an helper to chain middleware handlers together for an easier
+// Chain is a helper for chaining middleware handlers together for easier
 // management.
 type Chain []func(next HandlerC) HandlerC
 
+// 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 (c *Chain) Add(f ...interface{}) {
+	for _, h := range f {
+		switch v := h.(type) {
+		case func(http.Handler) http.Handler:
+			c.Use(v)
+		case func(HandlerC) HandlerC:
+			c.UseC(v)
+		default:
+			panic("Adding invalid handler to the middleware 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.
+func (c *Chain) With(f ...interface{}) *Chain {
+	n := make(Chain, len(*c))
+	copy(n, *c)
+	n.Add(f...)
+	return &n
+}
+
 // UseC appends a context-aware handler to the middleware chain.
 func (c *Chain) UseC(f func(next HandlerC) HandlerC) {
 	*c = append(*c, f)
 }
 
 // Use appends a standard http.Handler to the middleware chain without
-// lossing track of the context when inserted between two context aware handlers.
+// 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 to put
+// Caveat: the f function will be called on each request so you are better off putting
 // any initialization sequence outside of this function.
 func (c *Chain) Use(f func(next http.Handler) http.Handler) {
 	xf := func(next HandlerC) HandlerC {
@@ -33,14 +61,14 @@ func (c *Chain) Use(f func(next http.Handler) http.Handler) {
 }
 
 // Handler wraps the provided final handler with all the middleware appended to
-// the chain and return a new standard http.Handler instance.
+// the chain and returns a new standard http.Handler instance.
 // The context.Background() context is injected automatically.
 func (c Chain) Handler(xh HandlerC) http.Handler {
 	ctx := context.Background()
 	return c.HandlerCtx(ctx, xh)
 }
 
-// HandlerFC is an helper to provide a function (HandlerFuncC) to Handler().
+// HandlerFC is a helper to provide a function (HandlerFuncC) to Handler().
 //
 // HandlerFC is equivalent to:
 //  c.Handler(xhandler.HandlerFuncC(xhc))
@@ -49,18 +77,18 @@ func (c Chain) HandlerFC(xhf HandlerFuncC) http.Handler {
 	return c.HandlerCtx(ctx, HandlerFuncC(xhf))
 }
 
-// HandlerH is an helper to provide a standard http handler (http.HandlerFunc)
-// to Handler(). Your final handler won't have access the context though.
+// 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 (c Chain) HandlerH(h http.Handler) http.Handler {
 	ctx := context.Background()
 	return c.HandlerCtx(ctx, HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, r *http.Request) {
 		h.ServeHTTP(w, r)
 	}))
 }
 
-// HandlerF is an helper to provide a standard http handler function
+// HandlerF is a helper to provide a standard http handler function
 // (http.HandlerFunc) to Handler(). Your final handler won't have access
-// the context though.
+// to the context though.
 func (c Chain) HandlerF(hf http.HandlerFunc) http.Handler {
 	ctx := context.Background()
 	return c.HandlerCtx(ctx, HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, r *http.Request) {
@@ -69,7 +97,7 @@ func (c Chain) HandlerF(hf http.HandlerFunc) http.Handler {
 }
 
 // HandlerCtx wraps the provided final handler with all the middleware appended to
-// the chain and return a new standard http.Handler instance.
+// the chain and returns a new standard http.Handler instance.
 func (c Chain) HandlerCtx(ctx context.Context, xh HandlerC) http.Handler {
 	return New(ctx, c.HandlerC(xh))
 }

chain_example_test.go

@@ -35,10 +35,43 @@ func ExampleChain() {
 	})))
 }
 
+func ExampleAddChain() {
+	c := xhandler.Chain{}
+
+	close := xhandler.CloseHandler
+	cors := cors.Default().Handler
+	timeout := xhandler.TimeoutHandler(2 * time.Second)
+	auth := func(next xhandler.HandlerC) xhandler.HandlerC {
+		return xhandler.HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, r *http.Request) {
+			if v := ctx.Value("Authorization"); v == nil {
+				http.Error(w, "Not authorized", http.StatusUnauthorized)
+				return
+			}
+			next.ServeHTTPC(ctx, w, r)
+		})
+	}
+
+	c.Add(close, cors, timeout)
+
+	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!")
+	})))
+
+	// Create a new chain from an existing one, and add route-specific middleware to it
+	protected := c.With(auth)
+
+	mux.Handle("/admin", protected.Handler(xhandler.HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, req *http.Request) {
+		fmt.Fprintf(w, "protected endpoint!")
+	})))
+}
+
 func ExampleIf() {
 	c := xhandler.Chain{}
 
-	// Add timeout handler only if the path match a prefix
+	// 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/")

chain_test.go

@@ -110,3 +110,100 @@ func TestChainHandlerC(t *testing.T) {
 
 	assert.Equal(t, 3, handlerCalls, "all handler called once")
 }
+
+func TestAdd(t *testing.T) {
+	handlerCalls := 0
+	h1 := func(next HandlerC) HandlerC {
+		return HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, r *http.Request) {
+			handlerCalls++
+			ctx = context.WithValue(ctx, "test", 1)
+			next.ServeHTTPC(ctx, w, r)
+		})
+	}
+	h2 := func(next http.Handler) http.Handler {
+		handlerCalls++
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			// Change r and w values
+			w = httptest.NewRecorder()
+			r = &http.Request{}
+			next.ServeHTTP(w, r)
+		})
+	}
+	h3 := func(next HandlerC) HandlerC {
+		return HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, r *http.Request) {
+			handlerCalls++
+			ctx = context.WithValue(ctx, "test", 2)
+			next.ServeHTTPC(ctx, w, r)
+		})
+	}
+
+	c := Chain{}
+	c.Add(h1, h2, h3)
+	h := c.HandlerC(HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, r *http.Request) {
+		handlerCalls++
+
+		assert.Equal(t, 2, ctx.Value("test"),
+			"third handler should overwrite first handler's context value")
+		assert.Equal(t, 1, ctx.Value("mainCtx"),
+			"the mainCtx value should be pass through")
+	}))
+
+	mainCtx := context.WithValue(context.Background(), "mainCtx", 1)
+	h.ServeHTTPC(mainCtx, nil, nil)
+	assert.Equal(t, 4, handlerCalls, "all handler called once")
+}
+
+func TestWith(t *testing.T) {
+	handlerCalls := 0
+	h1 := func(next HandlerC) HandlerC {
+		return HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, r *http.Request) {
+			handlerCalls++
+			ctx = context.WithValue(ctx, "test", 1)
+			next.ServeHTTPC(ctx, w, r)
+		})
+	}
+	h2 := func(next http.Handler) http.Handler {
+		handlerCalls++
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			// Change r and w values
+			w = httptest.NewRecorder()
+			r = &http.Request{}
+			next.ServeHTTP(w, r)
+		})
+	}
+	h3 := func(next HandlerC) HandlerC {
+		return HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, r *http.Request) {
+			handlerCalls++
+			ctx = context.WithValue(ctx, "test", 2)
+			next.ServeHTTPC(ctx, w, r)
+		})
+	}
+
+	c := Chain{}
+	c.Add(h1)
+	d := c.With(h2, h3)
+
+	h := c.HandlerC(HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, r *http.Request) {
+		handlerCalls++
+
+		assert.Equal(t, 1, ctx.Value("test"),
+			"third handler should not overwrite the first handler's context value")
+		assert.Equal(t, 1, ctx.Value("mainCtx"),
+			"the mainCtx value should be pass through")
+	}))
+	i := d.HandlerC(HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, r *http.Request) {
+		handlerCalls++
+
+		assert.Equal(t, 2, ctx.Value("test"),
+			"third handler should overwrite first handler's context value")
+		assert.Equal(t, 1, ctx.Value("mainCtx"),
+			"the mainCtx value should be pass through")
+	}))
+
+	mainCtx := context.WithValue(context.Background(), "mainCtx", 1)
+	h.ServeHTTPC(mainCtx, nil, nil)
+	assert.Equal(t, 2, handlerCalls, "all handlers called once")
+	handlerCalls = 0
+	i.ServeHTTPC(mainCtx, nil, nil)
+	assert.Equal(t, 4, handlerCalls, "all handler called once")
+}

middleware.go

@@ -7,8 +7,8 @@ import (
 	"golang.org/x/net/context"
 )
 
-// CloseHandler returns a Handler cancelling the context when the client
-// connection close unexpectedly.
+// CloseHandler returns a Handler, cancelling the context when the client
+// connection closes unexpectedly.
 func CloseHandler(next HandlerC) HandlerC {
 	return HandlerFuncC(func(ctx context.Context, w http.ResponseWriter, r *http.Request) {
 		// Cancel the context if the client closes the connection
@@ -33,7 +33,7 @@ func CloseHandler(next HandlerC) HandlerC {
 
 // TimeoutHandler returns a Handler which adds a timeout to the context.
 //
-// Child handlers have the responsability to obey the context deadline and to return
+// Child handlers have the responsability of obeying the context deadline and to return
 // an appropriate error (or not) response in case of timeout.
 func TimeoutHandler(timeout time.Duration) func(next HandlerC) HandlerC {
 	return func(next HandlerC) HandlerC {

xhandler.go

@@ -8,7 +8,7 @@
 // the connection unexpectedly.
 //
 // You may create net/context aware middlewares pretty much the same way as
-// you would do with http.Handler.
+// you would with http.Handler.
 package xhandler // import "github.com/rs/xhandler"
 
 import (
@@ -23,7 +23,7 @@ type HandlerC interface {
 }
 
 // HandlerFuncC type is an adapter to allow the use of ordinary functions
-// as a xhandler.Handler. If f is a function with the appropriate signature,
+// as an xhandler.Handler. If f is a function with the appropriate signature,
 // xhandler.HandlerFuncC(f) is a xhandler.Handler object that calls f.
 type HandlerFuncC func(context.Context, http.ResponseWriter, *http.Request)