docs: documentation completed [skip ci]
Diff
docs/content/configuration/command-line-arguments.md | 6 +--
docs/content/configuration/environment-variables.md | 12 ++---
docs/content/contributions.md | 2 +-
docs/content/examples/basic-authentication.md | 26 +++++++----
docs/content/examples/cache-control-headers.md | 41 +++++++++++++++++-
docs/content/examples/compression.md | 43 ++++++++++++++++++-
docs/content/examples/cors.md | 20 ++++++++-
docs/content/examples/directory-listing.md | 15 ++++++-
docs/content/examples/docker.md | 2 +-
docs/content/examples/error-pages.md | 18 ++++++++-
docs/content/examples/file-descriptor-socket-passing.md | 16 ++++++-
docs/content/examples/http1.md | 13 +++++-
docs/content/examples/http2-tls.md | 21 ++++++++-
docs/content/examples/logging.md | 13 +++++-
docs/content/examples/security-headers.md | 17 +++++++-
docs/content/examples/worker-threads.md | 35 +++++++++++++++-
docs/content/getting-started.md | 4 +-
docs/content/index.md | 6 +--
docs/content/migration.md | 1 +-
docs/content/platforms-architectures.md | 2 +-
docs/content/semantic-versioning.md | 10 ++++-
docs/mkdocs.yml | 13 +++--
22 files changed, 305 insertions(+), 31 deletions(-)
@@ -1,10 +1,10 @@
# Command-Line Arguments
Server can be configured via the following command-line arguments.
The server can be configured via the following command-line arguments.
!!! tip "Remember"
- Command-line arguments are equivalent to their environment variables.
- Command-line arguments take precedence over their [environment variables](./environment-variables.md).
- Command-line arguments are equivalent to their [environment variables](./environment-variables.md).
- Command-line arguments take precedence over their equivalent environment variables.
```
@@ -1,10 +1,10 @@
# Environment Variables
Server can be configured via the following environment variables arguments.
The server can be configured via the following environment variables.
!!! tip "Remember"
- Environment variables are equivalent to their command-line arguments.
- [Command line arguments](./command-line-arguments.md) take precedence over their environment variables.
- [Command line arguments](./command-line-arguments.md) take precedence over their equivalent environment variables.
### SERVER_HOST
The address of the host (E.g 127.0.0.1). Default `[::]`.
@@ -13,7 +13,7 @@ The address of the host (E.g 127.0.0.1). Default `[::]`.
The port of the host. Default `80`.
### SERVER_LISTEN_FD
Optional file descriptor number (e.g. `0`) to inherit an already-opened TCP listener on (instead of using `SERVER_HOST` and/or `SERVER_PORT`).
Optional file descriptor number (e.g. `0`) to inherit an already-opened TCP listener on (instead of using `SERVER_HOST` and/or `SERVER_PORT`). Default empty (disabled).
### SERVER_ROOT
Relative or absolute root directory path of static files. Default `./public`.
@@ -34,16 +34,16 @@ Number of worker threads multiplier that'll be multiplied by the number of syste
Enable HTTP/2 with TLS support. Make sure also to adjust current server port. Default `false` (disabled).
### SERVER_HTTP2_TLS_CERT
Specify the file path to read the certificate. Default empty.
Specify the file path to read the certificate. Default empty (disabled).
### SERVER_HTTP2_TLS_KEY
Specify the file path to read the private key. Default empty.
Specify the file path to read the private key. Default empty (disabled).
### SERVER_CORS_ALLOW_ORIGINS
Specify a optional CORS list of allowed origin hosts separated by comas. Host ports or protocols aren't being checked. Use an asterisk (*) to allow any host. Default empty (disabled).
### 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).
`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_DIRECTORY_LISTING
Enable directory listing for all requests ending with the slash character (‘/’). Default `false` (disabled).
@@ -1,5 +1,5 @@
# Contributions
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in current work by you, as defined in the Apache-2.0 license, shall be dual licensed as described below, without any additional terms or conditions.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in current work by you, as defined in the [Apache License (Version 2.0)](https://github.com/joseluisq/static-web-server/blob/master/LICENSE-APACHE) license, shall be dual licensed as described below, without any additional terms or conditions.
Feel free to send some [Pull request](https://github.com/joseluisq/static-web-server/pulls) or file an [issue](https://github.com/joseluisq/static-web-server/issues).
@@ -1,6 +1,15 @@
# Basic HTTP Authentication
Create "user-id:password" pairs using your favourite tool.
**`SWS`** provides "Basic" HTTP Authentication Scheme using a `user-id/password` pairs encoded with `Base64`.
This feature is disabled by default and can be controlled by the string `--basic-auth` option or the equivalent [SERVER_BASIC_AUTH](./../configuration/environment-variables.md#server_basic_auth) env.
First, create a `user-id/password` pair using your favourite tool.
!!! info "Note"
Only the password must be encoded using the [`BCrypt`](https://en.wikipedia.org/wiki/Bcrypt) password-hashing function.
In this example we are using the Apache [`htpasswd`](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) tool.
```sh
htpasswd -nbBC5 "username" "password"
@@ -8,16 +17,17 @@ htpasswd -nbBC5 "username" "password"
```
!!! tip "Tip"
Speed of the password verification depends on the computing time cost of `bcrypt` algorithm used.
For example the `htpasswd` tool supports a `-C` argument in order to set the `bcrypt`'s computing time (higher is more secure but slower, default: 5, valid: 4 to 17).
The password verification happens at runtime but its verification speed depends on the computing time cost of `bcrypt` algorithm used.
For example the `htpasswd` tool supports a `-C` argument in order to adjust the `bcrypt`'s computing time.
Using a higher value is more secure but slower. The default values is `5` and the possible values are ranging from `4` to `17`.
Finally assign the credentails and run the server.
```sh
static-web-server
--port 8787
--root ./my-public-dir
--basic-auth='username:$2y$05$KYOM0uaMQnEknnu/ckcCuuFyNQbc8BJEUk5X.ixtoCQpjXsc4geHK'
static-web-server \
--port 8787 \
--root ./my-public-dir \
--basic-auth 'username:$2y$05$KYOM0uaMQnEknnu/ckcCuuFyNQbc8BJEUk5X.ixtoCQpjXsc4geHK'
```
@@ -0,0 +1,41 @@
# Cache Control Headers
**`SWS`** provides support for [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) HTTP header specifying a `public` and `max-age` response directives.
This feature is enabled by default and can be controlled by the boolean `-e, --cache-control-headers` option or the equivalent [SERVER_CACHE_CONTROL_HEADERS](./../configuration/environment-variables.md#server_cache_control_headers) env.
## Cache-Control Max-Age
Control headers are applied only to the following file types with the corresponding `max-age` values.
### One day
A `max-age` of *one day* duration is used by default.
!!! info "Note"
One day `max-age` for example includes `html` and other file types.
### One hour
A `max-age` of *one hour* is applied only to the following file types.
```txt
atom, json, rss, xml
```
### One year
A `max-age` of *one year* is applied only to the following file types.
```txt
bmp, bz2, css, doc, gif, gz, htc, ico, jpeg, jpg, js, map, mjs, mp3, mp4, ogg, ogv, pdf, png, rar, rtf, tar, tgz, wav, weba, webm, webp, woff, woff2, zip
```
Below an example of how to enable the feature.
```sh
static-web-server \
--port 8787 \
--root ./my-public-dir \
--cache-control-headers true
```
@@ -1 +1,44 @@
# Compression
**`SWS`** provides [`Gzip`](https://datatracker.ietf.org/doc/html/rfc1952), [`Deflate`](https://datatracker.ietf.org/doc/html/rfc1951#section-Abstract) and [`Brotli`](https://www.ietf.org/rfc/rfc7932.txt) compression of HTTP responses.
The compression functionality is determined by the [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header and is only applied to text-based web file types only.
## MIME types compressed
Only this list of common text-based MIME type files will be compressed either with `Gzip`, `Deflate` or `Brotli` via the `Accept-Encoding` header value.
```txt
text/html
text/css
text/javascript
text/xml
text/plain
text/csv
text/calendar
text/markdown
text/x-yaml
text/x-toml
text/x-component
application/rtf
application/xhtml+xml
application/javascript
application/x-javascript
application/json
application/xml
application/rss+xml
application/atom+xml
application/vnd.ms-fontobject
font/truetype
font/opentype
image/svg+xml
```
This feature is enabled by default and can be controlled by the boolean `-x, --compression` option or the equivalent [SERVER_COMPRESSION](./../configuration/environment-variables.md#server_compression) env.
```sh
static-web-server \
--port 8787 \
--root ./my-public-dir \
--compression true
```
@@ -0,0 +1,20 @@
# CORS
**`SWS`** provides optional [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) support.
A list of allowed origin hosts (URLs) should be specified and separated by comas.
Or an asterisk (*) can be used in order to allow any host.
This feature is disabled by default and can be controlled by the string `-c, --cors-allow-origins` option or the equivalent [SERVER_CORS_ALLOW_ORIGINS](./../configuration/environment-variables.md#server_cors_allow_origins) env.
Below an example of how to enable CORS.
```sh
static-web-server \
--port 8787 \
--root ./my-public-dir \
--cors-allow-origins "https://domain.com"
# Or use an asterisk to allow any host
# --cors-allow-origins "*"
```
@@ -1 +1,16 @@
# Directory Listing
**`SWS`** provides a directory listing feature to display content of directories.
This feature is disabled by default and can be controlled by the boolean `-z, --directory-listing` option or the equivalent [SERVER_DIRECTORY_LISTING](./../configuration/environment-variables.md#server_directory_listing) env.
```sh
static-web-server \
--port 8787 \
--root ./my-public-dir \
--directory-listing true
```
And here an example of how the directory listing looks like.
<img title="SWS - Directory Listing" src="https://user-images.githubusercontent.com/1700322/118666481-81f22c80-b7f3-11eb-8c10-d530304e0e34.png" width="400">
@@ -24,7 +24,7 @@ FROM joseluisq/static-web-server:2-alpine
## Docker Compose
Below a [Docker Compose](https://docs.docker.com/compose/) example using the [Traefik Proxy](https://traefik.io/).
Below a [Docker Compose](https://docs.docker.com/compose/) example using the [Traefik Proxy](https://traefik.io/traefik/).
```yaml
version: "3.3"
@@ -0,0 +1,18 @@
# Error Pages
**`SWS`** provides custom HTML error pages for the HTTP `404` and `50x` status errors.
This feature is enabled by default and can be controlled either by the string `--page404` ([SERVER_ERROR_PAGE_404](./../configuration/environment-variables.md#server_error_page_404)) or the `--page50x` ([SERVER_ERROR_PAGE_50X](./../configuration/environment-variables.md#server_error_page_50x)) arguments.
!!! info "Tip"
Note that either `--page404` and `--page50x` have defaults (optional values) so they can be specified or omitted as required.
Below an example of how to customize those HTLM pages.
```sh
static-web-server \
--port 8787 \
--root ./my-public-dir \
--page404 ./my-page-404.html \
--page50x ./my-page-50x.html
```
@@ -1,11 +1,23 @@
# File Descriptor Socket Passing
A **systemd** unit files example for [socket activation](http://0pointer.de/blog/projects/socket-activation.html) can be found under the [`systemd/`](https://github.com/joseluisq/static-web-server/tree/master/systemd) directory of the Git repository.
**SWS** provides the ability to accept a socket listener as a file descriptor for use in sandboxing and on-demand applications via `systemd` (Linux), `launchd` (Macos) or similar.
!!! tip "Tip"
The [Socket Activation](http://0pointer.de/blog/projects/socket-activation.html) model is basically an alternative to TCP port binding.
Socket activation is supported by the `-f, --fd` option or the equivalent [SERVER_LISTEN_FD](./../configuration/environment-variables.md#server_listen_fd) env.
If you are using `inetd`, its "`wait`" option should be used in conjunction with static-web-server's `--fd 0`
option.
## Systemd
If you're using `systemd` on Linux, there is a fully working example in the SWS Git repository under the [.`/systemd`](https://github.com/joseluisq/static-web-server/tree/master/systemd) directory.
## Testing
Alternatively, the light-weight [`systemfd`](https://github.com/mitsuhiko/systemfd) utility may be
useful. Especially for testing.
useful especially for testing purposes.
For example using `systemfd` utility as follow:
@@ -1,2 +1,15 @@
# HTTP/1
The HTTP/1 is the protocol by default and can be used specifying a host address via the `-a, --host` ([SERVER_HOST](./../configuration/environment-variables.md#server_host)) argument, the host port via `-p, --port` ([SERVER_PORT](./../configuration/environment-variables.md#server_port)) and the directory of the static files via `-d, --root` ([SERVER_ROOT](./../configuration/environment-variables.md#server_root)) argument.
!!! info "Tip"
Note that either `--host`, `--port` and `--root` have defaults (optional values) so they can be specified or omitted as required.
Below an example of how to run the server using HTTP/1.
```sh
static-web-server \
--host 127.0.0.1 \
--port 8787 \
--root ./my-public-dir
```
@@ -1 +1,20 @@
# HTTP/2 TLS
# HTTP/2 and TLS
**`SWS`** provides [HTTP/2](https://en.wikipedia.org/wiki/HTTP/2) protocol and [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) support.
This feature is disabled by default and can be activated via the boolean `-t, --http2` option as well as string arguments `--http2-tls-cert` (TLS certificate file path) and `--http2-tls-key` (private key file path).
!!! tip "Tips"
- Either `--host`, `--port` and `--root` have defaults (optional values) so they can be specified or omitted as required.
- Don't forget to adjust the proper `--port` value for the HTTP/2 & TLS feature.
- When this feature is enabled via `--http2=true` then the [security headers](./security-headers.md) are also enabled automatically.
```sh
static-web-server \
--host 127.0.0.1 \
--port 8787 \
--root ./my-public-dir \
--http2 true \
--http2-tls-cert ./my-tls.cert \
--http2-tls-key ./my-tls.key
```
@@ -1 +1,14 @@
# Logging
**`SWS`** provides logging support just specifying a log level in lower case. The values allowed are `error`, `warn`, `info`, `debug` and `trace`. The default value is `error`.
This feature is enabled by default and can be controlled by the string `-g, --log-level` option or the equivalent [SERVER_LOG_LEVEL](./../configuration/environment-variables.md#server_log_level) env.
Below an example of how to adjust the log level.
```sh
static-web-server \
--port 8787 \
--root ./my-public-dir \
--log-level "trace"
```
@@ -0,0 +1,17 @@
# Security Headers
**`SWS`** provides several [security headers](https://web.dev/security-headers/) support.
When the [HTTP/2](../examples/http2-tls.md) feature is activated *security headers* is enabled automatically.
This feature is disabled by default on HTTP/1 and can be controlled by the boolean `--security-headers` option or the equivalent [SERVER_SECURITY_HEADERS](./../configuration/environment-variables.md#server_security_headers) env.
## Headers included
The following headers are only included.
- `Strict-Transport-Security: max-age=63072000; includeSubDomains; preload" (2 years max-age)`
- `X-Frame-Options: DENY`
- `X-XSS-Protection: 1; mode=block`
- `X-Content-Type-Options: nosniff`
- `Content-Security-Policy: frame-ancestors`
@@ -0,0 +1,35 @@
# Worker Threads Customization
**`SWS`** allows to customize the number of worker threads powered by the [Tokio](https://tokio.rs/) runtime.
This feature can be controlled by the numeric `-n, --threads-multiplier` option or the equivalent [SERVER_THREADS_MULTIPLIER](./../configuration/environment-variables.md#server_threads_multiplier) env.
## Worker threads multiplier
The value of `-n, --threads-multiplier` works as multiplier digits in order to determine the number of worker threads used by the server.
Basically multipling this input number by the number of system CPUs.
The formula used is the following:
> worker threads = number of CPUs * n
*Where `n` is the input value of `-n, --threads-multiplier`.*
**For example:** If there are `4` available CPUs and the `--threads-multiplier` is `8` then the total of *worker threads* to use will be `32`.
!!! Info "Info"
When the `--threads-multiplier` input value is `0` or `1` then one thread per core is used (default value).
!!! warn "Warn"
Number of worker threads result should be a number between `1` and `32,768` though it is advised to keep this value on the smaller side. See [Tokio ` worker_threads` API](https://docs.rs/tokio/1.12.0/tokio/runtime/struct.Builder.html#method.worker_threads) for more details.
Below an example of how to adjust the number of worker threads.
```sh
static-web-server \
--port 8787 \
--root ./my-public-dir \
# NOTE: "8" gets multiplied by the number of the available cores.
--threads-multiplier 8
```
@@ -8,6 +8,6 @@ Then just type the following command.
static-web-server --port 8787 --root ./my-public-dir
```
For details about the avilable options type `static-web-server -h` or go [Command-line arguments](./configuration/command-line-arguments.md) section.
For details about the available options type `static-web-server -h` or go to the [Command-line arguments](./configuration/command-line-arguments.md) section.
If you want more advanced examples, take a look at [the examples](./examples/http1.md) section.
Or if you are looking fo more advanced examples, take a look at [the examples](./examples/http1.md) section.
@@ -22,15 +22,15 @@
## Overview
**Static Web Server** (or `SWS` abbreviated) is a very small and fast production-ready web server suitable to serve static web files or assets.
**Static Web Server** (or **`SWS`** abbreviated) is a very small and fast production-ready web server suitable to serve static web files or assets.
It is focused on **lightness and easy to use** principles but keeping [high performance and safety](https://blog.rust-lang.org/2015/04/10/Fearless-Concurrency.html) powered by [The Rust Programming Language](https://rust-lang.org).
Written on top of [Hyper](https://github.com/hyperium/hyper) and [Tokio](https://github.com/tokio-rs/tokio) runtime. It provides [concurrent and asynchronous networking abilities](https://rust-lang.github.io/async-book/01_getting_started/02_why_async.html) as well as the latest HTTP/1 - HTTP/2 implementations.
It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` (`x86`/`x86_64` and `ARM`/`ARM64`) as well as `Docker`.
It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` (`x86`/`x86_64`, `ARM`/`ARM64`) as well as `Docker`.
!!! tip "Tip"
!!! tip "Tips"
- If you're looking for `v1` please go to [1.x](https://github.com/joseluisq/static-web-server/tree/1.x) branch.
- If you want to migrate from `v1` to `v2` please take a look at [v2.0.0](https://github.com/joseluisq/static-web-server/releases/tag/v2.0.0) release.
@@ -0,0 +1 @@
# Migration
@@ -1,6 +1,6 @@
# Platforms & Architectures
Currently only the following platforms and architectures are supported.
Currently only the following platforms/architectures are supported.
## Linux
@@ -0,0 +1,10 @@
# Semantic Versioning
**`SWS`** project adheres to [Semantic Versioning](https://semver.org/) for every release like [`v1`](./changelog-v1.md) and latest [`v2`](./changelog-v2.md).
## Breaking changes
Only switches between ***major*** versions "could" contain *breaking changes* or not depending on the particular case.<br>
However this project try to keep away of any kind of *breaking change* as possible between ***major*** versions. But it still supports and prioritizes ***"no breaking changes"*** for ***minor*** and ***patch*** (bug fixes) versions.
In the other hand, if a *breaking change* is found to be *"strictly necessary"* to do. Then a new ***major*** version must be promoted as well as users informed accordingly in order they can do a seamlessly transition.
@@ -2,13 +2,13 @@
site_name: Static Web Server
site_description: 'A blazing fast and asynchronous web server for static files-serving ⚡'
site_author: 'Jose Quintana'
site_url: https://joseluisq.github.io/static-web-server/
dev_addr: 127.0.0.1:8000
site_url: https://sws.joseluisq.net
dev_addr: 0.0.0.0:8000
repo_name: joseluisq/static-web-server
repo_url: https://github.com/joseluisq/static-web-server/
edit_uri: edit/feature/website/docs/
edit_uri: edit/master/docs/
docs_dir: 'content'
@@ -120,12 +120,19 @@ nav:
- 'HTTP/2 and TLS': 'examples/http2-tls.md'
- 'Logging': 'examples/logging.md'
- 'Compression': 'examples/compression.md'
- 'Cache Control Headers': 'examples/cache-control-headers.md'
- 'CORS': 'examples/cors.md'
- 'Security Headers': 'examples/security-headers.md'
- 'Basic Authentication': 'examples/basic-authentication.md'
- 'Directory Listing': 'examples/directory-listing.md'
- 'Docker': 'examples/docker.md'
- 'File Descriptor Socket Passing': './examples/file-descriptor-socket-passing.md'
- 'Worker Threads Customization': 'examples/worker-threads.md'
- 'Error Pages': 'examples/error-pages.md'
- 'Platforms & Architectures': 'platforms-architectures.md'
- 'Changelog v2': 'changelog-v2.md'
- 'Migration': 'migration.md'
- 'Changelog v1': 'changelog-v1.md'
- 'Semantic Versioning': 'semantic-versioning.md'
- 'Contributions': 'contributions.md'
- 'License': 'license.md'
