feat: compression level option support (#381)

* Make fastest compression level the default setting

* Use balanced compression levels by default

* Fixed formatting and addressed clippy warning

* Change default zlib compression level to 3

* Updated docs to mention zlib compression

* Fixed setting spelling in docs

* Don't expose CompressionLevel::into_algorithm_level()

* Updated documentation of the compression feature

Author: palant

docs/content/configuration/command-line-arguments.md

@@ -28,6 +28,7 @@ cache-control-headers = true
 
 #### Auto Compression
 compression = true
+compression-level = "default"
 
 #### Error pages
 # Note: If a relative path is used then it will be resolved under the root directory.
@@ -88,7 +89,7 @@ health = false
 #### Maintenance Mode
 
 maintenance-mode = false
-# maintenance-mode-status = 503 
+# maintenance-mode-status = 503
 # maintenance-mode-file = "./maintenance.html"
 
 ### Windows Only

docs/content/configuration/config-file.md

@@ -78,10 +78,13 @@ Specify an optional CORS list of allowed HTTP headers separated by commas. It re
 Specify an optional CORS list of exposed HTTP headers separated by commas. It requires `SERVER_CORS_ALLOW_ORIGINS` to be used along with. Default `origin, content-type`.
 
 ### SERVER_COMPRESSION
-`Gzip`, `Deflate` or `Brotli` compression on demand determined by the `Accept-Encoding` header and applied to text-based web file types only. See [ad-hoc mime-type list](https://github.com/static-web-server/static-web-server/blob/master/src/compression.rs#L20). Default `true` (enabled).
+`Gzip`, `Deflate`, `Brotli` or `zlib` compression on demand determined by the `Accept-Encoding` header and applied to text-based web file types only. See [ad-hoc mime-type list](https://github.com/static-web-server/static-web-server/blob/master/src/compression.rs#L20). Default `true` (enabled).
+
+### SERVER_COMPRESSION_LEVEL
+Supported values are `fastest` (fast compression but larger resulting files), `best` (smallest file size but potentially slow) and `default` (algorithm-specific balanced compression level). Default is `default`.
 
 ### SERVER_COMPRESSION_STATIC
-Look up the pre-compressed file variant (`.gz` or `.br`) on disk of a requested file and serves it directly if available. Default `false` (disabled). The compression type is determined by the `Accept-Encoding` header.
+Look up the pre-compressed file variant (`.gz`, `.br` or `.zst`) on disk of a requested file and serves it directly if available. Default `false` (disabled). The compression type is determined by the `Accept-Encoding` header.
 
 ### SERVER_DIRECTORY_LISTING
 Enable directory listing for all requests ending with the slash character (‘/’). Default `false` (disabled).

docs/content/configuration/environment-variables.md

@@ -2,44 +2,37 @@
 
 **`SWS`** provides [`Gzip`](https://datatracker.ietf.org/doc/html/rfc1952), [`Deflate`](https://datatracker.ietf.org/doc/html/rfc1951#section-Abstract), [`Brotli`](https://www.ietf.org/rfc/rfc7932.txt) and [`Zstandard` (zstd)](https://datatracker.ietf.org/doc/html/rfc8878) compression of HTTP responses.
 
-The compression functionality is determined by the [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header and is only applied to text-based web file types.
+This feature is enabled by default and can be controlled by the boolean `-x, --compression` option or the equivalent [SERVER_COMPRESSION](../configuration/environment-variables.md#server_compression) env.
+
+```sh
+static-web-server \
+    --port 8787 \
+    --root ./my-public-dir \
+    --compression true
+```
+
+## Choice of compression algorithm
+
+The compression algorithm is determined by the [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header and the compression support built into SWS. By default SWS builds with support for `Gzip`, `Deflate`, `Brotli` and `Zstandard` algorithms.
 
 ## MIME types compressed
 
-Only this list of common text-based MIME-type files will be compressed either with `Gzip`, `Deflate` or `Brotli` via the `Accept-Encoding` header value.
+Compression is only applied to files with the MIME types listed below, indicating text and similarly well compressing formats. The asterisk `*` is a placeholder indicating an arbitrary MIME type part.
 
 ```txt
-text/html
-text/css
-text/javascript
-text/xml
-text/plain
-text/csv
-text/calendar
-text/markdown
-text/x-yaml
-text/x-toml
-text/x-component
+text/*
+*+xml
+*+json
 application/rtf
-application/xhtml+xml
 application/javascript
-application/x-javascript
 application/json
 application/xml
-application/rss+xml
-application/atom+xml
+font/ttf
+application/font-sfnt
 application/vnd.ms-fontobject
-font/truetype
-font/opentype
-image/svg+xml
 application/wasm
 ```
 
-This feature is enabled by default and can be controlled by the boolean `-x, --compression` option or the equivalent [SERVER_COMPRESSION](./../configuration/environment-variables.md#server_compression) env.
+## Compression level
 
-```sh
-static-web-server \
-    --port 8787 \
-    --root ./my-public-dir \
-    --compression true
-```
+SWS allows selecting the compression level via `--compression-level` command line option or the equivalent [SERVER_COMPRESSION_LEVEL](../configuration/environment-variables.md#server_compression_level) env. The available values are `fastest`, `best` and `default`. `fastest` will result in the lowest CPU load but also the worst compression factor. `best` will attempt to compress the data as much as possible (not recommended with `Brotli` or `Zstandard` compression, will be very slow). `default` tries to strike a balance, choosing a compression level where compression factor is already fairly good but the CPU load is still low.

docs/content/features/compression.md

@@ -37,6 +37,7 @@ use crate::{
     handler::RequestHandlerOpts,
     headers_ext::{AcceptEncoding, ContentCoding},
     http_ext::MethodExt,
+    settings::CompressionLevel,
     Error, Result,
 };
 
@@ -67,8 +68,9 @@ const AVAILABLE_ENCODINGS: &[ContentCoding] = &[
 ];
 
 /// Initializes dynamic compression.
-pub fn init(enabled: bool, handler_opts: &mut RequestHandlerOpts) {
+pub fn init(enabled: bool, level: CompressionLevel, handler_opts: &mut RequestHandlerOpts) {
     handler_opts.compression = enabled;
+    handler_opts.compression_level = level;
 
     const FORMATS: &[&str] = &[
         #[cfg(any(feature = "compression", feature = "compression-deflate"))]
@@ -81,7 +83,7 @@ pub fn init(enabled: bool, handler_opts: &mut RequestHandlerOpts) {
         "zstd",
     ];
     server_info!(
-        "auto compression: enabled={enabled}, formats={}",
+        "auto compression: enabled={enabled}, formats={}, compression level={level:?}",
         FORMATS.join(",")
     );
 }
@@ -108,7 +110,7 @@ pub(crate) fn post_process(
     );
 
     // Auto compression based on the `Accept-Encoding` header
-    match auto(req.method(), req.headers(), resp) {
+    match auto(req.method(), req.headers(), opts.compression_level, resp) {
         Ok(resp) => Ok(resp),
         Err(err) => {
             tracing::error!("error during body compression: {:?}", err);
@@ -130,6 +132,7 @@ pub(crate) fn post_process(
 pub fn auto(
     method: &Method,
     headers: &HeaderMap<HeaderValue>,
+    level: CompressionLevel,
     resp: Response<Body>,
 ) -> Result<Response<Body>> {
     // Skip compression for HEAD and OPTIONS request methods
@@ -154,25 +157,25 @@ pub fn auto(
         #[cfg(any(feature = "compression", feature = "compression-gzip"))]
         if encoding == ContentCoding::GZIP {
             let (head, body) = resp.into_parts();
-            return Ok(gzip(head, body.into()));
+            return Ok(gzip(head, body.into(), level));
         }
 
         #[cfg(any(feature = "compression", feature = "compression-deflate"))]
         if encoding == ContentCoding::DEFLATE {
             let (head, body) = resp.into_parts();
-            return Ok(deflate(head, body.into()));
+            return Ok(deflate(head, body.into(), level));
         }
 
         #[cfg(any(feature = "compression", feature = "compression-brotli"))]
         if encoding == ContentCoding::BROTLI {
             let (head, body) = resp.into_parts();
-            return Ok(brotli(head, body.into()));
+            return Ok(brotli(head, body.into(), level));
         }
 
         #[cfg(any(feature = "compression", feature = "compression-zstd"))]
         if encoding == ContentCoding::ZSTD {
             let (head, body) = resp.into_parts();
-            return Ok(zstd(head, body.into()));
+            return Ok(zstd(head, body.into(), level));
         }
 
         tracing::trace!("no compression feature matched the preferred encoding, probably not enabled or unsupported");
@@ -200,10 +203,17 @@ fn is_text(mime: Mime) -> bool {
 pub fn gzip(
     mut head: http::response::Parts,
     body: CompressableBody<Body, hyper::Error>,
+    level: CompressionLevel,
 ) -> Response<Body> {
+    const DEFAULT_COMPRESSION_LEVEL: i32 = 4;
+
     tracing::trace!("compressing response body on the fly using GZIP");
 
-    let body = Body::wrap_stream(ReaderStream::new(GzipEncoder::new(StreamReader::new(body))));
+    let level = level.into_algorithm_level(DEFAULT_COMPRESSION_LEVEL);
+    let body = Body::wrap_stream(ReaderStream::new(GzipEncoder::with_quality(
+        StreamReader::new(body),
+        level,
+    )));
     let header = create_encoding_header(head.headers.remove(CONTENT_ENCODING), ContentCoding::GZIP);
     head.headers.remove(CONTENT_LENGTH);
     head.headers.append(CONTENT_ENCODING, header);
@@ -220,12 +230,17 @@ pub fn gzip(
 pub fn deflate(
     mut head: http::response::Parts,
     body: CompressableBody<Body, hyper::Error>,
+    level: CompressionLevel,
 ) -> Response<Body> {
+    const DEFAULT_COMPRESSION_LEVEL: i32 = 4;
+
     tracing::trace!("compressing response body on the fly using DEFLATE");
 
-    let body = Body::wrap_stream(ReaderStream::new(DeflateEncoder::new(StreamReader::new(
-        body,
-    ))));
+    let level = level.into_algorithm_level(DEFAULT_COMPRESSION_LEVEL);
+    let body = Body::wrap_stream(ReaderStream::new(DeflateEncoder::with_quality(
+        StreamReader::new(body),
+        level,
+    )));
     let header = create_encoding_header(
         head.headers.remove(CONTENT_ENCODING),
         ContentCoding::DEFLATE,
@@ -245,12 +260,17 @@ pub fn deflate(
 pub fn brotli(
     mut head: http::response::Parts,
     body: CompressableBody<Body, hyper::Error>,
+    level: CompressionLevel,
 ) -> Response<Body> {
+    const DEFAULT_COMPRESSION_LEVEL: i32 = 4;
+
     tracing::trace!("compressing response body on the fly using BROTLI");
 
-    let body = Body::wrap_stream(ReaderStream::new(BrotliEncoder::new(StreamReader::new(
-        body,
-    ))));
+    let level = level.into_algorithm_level(DEFAULT_COMPRESSION_LEVEL);
+    let body = Body::wrap_stream(ReaderStream::new(BrotliEncoder::with_quality(
+        StreamReader::new(body),
+        level,
+    )));
     let header =
         create_encoding_header(head.headers.remove(CONTENT_ENCODING), ContentCoding::BROTLI);
     head.headers.remove(CONTENT_LENGTH);
@@ -268,10 +288,17 @@ pub fn brotli(
 pub fn zstd(
     mut head: http::response::Parts,
     body: CompressableBody<Body, hyper::Error>,
+    level: CompressionLevel,
 ) -> Response<Body> {
+    const DEFAULT_COMPRESSION_LEVEL: i32 = 3;
+
     tracing::trace!("compressing response body on the fly using ZSTD");
 
-    let body = Body::wrap_stream(ReaderStream::new(ZstdEncoder::new(StreamReader::new(body))));
+    let level = level.into_algorithm_level(DEFAULT_COMPRESSION_LEVEL);
+    let body = Body::wrap_stream(ReaderStream::new(ZstdEncoder::with_quality(
+        StreamReader::new(body),
+        level,
+    )));
     let header = create_encoding_header(head.headers.remove(CONTENT_ENCODING), ContentCoding::ZSTD);
     head.headers.remove(CONTENT_LENGTH);
     head.headers.append(CONTENT_ENCODING, header);

src/compression.rs

@@ -46,6 +46,15 @@ pub struct RequestHandlerOpts {
     pub root_dir: PathBuf,
     /// Compression feature.
     pub compression: bool,
+    #[cfg(any(
+        feature = "compression",
+        feature = "compression-gzip",
+        feature = "compression-brotli",
+        feature = "compression-zstd",
+        feature = "compression-deflate"
+    ))]
+    /// Compression level.
+    pub compression_level: crate::settings::CompressionLevel,
     /// Compression static feature.
     pub compression_static: bool,
     /// Directory listing feature.
@@ -108,6 +117,14 @@ impl Default for RequestHandlerOpts {
             root_dir: PathBuf::from("./public"),
             compression: true,
             compression_static: false,
+            #[cfg(any(
+                feature = "compression",
+                feature = "compression-gzip",
+                feature = "compression-brotli",
+                feature = "compression-zstd",
+                feature = "compression-deflate"
+            ))]
+            compression_level: crate::settings::CompressionLevel::Default,
             #[cfg(feature = "directory-listing")]
             dir_listing: false,
             #[cfg(feature = "directory-listing")]

src/handler.rs

@@ -317,7 +317,11 @@ impl Server {
             feature = "compression-brotli",
             feature = "compression-zstd",
         ))]
-        compression::init(general.compression, &mut handler_opts);
+        compression::init(
+            general.compression,
+            general.compression_level,
+            &mut handler_opts,
+        );
 
         // Cache control headers option
         control_headers::init(general.cache_control_headers, &mut handler_opts);

src/server.rs

@@ -258,6 +258,28 @@ pub struct General {
     )]
     /// Gzip, Deflate, Brotli or Zstd compression on demand determined by the Accept-Encoding header and applied to text-based web file types only.
     pub compression: bool,
+
+    #[cfg(any(
+        feature = "compression",
+        feature = "compression-gzip",
+        feature = "compression-brotli",
+        feature = "compression-zstd",
+        feature = "compression-deflate"
+    ))]
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(any(
+            feature = "compression",
+            feature = "compression-gzip",
+            feature = "compression-brotli",
+            feature = "compression-zstd",
+            feature = "compression-deflate"
+        )))
+    )]
+    #[arg(long, default_value = "default", env = "SERVER_COMPRESSION_LEVEL")]
+    /// Compression level to apply for Gzip, Deflate, Brotli or Zstd compression.
+    pub compression_level: super::CompressionLevel,
+
     #[cfg(any(
         feature = "compression",
         feature = "compression-gzip",