modified: README.md

README.md

@@ -18,7 +18,7 @@ Go HTTP router
 Usage
 -----
 
-For more details [GoDoc](https://godoc.org/github.com/nbari/violetear):
+Package [GoDoc](https://godoc.org/github.com/nbari/violetear), basic example:
 
 ```go
 package main
@@ -126,8 +126,9 @@ Request-Id: GET-1445528733916239110-5
 I handle dynamic requests
 ```
 
-Trying to use POST on the ``/:uuid`` resource will cause a Method not Allowed
-405:
+Trying to use POST on the ``/:uuid`` resource will cause a
+*Method not Allowed 405* this because only ``GET`` and ``HEAD``
+methods are allowed:
 
 ```sh
 $ http POST http://localhost:8080/50244127-45F6-4210-A89D-FFB0DA039425
@@ -141,6 +142,107 @@ X-Content-Type-Options: nosniff
 Method Not Allowed
 ```
 
+Middleware
+----------
+
+Violetear uses [Alice](http://justinas.org/alice-painless-middleware-chaining-for-go/) to handle [middleware](middleware).
+
+Example:
+
+```go
+package main
+
+import (
+    "github.com/nbari/violetear"
+    "github.com/nbari/violetear/middleware"
+    "log"
+    "net/http"
+)
+
+func commonHeaders(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        w.Header().Set("X-app-Version", "1.0")
+        next.ServeHTTP(w, r)
+    })
+}
+
+func middlewareOne(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        log.Println("Executing middlewareOne")
+        next.ServeHTTP(w, r)
+        log.Println("Executing middlewareOne again")
+    })
+}
+
+func middlewareTwo(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        log.Println("Executing middlewareTwo")
+        if r.URL.Path != "/" {
+            return
+        }
+        next.ServeHTTP(w, r)
+        log.Println("Executing middlewareTwo again")
+    })
+}
+
+func catchAll(w http.ResponseWriter, r *http.Request) {
+    log.Println("Executing finalHandler")
+    w.Write([]byte("I catch all"))
+}
+
+func foo(w http.ResponseWriter, r *http.Request) {
+    log.Println("Executing finalHandler")
+    w.Write([]byte("foo"))
+}
+
+func main() {
+    router := violetear.New()
+
+    stdChain := middleware.New(commonHeaders, middlewareOne, middlewareTwo)
+
+    router.Handle("/", stdChain.ThenFunc(catchAll), "GET,HEAD")
+    router.Handle("/foo", stdChain.ThenFunc(foo), "GET,HEAD")
+    router.HandleFunc("/bar", foo)
+
+    log.Fatal(http.ListenAndServe(":8080", router))
+}
+```
+
+> Notice the use or router.Handle and router.HandleFunc when using middleware
+you normally would use route.Handle
+
+Request output example:
+
+```sh
+$ http http://localhost:8080/
+HTTP/1.1 200 OK
+Content-Length: 11
+Content-Type: text/plain; charset=utf-8
+Date: Thu, 22 Oct 2015 16:08:18 GMT
+Request-Id: GET-1445530098002701428-3
+X-App-Version: 1.0
+
+I catch all
+```
+
+On the server you will see something like this:
+
+```sh
+$ go run test.go
+2015/10/22 18:07:55 Adding path: / [GET]
+2015/10/22 18:07:55 Adding path: /foo [GET]
+2015/10/22 18:07:55 Adding path: /bar [ALL]
+2015/10/22 18:08:18 Executing middlewareOne
+2015/10/22 18:08:18 Executing middlewareTwo
+2015/10/22 18:08:18 Executing finalHandler
+2015/10/22 18:08:18 Executing middlewareTwo again
+2015/10/22 18:08:18 Executing middlewareOne again
+```
+
+More references:
+
+* http://www.alexedwards.net/blog/making-and-using-middleware
+* https://justinas.org/alice-painless-middleware-chaining-for-go/
 
 
 Canonicalized headers issues