docs(v3): sync with the latest v3 changes on master

.vitepress/config.v3.mts

@@ -73,6 +73,7 @@ export const v3: DefaultTheme.Config = {
           { text: 'Maintenance Mode', link: '/v3/features/maintenance-mode' },
           { text: 'In-Memory Cache', link: '/v3/features/memory-cache' },
           { text: 'WebAssembly', link: '/v3/features/webassembly' },
+          { text: 'Open in Browser', link: '/v3/features/open-browser' },
           { text: 'Man Pages and Shell Completions', link: '/v3/features/man-pages-completions' },
           { text: 'Markdown Content Negotiation', link: '/v3/features/markdown-content-negotiation' },
           { text: 'Default Charset for Text Responses', link: '/v3/features/text-charset' },

src/v3/configuration/cli.md

@@ -19,9 +19,13 @@ Commands:
 
 Options:
   -a, --host <HOST>
-          Host address (E.g 127.0.0.1 or ::1) [env: SERVER_HOST=] [default: ::]
+          Host address (E.g 127.0.0.1 or ::1). The default `::` accepts both IPv6 and IPv4 connections where the OS supports dual-stack sockets [env: SERVER_HOST=] [default: ::]
   -p, --port <PORT>
-          Host port [env: SERVER_PORT=] [default: 8787]
+          Host port [env: SERVER_PORT=] [default: 8080]
+      --open [<OPEN>]
+          Open the server URL in the system default web browser after startup [env: SERVER_OPEN=] [default: false] [possible values: true, false]
+      --open-path <OPEN_PATH>
+          URL path opened in the browser. Requires the open option [env: SERVER_OPEN_PATH=]
   -f, --fd <FD>
           Instead of binding to a TCP port, accept incoming connections to an already-bound TCP socket listener on the specified file descriptor number (usually zero). Requires that the parent process (e.g. inetd, launchd, or systemd) binds an address and port on behalf of static-web-server, before arranging for the resulting file descriptor to be inherited by static-web-server. Cannot be used in conjunction with the port and host arguments. The included systemd unit file utilises this feature to increase security by allowing the static-web-server to be sandboxed more completely [env: SERVER_LISTEN_FD=]
       --unix-socket <UNIX_SOCKET>
@@ -35,7 +39,7 @@ Options:
   -b, --max-blocking-threads <MAX_BLOCKING_THREADS>
           Maximum number of blocking threads [env: SERVER_MAX_BLOCKING_THREADS=] [default: 512]
   -d, --root <ROOT>
-          Root directory path of static files [env: SERVER_ROOT=] [default: ./public]
+          Root directory path of static files [env: SERVER_ROOT=] [default: .]
       --page50x <PAGE50X>
           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. If a relative path is used then it will be resolved under the root directory [env: SERVER_ERROR_PAGE_50X=] [default: ./50x.html]
       --page404 <PAGE404>
@@ -69,7 +73,7 @@ Options:
       --https-redirect-host <HTTPS_REDIRECT_HOST>
           Canonical host name or IP of the HTTPS server. It depends on "https_redirect" to be enabled [env: SERVER_HTTPS_REDIRECT_HOST=] [default: localhost]
       --https-redirect-from-port <HTTPS_REDIRECT_FROM_PORT>
-          HTTP host port where the redirect server will listen for requests to redirect them to HTTPS. It depends on "https_redirect" to be enabled [env: SERVER_HTTPS_REDIRECT_FROM_PORT=] [default: 80]
+          HTTP host port where the redirect server will listen for requests to redirect them to HTTPS. It depends on "https_redirect" to be enabled [env: SERVER_HTTPS_REDIRECT_FROM_PORT=] [default: 8080]
       --https-redirect-from-hosts <HTTPS_REDIRECT_FROM_HOSTS>
           List of host names or IPs allowed to redirect from. HTTP requests must contain the HTTP 'Host' header and match against this list. It depends on "https_redirect" to be enabled [env: SERVER_HTTPS_REDIRECT_FROM_HOSTS=] [default: localhost]
       --index-files <INDEX_FILES>
@@ -85,7 +89,7 @@ Options:
       --directory-listing-order <DIRECTORY_LISTING_ORDER>
           Specify a default code number to order directory listing entries per `Name`, `Last modified` or `Size` attributes (columns). Code numbers supported: 0 (Name asc), 1 (Name desc), 2 (Last modified asc), 3 (Last modified desc), 4 (Size asc), 5 (Size desc). Default 6 (unordered) [env: SERVER_DIRECTORY_LISTING_ORDER=] [default: 6]
       --directory-listing-format <DIRECTORY_LISTING_FORMAT>
-          Specify a content format for directory listing entries. Formats supported: "html" or "json". Default "html" [env: SERVER_DIRECTORY_LISTING_FORMAT=] [default: html] [possible values: html, json]
+          Specify a content format for directory listing entries. Formats supported: "html", "json" or "auto". Default "html" [env: SERVER_DIRECTORY_LISTING_FORMAT=] [default: html] [possible values: html, json, auto]
       --directory-listing-download=<DIRECTORY_LISTING_DOWNLOAD>
           Specify list of enabled format(s) for directory download. Format supported: `targz`. Default to empty list (disabled) [env: SERVER_DIRECTORY_LISTING_DOWNLOAD=] [possible values: targz]
       --security-headers [<SECURITY_HEADERS>]
@@ -107,15 +111,15 @@ Options:
   -w, --config-file <CONFIG_FILE>
           Server TOML configuration file path [env: SERVER_CONFIG_FILE=] [default: ./sws.toml]
       --access-log-format <ACCESS_LOG_FORMAT>
-          Custom access log format string using %{token} syntax. When set, replaces the default request logging with a configurable format that includes response data. Tokens: method, uri, status, bytes, duration, remote_addr, x_real_ip, forwarded_for, host, user_agent, referer, timestamp, version. x_real_ip and forwarded_for are logged only for requests from --trusted-proxies, if set. Example: '%{remote_addr} "%{method} %{uri}" %{status} %{bytes}' [env: SERVER_ACCESS_LOG_FORMAT=] [default: ""]
+          Custom access log format string using %{token} syntax. When set, replaces the default request logging with a configurable format that includes response data. Tokens: method, uri, status, bytes, duration, remote_addr, x_real_ip, forwarded_for, host, user_agent, referer, timestamp, version. x_real_ip and forwarded_for are logged only for requests from --trusted-proxies. Example: '%{remote_addr} "%{method} %{uri}" %{status} %{bytes}' [env: SERVER_ACCESS_LOG_FORMAT=] [default: ""]
       --log-remote-address [<LOG_REMOTE_ADDRESS>]
           Log the remote address of each request, if available [env: SERVER_LOG_REMOTE_ADDRESS=] [default: false] [possible values: true, false]
       --log-x-real-ip [<LOG_X_REAL_IP>]
-          Log the X-Real-IP header for remote IP information [env: SERVER_LOG_X_REAL_IP=] [default: false] [possible values: true, false]
+          Log the X-Real-IP header of requests from --trusted-proxies [env: SERVER_LOG_X_REAL_IP=] [default: false] [possible values: true, false]
       --log-forwarded-for [<LOG_FORWARDED_FOR>]
-          Log the X-Forwarded-For header for remote IP information [env: SERVER_LOG_FORWARDED_FOR=] [default: false] [possible values: true, false]
+          Log the first X-Forwarded-For address of requests from --trusted-proxies [env: SERVER_LOG_FORWARDED_FOR=] [default: false] [possible values: true, false]
       --trusted-proxies <TRUSTED_PROXIES>
-          List of IPs to use X-Forwarded-For from. The default is to trust all [env: SERVER_TRUSTED_PROXIES=]
+          List of proxy IPs to use the X-Real-IP and X-Forwarded-For headers from. The default trusts no one, so the headers are not logged unless set. IPv4 entries also match their IPv4-mapped IPv6 form (`::ffff:a.b.c.d`) [env: SERVER_TRUSTED_PROXIES=]
       --redirect-trailing-slash [<REDIRECT_TRAILING_SLASH>]
           Check for a trailing slash in the requested directory URI and redirect permanently (308) to the same path with a trailing slash suffix if it is missing [env: SERVER_REDIRECT_TRAILING_SLASH=] [default: true] [possible values: true, false]
       --include-hidden [<INCLUDE_HIDDEN>]
@@ -129,7 +133,7 @@ Options:
       --text-charset [<TEXT_CHARSET>]
           Set a default `charset=utf-8` parameter on limited set of `text` responses that don't already have one [env: SERVER_TEXT_CHARSET=] [default: true] [possible values: true, false]
       --health [<HEALTH>]
-          Add the `/livez` (liveness) and `/readyz` (readiness) endpoints for Kubernetes-style probes. They answer `GET` and `HEAD` with `200 OK` and log requests at `debug` level only [env: SERVER_HEALTH=] [default: false] [possible values: true, false]
+          Add the `/livez` (liveness) and `/readyz` (readiness) endpoints for Kubernetes-style probes. They answer `GET` and `HEAD` with `200 OK` (`/readyz` returns `503` once shutdown starts or while the root directory is missing) and log requests at `debug` level only [env: SERVER_HEALTH=] [default: false] [possible values: true, false]
       --metrics [<METRICS>]
           Enable the /metrics endpoint that exposes Prometheus metrics for HTTP requests, connections, and latency [env: SERVER_METRICS=] [default: false] [possible values: true, false]
       --maintenance-mode [<MAINTENANCE_MODE>]

src/v3/configuration/env.md

@@ -9,11 +9,19 @@ The server can be configured via the following environment variables.
 
 ## SERVER_HOST
 
-Host address (e.g. `127.0.0.1` or `::1`). Default `[::]`.
+Host address (e.g. `127.0.0.1` or `::1`). The default `::` accepts both IPv6 and IPv4 connections where the OS supports dual-stack sockets. Default `::`.
 
 ## SERVER_PORT
 
-Host port. Default `8787`.
+Host port. Default `8080`.
+
+## SERVER_OPEN
+
+Open the server URL in the system default web browser after startup. See [Open in Browser](../features/open-browser.md). Default `false` (disabled).
+
+## SERVER_OPEN_PATH
+
+URL path opened in the browser. Requires `SERVER_OPEN`. Default empty (`/`).
 
 ## SERVER_LISTEN_FD
 
@@ -41,7 +49,7 @@ Maximum number of blocking threads. Default `512`.
 
 ## SERVER_ROOT
 
-Root directory path of static files. Default `./public`.
+Root directory path of static files. Default `.` (current directory).
 
 ## SERVER_ERROR_PAGE_50X
 
@@ -53,7 +61,7 @@ HTML file path for 404 errors. If the path is not specified or simply doesn't ex
 
 ## SERVER_FALLBACK_PAGE
 
-A HTML file path (not relative to the root) 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. If the path doesn't exist then the feature is not activated.
+A HTML file path (not relative to the root) 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. Requests for missing assets keep their `404`, see [Fallback Page](../features/error-pages.md#fallback-page-for-use-with-client-routers). If the path doesn't exist then the feature is not activated.
 
 ## SERVER_LOG_LEVEL
 
@@ -109,7 +117,7 @@ Canonical host name or IP of the HTTPS server. It depends on `SERVER_HTTPS_REDIR
 
 ## SERVER_HTTPS_REDIRECT_FROM_PORT
 
-HTTP host port where the redirect server will listen for requests to redirect them to HTTPS. It depends on `SERVER_HTTPS_REDIRECT` to be enabled. Default `80`.
+HTTP host port where the redirect server will listen for requests to redirect them to HTTPS. It depends on `SERVER_HTTPS_REDIRECT` to be enabled. Default `8080`.
 
 ## SERVER_HTTPS_REDIRECT_FROM_HOSTS
 
@@ -141,7 +149,7 @@ Specify a default code number to order directory listing entries per `Name`, `La
 
 ## SERVER_DIRECTORY_LISTING_FORMAT
 
-Specify a content format for directory listing entries. Formats supported: `html` or `json`. Default `html`.
+Specify a content format for directory listing entries. Formats supported: `html`, `json` or `auto` (chosen per request from the `Accept` header). See [Output format](../features/directory-listing.md#output-format). Default `html`.
 
 ## SERVER_DIRECTORY_LISTING_DOWNLOAD
 
@@ -193,15 +201,15 @@ Log the remote address of each request, if available. Default `false`.
 
 ## SERVER_LOG_X_REAL_IP
 
-Log the `X-Real-IP` header for remote IP information. Default `false`.
+Log the `X-Real-IP` header of requests from `SERVER_TRUSTED_PROXIES`. Default `false`.
 
 ## SERVER_LOG_FORWARDED_FOR
 
-Log the `X-Forwarded-For` header for remote IP information. Default `false`.
+Log the first `X-Forwarded-For` address of requests from `SERVER_TRUSTED_PROXIES`. Default `false`.
 
 ## SERVER_TRUSTED_PROXIES
 
-List of IPs to use `X-Forwarded-For` from. The default is to trust all. Default `""`.
+List of proxy IPs to use the `X-Real-IP` and `X-Forwarded-For` headers from. IPv4 entries also match their IPv4-mapped IPv6 form (`::ffff:a.b.c.d`). See [Trusted proxies](../features/logging.md#trusted-proxies). Default empty (trusts no one, so the headers are not logged).
 
 ## SERVER_REDIRECT_TRAILING_SLASH
 
@@ -229,7 +237,7 @@ Set a default `charset=utf-8` parameter on limited set of `text` responses that
 
 ## SERVER_HEALTH
 
-Add the `/livez` (liveness) and `/readyz` (readiness) endpoints for Kubernetes-style probes. They answer `GET` and `HEAD` with `200 OK` and log requests at `debug` level only. See [Health endpoint](../features/health-endpoint.md) for details. Default `false` (disabled).
+Add the `/livez` (liveness) and `/readyz` (readiness) endpoints for Kubernetes-style probes. They answer `GET` and `HEAD` with `200 OK` (`/readyz` returns `503` once shutdown starts or while the root directory is missing) and log requests at `debug` level only. See [Health endpoint](../features/health-endpoint.md) for details. Default `false` (disabled).
 
 ## SERVER_METRICS
 

src/v3/configuration/file.md

@@ -6,7 +6,7 @@ outline: deep
 
 **`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 a _string file path_ via the `-w, --config-file` option or its equivalent [SERVER_CONFIG_FILE](./../configuration/env#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/env#server-config-file) env.
 
 > [!TIP] The default config file path is checked at startup time
 > If using the default config file path (`./sws.toml`), SWS will attempt to load it at startup time.
@@ -21,58 +21,81 @@ Below is just an example showing all features with their default values.
 
 #### Address & Root dir
 host = "::"
-port = 80
-root = "./public"
+port = 8080
+root = "."
+
+#### Open the server URL in the browser on startup
+open = false
+# open-path = "/"
+
+#### Unix domain socket (Unix only)
+# unix-socket = "/run/sws.sock"
+# unix-socket-mode = 0o660 # octal
+unix-socket-force = false
+
+#### File descriptor binding
+# fd = 0
 
 #### Logging
 log-level = "error"
 log-format = "json"
+log-with-ansi = false
+# log-file = "/var/log/sws.log"
 
 #### Cache Control headers
 cache-control-headers = true
 
+#### ETag validators
+etag = true
+
 #### Auto Compression
 compression = true
 compression-level = "default"
 
+#### Check for existing pre-compressed files
+compression-static = true
+
 #### Error pages
 # Note: If a relative path is used then it will be resolved under the root directory.
 page404 = "./404.html"
 page50x = "./50x.html"
 
-#### HTTP/2 + TLS
+#### Page fallback for 404s
+# page-fallback = ""
+
+#### TLS, HTTP/2 & HTTPS redirect
+tls = false
+tls-cert = ""
+tls-key = ""
 http2 = false
-http2-tls-cert = ""
-http2-tls-key = ""
 https-redirect = false
 https-redirect-host = "localhost"
-https-redirect-from-port = 80
+https-redirect-from-port = 8080
 https-redirect-from-hosts = "localhost"
 
-#### CORS & Security headers
-# security-headers = true
-# cors-allow-origins = ""
+#### Security headers
+security-headers = true
 
-#### Directory listing
-directory-listing = false
+#### CORS
+cors-allow-origins = ""
+cors-allow-headers = "origin, content-type, authorization"
+cors-expose-headers = "origin, content-type"
 
-#### Directory listing sorting code
-directory-listing-order = 1
+#### List of index files
+index-files = "index.html"
 
-#### Directory listing content format
+#### Directory listing
+directory-listing = false
+directory-listing-order = 6
 directory-listing-format = "html"
-
-#### Directory listing download format
 directory-listing-download = []
 
 #### Basic Authentication
 # basic-auth = ""
 
-#### File descriptor binding
-# fd = ""
-
-#### Worker threads
+#### Worker and blocking threads
 threads-multiplier = 1
+max-blocking-threads = 512
 
 #### Grace period after a graceful shutdown
 grace-period = 0
@@ -86,45 +109,44 @@ max-header-size = 16384
 #### Maximum connections served at the same time (0 means no limit)
 max-connections = 0
 
-#### Page fallback for 404s
-# page-fallback = ""
-
 #### Custom access log format (replaces the default request line when set)
 # access-log-format = '%{remote_addr} - [%{timestamp}] "%{method} %{uri} %{version}" %{status} %{bytes} "%{referer}" "%{user_agent}"'
 
 #### Log request Remote Address if available
 log-remote-address = false
 
-#### Log real IP from X-Forwarded-For header if available
+#### Log real IPs from the X-Real-IP and X-Forwarded-For headers of trusted proxies
+log-x-real-ip = false
 log-forwarded-for = false
 
-#### IPs to accept the X-Forwarded-For header from. Empty means all
+#### Proxy IPs to accept the X-Real-IP and X-Forwarded-For headers from. Empty means none
 trusted-proxies = []
 
 #### Redirect to trailing slash in the requested directory uri
 redirect-trailing-slash = true
 
+#### Hidden files and symlinks
+include-hidden = false
+follow-symlinks = false
+
 #### Use relative root (skip root canonicalization at startup)
 use-relative-root = false
 
-#### Check for existing pre-compressed files
-compression-static = true
-
 #### Health-check endpoints (GET or HEAD `/livez` and `/readyz`)
 health = false
 
+#### Prometheus metrics endpoint (`/metrics`)
+metrics = false
+
 #### Markdown content negotiation
 accept-markdown = false
 
-#### Default charset for text responses (enabled by default)
-# text-charset = false
+#### Default charset for text responses
+text-charset = true
 
-#### List of index files
-# index-files = "index.html, index.htm"
 #### Maintenance Mode
-
 maintenance-mode = false
-# maintenance-mode-status = 503
+maintenance-mode-status = 503
 # maintenance-mode-file = "./maintenance.html"
 
 ### Windows Only
@@ -155,6 +177,13 @@ maintenance-mode = false
 # source = "**/*.{jpg,jpeg,png,ico,gif}"
 # headers.Strict-Transport-Security = "max-age=63072000; includeSubDomains; preload"
 
+#### d. Only for some response statuses, and for every response (not only files)
+# [[advanced.headers]]
+# source = "**"
+# status = [404]
+# scope = "all"
+# headers.Cache-Control = "no-store"
+
 
 ### URL Redirects (examples only)
 
@@ -196,7 +225,7 @@ maintenance-mode = false
 # capacity = 100
 # ttl = 1800      # 30 minutes
 # tti = 300       # 5 minutes
-# max-file-size = 8192  # 8 MiB
+# max-file-size = 8192  # in KiB (8 MiB)
 ```
 
 ### General options