compress

package
v14.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: BSD-3-Clause Imports: 13 Imported by: 0

README

Compression Middleware for Iris

The compress middleware works in both directions. It decompresses a request body according to the request's Content-Encoding, and compresses the response with the best encoding the client advertised in Accept-Encoding.

If you need finer control than the middleware gives you, the same package lets you acquire a request reader or a response writer by hand. Both are covered below.

Features of Iris Compress Middleware

The Iris compress middleware offers a variety of features to handle HTTP compression and decompression. These features include:

  1. Request Decompression: Automatically decompresses incoming request bodies based on the Content-Encoding header.
  2. Response Compression: Compresses outgoing response bodies based on the client's Accept-Encoding header.
  3. Support for Multiple Compression Algorithms: Supports gzip, deflate, brotli, snappy, s2 and zstd compression algorithms.
  4. Custom Compression Levels: Allows setting custom compression levels for supported algorithms.
Compression Algorithms

The Iris compress middleware supports the following compression algorithms:

  • gzip: A widely used compression algorithm that provides a good balance between compression ratio and speed.
  • deflate: A compression algorithm similar to gzip but with slightly different compression characteristics.
  • brotli: A modern compression algorithm that provides higher compression ratios than gzip and deflate.
  • snappy: A fast compression algorithm that provides lower compression ratios but is very efficient in terms of speed.
  • s2: A variant of snappy that offers faster decompression speeds.
  • zstd: Zstandard, a modern algorithm that compresses better than gzip at comparable or better speed.

Usage

To use the compress middleware, simply add it to your Iris application:

package main

import (
	"github.com/kataras/iris/v14"
	"github.com/kataras/iris/v14/middleware/compress"
)

func main() {
	app := iris.New()
	app.Use(compress.Handler)

	app.Post("/", func(ctx iris.Context) {
		body, _ := ctx.Body()
		ctx.Writef("Received: %s", string(body))
	})

	app.Listen(":8080")
}
Manually Acquiring a Request Reader for Decompression

In some cases, you might want to manually acquire a request reader for decompression. The NewRequestReader function can be used for this purpose.

Example
package main

import (
	"fmt"
	"io"
	"net/http"

	"github.com/kataras/iris/v14"
	"github.com/kataras/iris/v14/middleware/compress"
	"github.com/kataras/iris/v14/rest/errors"
)

func main() {
	app := iris.New()

	app.Post("/", func(ctx iris.Context) {
		r := ctx.Request()
		reader, ok, err := compress.NewRequestReader(r)
		if err != nil {
			errors.UnsupportedMediaType.Err(ctx, err) // the code carries the 415.
			return
		}
		if ok {
			defer reader.Close()
			r.Body = reader
		}

		body, _ := io.ReadAll(r.Body)
		ctx.Writef("Received: %s", string(body))
	})

	app.Listen(":8080")
}
Manually Acquiring a Response Writer for Compression

Similarly, you might want to manually acquire a response writer for compression. The AcquireResponseWriter function can be used for this purpose.

Example
package main

import (
	"net/http"

	"github.com/kataras/iris/v14"
	"github.com/kataras/iris/v14/middleware/compress"
	"github.com/kataras/iris/v14/rest/errors"
)

func main() {
	app := iris.New()

	app.Post("/", func(ctx iris.Context) {
		r := ctx.Request()
		w := ctx.ResponseWriter()

		writer, ok, err := compress.AcquireResponseWriter(w, r, -1)
		if err != nil {
			errors.UnsupportedMediaType.Err(ctx, err) // the code carries the 415.
			return
		}
		if ok {
			ctx.SetResponseWriter(writer)
			// Put the previous writer back before releasing. A released writer
			// returns to a pool, and a middleware registered outside this
			// handler (an access log, say) reads the Context's writer after it.
			defer func() {
				ctx.SetResponseWriter(w)
				compress.ReleaseResponseWriter(writer)
			}()
		}

		body, _ := ctx.Body()
		ctx.Writef("Received: %s", string(body))
	})

	app.Listen(":8080")
}

Documentation

Overview

Package compress negotiates gzip, deflate, brotli, snappy, s2 and zstd for the response and transparently decompresses a compressed request body.

