compress

README

Compress

Fast and easy-to-use compression package for Go applications.

Installation

The only requirement is the Go Programming Language.

$ go get github.com/kataras/compress

Getting Started

Import the package:

package main

import "github.com/kataras/compress"

Wrap a handler to enable writing and reading using the best offered compression:

import "net/http"

mux := http.NewServeMux()
// [...]
http.ListenAndServe(":8080", compress.Handler(mux))

Wrap any io.Writer for writing data using compression with NewWriter:

import "bytes"
import "encoding/json"

buf := new(bytes.Buffer)

w, err := compress.NewWriter(buf, compress.GZIP, -1)
if err != nil {
    panic(err)
}

json.NewEncoder(w).Encode(payload{Data: "my data"})

w.Close()

Wrap any io.Reader for reading compressed data with NewReader:

// Where resp.Body is an io.Reader.
r, err := compress.NewReader(resp.Body, compress.GZIP)
if err != nil {
    panic(err)
}
defer r.Close()

body, err := ioutil.ReadAll(r)

To retrieve the underline http.ResponseWriter please use w.(*compress.ResponseWriter).ResponseWriter.

Example Code:

import "net/http"

func handler(w http.ResponseWriter, r *http.Request) {
    target := "/your/asset.js"

	if pusher, ok := w.(*compress.ResponseWriter).ResponseWriter.(http.Pusher); ok {
		err := pusher.Push(target, &http.PushOptions{
            Header: http.Header{
                "Accept-Encoding": r.Header["Accept-Encoding"],
        }})
		if err != nil {
			if err == http.ErrNotSupported {
				http.Error(w, "HTTP/2 push not supported", http.StatusHTTPVersionNotSupported)
			} else {
				http.Error(w, err.Error(), http.StatusInternalServerError)
			}
			return
		}
    }
    
    // [...]
}

The http.CloseNotifier is obselete by Go authors, please use Request.Context().Done() instead.

Supported compression algorithms:

• gzip
• deflate
• brotli
• snappy

Please navigate through _examples directory for more.

License

This software is licensed under the MIT License.

Documentation

Index

• Constants
• Variables
• func AddCompressHeaders(h http.Header, encoding string)
• func GetEncoding(r *http.Request, offers []string) (string, error)
• func Handler(next http.Handler) http.HandlerFunc
• func ReadHandler(next http.Handler) http.HandlerFunc
• func WriteHandler(next http.Handler) http.HandlerFunc
• type Reader
  • func NewReader(src io.Reader, encoding string) (*Reader, error)
• type ResponseWriter
  • func NewResponseWriter(w http.ResponseWriter, r *http.Request, level int) (*ResponseWriter, error)
  • func (w *ResponseWriter) Flush()
  • func (w *ResponseWriter) Write(p []byte) (int, error)
  • func (w *ResponseWriter) WriteHeader(statusCode int)
• type Writer
  • func NewWriter(w io.Writer, encoding string, level int) (cw Writer, err error)

Constants

const (
	GZIP    = "gzip"
	DEFLATE = "deflate"
	BROTLI  = "br"
	SNAPPY  = "snappy"
	S2      = "s2"

	// IDENTITY when no transformation whatsoever.
	IDENTITY = "identity"
)

The available builtin compression algorithms.

const (
	AcceptEncodingHeaderKey  = "Accept-Encoding"
	VaryHeaderKey            = "Vary"
	ContentEncodingHeaderKey = "Content-Encoding"
	ContentLengthHeaderKey   = "Content-Length"
	ContentTypeHeaderKey     = "Content-Type"
)

Header keys.

Variables

var (
	// ErrResponseNotCompressed returned from NewResponseWriter
	// when response's Content-Type header is missing due to golang/go/issues/31753 or
	// when accept-encoding is empty. The caller should fallback to the original response writer.
	ErrResponseNotCompressed = errors.New("compress: response will not be compressed")
	// ErrRequestNotCompressed returned from NewReader
	// when request is not compressed.
	ErrRequestNotCompressed = errors.New("compress: request is not compressed")
	// ErrNotSupportedCompression returned from
	// NewResponseWriter, NewWriter and NewReader
	// when the request's Accept-Encoding was not found in the server's supported
	// compression algorithms. Check that error with `errors.Is`.
	ErrNotSupportedCompression = errors.New("compress: unsupported compression")
)

var DefaultOffers = []string{GZIP, DEFLATE, BROTLI, SNAPPY}

DefaultOffers is a slice of default content encodings. See `NewResponseWriter`.

Functions

func AddCompressHeaders

func AddCompressHeaders(h http.Header, encoding string)

AddCompressHeaders just adds the headers "Vary" to "Accept-Encoding" and "Content-Encoding" to the given encoding.

func GetEncoding

func GetEncoding(r *http.Request, offers []string) (string, error)

GetEncoding extracts the best available encoding from the request.

func Handler

func Handler(next http.Handler) http.HandlerFunc

Handler wraps a Handler and returns a new one which makes future Write calls to compress the data before sent and future request body to decompress the incoming data before read.

func ReadHandler

func ReadHandler(next http.Handler) http.HandlerFunc

ReadHandler is the decompress and read request body middleware.

func WriteHandler

func WriteHandler(next http.Handler) http.HandlerFunc

WriteHandler is the write using compression middleware.

Types

type Reader

type Reader struct {
	io.ReadCloser

	// We need this to reset the body to its original state, if requested.
	Src io.ReadCloser
	// Encoding is the compression alogirthm is used to decompress and read the data.
	Encoding string
}

Reader is a structure which wraps a compressed reader. It is used for determination across common request body and a compressed one.

func NewReader

func NewReader(src io.Reader, encoding string) (*Reader, error)

NewReader returns a new "Reader" wrapper of "src". It returns `ErrRequestNotCompressed` if client's request data are not compressed or `ErrNotSupportedCompression` if server missing the decompression algorithm. Note: on server-side the request body (src) will be closed automaticaly.

type ResponseWriter

type ResponseWriter struct {
	Writer
	http.ResponseWriter

	Encoding  string
	Level     int
	AutoFlush bool // defaults to true, flushes buffered data on each Write.
	// contains filtered or unexported fields
}

ResponseWriter is a compressed data http.ResponseWriter.

func NewResponseWriter

func NewResponseWriter(w http.ResponseWriter, r *http.Request, level int) (*ResponseWriter, error)

NewResponseWriter wraps the "w" response writer and returns a new compress response writer instance. It accepts http response writer, a net/http request value and the level of compression (use -1 for default compression level).

It returns the best candidate among "gzip", "defate", "br", "snappy" and "s2" based on the request's "Accept-Encoding" header value.

See `Handler/WriteHandler` for its usage. In-short, the caller should clear the writer through `defer Close()`.

func (*ResponseWriter) Flush

func (w *ResponseWriter) Flush()

Flush sends any buffered data to the client.

func (*ResponseWriter) Write

func (w *ResponseWriter) Write(p []byte) (int, error)

func (*ResponseWriter) WriteHeader

func (w *ResponseWriter) WriteHeader(statusCode int)

WriteHeader sends an HTTP response header with the provided status code. Deletes the "Content-Length" response header and calls the ResponseWriter's WriteHeader method.

type Writer

type Writer interface {
	io.WriteCloser
	// All known implementations contain `Flush`, `Reset` (and `Close`) methods,
	// so we wanna declare them upfront.
	Flush() error
	Reset(io.Writer)
}

Writer is an interface which all compress writers should implement.

func NewWriter

func NewWriter(w io.Writer, encoding string, level int) (cw Writer, err error)

NewWriter returns a Writer of "w" based on the given "encoding".