compress

Documentation

Overview

Package compress provides response compression middleware.

Supports gzip, brotli, and zstd encoding with automatic negotiation based on Accept-Encoding headers.

Usage

import "github.com/alexferl/zerohttp/middleware/compress"

// Use defaults (gzip, level 6)
app.Use(compress.New())

// Custom configuration
app.Use(compress.New(compress.Config{
    Algorithms: []compress.Algorithm{compress.Gzip, compress.Brotli},
    Level:      compress.BestSpeed,
}))

Content Types

Only compresses specific content types by default (text, json, etc). Customize with:

app.Use(compress.New(compress.Config{
    Types: []string{"text/html", "application/json", "application/xml"},
}))

Index

• Constants
• Variables
• func New(cfg ...Config) func(http.Handler) http.Handler
• type Algorithm
• type Compressor
  • func NewCompressor(level int, types ...string) *Compressor
  • func (c *Compressor) Handler(next http.Handler) http.Handler
  • func (c *Compressor) SetEncoder(encoding string, fn EncoderFunc)
• type Config
• type Encoder
• type EncoderFunc
• type Provider

Constants

const (
	Gzip    = Algorithm(httpx.ContentEncodingGzip)
	Deflate = Algorithm(httpx.ContentEncodingDeflate)
)

Variables

var DefaultCompressTypes = []string{
	httpx.MIMETextHTML,
	httpx.MIMETextCSS,
	httpx.MIMETextPlain,
	httpx.MIMETextJavaScript,
	httpx.MIMEApplicationJavaScript,
	httpx.MIMEApplicationJSON,
	httpx.MIMEApplicationXML,
	httpx.MIMETextXML,
	httpx.MIMEApplicationRSSXML,
	httpx.MIMEApplicationAtomXML,
	httpx.MIMEImageSVGXML,
}

DefaultCompressTypes are the MIME types compressed by default.

var DefaultConfig = Config{
	Level:         6,
	Types:         DefaultCompressTypes,
	Algorithms:    []Algorithm{Gzip, Deflate},
	ExcludedPaths: []string{},
	IncludedPaths: []string{},
}

DefaultConfig contains the default values for compression configuration.

Functions

func New

func New(cfg ...Config) func(http.Handler) http.Handler

New creates a compression middleware with the provided configuration

Types

type Algorithm

type Algorithm string

Algorithm defines supported compression algorithms

type Compressor

type Compressor struct {
	// contains filtered or unexported fields
}

Compressor represents a set of encoding configurations.

func NewCompressor

func NewCompressor(level int, types ...string) *Compressor

NewCompressor creates a new Compressor that will handle encoding responses.

func (*Compressor) Handler

func (c *Compressor) Handler(next http.Handler) http.Handler

Handler returns a new middleware that will compress the response.

func (*Compressor) SetEncoder

func (c *Compressor) SetEncoder(encoding string, fn EncoderFunc)

SetEncoder can be used to set the implementation of a compression algorithm.

type Config

type Config struct {
	// Level is the compression level (1-9 for gzip/deflate).
	// Default: 6
	Level int

	// Types are MIME types to compress.
	// Default: common text types (HTML, CSS, JS, JSON, XML, SVG)
	Types []string

	// Algorithms are compression algorithms to support.
	// Default: [Gzip, Deflate]
	// The order determines precedence when the client accepts multiple encodings -
	// earlier algorithms are preferred over later ones.
	Algorithms []Algorithm

	// ExcludedPaths contains paths to skip compression.
	// Supports exact matches, prefixes (ending with /), and wildcards (ending with *).
	// Cannot be used with IncludedPaths - setting both will panic.
	// Default: []
	ExcludedPaths []string

	// IncludedPaths contains paths where compression is explicitly applied.
	// If set, compression will only occur for paths matching these patterns.
	// Supports exact matches, prefixes (ending with /), and wildcards (ending with *).
	// If empty, compression applies to all paths (subject to ExcludedPaths).
	// Cannot be used with ExcludedPaths - setting both will panic.
	// Default: []
	IncludedPaths []string

	// Providers are optional custom compression providers.
	// If set, the providers' encoders will be used in addition to built-in gzip/deflate.
	// This allows users to add Brotli, zstd, or other algorithms without core dependencies.
	// Default: nil (use only built-in gzip/deflate)
	Providers []Provider
}

Config allows customization of compression behavior

type Encoder

type Encoder interface {
	// Encode wraps the provided io.Writer with compression.
	// The level parameter is algorithm-specific (e.g., 1-9 for gzip, 0-11 for brotli).
	Encode(w io.Writer, level int) io.Writer

	// Encoding returns the encoding name used in Accept-Encoding/Content-Encoding headers.
	// Common values: httpx.ContentEncodingGzip, httpx.ContentEncodingDeflate, httpx.ContentEncodingBrotli (brotli), httpx.ContentEncodingZstd.
	Encoding() string
}

Encoder is the interface for compression encoders. Users can implement this interface to provide custom compression algorithms (e.g., Brotli, zstd) without adding dependencies to the core library.

Example with github.com/andybalholm/brotli:

type BrotliEncoder struct{}
func (e BrotliEncoder) Encode(w io.Writer, level int) io.Writer {
	return brotli.NewWriterLevel(w, level)
}
func (e BrotliEncoder) Encoding() string { return httpx.ContentEncodingBrotli }

type EncoderFunc

type EncoderFunc func(w io.Writer, level int) io.Writer

EncoderFunc is a function that wraps the provided io.Writer with compression.

type Provider

type Provider interface {
	// GetEncoder returns a Encoder for the given encoding, or nil if not supported.
	// The encoding will be lowercase (e.g., httpx.ContentEncodingGzip, httpx.ContentEncodingBrotli, httpx.ContentEncodingZstd).
	GetEncoder(encoding string) Encoder
}

Provider creates compression encoders. Implement this interface to bring your own compression algorithms.

Example:

type MyCompressorProvider struct{}
func (p MyCompressorProvider) GetEncoder(encoding string) CompressionEncoder {
    switch encoding {
    case httpx.ContentEncodingBrotli:
        return BrotliEncoder{}
    case httpx.ContentEncodingZstd:
        return ZstdEncoder{}
    }
    return nil
}

cfg := config.CompressConfig{
    Providers: []config.CompressionProvider{MyCompressorProvider{}},
}