Brotli Compression

This document provides a detailed guide on how to configure and use Brotli compression in OpenResty Edge.

# Configuration Hierarchy Overview

OpenResty Edge offers multiple levels of Brotli compression configuration options, listed below in order of priority from highest to lowest:

1. Page Rules Configuration: Application > HTTP Application > Specific Application > Page Rules > Actions > Enable Gateway Brotli/Set Brotli Types
2. Global Custom Actions Configuration (Referenced by HTTP Application): Global Configuration > Global Custom Actions > Actions > Enable Gateway Brotli/Set Brotli Types
3. Application Settings Configuration: Application > HTTP Application > Specific Application > Settings > Brotli
4. Global Rewrite Rules Configuration: Global Configuration > Global Rewrite Rules > Actions > Enable Gateway Brotli/Set Brotli Types
5. Global Common Configuration: Global Configuration > Common Configuration > Brotli Configuration (enabled by default)

Note: When multiple levels are configured simultaneously, higher priority configurations will override lower priority ones.

# Global Common Configuration

Global common configuration serves as the foundation for Brotli compression, providing default compression parameters for the entire system.

# Configuration Parameters

# Default Compression Types

The system enables Brotli compression for the following MIME types by default:

text/plain

Tip: The text/html type is included in the compression scope by default and doesn’t need to be configured here.

# Global Rewrite Rules Configuration

Global rewrite rules allow you to configure Brotli compression for requests meeting specific conditions.

# Available Actions

• Enable Gateway Brotli: Dynamically enable or disable Brotli compression
• Set Brotli Compression Types: Customize MIME types for compression

Note: Compression types set here do not include text/html by default. If you need to compress HTML content, please add it manually.

# Global Custom Actions Configuration

Custom actions provide reusable Brotli compression configurations that can be referenced across multiple applications.

Configuration method is the same as global rewrite rules, but with higher priority.

# Application-Level Configuration

Application settings allow you to configure Brotli compression strategies for specific applications.

# Configuration Options

• Follow Global: Use settings from global common configuration
• Enable: Enable Brotli compression for the current application
• Disable: Disable Brotli compression for the current application

# Page Rules Configuration

Page rules provide the most granular Brotli compression control, allowing configuration for specific URL paths or conditions.

Configuration method is the same as global rewrite rules, but with the highest priority.

# Practical Application Example

The following example demonstrates the actual effect of Brotli compression.

# Test Scenario

The example configures a simple page rule that directly responds with “Hello World” text. Since global common configuration has Brotli compression enabled by default, no additional configuration is needed.

# Compression Effect Testing

Request with Brotli compression enabled:

$ curl test.com/enable --resolve test.com:80:127.0.0.1 -H 'Accept-Encoding: br' -v
* Added test.com:80:127.0.0.1 to DNS cache
* Hostname test.com was found in DNS cache
*   Trying 127.0.0.1:80...
* Connected to test.com (127.0.0.1) port 80 (#0)
> GET /enable HTTP/1.1
> Host: test.com
> User-Agent: curl/7.76.1
> Accept: */*
> Accept-Encoding: br
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Date: Fri, 30 May 2025 09:05:03 GMT
< Content-Type: text/html
< Transfer-Encoding: chunked
< Connection: keep-alive
< Req-ID: 0000008000046f7fd5f8000c
< Content-Encoding: br
<
* Connection #0 to host test.com left intact
�Hello World#

The response header contains Content-Encoding: br, confirming that compression is active.

Request without Brotli compression:

$ curl test.com/enable --resolve test.com:80:127.0.0.1 -v
*   Trying 127.0.0.1:80...
* Connected to test.com (127.0.0.1) port 80 (#0)
> GET /enable HTTP/1.1
> Host: test.com
> User-Agent: curl/7.76.1
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Date: Fri, 30 May 2025 08:42:51 GMT
< Content-Type: text/html
< Transfer-Encoding: chunked
< Connection: keep-alive
< Req-ID: 0000008000046f7fac58000b
<
Hello World

When the Accept-Encoding: br request header is not included, the server returns uncompressed original content.

# Additional Notes

When Gzip, Brotli, and zstd compression are enabled simultaneously, the priority order is: zstd > Brotli > Gzip.