From 3ca743a7b5a0133404f09d18d3a94f4d11046474 Mon Sep 17 00:00:00 2001 From: Jose Quintana Date: Sun, 25 Sep 2022 00:11:29 +0200 Subject: [PATCH] docs: pre-compressed files serving feature [skip ci] --- docs/content/configuration/command-line-arguments.md | 6 +++++- docs/content/configuration/environment-variables.md | 3 +++ docs/content/features/compression-static.md | 37 +++++++++++++++++++++++++++++++++++++ docs/mkdocs.yml | 1 + src/settings/cli.rs | 4 ++-- 5 files changed, 48 insertions(+), 3 deletions(-) create mode 100644 docs/content/features/compression-static.md diff --git a/docs/content/configuration/command-line-arguments.md b/docs/content/configuration/command-line-arguments.md index 2ed7f2a..30f8cf2 100644 --- a/docs/content/configuration/command-line-arguments.md +++ b/docs/content/configuration/command-line-arguments.md @@ -10,7 +10,7 @@ The server can be configured via the following command-line arguments. ``` $ static-web-server -h -static-web-server 2.11.0 +static-web-server 2.12.0 Jose Quintana A blazing fast and asynchronous web server for static files-serving. @@ -31,6 +31,10 @@ OPTIONS: -x, --compression Gzip, Deflate or Brotli compression on demand determined by the Accept-Encoding header and applied to text- based web file types only [env: SERVER_COMPRESSION=] [default: true] + --compression-static + Look up the pre-compressed file variant (`.gz` or `.br`) on disk of a requested file and serves it directly + if available. The compression type is determined by the `Accept-Encoding` header [env: + SERVER_COMPRESSION_STATIC=] [default: false] -w, --config-file Server TOML configuration file path [env: SERVER_CONFIG_FILE=] diff --git a/docs/content/configuration/environment-variables.md b/docs/content/configuration/environment-variables.md index d081ed1..7ee5bdc 100644 --- a/docs/content/configuration/environment-variables.md +++ b/docs/content/configuration/environment-variables.md @@ -60,6 +60,9 @@ Specify an optional CORS list of allowed HTTP headers separated by commas. It re ### 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/joseluisq/static-web-server/blob/master/src/compression.rs#L20). Default `true` (enabled). +### 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. + ### SERVER_DIRECTORY_LISTING Enable directory listing for all requests ending with the slash character (‘/’). Default `false` (disabled). diff --git a/docs/content/features/compression-static.md b/docs/content/features/compression-static.md new file mode 100644 index 0000000..5754bac --- /dev/null +++ b/docs/content/features/compression-static.md @@ -0,0 +1,37 @@ +# Pre-compressed files serving + +**`SWS`** provides support to serve pre-compressed [`Gzip`](https://datatracker.ietf.org/doc/html/rfc1952) or [`Brotli`](https://www.ietf.org/rfc/rfc7932.txt) files directly from the disk. + +SWS can look up existing pre-compressed file variants (`.gz` or `.br`) on disk and serve them directly. + +The feature is disabled by default and can be controlled by the boolean `--compression-static` option or the equivalent [SERVER_COMPRESSION_STATIC](./../configuration/environment-variables.md#server_compression_static) env. + +When the `compression-static` option is enabled and the pre-compressed file is found on the file system then it's served directly. +Otherwise, if the pre-compressed file is not found then SWS just continues the normal workflow (trying to serve the original file requested instead). Additionally, if for example the [compression](../features/compression.md) option was also enabled then the requested file can be compressed on the fly right after. + +!!! info "Compressed file type" + The pre-compressed file type is determined by the [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header value. + +Here is an example: + + +```sh +static-web-server -p=8787 -d=/var/www --compression-static=true -g=trace +``` + +Below are some relevant log entries to show how the feature works. + +```log +2022-09-22T21:30:12.904102Z INFO static_web_server::handler: incoming request: method=GET uri=/downloads/Capture5.png +2022-09-22T21:30:12.904218Z TRACE static_web_server::static_files: dir: base="/var/www", route="downloads/Capture5.png" +2022-09-22T21:30:12.904295Z TRACE static_web_server::compression_static: preparing pre-compressed file path variant of /var/www/downloads/Capture5.png +2022-09-22T21:30:12.904509Z TRACE static_web_server::compression_static: getting metadata for pre-compressed file variant /var/www/downloads/Capture5.png.gz +2022-09-22T21:30:12.904746Z TRACE hyper::proto::h1::conn: flushed({role=server}): State { reading: KeepAlive, writing: Init, keep_alive: Busy } +2022-09-22T21:30:12.904932Z TRACE static_web_server::static_files: file found: "/var/www/downloads/Capture5.png.gz" +2022-09-22T21:30:12.904983Z TRACE static_web_server::compression_static: pre-compressed file variant found, serving it directly +2022-09-22T21:30:12.905095Z TRACE hyper::proto::h1::conn: flushed({role=server}): State { reading: KeepAlive, writing: Init, keep_alive: Busy } +2022-09-22T21:30:12.905836Z TRACE encode_headers: hyper::proto::h1::role: Server::encode status=200, body=Some(Unknown), req_method=Some(GET) +2022-09-22T21:30:12.905965Z TRACE encode_headers: hyper::proto::h1::role: close time.busy=138µs time.idle=35.4µs +2022-09-22T21:30:12.906236Z DEBUG hyper::proto::h1::io: flushed 242 bytes +``` + diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 924b2a9..e788a75 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -128,6 +128,7 @@ nav: - 'HTTP/2 and TLS': 'features/http2-tls.md' - 'Logging': 'features/logging.md' - 'Compression': 'features/compression.md' + - 'Pre-compressed files serving': 'features/compression-static.md' - 'Cache Control Headers': 'features/cache-control-headers.md' - 'CORS': 'features/cors.md' - 'Security Headers': 'features/security-headers.md' diff --git a/src/settings/cli.rs b/src/settings/cli.rs index 543ff47..5fb712d 100644 --- a/src/settings/cli.rs +++ b/src/settings/cli.rs @@ -122,8 +122,8 @@ pub struct General { default_value = "false", env = "SERVER_COMPRESSION_STATIC" )] - /// Check for a pre-compressed file on disk and serve it if available. - /// The order of precedence is determined by the `Accept-Encoding` header. + /// Look up the pre-compressed file variant (`.gz` or `.br`) on disk of a requested file and serves it directly if available. + /// The compression type is determined by the `Accept-Encoding` header. pub compression_static: bool, #[structopt( -- libgit2 1.7.2