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
- Variables
- func GetAcceptEncoding(r *http.Request, offers ...string) (string, bool, error)
- func GetContentEncoding(r *http.Request, offers ...string) (string, bool, error)
- func Handler(ctx *context.Context)
- func Limited(maxDecompressedSize int64) context.Handler
- func ReleaseResponseWriter(w *ResponseWriter)
- func Safe(ctx *context.Context)
- type Reader
- type ResponseWriter
- type Writer
Constants ¶
const ( GZIP = "gzip" DEFLATE = "deflate" BROTLI = "br" SNAPPY = "snappy" S2 = "s2" ZSTD = "zstd" // IDENTITY no transformation whatsoever. IDENTITY = "identity" )
The available builtin compression algorithms.
const DefaultMaxDecompressedSize int64 = 32 << 20
DefaultMaxDecompressedSize is the ceiling applied by `Safe` and by `Limited`'s zero value: 32MB, matching ContextOptions.PostMaxMemory.
Variables ¶
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") )
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.
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 ¶
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 ¶
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 ¶
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 ¶
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)
}()
}
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.
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.