Network.Wai.Middleware.Gzip

Automatic gzip compression of responses.

How to use this module

This Middleware adds gzip encoding to an application. Its use is pretty straightforward, but it's good to know how and when it decides to encode the response body.

A few things to keep in mind when using this middleware:

• It is advised to put any Middlewares that change the response behind this one, because it bases a lot of its decisions on the returned response.
• Enabling compression may counteract zero-copy response optimizations on some platforms.
• This middleware is applied to every response by default. If it should only encode certain paths, Network.Wai.Middleware.Routed might be helpful.

The Middleware

There are a good amount of requirements that should be fulfilled before a response will actually be gzip encoded by this Middleware, so here's a short summary.

Request requirements:

• The request needs to accept "gzip" in the "Accept-Encoding" header.
• Requests from Internet Explorer 6 will not be encoded. (i.e. if the request's "User-Agent" header contains "MSIE 6")

Response requirements:

• The response isn't already encoded. (i.e. shouldn't already have a "Content-Encoding" header)
• The response isn't a 206 Partial Content (partial content should never be compressed)
• If the response contains a "Content-Length" header, it should be larger than the gzipSizeThreshold.
• The "Content-Type" response header's value should evaluate to True when applied to gzipCheckMime (though GzipPreCompressed will use the ".gz" file regardless of MIME type on any ResponseFile response)

gzip :: GzipSettings -> Middleware

Use gzip to compress the body of the response.

The Settings

If you would like to use the default settings, using just def is enough. The default settings don't compress file responses, only builder and stream responses, and only if the response passes the MIME and length checks. (cf. defaultCheckMime and gzipSizeThreshold)

To customize your own settings, use the def method and set the fields you would like to change as follows:

myGzipSettings :: GzipSettings
myGzipSettings =
  def
    { gzipFiles = GzipCompress
    , gzipCheckMime = myMimeCheckFunction
    , gzipSizeThreshold = 860
    }

data GzipSettings

Instances

Default GzipSettings

Use default MIME settings; do not compress files; skip compression on data smaller than 860 bytes.

Defined in Network.Wai.Middleware.Gzip

Methods

def :: GzipSettings

gzipFiles :: GzipSettings -> GzipFiles

Gzip behavior for files

Only applies to ResponseFile (responseFile) responses. So any streamed data will be compressed based solely on the response headers having the right "Content-Type" and "Content-Length". (which are checked with gzipCheckMime and gzipSizeThreshold, respectively)

gzipCheckMime :: GzipSettings -> ByteString -> Bool

Decide which files to compress based on MIME type

The ByteString is the value of the "Content-Type" response header and will default to False if the header is missing.

E.g. if you'd only want to compress json data, you might define your own function as follows:

myCheckMime mime = mime == "application/json"

gzipSizeThreshold :: GzipSettings -> Integer

Skip compression when the size of the response body is below this amount of bytes (default: 860.)

Setting this option to less than 150 will actually increase the size of outgoing data if its original size is less than 150 bytes.

This will only skip compression if the response includes a "Content-Length" header AND the length is less than this threshold.

How to handle file responses

data GzipFiles

Gzip behavior for files.

Constructors

GzipIgnore

Do not compress file (ResponseFile) responses. Any ResponseBuilder or ResponseStream might still be compressed.

GzipCompress

Compress files. Note that this may counteract zero-copy response optimizations on some platforms.

GzipCacheFolder FilePath

Compress files, caching the compressed version in the given directory.

GzipCacheETag FilePath

Takes the ETag response header into consideration when caching files in the given folder. If there's no ETag header, this setting is equivalent to GzipCacheFolder.

N.B. Make sure the gzip middleware is applied before any Middleware that will set the ETag header.

Since: 3.1.12

GzipPreCompressed GzipFiles

If we use compression then try to use the filename with ".gz" appended to it. If the file is missing then try next action.

Since: 3.0.17

Instances

Read GzipFiles

Defined in Network.Wai.Middleware.Gzip

Methods

readsPrec :: Int -> ReadS GzipFiles

readList :: ReadS [GzipFiles]

readPrec :: ReadPrec GzipFiles

readListPrec :: ReadPrec [GzipFiles]

Show GzipFiles

Defined in Network.Wai.Middleware.Gzip

Methods

showsPrec :: Int -> GzipFiles -> ShowS

show :: GzipFiles -> String

showList :: [GzipFiles] -> ShowS

Eq GzipFiles

Defined in Network.Wai.Middleware.Gzip

Methods

(==) :: GzipFiles -> GzipFiles -> Bool

(/=) :: GzipFiles -> GzipFiles -> Bool

Miscellaneous

def is re-exported for convenience sake, and defaultCheckMime is exported in case anyone wants to use it in defining their own gzipCheckMime function.

defaultCheckMime :: ByteString -> Bool

MIME types that will be compressed by default: text/ *, application/json, application/javascript, application/ecmascript, image/x-icon.

def :: Default a => a

The default value for this type.