docs: config file and custom http headers [skip ci]
Diff
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(-)
@@ -1,7 +1,7 @@
[package]
name = "static-web-server"
version = "2.7.1"
authors = ["Jose Quintana <https://git.io/joseluisq>"]
authors = ["Jose Quintana <https://joseluisq.net>"]
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"
@@ -1,6 +1,6 @@
The MIT License (MIT)
Copyright (c) 2019-present Jose Quintana <https://git.io/joseluisq>
Copyright (c) 2019-present Jose Quintana <https://joseluisq.net>
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
@@ -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)
@@ -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 <https://git.io/joseluisq>
static-web-server 2.8.0
Jose Quintana <https://joseluisq.net>
A blazing fast and asynchronous web server for static files-serving.
USAGE:
@@ -31,6 +31,9 @@ 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]
-w, --config-file <config-file>
Server TOML configuration file path [env: SERVER_CONFIG_FILE=]
-j, --cors-allow-headers <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,
@@ -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
```
@@ -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).
@@ -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"
```
@@ -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.
@@ -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.
@@ -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)
@@ -28,7 +28,7 @@ theme:
- content.code.annotate
- content.tabs.link
- header.autohide
- navigation.expand
- navigation.indexes
@@ -103,6 +103,8 @@ markdown_extensions:
- pymdownx.highlight:
linenums: true
linenums_style: pymdownx-inline
- pymdownx.tabbed:
alternate_style: true
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'
@@ -56,7 +56,7 @@ headers = { Access-Control-Allow-Origin = "*", X-XSS-PROTECTION = "1; mode=block
[[advanced.headers]]
source = "*.html"
source = "index.html"
[advanced.headers.headers]
Cache-Control = "public, max-age=36000"
Content-Security-Policy = "frame-ancestors 'self'"
