The router package provides a simple URL router and HandlerFunc dispatcher for go web apps. This post explains how to use it.
In its simplest form, just create a router instance and register HandlerFuncs to HTTP verb/path pairs. Use the router by calling Handle and ListenAndServe. A working example is shown below.
package main
import (
"github.com/toonketels/router"
"net/http"
)
func main() {
// Create a new router
appRouter := router.NewRouter()
// Register a handlerFunc for GET/"hello" paths
appRouter.Get("/hello", func(res http.ResponseWriter, req *http.Request) {
res.Write([]byte("hello"))
})
// Use this router
appRouter.Handle("/")
// Listen for requests
http.ListenAndServe(":3000", nil)
}
Now, let's dive a bit deeper in the package API.
HandlerFuncs
Once a router instance has been created, use its Get/Put/Post/Patch/Head/Options/Delete methods to register a handlerFunc to a route/HTTP verb pair.
// Register a handlerFunc for GET/"hello" paths
appRouter.Get("/hello", handlerFunc)
// Register a handlerFunc for PUT/"hello" paths
appRouter.Put("/hello", handlerFunc)
// Register a handlerFunc for POST/"hello" paths
appRouter.Post("/hello", handlerFunc)
// Register a handlerFunc for Patch/"hello" paths
appRouter.Patch("/hello", handlerFunc)
// Register a handlerFunc for HEAD/"hello" paths
appRouter.Head("/hello", handlerFunc)
// Register a handlerFunc for OPTIONS/"hello" paths
appRouter.Options("/hello", handlerFunc)
// Register a handlerFunc for DELETE/"hello" paths
appRouter.Delete("/hello", handlerFunc)
You can also register multiple handlerFuncs for a given route.
// Register the handlerFuncs
appRouter.Get("/user/:userid/hello", logUser, handleUser)
For this to work, all handlerFuncs should pass control to handlerFuncs coming after them by calling
cntxt.Next().
func loadUser(res http.ResponseWriter, req *http.Request) {
// Grab the context for the current request
cntxt := router.Context(req)
// Do something
// Pass over control to next handlerFunc
cntxt.Next(res, req)
}
If your handlerFunc wants to protect access to certain routes, it could do so by only calling cntxt.Next() when some authorization rule validates.
func allowAccess(res http.ResponseWriter, req *http.Request) {
if allowUserAccess() {
// Allows access
router.Context(req).Next(res, req)
return
}
// Denies access
}
HandlerFuncs can store data onto the requestContext to be used by handlerFuncs after them.
func loadUser(res http.ResponseWriter, req *http.Request) {
cntxt := router.Context(req)
user := getUserFromDB(cntxt.Params["userid"])
// Store the value in request specific store
_ = cntxt.Set("user", user)
cntxt.Next(res, req)
}
HandlerFuncs use cntxt.Get(key) to get the value. RequestContext has Set/ForceSet/Get/Delete methods all related to the data stored during the current request.
func handleUser(res http.ResponseWriter, req *http.Request) {
cntxt := router.Context(req)
// Get a value from the request specific store
if user, ok := cntxt.Get("user"); ok {
// Do something
}
// Do something else
}
Remember the route /user/:userid/hello? It matches routes like /user/14/hello or /user/richard/hello. HandlerFuncs can access the values of userid on the requestContext.
func loadUser(res http.ResponseWriter, req *http.Request) {
// Grab the userid param from the context
userid := router.Context(req).Params["userid"]
// Do something with it
}
As you might have noticed, handlers need to be http.HandlerFunc's. So you can use your existing ones if you don't need to access the requestContext.
Mounting handlerFuncs
Some handlerFuncs need to be executed for every request, like a logger. Instead of passing it to every registered route, we "mount" them using router.Mount().
appRouter := router.NewRouter()
// Mount handlerFuncs first
appRouter.Mount("/", logger)
appRouter.Mount("/", allowAccess)
// Then start matching paths
appRouter.Get("/user/:userid/hello", loadUser, handleUser)
The order in which you mounted and registered handlers, is the order in which they will be executed.
A request to /user/14/hello will result in logger to be called first, followed by allowAccess, loadUser and handleUser. That is as long as none of the handlerFunc's prevented the latter ones from executing by not calling next.
By changing the mountPath of allowAccess to /admin, we get different results.
// Mount handlerFuncs first
appRouter.Mount("/", logger)
appRouter.Mount("/admin", allowAccess)
// Then start matching paths
appRouter.Get("/user/:userid/hello", loadUser, handleUser)
appRouter.Get("/admin/user/:userid", loadUser, administerUserHandler)
It the above case a request to /user/20/hello will execute logger -> loadUser -> handleUser, while a request to /admin/user/20 executes logger -> allowAccess -> loadUser -> administerUserHandler.
We see that by dividing a complex handlerFunc into multiple smaller ones, we get more code reuse. It becomes easy to create a small set of "middleware" handlers to be reused on different routes. While the last handlerFunc is generally the one responsible for generating the actual response.
Error Handling
Besides storing data and dispatching the next handlerFunc cntxt has an Error method. Let's update the loadUser handlerFunc to take errors into account.
func loadUser(res http.ResponseWriter, req *http.Request) {
cntxt := router.Context(req)
user, err := getUserFromDB(cntxt.Params["userid"])
if err != nil {
// Let the errorHandlerFunc generate the error response.
// We stop executing the following handlers
cntxt.Error(res, req, err.Error(), 500)
return
}
// Store the value in request specific store
_ = cntxt.Set("user", user)
// Pass over control to next handlerFunc
cntxt.Next(res, req)
}
Calling cntxt.Error() notifies the requestContext an error has been made and further Next() call will be prevented. It delegates the requestHandling to a dedicated errorHandlerFunc to reply in a consistent manner.
Though calling Next() after an error will never dispatch the next HandlerFunc, it is wise to just return after the error so the current
HandlerFunc stops executing.
Previous HandlerFuncs are allowed to continue executing their code when the executing flow returns to them.
For instance, when the logger below is called, it records the time and calls the next HandlerFunc. If that handler errs, logger will resume as usual allowing it to log its output.
func logger(res http.ResponseWriter, req *http.Request) {
// The fist handlerFunc to be executed
// record the time when the request started
start := time.Now()
// Handle over control to the next handlerFunc.
router.Context(req).Next(res, req)
// We log once all other handlerFuncs are done executing
// so it needs to come after our call to cntxt.Next()
fmt.Println(req.Method, req.URL.Path, time.Since(start))
}
The actual response send to the client is handled by default ErrorRequestHandler. Which will just do http.Error(res, err, code).
Customize the response by updating your router's ErrorHandler. The function passed should comply with the ErrorHandler interface.
appRouter.ErrorHandler = func(res http.ResponseWriter, req *http.Request, err string, code int) {
http.Error(res, strings.ToUpper(err), code)
}
The request is passed to allow a different response to be send depending on request properties.
Similarly, configure the response generated when a route is not found by updating the router's NotFoundHandler which is a plain http.HandlerFunc.
Conclusion
With just a couple of concepts: registering requestHandlers, mounting requestHandlers and a requestContext for each request, we can do powerful things.
You can find some examples in the projects repo.