Make HTTP middleware easier to use

server/router/router.go

+// 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 provides an HTTP router with support for middleware and
+// subrouters. It wraps around julienschmidt/httprouter.
+package router
+
+import (
+        "net/http"
+
+        "github.com/julienschmidt/httprouter"
+        "golang.org/x/net/context"
+)
+
+type (
+        // Router is the main type for the package. To create a Router, use New.
+        Router struct {
+                hrouter    *httprouter.Router
+                middleware MiddlewareChain
+                BasePath   string
+        }
+
+        // Context contains the context, response writer, request, and params shared
+        // across Middleware and Handler functions.
+        Context struct {
+                context.Context
+                writer  http.ResponseWriter
+                Request *http.Request
+                Params  httprouter.Params
+                status  int
+        }
+)
+
+var (
+        _ http.Handler        = (*Router)(nil)
+        _ http.ResponseWriter = (*Context)(nil)
+        _ context.Context     = (*Context)(nil)
+)
+
+// New creates a Router.
+func New() *Router {
+        return &Router{
+                hrouter:  httprouter.New(),
+                BasePath: "/",
+        }
+}
+
+// Use adds middleware chains to the group. The added middleware applies to
+// all handlers registered on the router and to all handlers registered on
+// routers that may be derived from the router (using Subrouter).
+func (r *Router) Use(mc MiddlewareChain) {
+        r.middleware = append(r.middleware, mc...)

[iannucci, 2016/06/16 00:54:24]

should you use your join function above for this?

[nishanths, 2016/06/16 03:43:29]

No, because there is no need to force the allocation of a new array each time.

+}
+
+// Subrouter creates a new router with an updated base path.
+// The new router copies middleware and configuration from the
+// router it derives from.
+func (r *Router) Subrouter(relativePath string) *Router {
+        newRouter := &Router{
+                hrouter:  r.hrouter,
+                BasePath: makeBasePath(r.BasePath, relativePath),
+        }
+        if len(r.middleware) > 0 {
+                newRouter.middleware = make(MiddlewareChain, len(r.middleware))
+                copy(newRouter.middleware, r.middleware)
+        }
+        return newRouter
+}
+
+// GET is a shortcut for router.Handle("GET", mc, h)

[iannucci, 2016/06/16 00:54:25]

nit: missing 'path' in these comments

[nishanths, 2016/06/16 03:43:29]

Done!

+func (r *Router) GET(path string, mc MiddlewareChain, h Handler) {
+        r.Handle("GET", path, mc, h)
+}
+
+// HEAD is a shortcut for router.Handle("HEAD", mc, h)
+func (r *Router) HEAD(path string, mc MiddlewareChain, h Handler) {
+        r.Handle("HEAD", path, mc, h)
+}
+
+// OPTIONS is a shortcut for router.Handle("OPTIONS", mc, h)
+func (r *Router) OPTIONS(path string, mc MiddlewareChain, h Handler) {
+        r.Handle("OPTIONS", path, mc, h)
+}
+
+// POST is a shortcut for router.Handle("POST", mc, h)
+func (r *Router) POST(path string, mc MiddlewareChain, h Handler) {
+        r.Handle("POST", path, mc, h)
+}
+
+// PUT is a shortcut for router.Handle("PUT", mc, h)
+func (r *Router) PUT(path string, mc MiddlewareChain, h Handler) {
+        r.Handle("PUT", path, mc, h)
+}
+
+// PATCH is a shortcut for router.Handle("PATCH", mc, h)
+func (r *Router) PATCH(path string, mc MiddlewareChain, h Handler) {
+        r.Handle("PATCH", path, mc, h)
+}
+
+// DELETE is a shortcut for router.Handle("DELETE", mc, h)
+func (r *Router) DELETE(path string, mc MiddlewareChain, h Handler) {
+        r.Handle("DELETE", path, mc, h)
+}
+
+// Handle registers a middleware chain and a handler for the given method and
+// path. len(mc)==0 is allowed.

