Photo By: Nika Jones, S6
Channels and FsNotifiy to auto-reload HTTP handlers
By: Nika J.
Overview
The HTTP package in the standard library is great. We can use it, as is, for almost everything, plus it’s very extendable by exposing the the proper public methods to override. The problem with the package, as is, is that it expects for you to have defined all URL routes, that you expect to serve, beforehand, and those routes cannot change while the .Serve() method is blocking and serving those URLs.
We have a very small golang binary that we’ll simply call the Redirector. The Redirector will either serve up a small file with 200 OK response, it will do a 302 redirect to another URL, or serve a 404 Not Found. We have the Redirector so that we can maintain permalink URLs while serving static content from the same server that we need. The whole thing is pretty light and runs on a $1 a month VPS. Building it as a statically linked Go binary helps keeping the HTTP server component compact, fast and lean.
Occasionally, though, we need to add new http URL routes to the server because we add new pages to serve or move things around slightly. The first version of the Redirector had statically compiled URLs as expected by the http library. This meant that you needed to recompile the binary every time there was a need to change routes. Changing the routes happens pretty infrequently, but it does happen; therefore, the process of finding the source code (which often meant re-cloning from git), adding the new route to the source code, recompiling, copying the new binary to the server stopping the old binary, starting the new one, then finally removing the old copy so it doesn’t accidentally get started or cause confusion at a later date. That’s a pain for something that may happen once every few months.
The Redirector has since been modified so that the URLs are stored in an external file, and when that file changes the server automatically picks up those changes and loads the new URLs to be served by the Redirector making it much, much easier to support and change URLs. We’ve said good-bye to a complicated error prone way add URLs to one that’s much more manageable.
While, there are no real gotcha tricks we’ve had to use to get this to work. We thought it may be interesting for people using Go to see how we used some features tied closely to Go to achieve our desired effect. We’ve also packaged the steps that it takes to detect the changes in the file, and reload the URLs in a nice standalone library. I’ll walk you through the process of how to use fsNotify, channels and object composition to build this library.
For reference: the below code, is an example of where we started. Displaying the simplicity of the standard http library.
package main
import (
"log"
"net/http"
)
func main() {
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
FPrint(w, "Hello, big W.")
});
log.Fatal(http.ListenAndServe(":8080", nil))
}
Let’s Start
Now, that we have a starting place, the first thing that we need to do is come up with a step-by-step plan to get to get our final outcome:
Step-by-Step plan of action
- Create a file format to add, remove and update URLs
- Have the HTTP server listen for a change in this file
- When the file has changed, read the file to get new URLs
- Update the HTTP Handlers with the URLs from the file
- Update the HTTP Listener with the new HTTP Handlers
- Go to step 1 - (rinse and repeat)
The above steps translate into the following major Go functionality in the Redirector:
- Set up a channel for fsNotify file watcher to send events on
- Set up a function that can read in the file and setup the http handlers
- Set up a channel for ListenAndServe to listen for an update signal
- Set up a function that can glue the fsNotify and Serve restarts together
Making the file format
Let’s first create a file format that we can use to return a status code for a particular URL, then either serve a static file (from a known location) or redirect to another URL. We can do that by putting all of those elements in a space separated “Routes.txt” file like this:
200 /path/to/file /static/path/to/file
302 /url/to/redirect //url/redirected/to
That was easy, as this does what we want with minimal fuss. Now we can start with the code. ProTip: We’ll use the strings.Fields method to break a single line down to logical pieces. That way we can place as many spaces between objects to keep it readable.
Composing the http.Server object
First lets override the http.Serve method. We’ll use object composition for this, so we can use all of the functionally of the http.Server object and just override a very small part of it. This is a great feature of Go that introduces minimal code for the most reuse.
type Server struct {
ReloadFile chan string
reloadFunc ReloadHandlerFunc
reloadServe chan struct{}
http.Server
}
We’ve added three things to our Server object, which extends the http.Server object. The ReloadFile and reloadServe fields hold channels, which will get the signals that will do the reloads and restarts of the server. The reloadFunc holds the function that will be used to do the reloading of the handers. This can be defined outside of the library by the program using it. The ReloadFile can send signals to outside of the library as well.
How we block for the .Serve() method
The function that we expose as the ListenAndServe() method to override the http.ListenAndServe method, included the components to listen for an override as well as send a signal for the listener to reload.
func (ws *Server) ListenAndServe(address string, reloadFunc ReloadHandlerFunc) error {
ws.Addr = address
ws.reloadFunc = reloadFunc
// now wait for the other times when we needed to
go func() {
for {
// clear the handler
ws.Handler(nil)
ws.reloadFunc(ws)
ws.reloadServe <- struct{}{} // reset the listening binding
}
}()
ws.reloadFunc(ws)
return ws.Serve()
}
There are two main differences from this code than http.ListenAndServe, first we pass in the ReloadHandlerFunc type. This is a function that will be doing the reloading of the handlers. Within in this function you will set the handler, just as you would normally, it’s just capable of being reloaded. Within this function you block and wait for the notification that the file has changed. That’s where the blocking and waiting for the file notification happens. It’s the first signal received to start the reload/restart process.
The Internal listenAndServe method
Secondly, we send the modified internal listenAndServe function an empty struct to signal that it should restart with the newly loaded functions.
A quick look at the internal modified listenAndServe revels that the blocker is ws.reloadServe channel and not the http.Serve method which is in a go routine.
func (ws *Server) listenAndServe() error {
addr := ws.Addr
if addr == "" {
addr = ":http"
}
ln, err := net.Listen("tcp", addr)
if err != nil {
return err
}
for {
l := ln.(*net.TCPListener)
defer l.Close()
go func(gl net.Listener) {
ws.http.Serve(gl) // Where the blocking will normally happen
}(l)
<-ws.reloadServe // where the blocking is really happening
}
}
The file Watcher
With those two methods in place, we can start listing and reload the server when we have changes. Now, we’ll add the code that listens for the file change and kicks off everything. We’ll looks for the changes through the fsNotify.Watcher, this is currently an external library with plans to bring it into the standard library when it’s been battle tested. Once the watcher has received a notification on its channel, it starts reading the file and loading of the handler with the contents of the file process. The go routine needs to have the listener passed in as a parameter so it will act as expected. You can read more about this from a Go blog. http://golang-basic.blogspot.com/2014/06/golang-closures-running-as-go-routines.html
func (ws *Server) watchFile(watcher *fsnotify.Watcher) {
for {
select {
case event := <-watcher.Events:
if event.Op&fsnotify.Write == fsnotify.Write {
ws.ReloadFile <- event.Name
}
// For now we just print out errors, this can be handled another way.
case err := <-watcher.Errors:
log.Println("Watcher Error:", err)
}
}
}
How the contents from the file get loaded as URL Handlers
Finally we just need to add the reading of the file and reloading of the handlers functionality.
type ReloadHandlerFunc func(*Server)
This means that we can pass in the HTTP server to the reload function. This function will normally live outside of the library so we have only exposed the ReloadFile channel. This is the channel that will hold the file name that we are going to load, as it comes from the watchFile function that we described earlier.
// readRedirectFile is a helper function for reloading the URL handlers
func readRedirectFile(filename string) (rtnData []redirectData) {
if len(filename) == 0 {
log.Fatal("Please set a file to read from.")
}
inFile, _ := os.Open(filename)
defer inFile.Close()
scanner := bufio.NewScanner(inFile)
scanner.Split(bufio.ScanLines)
for scanner.Scan() {
ln := scanner.Text()
fields := strings.Fields(ln)
if len(fields) != 3 {
log.Fatal("The following line is not correct:\n" + ln)
}
code, err := strconv.Atoi(fields[0])
if err != nil {
log.Fatal("There was an error converting to int:", err)
}
rtnData = append(rtnData, redirectData{
StatusCode: code,
ReqPath: fields[1],
RtnPath: fields[2],
})
}
return rtnData
}
This function reads the file format that we defined earlier and places the results into a simple slice that has an object with all of the fields present. Once we have the slice we can loop through the slice and add the HTTP handlers in the actual reload function. For this example we will be using the http.DefaultServeMux which we need to overwrite each time, because it’s global to the http module. We can also swap out this default handler for something like httpouter which has wildcards and a bit more functionality to the routing. So you’re not limited to the http router within the standard library.
// reloadRoutes is a function that sits outside of the library to do the routes
// any way that the developer wants.
func reloadRoutes(watch *watchHttp.Server) {
allRoutes := readRedirectFile(<-watch.ReloadFile)
http.DefaultServeMux = http.NewServeMux()
for _, x := range allRoutes {
switch x.StatusCode {
case http.StatusOK:
func(path, filename string) {
data, err := ioutil.ReadFile(filename)
if err != nil {
log.Println("There was an error with the content file:", err)
}
content := strings.NewReader(string(data))
http.HandleFunc(path, func(w http.ResponseWriter, r *http.Request) {
http.ServeContent(w, r, filename, time.Now(), content)
})
}(x.ReqPath, x.RtnPath)
case http.StatusFound:
http.HandleFunc(x.ReqPath, func(w http.ResponseWriter, r *http.Request) {
http.Redirect(w, r, x.RtnPath, http.StatusFound)
})
}
}
watch.Handler(http.DefaultServeMux) // if you're not using the DefaultServeMux
}
Finally…
Having the file reload when a change is made, makes things a lot better. This means all we need to do is read the routes file to get a list of what we’re redirecting and serving up statically. This means that we don’t have to recompile the file each time that we have a new route to redirect to. However we could make it a bit better. We still need to stop and restart the server when we make a change to the routes file. This is ok, but it could be better. What if we “watch” the routes file and update the routes each time the file changes. That would be ideal, as all we would need to do is upload a new file and we’d be good to go.
That’s all. I’ve taken these parts and pieces and made a small library that can be used at github.com. This takes the patterns that we discussed here and abstracts them out.
You can find the full library on Github at https://github.com/artktec/watchserverfile. Does this help with how to use channels and composition when extending the Go standard library?