docs: config file and custom http headers [skip ci]

Cargo.toml

@@ -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"

LICENSE-MIT

@@ -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

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)

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 <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,

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
+```

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).
 

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"
+```

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.

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.

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)

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'

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'"