v0.29.0

docs/VHOSTS.md

@@ -59,6 +59,8 @@ listener are required so there is both an ingress to redirect and an HTTPS targe
 several TLS ports are selected, port 443 is preferred; otherwise the selected TLS target
 port must be unique.
 
+`www_redirect` defaults to false. When enabled, `www_redirect_target` selects an exact DNS hostname from `frontend.hosts` as canonical (default: the first hostname for backwards compatibility). RustProxy also claims its direct companion (`example.com` <-> `www.example.com`) on the same listeners and returns `308 Permanent Redirect` from that companion to the first hostname while preserving path/query. Wildcards and IP literals cannot be the canonical hostname for this feature. The companion also participates in vhost certificate assignment, but the selected certificate must still contain both DNS names in its SANs. When `force_ssl` is also enabled, an HTTP companion request redirects directly to the HTTPS canonical URL instead of creating two redirect hops.
+
 `forward_client_ip` defaults to true. Normal vhosts therefore receive the sanitized
 `Forwarded`, `X-Forwarded-For` and `X-Real-IP` client identity generated by RustProxy.
 Set it to false for applications whose own trusted-proxy/bypass logic must see the
@@ -260,7 +262,7 @@ affinity to the backend that actually answered.
 |---|---|---|
 | `mode` | `tcp` | `off`, `tcp`, `http` |
 | `path` | `/` | Leading slash, up to 1024 bytes; no authority/fragment |
-| `host` | null | Optional validated HTTP Host override |
+| `host` | null | Optional validated HTTP Host override; otherwise the first exact vhost DNS hostname is used |
 | `interval_ms` | 5000 | 250..300000 |
 | `timeout_ms` | 2000 | 50..60000; no greater than interval |
 | `slow_response_ms` | 1500 | 0 disables; otherwise no greater than timeout |
@@ -270,7 +272,7 @@ affinity to the backend that actually answered.
 TCP checks verify that an approved origin address accepts a connection. HTTP checks
 perform GET on the configured path, without redirects, cookies or authorization.
 They use HTTP/1.1, including verified TLS when appropriate, and measure time to
-headers, not the full body. For an h2c-only service, use TCP checks. Slow probes
+headers, not the full body. When `health_check.host` is empty, RustProxy automatically uses the first exact DNS hostname configured on the vhost so an IP-address backend can still route the probe through its name-based virtual host. If no exact DNS hostname exists, the existing backend-host fallback remains. Set `health_check.host` only when the probe must use a different Host value. For an h2c-only service, use TCP checks. Slow probes
 count as active failures. Active TCP/HTTP health is independent from `passive_health`.
 
 `passive_health.enabled` defaults to `false`. With that default, normal user traffic
@@ -407,7 +409,7 @@ storage and before downstream compression. Origin `Cache-Control: no-transform`
 wins and cannot be overridden from the vhost.
 
 Pages offers a static/maintenance response, a fallback for unassigned paths, and
-error overrides. Vhosts still retain their configured backend pool; static mode
+error overrides. The static/maintenance response can set an explicit HTTP status independently of its HTML body, so an operator can serve a maintenance document as `503 Service Unavailable` instead of returning `200`. Vhosts still retain their configured backend pool; static mode
 avoids forwarding but is not a backend-less static-file server. Host/path ACLs run
 first. Explicit error-status overrides change presentation, not authorization.
 Empty/inherit means use the global error policy; to disable one inherited error
@@ -420,3 +422,5 @@ to override inheritance. See MANAGEMENT.md for exact precedence.
 New backends use the backend URL host for the upstream `Host` header by default, matching nginx `proxy_pass` behavior. Enable **Preserve client Host** only when the application intentionally routes on the public hostname. This is especially important for embedded/lighttpd-style administration panels that may close or reject requests carrying an unknown Host. Existing explicit settings are preserved during upgrades.
 
 When an upstream request fails before an HTTP response is received, access logs include a bounded `upstream_error` field in addition to `upstream_status`.
+
+Multiple explicit hostnames can belong to a single vhost: `suba.local` and `subb.local` share the same routing, backends and configuration. Only the www/non-www companion of the selected canonical hostname redirects; other aliases continue serving traffic directly.