zstd-nginx-module-plus

# Name

zstd-nginx-module - Nginx module for the Zstandard compression.

# Table of Contents

• Name
• Status
• Synopsis
• Directives
  • ngx_http_zstd_filter_module
    • zstd_dict_file
    • zstd
    • zstd_comp_level
    • zstd_min_length
    • zstd_types
    • zstd_buffers
  • ngx_http_zstd_static_module
    • zstd_static
• Variables
  • ngx_http_zstd_filter_module
    • $zstd_ratio
• Lua API
• Author

# Status

This Nginx module is currently considered production ready.

# Synopsis

# specify the dictionary
zstd_dict_file /path/to/dict;

server {
    listen 127.0.0.1:8080;
    server_name localhost;

    location / {
        # enable zstd compression
        zstd on;
        zstd_min_length 256; # no less than 256 bytes
        zstd_comp_level 3; # set the level to 3

        proxy_pass http://foo.com;
    }
}

server {
    listen 127.0.0.1:8081;
    server_name localhost;

    location / {
        zstd_static on;
        root html;
    }
}

# Directives

# ngx_http_zstd_filter_module

The ngx_http_zstd_filter_module module is a filter that compresses responses using the “zstd” method. This often helps to reduce the size of transmitted data by half or even more.

# zstd_dict_file

Syntax: zstd_dict_file /path/to/dict;
Default: -
Context: http

Specifies the external dictionary.

WARNING: Be careful! The content-coding registration only specifies a means to signal the use of the zstd format, and does not additionally specify any mechanism for advertising/negotiating/synchronizing the use of a specific dictionary between client and server. Use the zstd_dict_file only if you can insure that both ends (server and client) are capable of using the same dictionary (e.g. advertise with a HTTP header). See https://github.com/tokers/zstd-nginx-module/issues/2 for the details.

# zstd

Syntax: zstd on | off;
Default: zstd off;
Context: http, server, location, if in location

Enables or disables zstd compression for response.

# zstd_comp_level

Syntax: zstd_comp_level level;
Default: zstd_comp_level 1;
Context: http, server, location

Sets a zstd compression level of a response. Acceptable values are in the range from 1 to ZSTD_maxCLevel().

# zstd_min_length

Syntax: zstd_min_length length;
Default: zstd_min_length 20;
Context: http, server, location

Sets the minimum length of a response that will be compressed by zstd. The length is determined only from the Content-Length response header field.

# zstd_types

Syntax: zstd_types mime-type …;
Default: zstd_types text/html;
Context: http, server, location

Enables zstd of responses for the specified MIME types in addition to text/html. The special value * matches any MIME type.

# zstd_buffers

Syntax: zstd_buffers number size;
Default: zstd_buffers 32 4k | 16 8k;
Context: http, server, location

Sets the number and size of buffers used to compress a response. By default the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.

# ngx_http_zstd_static_module

The ngx_http_zstd_static_module module allows sending precompressed files with the .zst filename extension instead of regular files.

# zstd_static

Syntax: zstd_static on | off | always;
Default: zstd_static off;
Context: http, server, location

Enables (“on”) or disables (“off”) checking the existence of precompressed files. The following directives are also taken into account: gzip_vary.

With the “always” value, “zstd” file is used in all cases, without checking if the client supports it.

# Variables

# ngx_http_zstd_filter_module

# $zstd_ratio

Achieved compression ratio, computed as the ratio between the original and compressed response sizes.

# Lua API

The resty.zstd.filter module provides Lua API for controlling zstd compression dynamically.

# resty.zstd.filter.enable

Syntax: resty.zstd.filter.enable(on)
Context: rewrite_by_lua, access_by_lua

Enables or disables zstd compression for the current request.

The on parameter is a boolean value:

• true - enable zstd compression for the current request
• false - disable zstd compression for the current request

Example:

local zstd = require "resty.zstd.filter"

-- Enable zstd compression for this request
zstd.enable(true)

# resty.zstd.filter.types

Syntax: resty.zstd.filter.types(types)
Context: rewrite_by_lua, access_by_lua

Sets the MIME types for which zstd compression should be enabled for the current request.

The types parameter is a string containing space-separated MIME types.

Example:

local zstd = require "resty.zstd.filter"

-- Set MIME types for zstd compression
zstd.types("text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss")

# resty.zstd.filter.comp_level

Syntax: resty.zstd.filter.comp_level(level)
Context: rewrite_by_lua, access_by_lua

Sets the zstd compression level for the current request.

The level parameter is an integer value in the range from 1 to 22.

Example:

local zstd = require "resty.zstd.filter"

-- Set compression level to 5
zstd.comp_level(5)

# Author

• Alex Zhang zchao1995@gmail.com, UPYUN Inc.
• Junlong LiLijunlong@openresty.com

# License

This Nginx module is licensed under BSD 2-Clause License.