|
…
|
||
|---|---|---|
| .. | ||
| CHANGELOG.md | ||
| LICENSE | ||
| README.md | ||
| doc.go | ||
| logger.go | ||
| negroni.go | ||
| recovery.go | ||
| response_writer.go | ||
| static.go | ||
README.md
Negroni
Notice: This is the library formerly known as
github.com/codegangsta/negroni -- Github will automatically redirect requests
to this repository, but we recommend updating your references for clarity.
Negroni is an idiomatic approach to web middleware in Go. It is tiny,
non-intrusive, and encourages use of net/http Handlers.
If you like the idea of Martini, but you think it contains too much magic, then Negroni is a great fit.
Language Translations:
Getting Started
After installing Go and setting up your
GOPATH, create your first .go file.
We'll call it server.go.
package main
import (
"fmt"
"net/http"
"github.com/urfave/negroni"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
fmt.Fprintf(w, "Welcome to the home page!")
})
n := negroni.Classic() // Includes some default middlewares
n.UseHandler(mux)
http.ListenAndServe(":3000", n)
}
Then install the Negroni package (NOTE: >= go 1.1 is required):
go get github.com/urfave/negroni
Then run your server:
go run server.go
You will now have a Go net/http webserver running on localhost:3000.
Is Negroni a Framework?
Negroni is not a framework. It is a middleware-focused library that is
designed to work directly with net/http.
Routing?
Negroni is BYOR (Bring your own Router). The Go community already has a number
of great http routers available, and Negroni tries to play well with all of them
by fully supporting net/http. For instance, integrating with Gorilla Mux
looks like so:
router := mux.NewRouter()
router.HandleFunc("/", HomeHandler)
n := negroni.New(Middleware1, Middleware2)
// Or use a middleware with the Use() function
n.Use(Middleware3)
// router goes last
n.UseHandler(router)
http.ListenAndServe(":3001", n)
negroni.Classic()
negroni.Classic() provides some default middleware that is useful for most
applications:
negroni.Recovery- Panic Recovery Middleware.negroni.Logger- Request/Response Logger Middleware.negroni.Static- Static File serving under the "public" directory.
This makes it really easy to get started with some useful features from Negroni.
Handlers
Negroni provides a bidirectional middleware flow. This is done through the
negroni.Handler interface:
type Handler interface {
ServeHTTP(rw http.ResponseWriter, r *http.Request, next http.HandlerFunc)
}
If a middleware hasn't already written to the ResponseWriter, it should call
the next http.HandlerFunc in the chain to yield to the next middleware
handler. This can be used for great good:
func MyMiddleware(rw http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
// do some stuff before
next(rw, r)
// do some stuff after
}
And you can map it to the handler chain with the Use function:
n := negroni.New()
n.Use(negroni.HandlerFunc(MyMiddleware))
You can also map plain old http.Handlers:
n := negroni.New()
mux := http.NewServeMux()
// map your routes
n.UseHandler(mux)
http.ListenAndServe(":3000", n)
Run()
Negroni has a convenience function called Run. Run takes an addr string
identical to http.ListenAndServe.
package main
import (
"github.com/urfave/negroni"
)
func main() {
n := negroni.Classic()
n.Run(":8080")
}
In general, you will want to use net/http methods and pass negroni as a
Handler, as this is more flexible, e.g.:
package main
import (
"fmt"
"log"
"net/http"
"time"
"github.com/urfave/negroni"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
fmt.Fprintf(w, "Welcome to the home page!")
})
n := negroni.Classic() // Includes some default middlewares
n.UseHandler(mux)
s := &http.Server{
Addr: ":8080",
Handler: n,
ReadTimeout: 10 * time.Second,
WriteTimeout: 10 * time.Second,
MaxHeaderBytes: 1 << 20,
}
log.Fatal(s.ListenAndServe())
}
Route Specific Middleware
If you have a route group of routes that need specific middleware to be executed, you can simply create a new Negroni instance and use it as your route handler.
router := mux.NewRouter()
adminRoutes := mux.NewRouter()
// add admin routes here
// Create a new negroni for the admin middleware
router.PathPrefix("/admin").Handler(negroni.New(
Middleware1,
Middleware2,
negroni.Wrap(adminRoutes),
))
If you are using Gorilla Mux, here is an example using a subrouter:
router := mux.NewRouter()
subRouter := mux.NewRouter().PathPrefix("/subpath").Subrouter().StrictSlash(true)
subRouter.HandleFunc("/", someSubpathHandler) // "/subpath/"
subRouter.HandleFunc("/:id", someSubpathHandler) // "/subpath/:id"
// "/subpath" is necessary to ensure the subRouter and main router linkup
router.PathPrefix("/subpath").Handler(negroni.New(
Middleware1,
Middleware2,
negroni.Wrap(subRouter),
))
Bundled Middleware
Static
This middleware will serve files on the filesystem. If the files do not exist,
it proxies the request to the next middleware. If you want the requests for
non-existent files to return a 404 File Not Found to the user you should look
at using http.FileServer as
a handler.
Example:
package main
import (
"fmt"
"net/http"
"github.com/urfave/negroni"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
fmt.Fprintf(w, "Welcome to the home page!")
})
// Example of using a http.FileServer if you want "server-like" rather than "middleware" behavior
// mux.Handle("/public", http.FileServer(http.Dir("/home/public")))
n := negroni.New()
n.Use(negroni.NewStatic(http.Dir("/tmp")))
n.UseHandler(mux)
http.ListenAndServe(":3002", n)
}
Will serve files from the /tmp directory first, but proxy calls to the next
handler if the request does not match a file on the filesystem.
Recovery
This middleware catches panics and responds with a 500 response code. If
any other middleware has written a response code or body, this middleware will
fail to properly send a 500 to the client, as the client has already received
the HTTP response code. Additionally, an ErrorHandlerFunc can be attached
to report 500's to an error reporting service such as Sentry or Airbrake.
Example:
package main
import (
"net/http"
"github.com/urfave/negroni"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
panic("oh no")
})
n := negroni.New()
n.Use(negroni.NewRecovery())
n.UseHandler(mux)
http.ListenAndServe(":3003", n)
}
Will return a 500 Internal Server Error to each request. It will also log the
stack traces as well as print the stack trace to the requester if PrintStack
is set to true (the default).
Example with error handler:
package main
import (
"net/http"
"github.com/urfave/negroni"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
panic("oh no")
})
n := negroni.New()
recovery := negroni.NewRecovery()
recovery.ErrorHandlerFunc = reportToSentry
n.Use(recovery)
n.UseHandler(mux)
http.ListenAndServe(":3003", n)
}
func reportToSentry(error interface{}) {
// write code here to report error to Sentry
}
Logger
This middleware logs each incoming request and response.
Example:
package main
import (
"fmt"
"net/http"
"github.com/urfave/negroni"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
fmt.Fprintf(w, "Welcome to the home page!")
})
n := negroni.New()
n.Use(negroni.NewLogger())
n.UseHandler(mux)
http.ListenAndServe(":3004", n)
}
Will print a log similar to:
[negroni] Started GET /
[negroni] Completed 200 OK in 145.446µs
on each request.
Third Party Middleware
Here is a current list of Negroni compatible middlware. Feel free to put up a PR linking your middleware if you have built one:
| Middleware | Author | Description |
|---|---|---|
| binding | Matt Holt | Data binding from HTTP requests into structs |
| cloudwatch | Colin Steele | AWS cloudwatch metrics middleware |
| cors | Olivier Poitrey | Cross Origin Resource Sharing (CORS) support |
| csp | Awake Networks | Content Security Policy (CSP) support |
| delay | Jeff Martinez | Add delays/latency to endpoints. Useful when testing effects of high latency |
| New Relic Go Agent | Yadvendar Champawat | Official New Relic Go Agent (currently in beta) |
| gorelic | Jingwen Owen Ou | New Relic agent for Go runtime |
| Graceful | Tyler Bunnell | Graceful HTTP Shutdown |
| gzip | phyber | GZIP response compression |
| JWT Middleware | Auth0 | Middleware checks for a JWT on the Authorization header on incoming requests and decodes it |
| logrus | Dan Buch | Logrus-based logger |
| oauth2 | David Bochenski | oAuth2 middleware |
| onthefly | Alexander Rødseth | Generate TinySVG, HTML and CSS on the fly |
| permissions2 | Alexander Rødseth | Cookies, users and permissions |
| prometheus | Rene Zbinden | Easily create metrics endpoint for the prometheus instrumentation tool |
| render | Cory Jacobsen | Render JSON, XML and HTML templates |
| RestGate | Prasanga Siripala | Secure authentication for REST API endpoints |
| secure | Cory Jacobsen | Middleware that implements a few quick security wins |
| sessions | David Bochenski | Session Management |
| stats | Florent Messa | Store information about your web application (response time, etc.) |
| VanGoH | Taylor Wrobel | Configurable AWS-Style HMAC authentication middleware |
| xrequestid | Andrea Franz | Middleware that assigns a random X-Request-Id header to each request |
| mgo session | Joel James | Middleware that handles creating and closing mgo sessions per request |
Examples
Alexander Rødseth created mooseware, a skeleton for writing a Negroni middleware handler.
Live code reload?
gin and fresh both live reload negroni apps.
Essential Reading for Beginners of Go & Negroni
About
Negroni is obsessively designed by none other than the Code Gangsta