It has no settings, so following the plain-handler rule its entry points are the `Handler` and `Safe` functions themselves (`Safe` refuses an unbounded request body); `Limited(maxDecompressedSize)` is the one variant that takes a setting and therefore returns a Handler.

Index

Constants

View Source
const (
	GZIP    = "gzip"
	DEFLATE = "deflate"
	BROTLI  = "br"
	SNAPPY  = "snappy"
	S2      = "s2"
	ZSTD    = "zstd"

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

The available builtin compression algorithms.

View Source
const DefaultMaxDecompressedSize int64 = 32 << 20

DefaultMaxDecompressedSize is the ceiling applied by `Safe` and by `Limited`'s zero value: 32MB, matching ContextOptions.PostMaxMemory.

Variables

View Source
var (
	// ErrNoEncoding returned when the request's Accept-Encoding or Content-Encoding was not found
	// or was IDENTITY.
	ErrNoEncoding = errors.New("compress: no encoding found")

	// ErrNotSupportedCompression returned when the request's Accept-Encoding (compress) or
	// Content-Encoding (decompress) was not found in the server's supported
	// compression algorithms or the header is empty or the header was IDENTITY.
	// Check with errors.Is.
	ErrNotSupportedCompression = errors.New("compress: no compression algorithm found for the request")
)
View Source
var AllEncodings = []string{GZIP, DEFLATE, BROTLI, SNAPPY, S2, ZSTD}

AllEncodings is a slice of default content encodings. See `AcquireResponseWriter`. ZSTD is last on purpose: on equal q-values the first offer wins, so clients sending a plain "Accept-Encoding: gzip, zstd" keep getting gzip.

View Source
var ErrDecompressedBodyTooLarge = errors.New("compress: decompressed request body too large")

ErrDecompressedBodyTooLarge is returned to a reader of the request body when the decompressed size exceeds the configured limit.

Functions

func GetAcceptEncoding

func GetAcceptEncoding(r *http.Request, offers ...string) (string, bool, error)

GetAcceptEncoding extracts the best available encoding from the request for response writer. It's the encoding the client supports so, server can decide which algorithm to use to compress.

Reports whether the request has an encoding that is supported by the server. If the request does not accept encoding then it returns an empty string, false and nil error, If the request accepts encoding but it's not supported by the server it returns an empty string, false and ErrNotSupportedCompression error.

func GetContentEncoding

func GetContentEncoding(r *http.Request, offers ...string) (string, bool, error)

GetContentEncoding extracts the best available encoding from the request for request body reader. It's the encoding the request sent data to the server. If the request has no encoding then it returns an empty string, false and nil error, If the request has encoding but it's not supported by the server it returns an empty string, false and ErrNotSupportedCompression error.

func Handler

func Handler(ctx *context.Context)

Handler retruns a new Handler which is responsible to decompress the request's body based on the "Content-Encoding" header and compress the response's body based on the client's "Accept-Encoding" header.

SECURITY WARNING: this handler places NO ceiling on the decompressed size of a request body.

A ~1MB "Content-Encoding: gzip" body of zeros expands to roughly 1GB, and any handler that calls ctx.Body or ctx.ReadJSON will allocate all of it. A handful of concurrent requests exhausts memory. Use one of:

  • compress.Safe, or compress.Limited(n), which cap the decompressed stream;
  • ContextOptions.BodyMaxMemory, which caps every request body application-wide;
  • the bodylimit middleware, registered AFTER this one.

This handler is kept unbounded for backwards compatibility and logs a warning once at first use when nothing else bounds the body.

Usage:

app.Use(compress.Handler)

OR

app.UseRouter(compress.Handler)

Prefer:

app.Use(compress.Safe)

func Limited

func Limited(maxDecompressedSize int64) context.Handler

Limited returns a compression handler that refuses to decompress a request body beyond "maxDecompressedSize" bytes.

This is the mitigation for a decompression bomb: a ~1MB gzip payload of zeros expands to roughly 1GB, and `Handler` hands the expanded stream to whatever reads ctx.Body()/ctx.ReadJSON with no ceiling at all. A handful of concurrent requests is enough to exhaust memory.

Pass a value <= 0 to use DefaultMaxDecompressedSize.

Usage:

app.Use(compress.Limited(8 << 20)) // 8MB decompressed

The two other ways to bound it, both of which cap the DECOMPRESSED stream correctly because they wrap the body after this middleware replaced it:

  • iris.WithContextOptions(func(o *iris.ContextOptions) { o.BodyMaxMemory = ... })
  • the bodylimit middleware, registered AFTER this one

func ReleaseResponseWriter

func ReleaseResponseWriter(w *ResponseWriter)

ReleaseResponseWriter returns the ResponseWriter to the pool. It flushes and closes the underline writer. It MUST be called after the response is done.

One response is not closed but handed back as it is, with the Content-Encoding and Vary taken off: one whose handler wrote nothing through w and declared a Content-Length of its own. See Disable.

A caller that put w on a Context with SetResponseWriter puts the previous writer back before calling this. The released value has no writer under it any more and is reused by another request, and a handler registered outside the caller (an access log, a recovery handler) still reads the Context's writer after the chain returns:

previous := ctx.ResponseWriter()
if w, ok, _ := compress.AcquireResponseWriter(previous, ctx.Request(), -1); ok {
	ctx.SetResponseWriter(w)
	defer func() {
		ctx.SetResponseWriter(previous)
		compress.ReleaseResponseWriter(w)
	}()
}

func Safe

func Safe(ctx *context.Context)

Safe is Limited with DefaultMaxDecompressedSize.

Prefer it over `Handler` for anything that accepts compressed request bodies from untrusted clients.

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 a wrapped `ErrNotSupportedCompression` if the "encoding" is empty or the server is missing its decompression algorithm, check it with errors.Is. Note: on server-side the request body (src) will be closed automaticaly.

func NewRequestReader

func NewRequestReader(r *http.Request) (*Reader, bool, error)

NewRequestReader returns a new "Reader" wrapper of the request body. The "Reader" is used to decompress the request body data. The "Reader" should be closed after use.

type ResponseWriter

type ResponseWriter struct {
	context.ResponseWriter

	Writer
	Encoding string
	Level    int
	// contains filtered or unexported fields
}

ResponseWriter is a compressed data http.ResponseWriter.

func AcquireResponseWriter

func AcquireResponseWriter(w context.ResponseWriter, r *http.Request, level int) (*ResponseWriter, bool, error)

AcquireResponseWriter returns a Compress.ResponseWriter from the pool. It accepts an Iris 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", "deflate", "br", "snappy", "s2" and "zstd" based on the request's "Accept-Encoding" header value.

func (*ResponseWriter) Disable

func (w *ResponseWriter) Disable() context.ResponseWriter

Disable steps this writer out of the chain and returns the writer it wrapped, implementing context.ResponseWriterDisabler.

It removes the Content-Encoding and the Vary entry that AcquireResponseWriter set optimistically, before the handler had chosen a Content-Type, and it marks the writer so the deferred ReleaseResponseWriter cannot close the compressor and write a footer into a response that is now uncompressed.

It is idempotent and safe to call before the first byte, which is the only time it makes sense: bytes already handed to the compressor cannot be recalled.

func (*ResponseWriter) Flush

func (w *ResponseWriter) Flush()

Flush implements the http.Flusher interface.

func (*ResponseWriter) FlushError

func (w *ResponseWriter) FlushError() error

FlushError drains the compressor and then the transport, and reports the first failure, implementing context.ResponseWriterFlushError.

The two stages are both required and their order matters: bytes sitting in the compressor's window have not reached the connection yet, and flushing the connection without draining the compressor first sends nothing.

func (*ResponseWriter) Write

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

Write writes the compressed data to the underline response writer.

func (*ResponseWriter) Written

func (w *ResponseWriter) Written() int

Written reports how many body bytes the handlers have written through this writer, counted before compression.

The count is kept here and not read from the writer underneath because a compressor buffers. Deflate, brotli, snappy, s2 and zstd hand nothing over until their window fills or they are closed, so after a handler wrote a short body the writer underneath still reports NoWritten. Code that asks "did a body already go out?" (rest/errors.Handler, Context.StopWithJSON, the router's default error handler) then answered no and wrote a second body after the first.

Before the first write it reports what the writer underneath does, so NoWritten and StatusCodeWritten keep their meaning. So does a disabled writer, whose writes pass straight through.

type Writer

type Writer interface {
	io.WriteCloser
	// All known implementations contain `Flush` and `Reset`  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 CompressWriter of "w" based on the given "encoding".

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL