docs: pre-compressed files serving feature [skip ci]
Diff
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(-)
@@ -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 <https://joseluisq.net>
A blazing fast and asynchronous web server for static files-serving.
@@ -31,6 +31,10 @@ OPTIONS:
-x, --compression <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 <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 <config-file>
Server TOML configuration file path [env: SERVER_CONFIG_FILE=]
@@ -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).
@@ -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
```
@@ -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'
@@ -122,8 +122,8 @@ pub struct General {
default_value = "false",
env = "SERVER_COMPRESSION_STATIC"
)]
pub compression_static: bool,
#[structopt(
