Brotli Compression

This document explains in detail how to configure and use Brotli compression in OpenResty Edge.

# Configuration Hierarchy Overview

OpenResty Edge provides Brotli compression configuration at multiple levels. Listed from highest to lowest priority:

1. Page rule configuration: Applications > HTTP Application > a specific application > Page Rules > Actions > Enable Gateway Brotli / Set Brotli Type
2. Global custom action configuration (referenced by an HTTP application): Global Configuration > Global Custom Actions > Actions > Enable Gateway Brotli / Set Brotli Type
3. App settings configuration: Applications > HTTP Application > a specific application > Settings > Brotli
4. Global rewrite rule configuration: Global Configuration > Global Rewrite Rules > Actions > Enable Gateway Brotli / Set Brotli Type
5. Global general configuration: Global Configuration > General Configuration > Brotli Configuration (enabled by default)

Note: When multiple levels are configured at the same time, the higher-priority configuration overrides the lower-priority one.

# Global General Configuration

The global general configuration is the base configuration for Brotli compression, providing the default compression parameters for the entire system.

# Configuration Parameters

# Default Compression Types

By default, the system enables Brotli compression for the following MIME types:

text/plain

Tip: The text/html type is included in the compression scope by default and does not need to be listed here again.

# Global Rewrite Rule Configuration

Global rewrite rules let you configure Brotli compression for requests that match specific conditions.

# Available Actions

• Enable Gateway Brotli: Dynamically enable or disable Brotli compression
• Set Brotli Compression Type: Customize the MIME types to compress

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

# Global Custom Action Configuration

Custom actions provide a reusable Brotli compression configuration that can be referenced by multiple applications.

The configuration is the same as for global rewrite rules, but has a higher priority.

# Application-Level Configuration

In the app settings, you can configure a Brotli compression policy for a specific application.

# Configuration Options

• Follow global: Use the setting from the global general configuration
• Enable: Enable Brotli compression for the current application
• Disable: Disable Brotli compression for the current application

# Page Rule Configuration

Page rules provide the most fine-grained control over Brotli compression, allowing configuration for specific URL paths or conditions.

The configuration is the same as for global rewrite rules, but has the highest priority.

# Practical Example

The following example demonstrates the actual effect of Brotli compression.

# Test Scenario

The example configures a simple page rule that responds directly with the text “Hello World”. Because the global general configuration enables Brotli compression by default, no additional configuration is needed.

# Compression Effect Test

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 includes Content-Encoding: br, confirming that compression is in effect.

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 request does not include the Accept-Encoding: br header, the server returns the original, uncompressed content.

# Additional Notes

When Gzip, Brotli, and zstd compression are enabled at the same time, the priority order is zstd > Brotli > Gzip.