| // Package alice provides a convenient way to chain http handlers. |
| package alice |
| |
| import "net/http" |
| |
| // A constructor for a piece of middleware. |
| // Some middleware use this constructor out of the box, |
| // so in most cases you can just pass somepackage.New |
| type Constructor func(http.Handler) http.Handler |
| |
| // Chain acts as a list of http.Handler constructors. |
| // Chain is effectively immutable: |
| // once created, it will always hold |
| // the same set of constructors in the same order. |
| type Chain struct { |
| constructors []Constructor |
| } |
| |
| // New creates a new chain, |
| // memorizing the given list of middleware constructors. |
| // New serves no other function, |
| // constructors are only called upon a call to Then(). |
| func New(constructors ...Constructor) Chain { |
| c := Chain{} |
| c.constructors = append(c.constructors, constructors...) |
| |
| return c |
| } |
| |
| // Then chains the middleware and returns the final http.Handler. |
| // New(m1, m2, m3).Then(h) |
| // is equivalent to: |
| // m1(m2(m3(h))) |
| // When the request comes in, it will be passed to m1, then m2, then m3 |
| // and finally, the given handler |
| // (assuming every middleware calls the following one). |
| // |
| // A chain can be safely reused by calling Then() several times. |
| // stdStack := alice.New(ratelimitHandler, csrfHandler) |
| // indexPipe = stdStack.Then(indexHandler) |
| // authPipe = stdStack.Then(authHandler) |
| // Note that constructors are called on every call to Then() |
| // and thus several instances of the same middleware will be created |
| // when a chain is reused in this way. |
| // For proper middleware, this should cause no problems. |
| // |
| // Then() treats nil as http.DefaultServeMux. |
| func (c Chain) Then(h http.Handler) http.Handler { |
| var final http.Handler |
| if h != nil { |
| final = h |
| } else { |
| final = http.DefaultServeMux |
| } |
| |
| for i := len(c.constructors) - 1; i >= 0; i-- { |
| final = c.constructors[i](final) |
| } |
| |
| return final |
| } |
| |
| // Append extends a chain, adding the specified constructors |
| // as the last ones in the request flow. |
| // |
| // Append returns a new chain, leaving the original one untouched. |
| // |
| // stdChain := alice.New(m1, m2) |
| // extChain := stdChain.Append(m3, m4) |
| // // requests in stdChain go m1 -> m2 |
| // // requests in extChain go m1 -> m2 -> m3 -> m4 |
| func (c Chain) Append(constructors ...Constructor) Chain { |
| newCons := make([]Constructor, len(c.constructors)) |
| copy(newCons, c.constructors) |
| newCons = append(newCons, constructors...) |
| |
| newChain := New(newCons...) |
| return newChain |
| } |