httpgzip

README

Httpgzip

Package httpgzip implements an http.Handler wrapper adding gzip compression for appropriate requests.

Documentation at https://godoc.org/github.com/xi2/httpgzip.

Download and install with go get github.com/xi2/httpgzip.

Documentation

Overview

Package httpgzip implements an http.Handler wrapper adding gzip compression for appropriate requests.

It attempts to properly parse the request's Accept-Encoding header according to RFC 2616 and does not do a simple string search for "gzip" (which will fail to do the correct thing for values such as "*" or "identity,gzip;q=0"). It will serve either gzip or identity content codings (identity meaning no encoding), or return 406 Not Acceptable status if it can do neither.

It works correctly with handlers which honour Range request headers (such as http.FileServer) by removing the Range header for requests which prefer gzip encoding. This is necessary since Range requests apply to the gzipped content but the wrapped handler is not aware of the compression when it writes byte ranges. The Accept-Ranges header is also stripped from corresponding responses.

For requests which prefer gzip encoding a Content-Type header is set using http.DetectContentType if it is not set by the wrapped handler.

Gzip implementation

By default, httpgzip uses the standard library gzip implementation. To use the optimized gzip implementation from https://github.com/klauspost/compress instead, download and install httpgzip with the "kpgzip" build tag:

go get -tags kpgzip github.com/xi2/httpgzip

or simply alter the import line in httpgzip.go.

Thanks

Thanks are due to Klaus Post for his blog post which inspired the creation of this package and is recommended reading:

    https://blog.klauspost.com/gzip-performance-for-go-webservers/

Index

• Constants
• Variables
• func NewHandler(h http.Handler, contentTypes []string) http.Handler
• func NewHandlerLevel(h http.Handler, contentTypes []string, level int) (http.Handler, error)

Examples

• NewHandler

Constants

const (
	NoCompression      = gzip.NoCompression
	BestSpeed          = gzip.BestSpeed
	BestCompression    = gzip.BestCompression
	DefaultCompression = gzip.DefaultCompression
)

These constants are copied from the gzip package, so that code that imports this package does not also have to import the gzip package.

Variables

var DefaultContentTypes = []string{
	"application/atom+xml",
	"application/font-sfnt",
	"application/javascript",
	"application/json",
	"application/ld+json",
	"application/manifest+json",
	"application/rdf+xml",
	"application/rss+xml",
	"application/schema+json",
	"application/vnd.geo+json",
	"application/vnd.ms-fontobject",
	"application/x-font-ttf",
	"application/x-javascript",
	"application/x-web-app-manifest+json",
	"application/xhtml+xml",
	"application/xml",
	"font/eot",
	"font/opentype",
	"image/bmp",
	"image/svg+xml",
	"image/vnd.microsoft.icon",
	"image/x-icon",
	"text/cache-manifest",
	"text/css",
	"text/html",
	"text/javascript",
	"text/plain",
	"text/vcard",
	"text/vnd.rim.location.xloc",
	"text/vtt",
	"text/x-component",
	"text/x-cross-domain-policy",
	"text/xml",
}

DefaultContentTypes is the default list of content types for which a Handler considers gzip compression. This list originates from the file compression.conf within the Apache configuration found at https://html5boilerplate.com/.

Functions

func NewHandler

func NewHandler(h http.Handler, contentTypes []string) http.Handler

NewHandler returns a new http.Handler which wraps a handler h adding gzip compression to certain responses. There are two cases where gzip compression is done. Case 1 is responses whose requests only allow gzip encoding and forbid identity encoding (identity encoding meaning no encoding). Case 2 is responses whose requests prefer gzip encoding, whose size is at least 512 bytes and whose content types are in contentTypes. If contentTypes is nil then DefaultContentTypes is considered instead.

The new http.Handler sets the Content-Encoding, Vary and Content-Type headers in its responses as appropriate. If a request expresses a preference for gzip encoding then any Range headers are removed from the request before it is passed through to h and Accept-Ranges headers are stripped from corresponding responses. This happens regardless of whether gzip encoding is eventually used in the response or not.

Example

This example is the http.FileServer example from the standard library but with gzip compression added.

package main

import (
	"log"
	"net/http"

	"github.com/xi2/httpgzip"
)

func main() {
	// Simple static webserver:
	log.Fatal(http.ListenAndServe(":8080",
		httpgzip.NewHandler(http.FileServer(http.Dir("/usr/share/doc")), nil)))
}

func NewHandlerLevel

func NewHandlerLevel(h http.Handler, contentTypes []string, level int) (http.Handler, error)

NewHandlerLevel is like NewHandler but allows one to specify the gzip compression level instead of assuming DefaultCompression.

The compression level can be DefaultCompression, NoCompression, or any integer value between BestSpeed and BestCompression inclusive. The error returned will be nil if the level is valid.