Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tokers/zstd-nginx-module
Nginx modules for the Zstandard compression
https://github.com/tokers/zstd-nginx-module
nginx nginx-module zstd
Last synced: about 2 months ago
JSON representation
Nginx modules for the Zstandard compression
- Host: GitHub
- URL: https://github.com/tokers/zstd-nginx-module
- Owner: tokers
- License: bsd-2-clause
- Created: 2018-10-11T02:50:44.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-04-22T08:51:49.000Z (5 months ago)
- Last Synced: 2024-07-28T15:34:53.871Z (2 months ago)
- Topics: nginx, nginx-module, zstd
- Language: C
- Homepage:
- Size: 68.4 KB
- Stars: 168
- Watchers: 8
- Forks: 23
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-nginx - zstd-nginx-module - Nginx modules for the Zstandard compression. (Third Party Modules / C Modules)
README
# Name
zstd-nginx-module - Nginx module for the [Zstandard compression](https://facebook.github.io/zstd/).# Table of Content
* [Name](#name)
* [Status](#status)
* [Synopsis](#synopsis)
* [Installation](#installation)
* [Directives](#directives)
* [ngx_http_zstd_filter_module](#ngx_http_zstd_filter_module)
* [zstd_dict_file](#zstd_dict_file)
* [zstd](#zstd)
* [zstd_comp_level](#zstd_comp_level)
* [zstd_min_length](#zstd_min_length)
* [zstd_types](#zstd_types)
* [zstd_buffers](#zstd_buffers)
* [ngx_http_zstd_static_module](#ngx_http_zstd_static_module)
* [zstd_static](#zstd_static)
* [Variables](#variables)
* [ngx_http_zstd_filter_module](#ngx_http_zstd_filter_module)
* [$zstd_ratio](#$zstd_ratio)
* [Author](#author)# Status
This Nginx module is currently considered experimental. Issues and PRs are welcome if you encounter any problems.
# Synopsis
```nginx
# 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 3proxy_pass http://foo.com;
}
}server {
listen 127.0.0.1:8081;
server_name localhost;location / {
zstd_static on;
root html;
}
}
```# Installation
To use theses modules, configure your nginx branch with `--add-module=/path/to/zstd-nginx-module`. Several points should be taken care.
* You can set environment variables `ZSTD_INC` and `ZSTD_LIB` to specify the path to `zstd.h` and the path to zstd shared library represently.
* static library will be tried prior to dynamic library, since this Nginx module uses some **advanced APIs** where static linking is recommended.
* System's zstd bundle will be linked if `ZSTD_INC` and `ZSTD_LIB` are not specified.
* Both `ngx_http_zstd_static_module` and `ngx_http_zstd_filter_module` will be configured.# 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 ztd 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, "zsted" 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.
# Author
Alex Zhang (张超) zchao1995@gmail, UPYUN Inc.
# License
This Nginx module is licensed under [BSD 2-Clause License](LICENSE).