github.com/lf4096/gin-compress

gin-compress

Middleware for Gin Gonic for compressing HTTP responses and decompressing HTTP requests.

Currently, this package supports Brotli, GZIP, Deflate, and ZSTD for both compressing and decompressing.

This was created for my own purposes. If you're looking for something that is perhaps a bit more actively supported, check out the official Gin GZIP Middleware.

Usage

If nothing special is desired, one can add the Compress middleware with the default config to your Gin router like so:

package main


import (
	"log"
	"github.com/gin-gonic/gin"
	limits "github.com/gin-contrib/size"
	"github.com/aurowora/compress"
)

func main() {
	r := gin.Default()
	r.Use(compress.Compress())
	// Limit payload to 10 MB, notice how it follows Compress() MW.
	// See the "Security" section below...
	r.Use(limits.RequestSizeLimiter(10 * 1024 * 1024)) 
	
	// Declare routes and do whatever else here...
	
	log.Fatalln(r.Run())
}

Despite the name, the Compress middleware handles compressing both the response body and decompressing the request body.

To configure the middleware, pass the return value of the functions beginning with With to the middleware's constructors, like so:

// disables Brotli
r.Use(compress.Compress(compress.WithAlgo(compress.BROTLI, false)))

Configuration

The following configuration options are available for the Compress middleware:

Function Signature	Default	Description
WithAlgo(algo string, enable bool)	All enabled	Allows enabling/disabling any of the supported algorithms. Valid algorithms are currently compress.ZSTD, compress.BROTLI, compress.GZIP, and compress.DEFLATE
WithCompressLevel(algo string, level int)	Default for all algorithms	Allows setting the compression level for any supported algorithm. See the Brotli*, GzFlate*, and Zstd* constants.
WithPriority(algo string, priority int)	Order is Brotli, GZIP, Deflate, ZSTD	Specify the priority of an algorithm when the client will accept multiple. Higher priorities win.
WithExcludeFunc(f func(c *gin.Context) bool)	Not Set	Specify a function to be called to determine if the compressor should run. Note that response headers/body is not available at this point.
WithMinCompressBytes(numBytes int)	512	Do not invoke the compressor unless the response body is at least this many bytes
WithMaxDecodeSteps(steps int)	1	Determines how many rounds of decompression to perform if Content-Encoding includes multiple decompression algorithms.
WithDecompressBody(decompress bool)	true	Specifies whether the request body should be decompressed at all.

Security

Bugs/design flaws in the underlying compression algorithm implementations could allow for "zip bombs" that, when decompressed, expand to massive payloads. This results in high resource usage and potentially even denial of service. To mitigate this, applications making use of the request body decompression feature (i.e. WithDecompressBody(true), which is the default), should also use gin-contrib/size (or an equivalent) to limit the size of request bodies.

It is important that any payload size limiter middleware used come after the compress middleware as it will be useless otherwise.

An example of correct usage is shown above.

Tests

Tests cover most functionality in this package. The built-in tests can be run using go test.

License Notice

gin-compress Copyright (C) 2022 Aurora McGinnis

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at https://mozilla.org/MPL/2.0/.

The full terms of the Mozilla Public License 2.0 can also be found in the LICENSE.txt file within this repository.

The author of this package is not associated with the authors of Gin in any way.