[iannucci, 2016/06/16 00:54:24]

may want to add a pointer to the format of path in the original router's
documentation (See godoc.org/......./httprouter#Path for documentation on how
the path may be formatted)

[nishanths, 2016/06/16 03:43:29]

Done. There is no separate section on path formatting, unfortunately.

+func (r *Router) Handle(method, path string, mc MiddlewareChain, h Handler) {
+        handle := r.adapt(mc, h)
+        r.hrouter.Handle(method, httprouter.CleanPath(r.BasePath+path), handle)
+}
+
+// ServeHTTP makes Router implement the http.Handler interface.
+func (r *Router) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
+        r.hrouter.ServeHTTP(rw, req)
+}
+
+// adapt adapts given middleware chain and handler into a httprouter-style handle.
+func (r *Router) adapt(mc MiddlewareChain, h Handler) httprouter.Handle {
+        return httprouter.Handle(func(rw http.ResponseWriter, req *http.Request, p httprouter.Params) {
+                // TODO(maybe): Use a free list for making Contexts.
+                run(NewContext(context.Background(), rw, req, p), r.middleware, mc, h)
+        })
+}
+
+func makeBasePath(base, relative string) string {
+        path := httprouter.CleanPath(base + relative)
+        // After CleanPath, len(path) >= 0.

[iannucci, 2016/06/16 00:54:25]

what if base and relative are both ""?

[nishanths, 2016/06/16 03:43:29]

Currently, makeBasePath("", "") => "/".
We have a local test for this router_test.go testing the above.

There is also a related httprouter test:
https://github.com/julienschmidt/httprouter/blob/master/path_test.go#L24

Here's the implementation:
https://github.com/julienschmidt/httprouter/blob/master/path.go#L22

+        if path[len(path)-1] != '/' {
+                path = path + "/"
+        }
+        return path
+}
+
+// NewContext creates a Context with the given parameters.
+func NewContext(c context.Context, rw http.ResponseWriter, req *http.Request, p httprouter.Params) *Context {

[iannucci, 2016/06/16 00:54:25]

is this for testing, or are users expected to call this?

[nishanths, 2016/06/16 03:43:29]

Removing for now. I could not think of users wanting to call this or for a
pressing need for this in tests. But I might be missing something (see Nodir's
last comment in this thread:
https://docs.google.com/document/d/1daiHkDisRor0tX0KZyhRAL4h7qgF0aYydIEixI-fT...)

+        return &Context{
+                Context: c,
+                writer:  rw,
+                Request: req,
+                Params:  p,
+        }
+}
+
+// Header is used to implement http.ResponseWriter interface.
+func (c *Context) Header() http.Header {
+        return c.writer.Header()
+}
+
+// Write is used to implement http.ResponseWriter interface.
+// If called from a Middleware function, the rules mentioned in the
+// documentation for Middleware must be followed.
+func (c *Context) Write(p []byte) (int, error) {
+        if c.status == 0 {

[iannucci, 2016/06/16 00:54:24]

if !c.Written()

[nishanths, 2016/06/16 03:43:29]

Done.

+                c.status = http.StatusOK
+        }
+        return c.writer.Write(p)
+}
+
+// WriteHeader is used to implement http.ResponseWriter interface.
+// If called from a Middleware function, the rules mentioned in the
+// documentation for Middleware must be followed.
+func (c *Context) WriteHeader(code int) {
+        if c.status == 0 {

[iannucci, 2016/06/16 00:54:24]

if !c.Written()

[nishanths, 2016/06/16 03:43:27]

Done.

+                c.status = code
+        }
+        c.writer.WriteHeader(code)
+}
+
+// StatusCode returns the written HTTP status code or 0 if it was not written.
+func (c *Context) StatusCode() int {
+        return c.status
+}
+
+// Written indicates whether a HTTP response has been written.
+func (c *Context) Written() bool {
+        return c.status != 0
+}