Zstandard (zstd) Compression

This document provides a detailed guide on how to configure and use Zstandard (zstd) compression in OpenResty Edge.

# Configuration Hierarchy Overview

OpenResty Edge offers multiple levels of zstd 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 Zstandard/Set Zstandard Types
2. Global Custom Actions Configuration (Referenced by HTTP Application): Global Configuration > Global Custom Actions > Actions > Enable Gateway Zstandard/Set Zstandard Types
3. Application Settings Configuration: Application > HTTP Application > Specific Application > Settings > Zstandard
4. Global Rewrite Rules Configuration: Global Configuration > Global Rewrite Rules > Actions > Enable Gateway Zstandard/Set Zstandard Types
5. Global Common Configuration: Global Configuration > Common Configuration > Zstandard 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 zstd compression, providing default compression parameters for the entire system.

# Configuration Parameters

# Default Compression Types

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

text/plain text/css text/xml text/javascript text/cache-manifest
text/vtt text/x-component application/javascript application/json
application/ld+json application/xml application/xhtml+xml
application/rss+xml application/atom+xml application/manifest+json
application/x-web-app-manifest+json application/vnd.geo+json
application/vnd.ms-fontobject application/x-font-ttf application/wasm
font/opentype image/svg+xml image/bmp

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 zstd compression for requests meeting specific conditions.

# Available Actions

• Enable Gateway Zstandard: Dynamically enable or disable Zstandard compression
• Set Zstandard 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 zstd 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 zstd compression strategies for specific applications.

# Configuration Options

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

# Page Rules Configuration

Page rules provide the most granular zstd 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 zstd compression.

# Test Scenario

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

# Compression Effect Testing

Request with zstd compression enabled:

$ curl test.com/enable --resolve test.com:80:127.0.0.1 -H 'Accept-Encoding: zstd' -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: */*
> Accept-Encoding: zstd
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Content-Type: text/html
< Transfer-Encoding: chunked
< Connection: keep-alive
< Req-ID: 0000008000046f7f9e280008
< Content-Encoding: zstd
<
Warning: Binary output can mess up your terminal. Use "--output -" to tell
Warning: curl to output it to your terminal anyway, or consider "--output
Warning: <FILE>" to save to a file.

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

Request without zstd 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: zstd 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.