negronimodified

Overview ¶

Package negronimodified implements checking and setting of last modified headers handler middleware for Negroni.

Basics ¶

HTTP servers or content generators in the background can supress sending the HTTP body content along with the response based on some of the headers set in client request, most notably the "Last-Modified" on the server side and "If-Modified-Since" on the user-agent side. There are some other headers that impact this functionality, such as "Cache-Control" (more on this later), but these two are the main ones we deal with on average basis.

When the server (or whatever is responsible for setting the header content) decides that the content of interest has a certain generated time attached to it, it can inform the client about in the response it sends back along side the actual content. The client can then leverage this data for its cacheing purposes. It does this in a way that in the next identical request it sends this same time to the server where it can check it against the requested content time and if the times match, none of it needs to be sent to the client. This way we save on processing resources, bandwidth and, consequentially, time.

Usage

package main

import (
	`fmt`
	`net/http`

	`github.com/codegangsta/negroni`
	`github.com/mocheryl/negroni-modified`
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc(`/`, func(w http.ResponseWriter, req *http.Request) {
		w.Header().Set(`Last-Modified`, `Mon, 02 Jan 2006 16:04:05 GMT`)
		fmt.Fprintf(w, `This content will not be re-served if you ask about the modification time in the HTTP header!`)
	})

	n := negroni.Classic()
	n.Use(negronimodified.NewModified())
	n.UseHandler(mux)
	n.Run(`:3000`)
}

The above code initializes the middleware with default settings. These include the setting that will add "Cache-Control" header with a value of "public, must-revalidate", which means that everything should be cached and reevaluated.

You can set your own value (or remove it all-together) by initializing the middleware like this:

NewModifiedWithCacheControl([]string{`private`})

Tips ¶

To avoid having to study on how to manipulate the headers correctly, you can use some of the included convenience function.

To set the modification time use:

SetLastModified(responseWriter, `Mon, 02 Jan 2006 16:04:05 GMT`)

If you worry about setting the value in a correct date and time format, a version of a function whose second argument is a time.Date type has also been included:

SetLastModifiedTime(responseWriter, time.Date(2006, 1, 2, 16, 4, 5, 0, tz))

Because the header checkup happens further down the line, it means that a lot of content processing and generation goes on at first only to find out at the end that it will be discarded due to the fact that the client already has the latest version. We can prevent all this unnecessary data processing by executing and checking for the returned value of the following included convenience function:

IfModifiedSince(request, `Mon, 02 Jan 2006 16:04:05 GMT`)

If times are off, if should return true and we can proceed as usual, otherwise halt any further operations on data generating. A practical example would look like this:

if !IfModifiedSince(request, `Mon, 02 Jan 2006 16:04:05 GMT`) {
	return  // Content hasn't changed, i.e. client already has the latest version.
}

Naturally, a time.Date variant of this function also exists:

IfModifiedSince(request, time.Date(2006, 1, 2, 16, 4, 5, 0, tz))

Further Reading ¶

For additional information, please check the following link on official definition: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.5