.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
   under the License.

.. include:: ../../common.defs

.. _admin-plugins-compress:

Compress Plugin
***************

This plugin adds compression and decompression options to both origin and cache
responses.

Purpose
=======

Not all clients can handle compressed content. Not all origin servers are
configured to respond with compressed content when a client says it can accept
it. And it's not always necessary to make two separate requests to an origin,
and track two separate cache objects, for the same content - once for a
compressed version and another time for an uncompressed version.

This plugin tidies up these problems by transparently compressing or deflating
origin responses, as necessary, so that both variants of a response are stored
as :term:`alternates <alternate>` and the appropriate version is used for client responses,
depending on the client's indication (via an ``Accept`` request header) of what
it can support.

Additionally, this plugin adds configurability for what types of origin
responses will receive this treatment, which will be proxied and cached with
default behavior, and which may be explicitly disallowed to cache both
compressed and deflated versions (because, for example, the cost of compression
is known ahead of time to outweigh the space and bandwidth savings and you wish
to avoid |TS| even testing for the possibility).

Installation
============

This plugin is considered stable and is included with |TS| by default. There
are no special steps necessary for its installation.

Configuration
=============

This plugin can be used as either global plugin or remap plugin.
It can be enabled globally for |TS| by adding the following to your
:file:`plugin.config`::

   compress.so

With no further options, this will enable the following default behavior:

*  Enable caching of compressed responses. Uncompressed and compressed versions
   are maintained as separate :term:`alternates <alternate>` via
   ``Vary: Accept-Encoding``.

*  Compress objects with `text/*` content types for every origin.

*  Don't hide `Accept` encoding headers from origin servers (for an offloading
   reverse proxy).

*  No URLs are disallowed from compression.

*  Disable flush (flush compressed content to client).

* Only objects greater than 1Kb will be compressed

