README
¶
Alice
Alice provides a convenient way to chain your HTTP middleware functions and the app handler.
In short, it transforms
Middleware1(Middleware2(Middleware3(App)))
to
alice.New(Middleware1, Middleware2, Middleware3).Then(App).
Why?
None of the other middleware chaining solutions behaves exactly like Alice. Alice is as minimal as it gets: in essence, it's just a for loop that does the wrapping for you.
Check out this blog post for explanation how Alice is different from other chaining solutions.
Usage
Your middleware constructors should have the form of
func (http.Handler) http.Handler
Some middleware provide this out of the box. For ones that don't, it's trivial to write one yourself.
func myStripPrefix(h http.Handler) http.Handler {
return http.StripPrefix("/old", h)
}
This complete example shows the full power of Alice.
package main
import (
"net/http"
"time"
"github.com/PuerkitoBio/throttled"
"github.com/justinas/alice"
"github.com/justinas/nosurf"
)
func timeoutHandler(h http.Handler) http.Handler {
return http.TimeoutHandler(h, 1*time.Second, "timed out")
}
func myApp(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("Hello world!"))
}
func main() {
th := throttled.Interval(throttled.PerSec(10), 1, &throttled.VaryBy{Path: true}, 50)
myHandler := http.HandlerFunc(myApp)
chain := alice.New(th.Throttle, timeoutHandler, nosurf.NewPure).Then(myHandler)
http.ListenAndServe(":8000", chain)
}
Here, the request will pass throttled first, then an http.TimeoutHandler we've set up, then nosurf and will finally reach our handler.
Note that Alice makes no guarantees for how one or another piece of middleware will behave. It executes all middleware sequentially so that if a piece of middleware were to stop the chain, the request will not reach the inner handlers. This is intentional behavior.
Alice works with Go 1.0 and higher, but running tests requires at least Go 1.1.
Contributing
- Find an issue that bugs you / open a new one.
- Discuss.
- Branch off, commit, test.
- Make a pull request / attach the commits to the issue.
Documentation
¶
Overview ¶
Package alice provides a convenient way to chain http handlers.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Chain ¶
type Chain struct {
// contains filtered or unexported fields
}
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.
func New ¶
func New(constructors ...Constructor) Chain
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 (Chain) Append ¶
func (c Chain) Append(constructors ...Constructor) Chain
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 (Chain) Extend ¶
Extend extends a chain by adding the specified chain as the last one in the request flow.
Extend returns a new chain, leaving the original one untouched.
stdChain := alice.New(m1, m2) ext1Chain := alice.New(m3, m4) ext2Chain := stdChain.Extend(ext1Chain) // requests in stdChain go m1 -> m2 // requests in ext1Chain go m3 -> m4 // requests in ext2Chain go m1 -> m2 -> m3 -> m4
Another example:
aHtmlAfterNosurf := alice.New(m2)
aHtml := alice.New(m1, func(h http.Handler) http.Handler {
csrf := nosurf.New(h)
csrf.SetFailureHandler(aHtmlAfterNosurf.ThenFunc(csrfFail))
return csrf
}).Extend(aHtmlAfterNosurf)
// requests to aHtml hitting nosurfs success handler go m1 -> nosurf -> m2 -> target-handler
// requests to aHtml hitting nosurfs failure handler go m1 -> nosurf -> m2 -> csrfFail
func (Chain) ThenFuncWithContext ¶
func (c Chain) ThenFuncWithContext(cnx context.Context, fn ContextHandlerFunc) *ContextAdapter
ThenFunc works identically to Then, but takes a HandlerFunc instead of a Handler.
The following two statements are equivalent:
c.Then(http.HandlerFunc(fn)) c.ThenFunc(fn)
ThenFunc provides all the guarantees of Then.
func (Chain) ThenWithContext ¶
func (c Chain) ThenWithContext(cnx context.Context, h ContextHandler) *ContextAdapter
we return a context adapter because we can him directly serve
type Constructor ¶
type Constructor func(ContextHandler) ContextHandler
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 ContextAdapter ¶
type ContextAdapter struct {
// contains filtered or unexported fields
}
func NewContextAdapter ¶
func NewContextAdapter(c context.Context, handler ContextHandler) *ContextAdapter
func (*ContextAdapter) ServeHTTP ¶
func (ca *ContextAdapter) ServeHTTP(rw http.ResponseWriter, req *http.Request)
type ContextHandler ¶
type ContextHandlerFunc ¶
func (ContextHandlerFunc) ServeHTTPContext ¶
func (h ContextHandlerFunc) ServeHTTPContext(ctx context.Context, rw http.ResponseWriter, r *http.Request)
Source Files