Zstandard (zstd) Compression

This document explains in detail how to configure and use Zstandard (zstd) compression in OpenResty Edge.

# Configuration Hierarchy Overview

OpenResty Edge provides zstd 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 Zstandard / Set Zstandard Type
2. Global custom action configuration (referenced by an HTTP application): Global Configuration > Global Custom Actions > Actions > Enable Gateway Zstandard / Set Zstandard Type
3. App settings configuration: Applications > HTTP Application > a specific application > Settings > Zstandard
4. Global rewrite rule configuration: Global Configuration > Global Rewrite Rules > Actions > Enable Gateway Zstandard / Set Zstandard Type
5. Global general configuration: Global Configuration > General Configuration > Zstandard 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 zstd compression, providing the default compression parameters for the entire system.

# Configuration Parameters

# Default Compression Types

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

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 does not need to be listed here again.

# Global Rewrite Rule Configuration

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

# Available Actions

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

# Configuration Options

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

# Page Rule Configuration

Page rules provide the most fine-grained control over zstd 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 zstd compression.

# Test Scenario

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

# Compression Effect Test

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

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 request does not include the Accept-Encoding: zstd 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.