//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

[[gzip-filter]]
=== Gzip Handler

[[gzip-filter-metadata]]
==== Info

* Classname: `org.eclipse.jetty.server.handler.gzip.GzipHandler`
* Maven Artifact: org.eclipse.jetty:jetty-servlets
* Javadoc: {JDURL}/org/eclipse/jetty/server/handler/gzip/GzipHandler.html

[[gzip-filter-usage]]
==== Usage

The Jetty `GzipHandler` is a compression handler that you can apply to any dynamic resource (servlet).
It fixes many of the bugs in commonly available compression filters: it works with asynchronous servlets; it handles all ways to set content length.
Some user-agents might be excluded from compression to avoid common browser bugs (yes, this means IE!).

The `GzipHandler` can be added to the entire server by enabling the `gzip.mod` module.
It may also be added to individual contexts in a context xml file.

____
[NOTE]
Jetty 9 only compresses using GZip.
Using deflate HTTP compression is not supported and will not function.
____

[[gzip-filter-rules]]
==== Gzip Rules

`GzipHandler` will gzip the content of a response if:

* It is mapped to a matching path
* The request method is configured to support gzip
* The request is not from an excluded User-Agent
* accept-encoding header is set to gzip
* The response status code is >=200 and <300
* The content length is unknown or more than the minGzipSize initParameter or the minGzipSize is 0(default)
* The content-type does not match an excluded mime-type
* No content-encoding is specified by the resource

Compressing the content can greatly improve the network bandwidth usage, but at the cost of memory and CPU cycles.
The link:#default-servlet[DefaultServlet] is capable of serving pre-compressed static content, which saves memory and CPU.

The `GzipHandler` installs an output interceptor which passes through to the `DefaultServlet`.
If the content served by `DefaultServlet` is already compressed, the `GzipHandler` does nothing; if it is not compressed, the content is compressed on-the-fly.

____
[NOTE]
Automatic precompression by the `DefaultServlet` can be configured.
Read more about the `DefaultServlet` link:#default-servlet[here.]
____


[[gzip-filter-init]]
==== Gzip Configuration

minGzipSize::
Content will only be compressed if content length is either unknown or greater than `minGzipSize`.
checkGzExists (Deprecated)::
False by default.
If set to true, the handler will check for pre-compressed content.
includedMethods::
List of HTTP methods to compress.
If not set, only `GET` requests are compressed.
includedMimeTypes::
List of MIME types to compress.
excludedMimeTypes::
List of MIME types not to compress.
excludedAgentPatterns::
A list of regex patterns for User-Agent names from which requests should not be compressed.
excludedPaths::
List of paths to exclude from compression.
Performs a `String.startsWith(String)` comparison to check if the path matches.
If it does match then there is no compression.
To match subpaths use excludePathPatterns instead.
includedPaths::
List of paths to consider for compression.
includePaths::
List of paths to definitely consider for compression.
