From b0ca3d1196a9cb138ab939a2b7d77ff692054ce9 Mon Sep 17 00:00:00 2001 From: Jose Quintana Date: Tue, 5 Jul 2022 00:06:33 +0200 Subject: [PATCH] docs: minor typo fixes [skip ci] --- README.md | 14 +++++++------- docs/content/building-from-source.md | 10 +++++----- docs/content/configuration/config-file.md | 16 ++++++++-------- docs/content/configuration/environment-variables.md | 21 ++++++++++----------- docs/content/download-and-install.md | 8 ++------ docs/content/features/basic-authentication.md | 10 +++++----- docs/content/features/cache-control-headers.md | 8 ++++---- docs/content/features/compression.md | 2 +- docs/content/features/cors.md | 10 +++++----- docs/content/features/custom-http-headers.md | 16 ++++++++-------- docs/content/features/directory-listing.md | 12 ++++++------ docs/content/features/docker.md | 2 +- docs/content/features/error-pages.md | 6 +++--- docs/content/features/file-descriptor-socket-passing.md | 7 +++---- docs/content/features/graceful-shutdown.md | 12 ++++++------ docs/content/features/http1.md | 4 ++-- docs/content/features/logging.md | 8 ++++---- docs/content/features/windows-service.md | 12 ++++++------ docs/content/features/worker-threads.md | 8 ++++---- docs/content/getting-started.md | 2 +- docs/content/index.md | 4 ++-- docs/content/migration.md | 12 ++++++------ docs/content/platforms-architectures.md | 2 +- docs/content/semantic-versioning.md | 6 +++--- 24 files changed, 103 insertions(+), 109 deletions(-) diff --git a/README.md b/README.md index 020c464..6431c6d 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ **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). +It is focused on **lightness and easy-to-use** principles while 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. @@ -37,12 +37,12 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` - Built with [Rust](https://rust-lang.org) which is focused on [safety, speed and concurrency](https://kornel.ski/rust-c-speed). - Memory safe and very reduced CPU and RAM overhead. -- Blazing fast static files-serving and asynchronous powered by latest [Hyper](https://github.com/hyperium/hyper/), [Tokio](https://github.com/tokio-rs/tokio) and a set of [awesome crates](https://github.com/joseluisq/static-web-server/blob/master/Cargo.toml). +- Blazing fast static files-serving and asynchronous powered by the latest [Hyper](https://github.com/hyperium/hyper/), [Tokio](https://github.com/tokio-rs/tokio) and a set of [awesome crates](https://github.com/joseluisq/static-web-server/blob/master/Cargo.toml). - Single __4MB__ (uncompressed) and fully static binary with no dependencies ([Musl libc](https://doc.rust-lang.org/edition-guide/rust-2018/platform-and-target-support/musl-support-for-fully-static-binaries.html)). Suitable for running on [any Linux distro](https://en.wikipedia.org/wiki/Linux_distribution) or [Docker container](https://hub.docker.com/r/joseluisq/static-web-server/tags). - Optional GZip, Deflate or Brotli compression for text-based web files only. -- Compression on demand via [Accept-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header. +- Compression on-demand via [Accept-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header. - [Partial Content Delivery](https://en.wikipedia.org/wiki/Byte_serving) support for byte-serving of large files. -- Optional [Cache Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) headers for assets. +- Optional [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) headers for assets. - [Termination signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) handling with [graceful shutdown](https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-best-practices-terminating-with-grace) ability and grace period. - [HTTP/2](https://tools.ietf.org/html/rfc7540) + TLS support. - [Security headers](https://web.dev/security-headers/) for HTTP/2 by default. @@ -53,13 +53,13 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` - [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. +- Fallback pages for 404 errors are useful for Single-page applications. - Run the server as [Windows Service](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc783643(v=ws.10)). - Configurable using CLI arguments, environment variables or a file. - Default and custom error pages. -- 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. +- First-class [Docker](https://docs.docker.com/get-started/overview/) support. [Scratch](https://hub.docker.com/_/scratch) and the 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. +- Cross-platform and binaries are available for Linux, macOS, Windows & FreeBSD x86_64 / ARM. ## Documentation diff --git a/docs/content/building-from-source.md b/docs/content/building-from-source.md index 1334708..7fe7043 100644 --- a/docs/content/building-from-source.md +++ b/docs/content/building-from-source.md @@ -1,14 +1,14 @@ # Building from Source -Follow these instructions to either build **`SWS`** project from source or the HTML documentation. +Follow these instructions to either build **`SWS`** project from the source or the HTML documentation. ## Building project from source -If you want to build **`SWS`** from source, all you need is a [Rust 2021 Edition](https://blog.rust-lang.org/2021/05/11/edition-2021.html) installed. +If you want to build **SWS** from the source, all you need is a [Rust 2021 Edition](https://blog.rust-lang.org/2021/05/11/edition-2021.html) installed. So make sure to install Rust [1.56.0](https://blog.rust-lang.org/2021/10/21/Rust-1.56.0.html) or higher (or nightly) along with [the toolchain(s)](https://rust-lang.github.io/rustup/concepts/toolchains.html) of your preference. -Then clone the repository and use [Cargo](https://doc.rust-lang.org/cargo/) to build the project from source. +Then clone the repository and use [Cargo](https://doc.rust-lang.org/cargo/) to build the project from the source. ```sh git clone https://github.com/joseluisq/static-web-server.git @@ -23,13 +23,13 @@ Finally, the release binary should be available at `target/release/static-web-se ## Building documentation from source -All HTML documentation is located in `docs/` project's directory and is built using [Material for MkDocs](https://github.com/squidfunk/mkdocs-material). +All HTML documentation is located in the `docs/` project's directory and is built using [Material for MkDocs](https://github.com/squidfunk/mkdocs-material). It's only necessary to have [Docker](https://www.docker.com/get-started/) installed. ### Building documentation -By default the docs will be built in `/tmp/docs` directory, to do so follow these steps. +By default the docs will be built in the `/tmp/docs` directory, to do so follow these steps. ```sh git clone https://github.com/joseluisq/static-web-server.git diff --git a/docs/content/configuration/config-file.md b/docs/content/configuration/config-file.md index 9d827e7..b633cc5 100644 --- a/docs/content/configuration/config-file.md +++ b/docs/content/configuration/config-file.md @@ -1,12 +1,12 @@ # 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. +**`SWS`** can be configured using a [TOML](https://toml.io/en/) file 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. +It's disabled by default and can be enabled by passing a _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. +Below is just an example showing all features with their default values. ```toml [general] @@ -78,11 +78,11 @@ log-remote-address = false ### General options -The TOML `[general]` section allows to adjust the current options actually available via the CLI/ENV ones. +The TOML `[general]` section allows adjusting the current options available via the CLI/ENV ones. -So they are equivalent each other **except** the `-w, --config-file` option which is omitted and can not be used for obvious reasons. +So they are equivalent to each other **except** for the `-w`, --config-file` option which is omitted and can not be used for obvious reasons. -!!! info "Config file based features are optional" +!!! 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 @@ -93,11 +93,11 @@ For example [Custom HTTP Headers](../features/custom-http-headers.md). ### Precendence -Whatever config file based feature option will take precedence over its CLI or ENV equivalent. +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. +The following command runs the server using a 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 2b8d7f3..30e60e6 100644 --- a/docs/content/configuration/environment-variables.md +++ b/docs/content/configuration/environment-variables.md @@ -4,7 +4,7 @@ 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 equivalent 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 `[::]`. @@ -19,10 +19,10 @@ Optional file descriptor number (e.g. `0`) to inherit an already-opened TCP list 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). +The Server configuration file path is 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). +Defines a grace period in seconds after a `SIGTERM` signal is caught which will delay the server before shutting it down gracefully. The maximum value is `255` seconds. The default value is `0` (no delay). ### SERVER_LOG_LEVEL Specify a logging level in lower case. Possible values are `error`, `warn`, `info`, `debug` or `trace`. Default `error`. @@ -31,19 +31,19 @@ Specify a logging level in lower case. Possible values are `error`, `warn`, `inf Log incoming requests information along with its Remote Address (IP) if available using the `info` log level. ### SERVER_ERROR_PAGE_404 -HTML file path for 404 errors. If path is not specified or simply don't exists then server will use a generic HTML error message. Default `./public/404.html`. +HTML file path for 404 errors. If the path is not specified or simply doesn't exist then the server will use a generic HTML error message. Default `./public/404.html`. ### SERVER_ERROR_PAGE_50X -HTML file path for 50x errors. If path is not specified or simply don't exists then server will use a generic HTML error message. Default `./public/50x.html` +HTML file path for 50x errors. If the path is not specified or simply doesn't exist then the server will use a generic HTML error message. Default `./public/50x.html` ### SERVER_FALLBACK_PAGE HTML file path that is used for `GET` requests when the requested path doesn't exist. The fallback page is served with a `200` status code, useful when using client routers (E.g `React Router`). If the path is not specified or simply doesn't exist then this feature will not be active. ### SERVER_THREADS_MULTIPLIER -Number of worker threads multiplier that'll be multiplied by the number of system CPUs using the formula: `worker threads = number of CPUs * n` where `n` is the value that changes here. When multiplier value is 0 or 1 then the `number of CPUs` is used. 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. Default one thread per core. +The number of worker threads multiplier that'll be multiplied by the number of system CPUs using the formula: `worker threads = number of CPUs * n` where `n` is the value that changes here. When the multiplier value is 0 or 1 then the `number of CPUs` is used. The 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. Default one thread per core. ### SERVER_HTTP2_TLS -Enable HTTP/2 with TLS support. Make sure also to adjust current server port. Default `false` (disabled). +Enable HTTP/2 with TLS support. Make sure also to adjust the current server port. Default `false` (disabled). ### SERVER_HTTP2_TLS_CERT Specify the file path to read the certificate. Default empty (disabled). @@ -52,10 +52,10 @@ Specify the file path to read the certificate. Default empty (disabled). 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). +Specify an optional CORS list of allowed origin hosts separated by commas. Host ports or protocols aren't being checked. Use an asterisk (*) to allow any host. Default empty (disabled). ### SERVER_CORS_ALLOW_HEADERS -Specify an optional CORS list of allowed HTTP headers separated by comas. It requires `SERVER_CORS_ALLOW_ORIGINS` to be used along with. Default `origin, content-type`. +Specify an optional CORS list of allowed HTTP headers separated by commas. It requires `SERVER_CORS_ALLOW_ORIGINS` to be used along with. Default `origin, content-type`. ### 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). @@ -76,8 +76,7 @@ Enable cache control headers for incoming requests based on a set of file types. It provides [The "Basic" HTTP Authentication Scheme](https://datatracker.ietf.org/doc/html/rfc7617) using credentials as `user-id:password` pairs, encoded using `Base64`. Password must be encoded using the [BCrypt](https://en.wikipedia.org/wiki/Bcrypt) password-hashing function. Default empty (disabled). ## Windows - -Following options and commands are Windows platform specific. +The following options and commands are Windows platform-specific. ### SERVER_WINDOWS_SERVICE Run the web server as a Windows Service. See [more details](../features/windows-service.md). diff --git a/docs/content/download-and-install.md b/docs/content/download-and-install.md index c0d12f3..474218e 100644 --- a/docs/content/download-and-install.md +++ b/docs/content/download-and-install.md @@ -42,14 +42,10 @@ Via [Scoop](https://scoop.sh/) scoop install static-web-server ``` -Via [Chocolatey](https://chocolatey.org/) - -```powershell -choco install static-web-server --version=2.9.0 -``` - ## Binaries +Precompiled binaries grouped by CPU architectures. + ### x86_64 - [static-web-server-v2.9.0-x86_64-apple-darwin.tar.gz](https://github.com/joseluisq/static-web-server/releases/download/v2.9.0/static-web-server-v2.9.0-x86_64-apple-darwin.tar.gz)
diff --git a/docs/content/features/basic-authentication.md b/docs/content/features/basic-authentication.md index 09c2522..3f4c2a2 100644 --- a/docs/content/features/basic-authentication.md +++ b/docs/content/features/basic-authentication.md @@ -8,7 +8,7 @@ The format to use is the following: > `username:encrypted-password` -Both separated by a `:` (punctuation mark) character. +Both are separated by a `:` (punctuation mark) character. !!! info "Password Encryption" Only the password must be encoded using the [`BCrypt`](https://en.wikipedia.org/wiki/Bcrypt) password-hashing function. @@ -25,15 +25,15 @@ htpasswd -nBC10 "username" !!! tip "Password Security Advice" 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. + For example, the `htpasswd` tool supports a `-C` argument 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`. + Using a higher value is more secure but slower. The default value is `5` and the possible values are ranging from `4` to `17`. !!! tip "Docker Compose Advice" - If you are using `SERVER_BASIC_AUTH` env via a `docker-compose.yml` file don't forget to replace single `$` (dollar sign) with a `$$` (double-dollar sign) when you want individual `$` dollar signs in your configuration to be treated by Docker as literals.
+ If you are using `SERVER_BASIC_AUTH` env via a `docker-compose.yml` file don't forget to replace a single `$` (dollar sign) with a `$$` (double-dollar sign) when you want individual `$` dollar signs in your configuration to be treated by Docker as literals.
More details at [Docker Compose file: variable substitution](https://docs.docker.com/compose/compose-file/compose-file-v2/#variable-substitution) -Finally assign the credentails and run the server. +Finally, assign the credentials and run the server. ```sh static-web-server \ diff --git a/docs/content/features/cache-control-headers.md b/docs/content/features/cache-control-headers.md index c063963..cf12d85 100644 --- a/docs/content/features/cache-control-headers.md +++ b/docs/content/features/cache-control-headers.md @@ -1,6 +1,6 @@ -# Cache Control Headers +# Cache-Control Headers -**`SWS`** provides support for *arbitrary* [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) HTTP header specifying a `public` and `max-age` response directives. +**`SWS`** provides support for *arbitrary* [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) HTTP header specifying `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. @@ -13,7 +13,7 @@ Control headers are applied only to the following file types with the correspond 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-day `max-age` for example includes `html` and other file types. ### One hour @@ -31,7 +31,7 @@ A `max-age` of *one year* is applied only to the following file types. avif, bmp, bz2, css, doc, gif, gz, htc, ico, jpeg, jpg, js, jxl, 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. +Below is an example of how to enable the feature. ```sh static-web-server \ diff --git a/docs/content/features/compression.md b/docs/content/features/compression.md index eb3b2ef..7eda687 100644 --- a/docs/content/features/compression.md +++ b/docs/content/features/compression.md @@ -2,7 +2,7 @@ **`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. +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. ## MIME types compressed diff --git a/docs/content/features/cors.md b/docs/content/features/cors.md index 07a8564..0dc07a8 100644 --- a/docs/content/features/cors.md +++ b/docs/content/features/cors.md @@ -2,12 +2,12 @@ **`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. +A list of allowed origin hosts (URLs) should be specified and separated by commas. +Or an asterisk (*) can be used 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. +Below is an example of how to enable CORS. ```sh static-web-server \ @@ -21,7 +21,7 @@ static-web-server \ ## Allowed headers -The server also supports a list of [CORS allowed headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) separated by comas. +The server also supports a list of [CORS allowed headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) separated by commas. This feature depends on `--cors-allow-origins` to be used along with this feature. It can be controlled by the string `-j, --cors-allow-headers` option or the equivalent [SERVER_CORS_ALLOW_HEADERS](./../configuration/environment-variables.md#server_cors_allow_headers) env. @@ -29,7 +29,7 @@ This feature depends on `--cors-allow-origins` to be used along with this featur - The default allowed headers value is `origin, content-type`. - The server also supports [preflight requests](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) via the `OPTIONS` method. See [Preflighted requests in CORS](./../http-methods/#preflighted-requests-in-cors). -Below an example of how to CORS. +Below is an example of how to CORS. ```sh static-web-server \ diff --git a/docs/content/features/custom-http-headers.md b/docs/content/features/custom-http-headers.md index 41cf931..d30ffc1 100644 --- a/docs/content/features/custom-http-headers.md +++ b/docs/content/features/custom-http-headers.md @@ -1,28 +1,28 @@ # Custom HTTP Headers -**`SWS`** allows to customize the server [HTTP Response headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) on demand. +**SWS** allows customizing 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). +The Server HTTP response headers should be defined mainly as an [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 `source` key containing a 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. +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. + The headers order is important since it determines 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. +The 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 @@ -30,9 +30,9 @@ A set of valid plain [HTTP headers](https://developer.mozilla.org/en-US/docs/Web ## Examples -Below some examples of how to customize server HTTP headers in three variants. +Below are some examples of how to customize server HTTP headers in three variants. -### Oneline version +### One-line version ```toml [advanced] diff --git a/docs/content/features/directory-listing.md b/docs/content/features/directory-listing.md index 6524346..9db30ea 100644 --- a/docs/content/features/directory-listing.md +++ b/docs/content/features/directory-listing.md @@ -1,6 +1,6 @@ # Directory Listing -**`SWS`** provides a directory listing feature to display content of directories. +**`SWS`** provides a directory listing feature to display the 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. @@ -17,19 +17,19 @@ And here an example of how the directory listing looks like. ## Sorting -Sorting by `Name`, `Last modified` and `Size` is enabled as clickable columns when directory listing is activated via the `--directory-listing=true` option. +Sorting by `Name`, `Last modified` and `Size` is enabled as clickable columns when the directory listing is activated via the `--directory-listing=true` option. -You can also use the `sort` query parameter to sort manually by certain attribute from URI. E.g `https://localhost/?sort=5`. +You can also use the `sort` query parameter to sort manually by certain attributes from URI. E.g `https://localhost/?sort=5`. ## Sorting by default -Some times one wants to sort by certain attribute but by **default**. In that case default ascending or descending ordering of files/dirs by their attributes is provided by the numeric `--directory-listing-order` option or the equivalent [SERVER_DIRECTORY_LISTING_ORDER](./../configuration/environment-variables.md#server_directory_listing_order) env. +Sometimes one wants to sort by certain attribute but by **default**. In that case, the default ascending or descending ordering of files/dirs by their attributes is provided by the numeric `--directory-listing-order` option or the equivalent [SERVER_DIRECTORY_LISTING_ORDER](./../configuration/environment-variables.md#server_directory_listing_order) env. To do so you have to pass a [code sorting number](#code-numbers-for-sorting). E.g `--directory-listing-order=2`. ## Code numbers for sorting -Below the possible number code values for sorting/ordering which are grouped by attribute. +Below are the possible number code values for sorting or ordering which are grouped by attribute. ### Name @@ -52,7 +52,7 @@ Below the possible number code values for sorting/ordering which are grouped by !!! info "Tips" - The `--directory-listing-order` option depends on `--directory-listing` to be enabled. - - Use the query `?sort=NUMBER` to customize the sorting. E.g `https://localhost/?sort=5` (sort by Size in descending order) + - Use the query `?sort=NUMBER` to customize the sorting. E.g `https://localhost/?sort=5` (sort by size in descending order) Example: diff --git a/docs/content/features/docker.md b/docs/content/features/docker.md index a907266..ee2ecf0 100644 --- a/docs/content/features/docker.md +++ b/docs/content/features/docker.md @@ -20,7 +20,7 @@ To give the server a quick try just run the following commands. !!! info "Tips" - [Server CLI arguments](/configuration/command-line-arguments/) can be provided directly to the container or omitted as shown below. - - It can specify a Docker volume like `-v $HOME/my-public-dir:/public` in order to overwrite the default root directory. + - It can specify a Docker volume like `-v $HOME/my-public-dir:/public` to overwrite the default root directory. Run the scratch Docker image (just the binary) diff --git a/docs/content/features/error-pages.md b/docs/content/features/error-pages.md index 4b2a685..d8b7d0f 100644 --- a/docs/content/features/error-pages.md +++ b/docs/content/features/error-pages.md @@ -7,7 +7,7 @@ This feature is enabled by default and can be controlled either by the string `- !!! info "Tip" 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 HTML pages. +Below is an example of how to customize those HTML pages. ```sh static-web-server \ @@ -19,9 +19,9 @@ static-web-server \ ## Fallback Page for use with Client Routers -HTML file path that is used for GET requests when the requested path doesn't exist. The fallback page is served with a 200 status code, useful when using client routers like `React Router` or similar. If the path is not specified or simply doesn't exist then this feature will not be active. +HTML file path that is used for `GET` requests when the requested path doesn't exist. The fallback page is served with a `200` status code, useful when using client routers like `React Router` or similar. If the path is not specified or simply doesn't exist then this feature will not be active. -It can be set with the `SERVER_FALLBACK_PAGE` environment variable or with the cli argument `--page-fallback`. +It can be set with the `SERVER_FALLBACK_PAGE` environment variable or with the CLI argument `--page-fallback`. ```sh static-web-server \ diff --git a/docs/content/features/file-descriptor-socket-passing.md b/docs/content/features/file-descriptor-socket-passing.md index d8e7860..25be907 100644 --- a/docs/content/features/file-descriptor-socket-passing.md +++ b/docs/content/features/file-descriptor-socket-passing.md @@ -3,7 +3,7 @@ **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. + The [Socket Activation](http://0pointer.de/blog/projects/socket-activation.html) model is 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. @@ -16,10 +16,9 @@ If you're using `systemd` on Linux, there is a fully working example in the SWS ## Testing -Alternatively, the light-weight [`systemfd`](https://github.com/mitsuhiko/systemfd) utility may be -useful especially for testing purposes. +Alternatively, the lightweight [`systemfd`](https://github.com/mitsuhiko/systemfd) utility may be useful, especially for testing purposes. -For example using `systemfd` utility as follow: +For example, using `systemfd` utility as follow: ```sh systemfd --no-pid -s http::8091 -- path/to/static-web-server --fd 0 diff --git a/docs/content/features/graceful-shutdown.md b/docs/content/features/graceful-shutdown.md index d65be2a..0ea6b1a 100644 --- a/docs/content/features/graceful-shutdown.md +++ b/docs/content/features/graceful-shutdown.md @@ -1,25 +1,25 @@ # Graceful Shutdown -**`SWS`** has the ability to terminate gracefully what is known as a [graceful shutdown](https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-best-practices-terminating-with-grace) process. +**SWS** can terminate gracefully in what is known as a [graceful shutdown](https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-best-practices-terminating-with-grace) process. -It means that when a `SIGTERM` [termination signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) is caught the server will stop receiving more requests immediately but in turn it will continue processing all existing requests until they are completed (or closed). +It means that when a `SIGTERM` [termination signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) is caught the server will stop receiving more requests immediately but in turn, it will continue processing all existing requests until they are completed (or closed). !!! info "Notes" - In **BSD/Unix-like** systems, SWS will start the graceful shutdown process when a `SIGTERM`, `SIGINT` or `SIGQUIT` [termination signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) is caught. - - In **Windows** systems otherwise, SWS will start the graceful shutdown process right after a CTRL + C. Which is used to abort the current task. + - In **Windows** systems otherwise, SWS will start the graceful shutdown process right after a CTRL + C. This is used to abort the current task. ## Grace Period Sometimes one wants to control the graceful shutdown process for different reasons. For example during [Kubernetes rollouts](https://github.com/joseluisq/static-web-server/issues/79). -In these situations, SWS allows to ***delay*** the graceful shutdown process right after a `SIGTERM` providing a grace period in seconds. +In these situations, SWS allows delaying the graceful shutdown process right after a `SIGTERM` providing a grace period of seconds. The feature is disabled by default and can be controlled by the numeric `-q, --grace-period` option or its equivalent [SERVER_GRACE_PERIOD](./../configuration/environment-variables.md#server_grace_period) env. !!! tip "Tip" - The maximum grace period value is `255` seconds (4.25 min). Default value is `0` (no delay). + The maximum grace period value is `255` seconds (4.25 min). The default value is `0` (no delay). -Here an example of delaying the graceful shutdown process by `10` seconds after a `SIGTERM`. +Here is an example of delaying the graceful shutdown process by `10` seconds after a `SIGTERM`. ```sh static-web-server -p 8787 -d ./public/ -g trace --grace-period 10 diff --git a/docs/content/features/http1.md b/docs/content/features/http1.md index a9b00d3..1cd2810 100644 --- a/docs/content/features/http1.md +++ b/docs/content/features/http1.md @@ -1,12 +1,12 @@ # 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 port of the host via `-p, --port` ([SERVER_PORT](./../configuration/environment-variables.md#server_port)) and the directory of the static files using the `-d, --root` ([SERVER_ROOT](./../configuration/environment-variables.md#server_root)) argument. +The HTTP/1 is the protocol by default and can be used to specify a host address via the `-a, --host` ([SERVER_HOST](./../configuration/environment-variables.md#server_host)) argument, the port of the host via `-p, --port` ([SERVER_PORT](./../configuration/environment-variables.md#server_port)) and the directory of the static files using the `-d, --root` ([SERVER_ROOT](./../configuration/environment-variables.md#server_root)) argument. !!! info "Tips" - Either `--host`, `--port` and `--root` have defaults (optional values) so they can be specified or omitted as required. - The server provides [Termination Signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) handling with [Graceful Shutdown](https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-best-practices-terminating-with-grace) ability by default. -Below an example of how to run the server using HTTP/1. +Below is an example of how to run the server using HTTP/1. ```sh static-web-server \ diff --git a/docs/content/features/logging.md b/docs/content/features/logging.md index 9db2872..ab691ac 100644 --- a/docs/content/features/logging.md +++ b/docs/content/features/logging.md @@ -1,10 +1,10 @@ # 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`. +**`SWS`** provides logging support by 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. +Below is an example of how to adjust the log level. ```sh static-web-server \ @@ -19,7 +19,7 @@ SWS provides **Remote Address (IP)** logging for every request via an `INFO` log This feature is disabled by default and can be enabled by the boolean `--log-remote-address` option or the equivalent [SERVER_LOG_REMOTE_ADDRESS](./../configuration/environment-variables.md#server_log_remote_address) env. -If the feature is enabled then log entries for requests will contain a `remote_addr` section with the remote address (IP) value. Otherwise it will be empty. +If the feature is enabled then log entries for requests will contain a `remote_addr` section with the remote address (IP) value. Otherwise, it will be empty. Log entry example: @@ -27,7 +27,7 @@ Log entry example: 2022-05-23T22:24:50.519540Z INFO static_web_server::handler: incoming request: method=GET uri=/ remote_addr=192.168.1.126:57625 ``` -Below an example of how to enable Remote Address (IP) logging. Note the last two entries. +Below is an example of how to enable Remote Address (IP) logging. Note the last two entries. ```sh static-web-server -a "0.0.0.0" -p 8080 -d docker/public/ -g info --log-remote-address=true diff --git a/docs/content/features/windows-service.md b/docs/content/features/windows-service.md index 7523042..e8fecee 100644 --- a/docs/content/features/windows-service.md +++ b/docs/content/features/windows-service.md @@ -9,12 +9,12 @@ This feature is disabled by default and can be controlled by the boolean `-s, -- **Important notes** -- This is a Windows platform specific feature. It means the `--windows-service` argument and its env will not be present in Unix-like systems. -- Running SWS as a Windows service doesn't require to enable it via the [configuration file](../configuration/config-file.md) (`windows-service = true`) because it's already enabled during the service installation. +- This is a Windows platform-specific feature. It means the `--windows-service` argument and its env will not be present in Unix-like systems. +- Running SWS as a Windows service doesn't require enabling it via the [configuration file](../configuration/config-file.md) (`windows-service = true`) because it's already enabled during the service installation. ## Service privileges -To either install or uninstall the SWS Windows service requires *administrator* privileges, so make sure to open the terminal application as administrator or give to your [Powershell](https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.2) session enough privileges otherwise you will get an `"Access is denied"` error. +To either install or uninstall the SWS Windows service requires *administrator* privileges, so make sure to open the terminal application as administrator or give your [Powershell](https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.2)](https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.2) session enough privileges otherwise you will get an `"Access is denied"` error. We recommend a [Powershell](https://docs.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.2) session with administrator privileges. @@ -37,7 +37,7 @@ static-web-server.exe -w C:\Users\MyUser\config.toml install SWS doesn't provide a way to interact with Windows services directly. Instead, use the Windows built-in tools to interact with the SWS service once created. -For that purpose you can use either the Windows [sc.exe](https://docs.microsoft.com/en-us/windows/win32/services/configuring-a-service-using-sc) or the [services.msc](https://docs.microsoft.com/en-us/windows/win32/services/services) application. +For that purpose, you can use either the Windows [sc.exe](https://docs.microsoft.com/en-us/windows/win32/services/configuring-a-service-using-sc) or the [services.msc](https://docs.microsoft.com/en-us/windows/win32/services/services) application. For example, using `sc.exe` you can show the SWS service configuration used once installed. @@ -59,7 +59,7 @@ sc.exe qc "static-web-server" # SERVICE_START_NAME : LocalSystem ``` -Remember that alternatively you can also use the `services.msc` application if you prefer GUI service control. +Remember that alternatively, you can also use the `services.msc` application if you prefer GUI service control. ### Start @@ -126,7 +126,7 @@ sc.exe query "static-web-server" ## Uninstall the service -To uninstall the SWS service just use the `uninstall` command. Note that the service should be first stopped before to uninstall it. +To uninstall the SWS service just use the `uninstall` command. Note that the service should be first stopped before uninstalling it. ```powershell static-web-server.exe uninstall diff --git a/docs/content/features/worker-threads.md b/docs/content/features/worker-threads.md index fe35071..dd48472 100644 --- a/docs/content/features/worker-threads.md +++ b/docs/content/features/worker-threads.md @@ -1,14 +1,14 @@ # Worker Threads Customization -**`SWS`** allows to customize the number of worker threads powered by the [Tokio](https://tokio.rs/) runtime. +**SWS** allows customizing 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. +The value of `-n, --threads-multiplier` works as multiplier digits to determine the number of worker threads used by the server. -Basically multipling this input number by the number of system CPUs. +Multiplying this input number by the number of system CPUs. The formula used is the following: @@ -24,7 +24,7 @@ The formula used is the following: !!! 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. +Below is an example of how to adjust the number of worker threads. ```sh static-web-server \ diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md index e9b125b..3885c8d 100644 --- a/docs/content/getting-started.md +++ b/docs/content/getting-started.md @@ -13,7 +13,7 @@ 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). + You can specify a Docker volume like `-v $HOME/my-public-dir:/public` to overwrite the default root directory. See [Docker examples](features/docker.md). - 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). diff --git a/docs/content/index.md b/docs/content/index.md index aee440a..96625f6 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -25,7 +25,7 @@ **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). +It is focused on **lightness and easy-to-use** principles while keeping [high](https://blog.rust-lang.org/2015/04/10/Fearless-Concurrency.html) 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. @@ -44,7 +44,7 @@ It's cross-platform and available for `Linux`, `macOS`, `Windows` and `FreeBSD` - Blazing fast static files-serving and asynchronous powered by latest [Hyper](https://github.com/hyperium/hyper/), [Tokio](https://github.com/tokio-rs/tokio) and a set of [awesome crates](https://github.com/joseluisq/static-web-server/blob/master/Cargo.toml). - Single __4MB__ (uncompressed) and fully static binary with no dependencies ([Musl libc](https://doc.rust-lang.org/edition-guide/rust-2018/platform-and-target-support/musl-support-for-fully-static-binaries.html)). Suitable for running on [any Linux distro](https://en.wikipedia.org/wiki/Linux_distribution) or [Docker container](https://hub.docker.com/r/joseluisq/static-web-server/tags). - Optional GZip, Deflate or Brotli compression for text-based web files only. -- Compression on demand via [Accept-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header. +- Compression on-demand via [Accept-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header. - [Partial Content Delivery](https://en.wikipedia.org/wiki/Byte_serving) support for byte-serving of large files. - Optional [Cache Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) headers for assets. - [Termination signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) handling with [graceful shutdown](https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-best-practices-terminating-with-grace) ability and grace period. diff --git a/docs/content/migration.md b/docs/content/migration.md index c6da273..0c78841 100644 --- a/docs/content/migration.md +++ b/docs/content/migration.md @@ -1,13 +1,13 @@ # Migrating from v1 to v2 -The `v2` introduces notable changes including new features, performance improvements and new targets support like ARM64 and OSes like FreeBSD. +The `v2` introduces notable changes including new features, performance improvements and new target support like ARM64 and OSes like FreeBSD. -This version `v2` was re-written almost from scratch on top of [Hyper](https://github.com/hyperium/hyper) and [Tokio](https://github.com/tokio-rs/tokio) runtime which give us the [Rust asynchronous ability](https://rust-lang.github.io/async-book/01_getting_started/02_why_async.html) by default and latest HTTP/1 - HTTP/2 implementation improvements. -However it still try to keep the same principles of its `v1`: lightness and easy to use. Therefore a migration should not be a big deal. +This version `v2` was re-written almost from scratch on top of [Hyper](https://github.com/hyperium/hyper) and [Tokio](https://github.com/tokio-rs/tokio) runtime which gives us the [Rust asynchronous ability](https://rust-lang.github.io/async-book/01_getting_started/02_why_async.html) by default and the latest HTTP/1 - HTTP/2 implementation improvements. +However, it still tries to keep the same principles of its `v1`: lightness and easy-to-use. Therefore migration should not be a big deal. ## v2 breaking changes -This major `v2` has few breaking changes. However a migration should not represent a problem. +This major `v2` has few breaking changes. However, migration should not represent a problem. !!! tip "Tip" @@ -16,7 +16,7 @@ This major `v2` has few breaking changes. However a migration should not represe Please have in mind the following changes in `v2`: - The server now supports only a root directory path (via `--root` or its equivalent env) so an assets path option is no longer required. -- Cache control headers are applied to assets in an arbitrary manner. See [control headers examples](./features/cache-control-headers.md) for more details. +- Cache-control headers are arbitrarily applied to assets. See [control headers examples](./features/cache-control-headers.md) for more details. - OpenSSL TLS for HTTP/1 is no longer supported, instead for the HTTP/2 & TLS (via `--http2` option) the server uses [h2](https://github.com/hyperium/h2) which is on top of [Rustls](https://github.com/ctz/rustls). It means that instead of using a `.p12` or `.pfx` file you can now use only a certificate file along with its private key. See [HTTP/2 & TLS examples](./features/http2-tls.md) for more details. -The rest of known options are equivalent to `v1` (except the new ones of course). +The rest of the known options are equivalent to `v1` (except the new ones of course). diff --git a/docs/content/platforms-architectures.md b/docs/content/platforms-architectures.md index a67c0de..df50069 100644 --- a/docs/content/platforms-architectures.md +++ b/docs/content/platforms-architectures.md @@ -1,6 +1,6 @@ # Platforms & Architectures -Currently only the following platforms/architectures are supported. +Currently, only the following platforms/architectures are supported. !!! info "Docker" For Docker images supported list see [Docker OS/Arch](/features/docker/#osarch). diff --git a/docs/content/semantic-versioning.md b/docs/content/semantic-versioning.md index f213d06..2608687 100644 --- a/docs/content/semantic-versioning.md +++ b/docs/content/semantic-versioning.md @@ -1,10 +1,10 @@ # Semantic Versioning -**`SWS`** project adheres to [Semantic Versioning](https://semver.org/) for every release like [`v1`](https://github.com/joseluisq/static-web-server/blob/1.x/CHANGELOG.md) and latest [`v2`](https://github.com/joseluisq/static-web-server/blob/master/CHANGELOG.md). +**`SWS`** project adheres to [Semantic Versioning](https://semver.org/) for every release like [`v1`](https://github.com/joseluisq/static-web-server/blob/1.x/CHANGELOG.md) and the latest [`v2`](https://github.com/joseluisq/static-web-server/blob/master/CHANGELOG.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. +However, this project tries to keep away from any kind of _breaking change_ 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. +On 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 so they can do a seamless transition. -- libgit2 1.7.2