go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/server/router/handler.go (about)

     1  // Copyright 2016 The LUCI Authors.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package router
    16  
    17  // Handler is the type for all request handlers.
    18  type Handler func(*Context)
    19  
    20  // Middleware does some pre/post processing of a request.
    21  //
    22  // It is a function that accepts a context carrying an http.Request and
    23  // an http.ResponseWriter and the `next` function. `next` is either the final
    24  // request handler or a next link in the middleware chain.
    25  //
    26  // A middleware implementation must obey the following rules:
    27  //   - Middleware *must* call `next` if it has not written the response itself.
    28  //   - Middleware *must not* call `next` if it has written the response.
    29  //   - Middleware *may* modify the context in-place before calling `next`.
    30  //
    31  // Note that writing the response after `next` is called is undefined behavior.
    32  // It may or may not work depending on what exact happened down the chain.
    33  type Middleware func(c *Context, next Handler)
    34  
    35  // MiddlewareChain is an ordered collection of Middleware.
    36  //
    37  // The first middleware is the outermost, i.e. it will be called first when
    38  // processing a request.
    39  type MiddlewareChain []Middleware
    40  
    41  // RunMiddleware executes the middleware chain and the handler with the given
    42  // initial context. Useful to execute a chain of functions in tests.
    43  func RunMiddleware(c *Context, mc MiddlewareChain, h Handler) {
    44  	run(c, mc, nil, h)
    45  }
    46  
    47  // NewMiddlewareChain creates a new MiddlewareChain with the supplied Middleware
    48  // entries.
    49  func NewMiddlewareChain(mw ...Middleware) MiddlewareChain {
    50  	if len(mw) == 0 {
    51  		return nil
    52  	}
    53  	return append(MiddlewareChain(nil), mw...)
    54  }
    55  
    56  // Extend returns a new MiddlewareChain with the supplied Middleware appended to
    57  // the end.
    58  func (mc MiddlewareChain) Extend(mw ...Middleware) MiddlewareChain {
    59  	ext := make(MiddlewareChain, 0, len(mc)+len(mw))
    60  	return append(append(ext, mc...), mw...)
    61  }
    62  
    63  // run executes the middleware chains m and n and the handler h using
    64  // c as the initial context. If a middleware or handler is nil, run
    65  // simply advances to the next middleware or handler.
    66  func run(c *Context, m, n MiddlewareChain, h Handler) {
    67  	switch {
    68  	case len(m) > 0:
    69  		if m[0] != nil {
    70  			m[0](c, func(ctx *Context) { run(ctx, m[1:], n, h) })
    71  		} else {
    72  			run(c, m[1:], n, h)
    73  		}
    74  	case len(n) > 0:
    75  		if n[0] != nil {
    76  			n[0](c, func(ctx *Context) { run(ctx, nil, n[1:], h) })
    77  		} else {
    78  			run(c, nil, n[1:], h)
    79  		}
    80  	case h != nil:
    81  		h(c)
    82  	}
    83  }