wai-extra-3.1.17: Provides some basic WAI handlers and middleware.

Copyright | Michael Snoyman
License | BSD3
Maintainer | Michael Snoyman <michael@snoyman.com>
Stability | Unstable
Portability | portable
Safe Haskell | None
Language | Haskell2010

Network.Wai.Middleware.Gzip

Contents

- How to use this module
  - The Middleware
  - The Settings
  - How to handle file responses
  - Miscellaneous

Description

Automatic gzip compression of responses.

Synopsis

- gzip :: GzipSettings -> Middleware
- data GzipSettings
- defaultGzipSettings :: GzipSettings
- gzipFiles :: GzipSettings -> GzipFiles
- gzipCheckMime :: GzipSettings -> ByteString -> Bool
- gzipSizeThreshold :: GzipSettings -> Integer
- data GzipFiles
  - = GzipIgnore
  - | GzipCompress
  - | GzipCacheFolder FilePath
  - | GzipCacheETag FilePath
  - | GzipPreCompressed GzipFiles
- defaultCheckMime :: ByteString -> Bool
- def :: GzipSettings

# 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 `Middleware`s 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, use `defaultGzipSettings`. 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 `defaultGzipSettings` and set the fields you would like to change as follows:

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

data GzipSettings #

#### Instances

Instances details

Default GzipSettings # | DO NOT USE THIS INSTANCE! Please use `defaultGzipSettings`. This instance will be removed in a future major version.
Instance details Defined in Network.Wai.Middleware.Gzip Methods def :: GzipSettings #

defaultGzipSettings :: GzipSettings #

Default settings for the `gzip` middleware.

- Does not compress files.
- Uses `defaultCheckMime`.
- Compession threshold set to 860 bytes.

Since: 3.1.14.0

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

Instances details

Read GzipFiles # |
Instance details Defined in Network.Wai.Middleware.Gzip Methods readsPrec :: Int -> ReadS GzipFiles # readList :: ReadS [GzipFiles] # readPrec :: ReadPrec GzipFiles # readListPrec :: ReadPrec [GzipFiles] #
Show GzipFiles # |
Instance details Defined in Network.Wai.Middleware.Gzip Methods showsPrec :: Int -> GzipFiles -> ShowS # show :: GzipFiles -> String # showList :: [GzipFiles] -> ShowS #
Eq GzipFiles # |
Instance details Defined in Network.Wai.Middleware.Gzip Methods (==) :: GzipFiles -> GzipFiles -> Bool # (/=) :: GzipFiles -> GzipFiles -> Bool #

## Miscellaneous

`defaultCheckMime` is exported in case anyone wants to use it in defining their own `gzipCheckMime` function. `def` has been re-exported for convenience sake, but its use is now heavily discouraged. Please use the explicit `defaultGzipSettings`.

defaultCheckMime :: ByteString -> Bool #

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

def :: GzipSettings #

Deprecated: Please use `defaultGzipSettings`. `def` and the Default instance will be removed in a future major update.

Deprecated synonym for the `defaultGzipSettings`.