From 7dda2ea54c43bd2ee5de4f86385df655d179e3eb Mon Sep 17 00:00:00 2001 From: Jose Quintana Date: Tue, 3 May 2022 15:22:12 +0200 Subject: [PATCH] docs: config file and custom http headers [skip ci] --- Cargo.toml | 2 +- LICENSE-MIT | 2 +- README.md | 6 ++++-- docs/content/configuration/command-line-arguments.md | 7 +++++-- docs/content/configuration/config-file.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/content/configuration/environment-variables.md | 3 +++ docs/content/features/custom-http-headers.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/content/getting-started.md | 6 +++--- docs/content/index.md | 4 +++- docs/content/license.md | 2 +- docs/mkdocs.yml | 6 +++++- tests/toml/config.toml | 2 +- 12 files changed, 185 insertions(+), 13 deletions(-) create mode 100644 docs/content/configuration/config-file.md create mode 100644 docs/content/features/custom-http-headers.md diff --git a/Cargo.toml b/Cargo.toml index ede34ef..400d9a1 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "static-web-server" version = "2.7.1" -authors = ["Jose Quintana "] +authors = ["Jose Quintana "] license = "MIT OR Apache-2.0" description = "A blazing fast and asynchronous web server for static files-serving." repository = "https://github.com/joseluisq/static-web-server" diff --git a/LICENSE-MIT b/LICENSE-MIT index 0e60829..5b9c9bb 100644 --- a/LICENSE-MIT +++ b/LICENSE-MIT @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2019-present Jose Quintana +Copyright (c) 2019-present Jose Quintana Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in diff --git a/README.md b/README.md index f78b287..67ee839 100644 --- a/README.md +++ b/README.md @@ -52,8 +52,10 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` - Optional directory listing. - [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) support. - Basic HTTP Authentication. +- Customizable HTTP Response Headers for specific file requests via glob patterns. +- Fallback pages for 404 errors useful for Single-page applications. +- Configurable using CLI arguments, environment variables or a file. - Default and custom error pages. -- Configurable using CLI arguments or environment variables. - First-class [Docker](https://docs.docker.com/get-started/overview/) support. [Scratch](https://hub.docker.com/_/scratch) and latest [Alpine Linux](https://hub.docker.com/_/alpine) Docker images available. - Ability to accept a socket listener as a file descriptor for use in sandboxing and on-demand applications (E.g [systemd](http://0pointer.de/blog/projects/socket-activation.html)). - Cross-platform. Binaries available for Linux, macOS, Windows & FreeBSD x86_64 / ARM. @@ -83,4 +85,4 @@ Feel free to send some [Pull request](https://github.com/joseluisq/static-web-se This work is primarily distributed under the terms of both the [MIT license](LICENSE-MIT) and the [Apache License (Version 2.0)](LICENSE-APACHE). -© 2019-present [Jose Quintana](https://git.io/joseluisq) +© 2019-present [Jose Quintana](https://joseluisq.net) diff --git a/docs/content/configuration/command-line-arguments.md b/docs/content/configuration/command-line-arguments.md index 00c6e3c..e167887 100644 --- a/docs/content/configuration/command-line-arguments.md +++ b/docs/content/configuration/command-line-arguments.md @@ -10,8 +10,8 @@ The server can be configured via the following command-line arguments. ``` $ static-web-server -h -static-web-server 2.7.0 -Jose Quintana +static-web-server 2.8.0 +Jose Quintana A blazing fast and asynchronous web server for static files-serving. USAGE: @@ -31,6 +31,9 @@ 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] + -w, --config-file + Server TOML configuration file path [env: SERVER_CONFIG_FILE=] + -j, --cors-allow-headers Specify an optional CORS list of allowed headers separated by comas. Default "origin, content-type". It requires `--cors-allow-origins` to be used along with [env: SERVER_CORS_ALLOW_HEADERS=] [default: origin, diff --git a/docs/content/configuration/config-file.md b/docs/content/configuration/config-file.md new file mode 100644 index 0000000..9d0a63c --- /dev/null +++ b/docs/content/configuration/config-file.md @@ -0,0 +1,92 @@ +# TOML Configuration File + +**`SWS`** can be configured using a [TOML](https://toml.io/en/) file in order to adjust the general server features as well as other advanced ones. + +It's disabled by default and can be enabled by passing an *string file path* via the `-w, --config-file` option or its equivalent [SERVER_CONFIG_FILE](./../configuration/environment-variables.md#server_config_file) env. + +## TOML File (Manifest) + +Below just an example showing all features with its default values. + +```toml +[general] + +#### Address & Root dir +host = "::" +port = 8087 +root = "docker/public" + +#### Logging +log-level = "trace" + +#### Cache Control headers +cache-control-headers = true + +#### Auto Compression +compression = true + +#### Error pages +page404 = "docker/public/404.html" +page50x = "docker/public/50x.html" + +#### HTTP/2 + TLS +http2 = false +http2-tls-cert = "" +http2-tls-key = "" + +#### Security headers +security-headers = true + +#### CORS +cors-allow-origins = "" +cors-allow-headers = "" + +#### Directoy listing +directory-listing = false +directory-listing-order = 6 + +#### Basich Authentication +basic-auth = "" + +#### File descriptor binding +# fd = "" + +#### Worker threads +threads-multiplier = 1 + +#### Grace period after a graceful shutdown +grace-period = 0 + +#### Page fallback for 404s +page-fallback = "" + + +[advanced] + +#### .... +``` + +### General options + +The TOML `[general]` section allows to adjust the current options actually available via the CLI/ENVs ones. + +So they are equivalent each other **except** the `-w, --config-file` option which is omitted and can not be used for obvious reasons. + +!!! info "Config file based features are optional" + All server feature options via the configuration file are optional and can be omitted as needed. + +### Advanced options + +The TOML `[advanced]` section is intended for more complex features. + +### Precendence + +Whatever config file based feature option will take precedence over its CLI or ENV equivalent. + +## Usage + +The following command runs the server using an specific `config.toml` file. + +```sh +static-web-server -w config.toml +``` diff --git a/docs/content/configuration/environment-variables.md b/docs/content/configuration/environment-variables.md index 07f715a..bab3034 100644 --- a/docs/content/configuration/environment-variables.md +++ b/docs/content/configuration/environment-variables.md @@ -18,6 +18,9 @@ Optional file descriptor number (e.g. `0`) to inherit an already-opened TCP list ### SERVER_ROOT Relative or absolute root directory path of static files. Default `./public`. +### SERVER_CONFIG_FILE +The Server configuration file path in TOML format. See [The TOML Configuration File](../configuration/config-file.md). + ### SERVER_GRACE_PERIOD Defines a grace period in seconds after a `SIGTERM` signal is caught which will delay the server before to shut it down gracefully. The maximum value is `255` seconds. Default value is `0` (no delay). diff --git a/docs/content/features/custom-http-headers.md b/docs/content/features/custom-http-headers.md new file mode 100644 index 0000000..41cf931 --- /dev/null +++ b/docs/content/features/custom-http-headers.md @@ -0,0 +1,66 @@ +# Custom HTTP Headers + +**`SWS`** allows to customize the server [HTTP Response headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) on demand. + +## Structure + +The Server HTTP response headers should be defined mainly as [Array of Tables](https://toml.io/en/v1.0.0#array-of-tables). + +Each table entry should have two key/value pairs: + +- One `source` key containing an string *glob pattern*. +- One `headers` key containing a [set or hash table](https://toml.io/en/v1.0.0#table) describing plain HTTP headers to apply. + +A particular set of HTTP headers can only be applied when a `source` matches against the request uri. + +!!! info "Custom HTTP headers take precedence over existing ones" + Whatever custom HTTP header could **replace** an existing one if it was previously defined (E.g server default headers) and matches its `source`. + + The headers order is important since it determine its precedence. + + **Example:** if the feature `--cache-control-headers=true` is enabled but also a custom `cache-control` header was defined then the custom header will have priority. + +### Source + +Source is a [Glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) that should match against the uri that is requesting a resource file. + +### Headers + +A set of valid plain [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) to be applied. + +## Examples + +Below some examples of how to customize server HTTP headers in three variants. + +### Oneline version + +```toml +[advanced] + +[[advanced.headers]] +source = "**/*.{js,css}" +headers = { Access-Control-Allow-Origin = "*", X-XSS-PROTECTION = "1; mode=block" } +``` + +### Multiline version + +```toml +[advanced] + +[[advanced.headers]] +source = "*.html" +[advanced.headers.headers] +Cache-Control = "public, max-age=36000" +Content-Security-Policy = "frame-ancestors 'self'" +Strict-Transport-Security = "max-age=63072000; includeSubDomains; preload" +``` + +### Multiline version with explicit header key (dotted) + +```toml +[advanced] + +[[advanced.headers]] +source = "**/*.{jpg,jpeg,png,ico,gif}" +headers.Strict-Transport-Security = "max-age=63072000; includeSubDomains; preload" +``` diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md index a6ac352..e9b125b 100644 --- a/docs/content/getting-started.md +++ b/docs/content/getting-started.md @@ -15,6 +15,6 @@ docker run --rm -it -p 8787:80 joseluisq/static-web-server:2 !!! info "Docker Tip" You can specify a Docker volume like `-v $HOME/my-public-dir:/public` in order to overwrite the default root directory. See [Docker examples](features/docker.md). -To see the available options type `static-web-server -h` or go to the [Command-line arguments](./configuration/command-line-arguments.md) section. - -Or if you are looking for more advanced examples then have a look at [the features](./features/http1.md) section. +- Type `static-web-server --help` or go to the [Command-line arguments](./configuration/command-line-arguments.md) section. +- See how to configure the server using a [configuration file](configuration/config-file.md). +- Have also a look at [the features](./features/http1.md) section for more advanced examples. diff --git a/docs/content/index.md b/docs/content/index.md index 4d34f64..96e4138 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -56,8 +56,10 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` - Optional directory listing. - [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) support. - Basic HTTP Authentication. +- Customizable HTTP Response Headers for specific file requests via glob patterns. +- Fallback pages for 404 errors useful for Single-page applications. +- Configurable using CLI arguments, environment variables or a file. - Default and custom error pages. -- Configurable using CLI arguments or environment variables. - First-class [Docker](https://docs.docker.com/get-started/overview/) support. [Scratch](https://hub.docker.com/_/scratch) and latest [Alpine Linux](https://hub.docker.com/_/alpine) Docker images available. - Ability to accept a socket listener as a file descriptor for use in sandboxing and on-demand applications (E.g [systemd](http://0pointer.de/blog/projects/socket-activation.html)). - Cross-platform. Binaries available for Linux, macOS, Windows & FreeBSD x86_64 / ARM. diff --git a/docs/content/license.md b/docs/content/license.md index cb90e83..298f1e3 100644 --- a/docs/content/license.md +++ b/docs/content/license.md @@ -2,4 +2,4 @@ This work is primarily distributed under the terms of both the [MIT license](https://github.com/joseluisq/static-web-server/blob/master/LICENSE-MIT) and the [Apache License (Version 2.0)](https://github.com/joseluisq/static-web-server/blob/master/LICENSE-APACHE). -© 2019-present [Jose Quintana](https://git.io/joseluisq) +© 2019-present [Jose Quintana](https://github.com/joseluisq) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 9b74b66..898d8f5 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -28,7 +28,7 @@ theme: - content.code.annotate - content.tabs.link - header.autohide - - navigation.expand + # - navigation.expand - navigation.indexes # - navigation.instant # - navigation.sections @@ -103,6 +103,8 @@ markdown_extensions: - pymdownx.highlight: linenums: true linenums_style: pymdownx-inline + - pymdownx.tabbed: + alternate_style: true # Plugins plugins: @@ -118,6 +120,7 @@ nav: - 'Configuration': - 'Command Line Arguments': 'configuration/command-line-arguments.md' - 'Environment Variables': 'configuration/environment-variables.md' + - 'TOML Configuration File': 'configuration/config-file.md' - 'Building from Source': 'building-from-source.md' - 'Features': - 'HTTP/1': 'features/http1.md' @@ -135,6 +138,7 @@ nav: - 'File Descriptor Socket Passing': './features/file-descriptor-socket-passing.md' - 'Worker Threads Customization': 'features/worker-threads.md' - 'Error Pages': 'features/error-pages.md' + - 'Custom HTTP Headers': 'features/custom-http-headers.md' - 'Platforms & Architectures': 'platforms-architectures.md' - 'Migration from v1 to v2': 'migration.md' - 'Changelog v2 (latest stable)': 'https://github.com/joseluisq/static-web-server/blob/master/CHANGELOG.md' diff --git a/tests/toml/config.toml b/tests/toml/config.toml index 5416e22..51de796 100644 --- a/tests/toml/config.toml +++ b/tests/toml/config.toml @@ -56,7 +56,7 @@ headers = { Access-Control-Allow-Origin = "*", X-XSS-PROTECTION = "1; mode=block # #### b. Multiline version [[advanced.headers]] -source = "*.html" +source = "index.html" [advanced.headers.headers] Cache-Control = "public, max-age=36000" Content-Security-Policy = "frame-ancestors 'self'" -- libgit2 1.7.2