brotli

Description

The brotli Plugin dynamically sets the behavior of brotli in Nginx.

Prerequisites

This Plugin requires brotli shared libraries.

The example commands to build and install brotli shared libraries:

  1. wget https://github.com/google/brotli/archive/refs/tags/v1.1.0.zip
  2. unzip v1.1.0.zip
  3. cd brotli-1.1.0 && mkdir build && cd build
  4. cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local/brotli ..
  5. sudo cmake --build . --config Release --target install
  6. sudo sh -c "echo /usr/local/brotli/lib >> /etc/ld.so.conf.d/brotli.conf"
  7. sudo ldconfig
brotli - 图1caution

If the upstream is returning a compressed response, then the Brotli plugin won’t be able to compress it.

Attributes

NameTypeRequiredDefaultValid valuesDescription
typesarray[string] or “False[“text/html”]Dynamically sets the brotli_types directive. Special value ““ matches any MIME type.
min_lengthintegerFalse20>= 1Dynamically sets the brotli_min_length directive.
comp_levelintegerFalse6[0, 11]Dynamically sets the brotli_comp_level directive.
modeintegerFalse0[0, 2]Dynamically sets the brotli decompress mode, more info in RFC 7932.
lgwinintegerFalse19[0, 10-24]Dynamically sets the brotli sliding window size, lgwin is Base 2 logarithm of the sliding window size, set to 0 lets compressor decide over the optimal value, more info in RFC 7932.
lgblockintegerFalse0[0, 16-24]Dynamically sets the brotli input block size, lgblock is Base 2 logarithm of the maximum input block size, set to 0 lets compressor decide over the optimal value, more info in RFC 7932.
http_versionnumberFalse1.11.1, 1.0Like the gzip_http_version directive, sets the minimum HTTP version of a request required to compress a response.
varybooleanFalsefalseLike the gzip_vary directive, enables or disables inserting the “Vary: Accept-Encoding” response header field.

Enable Plugin

The example below enables the brotli Plugin on the specified Route:

brotli - 图2note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

  1. admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
  1. curl -i http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
  2. {
  3. "uri": "/",
  4. "plugins": {
  5. "brotli": {
  6. }
  7. },
  8. "upstream": {
  9. "type": "roundrobin",
  10. "nodes": {
  11. "httpbin.org": 1
  12. }
  13. }
  14. }'

Example usage

Once you have configured the Plugin as shown above, you can make a request as shown below:

  1. curl http://127.0.0.1:9080/ -i -H "Accept-Encoding: br"
  1. HTTP/1.1 200 OK
  2. Content-Type: text/html; charset=utf-8
  3. Transfer-Encoding: chunked
  4. Connection: keep-alive
  5. Date: Tue, 05 Dec 2023 03:06:49 GMT
  6. Access-Control-Allow-Origin: *
  7. Access-Control-Allow-Credentials: true
  8. Server: APISIX/3.6.0
  9. Content-Encoding: br
  10. Warning: Binary output can mess up your terminal. Use "--output -" to tell
  11. Warning: curl to output it to your terminal anyway, or consider "--output
  12. Warning: <FILE>" to save to a file.

Delete Plugin

To remove the brotli Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
  2. {
  3. "uri": "/",
  4. "upstream": {
  5. "type": "roundrobin",
  6. "nodes": {
  7. "httpbin.org": 1
  8. }
  9. }
  10. }'