Make HTTP middleware easier to use

server/middleware/middleware.go

 // Copyright 2015 The LUCI Authors. All rights reserved.
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
 // Package middleware defines base type for context-aware HTTP request handler.
 // See appengine/middleware for examples of how to use it in GAE environment.
 package middleware
 
 import (
         "net/http"
 
         "github.com/julienschmidt/httprouter"
         "golang.org/x/net/context"
 )
 
 // Handler is the type for all request handlers. Of particular note, it's the
 // same as httprouter.Handle, except that it also has a context parameter.
 type Handler func(context.Context, http.ResponseWriter, *http.Request, httprouter.Params)
 
+// ChainedHandler is the same as Handler, except that it includes a Handler
+// parameter that calls the next ChainedHandler in the middleware chain when invoked.
+type ChainedHandler func(context.Context, http.ResponseWriter, *http.Request, httprouter.Params, Handler)

[iannucci, 2016/06/09 21:30:08]

Since we have all the middleware in this repo, it would probably be best to just
atomically change everything once we converge on the design particulars I think
:)

[Vadim Sh., 2016/06/09 21:45:12]

+1

Having both Handler and ChainedHandler is confusing.

While at it... Maybe hide r, rw, p, and next inside single struct? Robbie, what
do you think?

type Context {
  context.Context

  Response http.ResponseWriter
  Request *http.Request
  Params httprouter.Params

  Next Handler
}

type Handler func(Context)

or maybe keep Next outside the context, since it's sort of changing all the time
(not really a stable during execution of the request, like other stuff in the
context).

[nishanths, 2016/06/13 17:30:44]

I like this too. I've changed the router package to use the Context-style Vadim
describes with a few changes. Next is provided as a method on *Context. Instead,
the struct contains a field for the list of handlers.

+
 // Middleware takes a handler, wraps it with some additional logic, and returns
 // resulting handler.
 type Middleware func(Handler) Handler
 
-// Base is a start of the middlware chain. It sets up initial context with all
+// Chain contains a Handler and a pointer to the next element in the Chain.
+type Chain struct {
+        Handler ChainedHandler
+        next    *Chain
+}

[iannucci, 2016/06/09 21:30:08]

Why not just a []Handler? I think it could simplify basically all of the
functions you have below :-)

[Vadim Sh., 2016/06/09 21:45:12]

+1

since chains are append-only, it is even fine to reuse underlying array for
storage

[nishanths, 2016/06/13 17:30:44]

Good point. The API primariy now uses router.Handler and []router.Handler.

+
+// Handle calls the chain's Handler function after adding necessary arguments.
+func (c *Chain) Handle(ctx context.Context, wr http.ResponseWriter, r *http.Request, p httprouter.Params) {
+        if c.next != nil {
+                c.Handler(ctx, wr, r, p, c.next.Handle)
+        }
+}
+
+// Append adds chains to an existing chain and returns the result.
+func (c Chain) Append(chains ...Chain) Chain {
+        if len(chains) == 0 {
+                return c
+        }
+        // TODO(nishanths): Hold a private reference to the tail *Chain in the
+        // Chain struct to eliminate this loop.
+        for ; c.next != nil; c = *c.next {
+        }
+        c.next = &chains[0]
+        return chains[0].Append(chains[1:]...)
+}
+
+// AppendHandlers adds a list of ChainedHandlers to a Chain.
+func (c Chain) AppendHandlers(handlers ...ChainedHandler) Chain {
+        chain := NewChain(handlers...)
+        return c.Append(chain)
+}
+
+// NewChain creates a Chain from ChainedHandler list.
+func NewChain(handlers ...ChainedHandler) Chain {
+        if len(handlers) == 0 {
+                return Chain{handlers[0], nil}
+        }
+        next := NewChain(handlers[1:]...)
+        return Chain{handlers[0], &next}
+}
+
+// Base is a start of the middleware chain. It sets up initial context with all
 // base services and passes it to the given handler. Return value of Base can
 // be plugged in into httprouter directly.
 type Base func(Handler) httprouter.Handle
 
 // TestingBase is Base that passes given context to the handler. Useful in
 // tests.
 func TestingBase(c context.Context) Base {
         return func(h Handler) httprouter.Handle {
                 return func(rw http.ResponseWriter, r *http.Request, p httprouter.Params) {
                         h(c, rw, r, p)
                 }
         }
 }
 
 // WithContextValue is a middleware that adds a value to the context before
 // calling the handler.
 func WithContextValue(h Handler, key, val interface{}) Handler {
         return func(c context.Context, rw http.ResponseWriter, r *http.Request, p httprouter.Params) {
                 h(context.WithValue(c, key, val), rw, r, p)
         }
 }