gzipped

README

gzipped.FileServer

Drop-in replacement for golang http.FileServer which supports static content compressed with gzip (including zopfli) or brotli.

This allows major bandwidth savings for CSS, JavaScript libraries, fonts, and other static compressible web content. It also means you can compress the content without significant runtime penalty.

Example

Suppose /var/www/assets/css contains your style sheets, and you want to make them available as /css/*.css:

package main

import (
	"log"
	"net/http"

	"github.com/lpar/gzipped/v2"
)

func main() {
	log.Fatal(http.ListenAndServe(":8080", http.StripPrefix("/css",
    gzipped.FileServer(gzipped.Dir("/var/www/assets/css")))))
}
// curl localhost:8080/css/styles.css

Using httprouter?

router := httprouter.New()
router.Handler("GET", "/css/*filepath", 
  gzipped.FileServer(gzipped.Dir("/var/www/assets/css"))))
log.Fatal(http.ListenAndServe(":8080", router)

Change history

In version 2.0, we require use of gzipped.Dir, a drop-in replacement for http.Dir. Our gzipped.Dir has the additional feature of letting us check for the existence of files without opening them. This means we can scan to see what encodings are available, then negotiate that list against the client's preferences, and then only (attempt to) open and serve the correct file.

This change means we can let github.com/kevinpollet/nego handle the content negotiation, and remove the dependency on gddo (godoc), which was pulling in 48 dependencies (see #6).

Detail

For any given request at /path/filename.ext, if:

1. There exists a file named /path/filename.ext.(gz|br) (starting from the appropriate base directory), and
2. the client will accept content compressed via the appropriate algorithm, and
3. the file can be opened,

then the compressed file will be served as /path/filename.ext, with a Content-Encoding header set so that the client transparently decompresses it. Otherwise, the request is passed through and handled unchanged.

Unlike other similar code I found, this package has a license, parses Accept-Encoding headers properly, and has unit tests.

Caveats

All requests are passed to Go's standard http.ServeContent method for fulfilment. MIME type sniffing, accept ranges, content negotiation and other tricky details are handled by that method.

It is up to you to ensure that your compressed and uncompressed resources are kept in sync.

Directory browsing isn't supported. That includes remapping URLs ending in / to index.html, index.htm, Welcome.html or whatever -- if you want URLs remapped that way, I suggest having your router do it, or using middleware, so that you have control over the behavior. For example, to add support for index.html files in directories:

func withIndexHTML(h http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if strings.HasSuffix(r.URL.Path, "/") {
			newpath := path.Join(r.URL.Path, "index.html")
			r.URL.Path = newpath
		}
		h.ServeHTTP(w, r)
	})
}
// ...

fs := withIndexHTML(gzipped.FileServer(http.Dir("/var/www")))

Or to add support for directory browsing:

func withBrowsing(h http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if strings.HasSuffix(r.URL.Path, "/") {
			http.ServeFile(w, r, ".")
		}
	})
}
// ...

fs := withBrowsing(gzipped.FileServer(http.Dir("/var/www")))

Related

• You might consider precompressing your CSS with minify.

• If you want to get the best possible compression for clients which don't support brotli, use zopfli.

• To compress your dynamically-generated HTML pages on the fly, I suggest gziphandler.

Documentation

Index

• func FileServer(root FileSystem) http.Handler
• type Dir
  • func (d Dir) Exists(name string) bool
  • func (d Dir) Open(name string) (http.File, error)
• type FileSystem

Functions

func FileServer

func FileServer(root FileSystem) http.Handler

FileServer is a drop-in replacement for Go's standard http.FileServer which adds support for static resources precompressed with gzip, at the cost of removing the support for directory browsing.

If file filename.ext has a compressed version filename.ext.gz alongside it, if the client indicates that it accepts gzip-compressed data, and if the .gz file can be opened, then the compressed version of the file will be sent to the client. Otherwise the request is passed on to http.ServeContent, and the raw (uncompressed) version is used.

It is up to you to ensure that the compressed and uncompressed versions of files match and have sensible timestamps.

Compressed or not, requests are fulfilled using http.ServeContent, and details like accept ranges and content-type sniffing are handled by that method.

Types

type Dir

type Dir string

Dir is a replacement for the http.Dir type, and implements FileSystem.

func (Dir) Exists

func (d Dir) Exists(name string) bool

Exists tests whether a file with the specified name exists, resolved relative to the base directory.

func (Dir) Open

func (d Dir) Open(name string) (http.File, error)

Open defers to http.Dir's Open so that gzipped.Dir implements http.FileSystem.

type FileSystem

type FileSystem interface {
	http.FileSystem
	Exists(string) bool
}

FileSystem is a wrapper around the http.FileSystem interface, adding a method to let us check for the existence of files without (attempting to) open them.