From c1269d759b57b74acf2bef5c190e2a11659ca17e Mon Sep 17 00:00:00 2001 From: Jose Quintana Date: Thu, 28 Oct 2021 00:48:28 +0200 Subject: [PATCH] docs: documentation completed [skip ci] --- 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(-) create mode 100644 docs/content/examples/cache-control-headers.md create mode 100644 docs/content/examples/cors.md create mode 100644 docs/content/examples/error-pages.md create mode 100644 docs/content/examples/security-headers.md create mode 100644 docs/content/examples/worker-threads.md create mode 100644 docs/content/migration.md create mode 100644 docs/content/semantic-versioning.md diff --git a/docs/content/configuration/command-line-arguments.md b/docs/content/configuration/command-line-arguments.md index 304bc9f..3815b2b 100644 --- a/docs/content/configuration/command-line-arguments.md +++ b/docs/content/configuration/command-line-arguments.md @@ -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. ``` diff --git a/docs/content/configuration/environment-variables.md b/docs/content/configuration/environment-variables.md index bb8d75b..5e1b62d 100644 --- a/docs/content/configuration/environment-variables.md +++ b/docs/content/configuration/environment-variables.md @@ -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). diff --git a/docs/content/contributions.md b/docs/content/contributions.md index 2fd3681..e019eb5 100644 --- a/docs/content/contributions.md +++ b/docs/content/contributions.md @@ -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). diff --git a/docs/content/examples/basic-authentication.md b/docs/content/examples/basic-authentication.md index 77e9d63..e103e2e 100644 --- a/docs/content/examples/basic-authentication.md +++ b/docs/content/examples/basic-authentication.md @@ -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' ``` diff --git a/docs/content/examples/cache-control-headers.md b/docs/content/examples/cache-control-headers.md new file mode 100644 index 0000000..2335722 --- /dev/null +++ b/docs/content/examples/cache-control-headers.md @@ -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 +``` diff --git a/docs/content/examples/compression.md b/docs/content/examples/compression.md index 5c4a92a..070e98a 100644 --- a/docs/content/examples/compression.md +++ b/docs/content/examples/compression.md @@ -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 +``` diff --git a/docs/content/examples/cors.md b/docs/content/examples/cors.md new file mode 100644 index 0000000..787bfcd --- /dev/null +++ b/docs/content/examples/cors.md @@ -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 "*" +``` diff --git a/docs/content/examples/directory-listing.md b/docs/content/examples/directory-listing.md index 40bec1d..40ae875 100644 --- a/docs/content/examples/directory-listing.md +++ b/docs/content/examples/directory-listing.md @@ -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. + + diff --git a/docs/content/examples/docker.md b/docs/content/examples/docker.md index 54a77ec..697ba1f 100644 --- a/docs/content/examples/docker.md +++ b/docs/content/examples/docker.md @@ -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" diff --git a/docs/content/examples/error-pages.md b/docs/content/examples/error-pages.md new file mode 100644 index 0000000..e6611d4 --- /dev/null +++ b/docs/content/examples/error-pages.md @@ -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 +``` diff --git a/docs/content/examples/file-descriptor-socket-passing.md b/docs/content/examples/file-descriptor-socket-passing.md index 0deb191..d8e7860 100644 --- a/docs/content/examples/file-descriptor-socket-passing.md +++ b/docs/content/examples/file-descriptor-socket-passing.md @@ -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: diff --git a/docs/content/examples/http1.md b/docs/content/examples/http1.md index a805584..8f92c59 100644 --- a/docs/content/examples/http1.md +++ b/docs/content/examples/http1.md @@ -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 +``` diff --git a/docs/content/examples/http2-tls.md b/docs/content/examples/http2-tls.md index 326b79c..0b1a7df 100644 --- a/docs/content/examples/http2-tls.md +++ b/docs/content/examples/http2-tls.md @@ -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 +``` diff --git a/docs/content/examples/logging.md b/docs/content/examples/logging.md index b921bbe..b4dfa88 100644 --- a/docs/content/examples/logging.md +++ b/docs/content/examples/logging.md @@ -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" +``` diff --git a/docs/content/examples/security-headers.md b/docs/content/examples/security-headers.md new file mode 100644 index 0000000..bcaf43a --- /dev/null +++ b/docs/content/examples/security-headers.md @@ -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` diff --git a/docs/content/examples/worker-threads.md b/docs/content/examples/worker-threads.md new file mode 100644 index 0000000..fe35071 --- /dev/null +++ b/docs/content/examples/worker-threads.md @@ -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 +``` diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md index ad49d95..a0449a5 100644 --- a/docs/content/getting-started.md +++ b/docs/content/getting-started.md @@ -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. diff --git a/docs/content/index.md b/docs/content/index.md index fff27cc..f8bf488 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -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. diff --git a/docs/content/migration.md b/docs/content/migration.md new file mode 100644 index 0000000..689e8d2 --- /dev/null +++ b/docs/content/migration.md @@ -0,0 +1 @@ +# Migration diff --git a/docs/content/platforms-architectures.md b/docs/content/platforms-architectures.md index 78fe858..b650fbe 100644 --- a/docs/content/platforms-architectures.md +++ b/docs/content/platforms-architectures.md @@ -1,6 +1,6 @@ # Platforms & Architectures -Currently only the following platforms and architectures are supported. +Currently only the following platforms/architectures are supported. ## Linux diff --git a/docs/content/semantic-versioning.md b/docs/content/semantic-versioning.md new file mode 100644 index 0000000..0411774 --- /dev/null +++ b/docs/content/semantic-versioning.md @@ -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.
+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. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 6592c58..c583077 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -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 # Repository 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' -- libgit2 1.7.2