Alternatively, a configuration may be specified (shown here using the sample
configuration provided with the plugin's source)::

   compress.so <path-to-plugin>/sample.compress.config

This can be used as remap plugin by pointing to config file in remap rule
:file:`remap.config`::

   @plugin=compress.so @pparam=sample.compress.config

The following sections detail the options you may specify in the plugin's
configuration file. Options may be used globally, or may be specified on a
per-site basis by preceding them with a `[<site>]` line, where `<site>` is the
client-facing domain for which the options should apply.

Per site configuration for remap plugin should be ignored.

cache
-----

Controls which version of the response is stored in cache when the compress
transform runs (i.e., when the client sends ``Accept-Encoding``).

When set to ``true``, the compressed (transformed) response is cached. When set
to ``false``, the uncompressed (untransformed) response is cached and
compression is performed on-the-fly for subsequent cache hits.

.. note::

   The plugin always adds ``Vary: Accept-Encoding`` to compressible responses.
   This causes |TS| to use separate cache :term:`alternates <alternate>` (keys)
   for requests with different ``Accept-Encoding`` values. Which body
   representation is actually stored in cache still depends on the ``cache``
   option: with ``cache true`` the compressed response is cached, while with
   ``cache false`` only the uncompressed response is cached and compression is
   performed on-the-fly for clients that send ``Accept-Encoding``.

Enabled by default.

range-request
-------------

This config controls behavior of this plugin when a client send ``Range`` header and ``Accept-Encoding`` header in the same time.

====================== =================================================================
Value                  Description
====================== =================================================================
none                   Do nothing
true                   Same as ``none`` for compatibility
remove-range           Remove ``Range`` header if the request has both headers
remove-accept-encoding Remove ``Accept-Encoding`` header if the request has both headers
no-compression         Do NOT compress Partial Content (default)
false                  Same as ``no-compression`` for compatiblity
====================== =================================================================

.. important::

   Do NOT set this to ``none`` (or ``true``) if the cache config is set to ``false``. This combination will deliver corrupted content.


.. important::

   Some plugins (like cache_range_request) remove ``Range`` header. If you set ``remove-range`` or ``remove-accept-encoding``, be careful with the order of plugins.

compressible-content-type
-------------------------

Provides a wildcard to match against content types, determining which are to be
considered compressible. This defaults to ``text/*``. Takes one Content-Type
per line.

compressible-status-code
------------------------

A comma separated list of response status codes for which to enable
compression. Defaults to 200, 206, 304.

minimum-content-length
----------------------

Minimum Content-Length value sent by the origin server to consider the response
compressible. Due to the overhead and latency of compression and decompression,
it only makes sense to compress files above a certain size threshold.
Compressing files below 150 bytes can actually make them larger. This setting
only applies if the response explicitly sends Content-Length. Regardless of
this setting, responses with ``Content-Length: 0`` are considered not
compressible. Defaults to 1024 bytes.

content_type_ignore_parameters
------------------------------

When set to ``true``, parameter substrings of a response ``Content-Type`` header
value (for example ``; charset=utf-8``) are ignored for the purpose of
``compressible-content-type`` pattern matching, unless the pattern itself
includes a ``;``. This allows a pattern like ``application/json`` to match
responses such as ``application/json; charset=utf-8``. When set to ``false``,
the full value including parameters is used for matching. Defaults to ``false``.

allow
--------

Provides a wildcard pattern which will be applied to request URLs. Any which
match the pattern will be considered compressible, and only deflated versions
of the objects will be cached and returned to clients. This may be useful for
objects which already have their own compression built-in, to avoid the expense
of multiple rounds of compression for trivial gains. If the regex is preceded by
``!`` (for example ``allow !*/nothere/*``), it disables the plugin from those machine URLs.

enabled
-------

When set to ``true`` (the default) permits objects to be compressed, and when ``false``
effectively disables the plugin in the current context.

flush
-----

Enables (``true``) or disables (``false``) flushing of compressed objects to
clients. This calls the compression algorithm's mechanism (Z_SYNC_FLUSH and for gzip
and BROTLI_OPERATION_FLUSH for brotli) to send compressed data early.

remove-accept-encoding
----------------------

When set to ``true`` this option causes the plugin to strip the request's
``Accept-Encoding`` header when contacting the origin server. Setting this option to ``false``
will leave the header intact if the client provided it.

*  To ease the load on the origins.

*  For when the proxy parses responses, and the resulting compression and
   decompression is wasteful.

supported-algorithms
----------------------

Provides the compression algorithms that are supported, a comma separate list
of values. This will allow |TS| to selectively support ``gzip``, ``deflate``,
brotli (``br``), and zstd (``zstd``) compression. The default is ``gzip``.
Multiple algorithms can be selected using ',' delimiter, for instance,
``supported-algorithms deflate,gzip,br,zstd``. Note that this list must **not**
contain any white-spaces!

============== =================================================================
Algorithm      Description
============== =================================================================
gzip           Standard gzip compression (default, widely supported)
deflate        Deflate compression (RFC 1951)
br             Brotli compression (modern, efficient)
zstd           Zstandard compression (fast, high compression ratio)
============== =================================================================

Note that if :ts:cv:`proxy.config.http.normalize_ae` is ``1``, only gzip will
be considered, if it is ``2``, only br or gzip will be considered, if it is ``4``,
only zstd, br, or gzip will be considered, and if it is ``5``, all combinations
of zstd, br, and gzip will be considered.

gzip-compression-level
-----------------------

Sets the compression level for gzip compression. Valid values are 1-9, where
1 is fastest compression (lowest compression ratio) and 9 is slowest compression
(highest compression ratio). The default is 6, which provides a good balance
between compression speed and ratio.

brotli-compression-level
-------------------------

Sets the compression level for Brotli compression. Valid values are 0-11, where
0 is fastest compression (lowest compression ratio) and 11 is slowest compression
(highest compression ratio). The default is 6, which provides a good balance
between compression speed and ratio.

brotli-lgwin
------------

Sets the window size for Brotli compression. Valid values are 10-24, where
larger values provide better compression but use more memory. The default is 16.
This parameter controls the sliding window size used during compression:

- 10: 1KB window (fastest, least memory)
- 16: 64KB window (default, good balance)
- 24: 16MB window (slowest, most memory, best compression)

zstd-compression-level
----------------------

Sets the compression level for Zstandard compression. Valid values are 1-22, where
1 is fastest compression (lowest compression ratio) and 22 is slowest compression
(highest compression ratio). The default is 12, which provides an excellent
balance between compression speed and ratio for web content.

Examples
========

To establish global defaults for all site requests passing through |TS|, while
overriding just a handful for requests to content at ``www.example.com``, you
might create a configuration with the following options::

   # Set some global options first
   cache true
   remove-accept-encoding false
   compressible-content-type text/*
   compressible-content-type application/json
   compressible-status-code 200, 206
   minimum-content-length 860
   flush false
   gzip-compression-level 6
   brotli-compression-level 6
   brotli-lgwin 16
   zstd-compression-level 12

   # Now set a configuration for www.example.com
   [www.example.com]
   cache false
   remove-accept-encoding true
   allow !/notthis/*.js
   allow /this/*.js
   flush true

   # Allows brotli encoded response from origin but is not capable of brotli compression
   [brotli.allowed.com]
   enabled true
   compressible-content-type text/*
   compressible-content-type application/json
   content_type_ignore_parameters true
   flush true
   supported-algorithms gzip,deflate

   # Supports brotli compression with custom settings
   [brotli.compress.com]
   enabled true
   compressible-content-type text/*
   compressible-content-type application/json
   content_type_ignore_parameters true
   flush true
   supported-algorithms br,gzip
   brotli-compression-level 8
   brotli-lgwin 20

   # Supports zstd compression for high efficiency
   [zstd.compress.com]
   enabled true
   compressible-content-type text/*
   compressible-content-type application/json
   compressible-content-type application/javascript
   flush true
   supported-algorithms zstd,gzip
   zstd-compression-level 15

   # Supports all compression algorithms with optimized settings
   [all.compress.com]
   enabled true
   compressible-content-type text/*
   compressible-content-type application/json
   flush true
   supported-algorithms zstd,br,gzip,deflate
   gzip-compression-level 7
   brotli-compression-level 9
   brotli-lgwin 18
   zstd-compression-level 10

   # This origin does it all
   [bar.example.com]
   enabled false

   # A reasonable list of content-types that are compressible
   compressible-content-type text/*
   compressible-content-type *font*
   compressible-content-type *javascript
   compressible-content-type *json
   compressible-content-type *ml;*
   compressible-content-type *mpegURL
   compressible-content-type *mpegurl
   compressible-content-type *otf
   compressible-content-type *ttf
   compressible-content-type *type
   compressible-content-type *xml
   compressible-content-type application/eot
   compressible-content-type application/pkix-crl
   compressible-content-type application/x-httpd-cgi
   compressible-content-type application/x-perl
   compressible-content-type image/vnd.microsoft.icon
   compressible-content-type image/x-icon

Assuming the above options are in a file at ``/etc/trafficserver/compress.config``
the plugin would be enabled for |TS| in :file:`plugin.config` as::

   compress.so /etc/trafficserver/compress.config

Alternatively, the compress plugin can be used as a remap plugin: ::

   map http://www.example.com http://origin.example.com \
      @plugin=compress.so @pparam=compress.config

   $ cat /etc/trafficserver/compress.config
   enabled true
   cache true
   compressible-content-type *xml
   supported-algorithms
