Enabling automatic compression

Fastly's compression feature dynamically fetches content from origin, compresses it according to the user's requested format (either Brotli or gzip), and then caches it. There are two ways to enable compression:

Limitations and caveats

During limited availability, keep in mind the following:

  • The API endpoint name is currently /gzip. API documentation for automatic compression currently appears in the documentation for the gzip endpoint during limited availability. The documented gzip API fully supports Brotli compression.
  • Brotli will be the default compression format used for browsers that support it. Once Fastly enables Brotli compression for your account, we will use Brotli compression by default for responses any time a client's Brotli-capable browser sends us the appropriate Accept-Encoding header. Brotli is the preferred compression format for multiple Accept-Encoding values where gzip is also an option.

When considering the general behavior of Fastly's compression feature, keep in mind the following:

  • Compression is only supported for content served uncompressed from your origin. To use automatic compression, ensure your content doesn't require decompression before compression is applied.
  • Compression is currently incompatible with non-cacheable content. To use automatic compression, ensure your content can be cached for delivery.
  • Compression of cacheable is currently incompatible with Edge Side Includes (ESIs). We recommend using compression for cacheable (static) content only when ESI is not also applied.
  • Compression is currently incompatible with Segmented Caching. To use automatic compression ensure Segmented Caching is disabled.

Enabling compression

To dynamically compress cacheable content based on file extension or content-type, follow the steps below to enable the default compression policy:

  1. Log in to the Fastly web interface.
  2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
  3. Click the Edit configuration button and then select the option to clone the active version. The Domains page appears.
  4. Click the Content link. The Content page appears.
  5. Click the Default compression policy switch to enable compression. Fastly supports both Brotli (the default) and gzip compression formats. The exact format selected depends on which ones your browser supports.
  6. Click the Activate button to deploy your configuration changes.

Setting up an advanced compression policy

To set up an advanced compression policy that specifies exactly which types of content are compressed and the conditions under which this compression occurs, follow the steps below:

  1. Log in to the Fastly web interface.
  2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
  3. Click the Edit configuration button and then select the option to clone the active version. The Domains page appears.
  4. Click the Content link. The Content page appears.
  5. Click the Set up advanced compression button. The Create a compression policy page appears.
  6. Click the Override these defaults link. Additional compression fields appear.
  7. Fill out the Create a compression policy fields as follows:
    • In the Name field, enter a human-readable name for your new compression policy.
    • In the Extensions field, enter the file extension for each file type to be dynamically compressed, separated by spaces. Only enter the three- or four-letter string representing the file extension.
    • In the Content types field, enter the content-type for each type of content you wish to have dynamically compressed, separated by spaces. Do not use regular expressions.
  8. Click the Create button. The new compression policy appears.
  9. Click the Activate button to deploy your configuration changes.

Automatic normalization

Because compression is one of the most common reasons to vary output based on a request header, Fastly will normalize the value of Accept-Encoding on incoming requests. The modified header will be set to a single encoding type, or none, and will reflect the best compression scheme supported by the browser.

Specifically, we run the following steps on inbound requests:

  1. If the User-Agent matches a pattern for browsers that have problems with compressed responses, remove the Accept-Encoding header
  2. Else if the Accept-Encoding header includes the string "br", set the entire value to the string "br"
  3. Else if the Accept-Encoding header includes the string "gzip", set the entire value to the string "gzip"
  4. Else if the Accept-Encoding header includes the string "deflate", set the entire value to the string "deflate"
  5. Else remove the Accept-Encoding header

Where this normalization process has changed the header value, the original value is made available in the custom header Fastly-Orig-Accept-Encoding.

Back to Top