DeflateFilter

The main task of the DeflateFilter is to compress the content of an HTTP response body. It uses the zlib library to perform this job. The filter is also able to measure the bandwidth of a client's connection. To do this task, it intercepts the request of the client and sends back an HTML page with some JavaScript that measures the bandwidth. The measured bandwidth is stored into a cookie. Based upon this cookie and a configured bandwidth threshold, the DeflateFilter is able to decide if compression is enabled or not. This behavior is especially useful when clients with low connection speed are expected to use the web application.

Classname

 ch::nevis::isiweb4::filter::deflate::DeflateFilter

Library

libDeflateFilter.so.1

Configuration

AlwaysCompress

Type: boolean
Usage Constraint: optional, advanced
Default: false

If this value is set to true, bandwidth is never measured and compression is always enabled. Thus, content will always be compressed (if the client is able to read compressed content). Used if clients are known to have slow connections or if the bandwidth measurement can confuse clients.

BandwidthThreshold

Type: integer
Usage Constraint: optional
Default: 100

Defines the bandwidth threshold in KBit/s, below which compression is enabled.
Impact: CPU/Bandwidth tradeoff

DataAmount

Type: integer
Usage Constraint: optional, advanced
Default: 50000

Defines the data amount, in bytes, sent to the client as bandwidth measurement is performed. A higher value results in a slower bandwidth test but more accurate measurement results.
Impact: Tradeoff between initial measurement time and cpu/bandwidth lost due to measurement error

CompressContentType

Type: string
Usage Constraint: optional
Default: text/html text/xml text/plain

Defines a newline or space separated list of content-types that will be compressed and permits configuration of mime types. The response will be compressed if its mime type is contained in the configured list.

Brotli.Quality

Type: integer, min: 0, max: 11
Usage Constraint: optional, advanced
Default: 5

Defines the Brotli compression quality used. A lower value reduces the CPU and memory usage while a higher value improves the compression ratio. Setting quality level 10 or 11 is not recommended since it enables resource intensive compression modes.

CompressionLevel

Type: integer
Usage Constraint: optional, advanced
Default: -1

Defines the compression level used (0-9)
0 = no compression; 9 = maximum compression; -1 = default compression
Impact: CPU/Bandwidth tradeoff, also depends on data.

CookieLifetime

Type: integer
Usage Constraint: optional, advanced
Default: 0

Defines the lifetime, in seconds, of the cookie set after bandwidth measurement. If the cookie expires, the bandwidth is measured again. A value of 0 means that the cookie expires if the browser is restarted. Use shorter lifetimes if you expect the bandwidth values to be around the bandwidth threshold and change often. This might be the case for wireless connections, or if multiple clients share a slow connection.

NoInterceptionPattern

Type: string
Usage Constraint: optional, troubleshooting

Specifies a whitespace-separated list of URI regexps (<regexp>[) where no interception takes place. The content provider might initiate interceptions, which can get confused if bandwidth measurement is done at the same time. Set the pattern to match these locations. The default regex type is PCRE(da).

CompressionBufferSize

Type: integer, min: 1024
Usage Constraint: optional, advanced
Default: 4096

The CompressionBufferSize directive specifies the size (in bytes) of the fragments that the zlib library should compress at one time.

CompressionMemLevel

Type: integer, min: 1, max: 9
Usage Constraint: optional, advanced
Default: 9

The CompressionMemLevel parameter specifies how much memory should be allocated for the internal compression state. If CompressionMemLevel=1, the compression process uses minimum memory but is slow and reduces the compression ratio. If CompressionMemLevel=9, compression happens at optimum speed but uses maximum memory.

CompressionWindowSize

Type: integer, min: -15, max: -8
Usage Constraint: optional, advanced
Default: -15

The CompressionWindowSize parameter sets the size of the history buffer. The buffer's size will be calculated the following way: WindowSizeBytes = 2^(WindowSizeParam*-1). Choose a value between -8 and -15. Using a lower value improves the compression ratio at the cost of increased memory usage.

Example

In the sample code below, the DeflateFilter compresses all responses with the specified content types into a gzip file and sends this file to the front end. The filter only compresses content with the following content types:

• text/html
• text/xml
• text/plain

<filter>
 <filter-name>DeflateFilter</filter-name>
 <filter-class>ch::nevis::isiweb4::filter::deflate::DeflateFilter</filter-class>
 <init-param>
         <param-name>AlwaysCompress</param-name>
         <param-value>true</param-value>
 </init-param>
 <init-param>
         <param-name>CompressContentType</param-name>
         <param-value>text/html text/xml text/plain</param-value>
 </init-param>
</filter>

Place the DeflateFilter in the beginning of the filter and servlet chain (just after the front end).

note

The DeflateFilter only compresses content if the front end sends the Accept-Encoding header with supported compressions (gzip or deflate). If this is not the case, the filter does not compress any response, even if the filter attribute AlwaysCompress is set to "true".

You can find the above example in examples/various/DeflateFilter.example on the installed nevisProxy package.