Make HTTP middleware easier to use

server/router/handler.go

Index: server/router/handler.go
diff --git a/server/router/handler.go b/server/router/handler.go
new file mode 100644
index 0000000000000000000000000000000000000000..a372af2e53893ecdb340e99677a4e07c9a557008
--- /dev/null
+++ b/server/router/handler.go
@@ -0,0 +1,71 @@
+// Copyright 2016 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 router
+
+import "golang.org/x/net/context"
+
+type (
+	// Handler is the type for all request handlers.
+	Handler func(*Context)
+
+	// Middleware is a function that accepts a shared context and the next
+	// function. Since Middleware is typically part of a chain of functions
+	// that handles a HTTP request, it must obey the following rules.

[nodir, 2016/06/15 20:14:43]

an HTTP

[nishanths, 2016/06/16 00:14:18]

Done.

+	//
+	// Middleware must call next if it has not written to the Context
+	// by the end of the function. A Middleware must not call the next
+	// function if it has written to the Context. Middleware must not write
+	// to the Context after c.Written()==true. Middleware may

[nodir, 2016/06/15 20:14:43]

"after next is called and c.Written()==true"
otherwise, strictly speaking, it means it can write to context only once

[nishanths, 2016/06/16 00:14:18]

Done.

+	// modify the embedded context before calling  next.

[nodir, 2016/06/15 20:14:43]

use "a" and "the" consistently across paragraph (Middleware, A Middleware, call
next, call the next function)

[nishanths, 2016/06/16 00:14:18]

My bad. Done.

+	Middleware func(c *Context, next Handler)
+
+	// MiddlewareChain is a list of Middleware.
+	MiddlewareChain []Middleware
+)
+
+// Run executes the middleware chain and final handler with the given context as
+// the initial context.
+func (mc MiddlewareChain) Run(c *Context, h Handler) {
+	run(c, mc, nil, h)
+}
+
+// run executes the middleware chains m and n, and the handler h using the
+// Context c as the initial context.
+func run(c *Context, m, n MiddlewareChain, h Handler) {
+	if len(m) > 0 {

[nodir, 2016/06/15 20:14:43]

use `switch {`

[nishanths, 2016/06/16 00:14:18]

Done.

+		m[0](c, Handler(func(ctx *Context) {

[nodir, 2016/06/15 20:14:43]

`Handler(` is unnecessary because func is a literal

[nishanths, 2016/06/16 00:14:18]

Done.

+			run(ctx, m[1:], n, h)
+		}))
+	} else if len(n) > 0 {
+		n[0](c, Handler(func(ctx *Context) {

[nodir, 2016/06/15 20:14:43]

same here

[nishanths, 2016/06/16 00:14:18]

Done.

+			run(ctx, m, n[1:], h)
+		}))
+	} else {
+		h(c)
+	}
+}
+
+// MergeMiddlewareChains allocates a new array and copies the given middleware
+// chains into it.
+func MergeMiddlewareChains(mchains ...MiddlewareChain) (final MiddlewareChain) {
+	finalLen := 0
+	for _, mc := range mchains {
+		finalLen += len(mc)
+	}
+	final = make(MiddlewareChain, 0, finalLen)

[nodir, 2016/06/15 20:14:43]

optional: return if finalLen == 0

[nishanths, 2016/06/16 00:14:18]

Done.

+	for _, mc := range mchains {
+		final = append(final, mc...)
+	}
+	return
+}
+
+// MiddlewareWithContext returns a Middleware that embeds the given
+// context.Context into the shared context and calls the next handler.
+func MiddlewareWithContext(c context.Context) Middleware {

[nodir, 2016/06/15 20:14:43]

I am not sure we need this. odds are there will be only one usage in the
luci-common-base middleware sets up all services. dunno.

[nishanths, 2016/06/16 00:14:18]

I've left it in (for now). We can see how it turns out when we refactor the code
for the new API.

+	return Middleware(func(ctx *Context, next Handler) {

[nodir, 2016/06/15 20:14:43]

perhaps `Middleware(` is unnecessary

[nishanths, 2016/06/16 00:14:18]

Done.

+		ctx.Context = c
+		next(ctx)
+	})
+}