docs: update all documentation and landing page for preload performance

- README: new end-to-end benchmarks (137k req/sec), preload/gc_percent
  config and env vars, updated architecture diagram with path cache
- CLI.md: add --preload and --gc-percent to flag reference
- USER_GUIDE.md: new 'Preloading for Maximum Performance' section,
  GC tuning guide, Docker preload example, updated SIGHUP docs
- Landing page: hero stats show 137k req/sec, benchmark table replaces
  old Docker numbers with localhost results (beats Bun), updated feature
  cards, config tabs, structured data, and meta tags

Author: jkyberneees

CLI.md

@@ -186,6 +186,7 @@ Grouped by concern for readability. All flags are optional; unset flags do not o
 |------|------|---------|--------------|
 | `--host` | string | `` (all interfaces) | `server.addr` (host part) |
 | `--port`, `-p` | int | `8080` | `server.addr` (port part) |
+| `--redirect-host` | string | — | `server.redirect_host` |
 | `--tls-cert` | string | — | `server.tls_cert` |
 | `--tls-key` | string | — | `server.tls_key` |
 | `--tls-port` | int | `8443` | `server.tls_addr` (port part) |
@@ -205,6 +206,8 @@ Grouped by concern for readability. All flags are optional; unset flags do not o
 |------|------|---------|--------------|
 | `--no-cache` | bool | `false` | `cache.enabled = false` |
 | `--cache-size` | string | `256MB` | `cache.max_bytes` (parses `256MB`, `64MB`, `1GB`) |
+| `--preload` | bool | `false` | `cache.preload` — load all files into cache at startup |
+| `--gc-percent` | int | `0` | `cache.gc_percent` — Go GC target % (0 = default; try 400 for throughput) |
 
 #### Compression
 
@@ -244,6 +247,7 @@ static-web --dir-listing --no-dotfile-block ~/Downloads
 
 # Serve with TLS (HTTPS on :443, HTTP redirect on :80)
 static-web --port 80 --tls-port 443 \
+           --redirect-host static.example.com \
            --tls-cert /etc/ssl/cert.pem \
            --tls-key  /etc/ssl/key.pem \
            ./public
@@ -265,6 +269,9 @@ static-web
 # Disable caching (useful during local development to see file changes immediately)
 static-web --no-cache ./dist
 
+# Maximum throughput: preload all files + tune GC
+static-web --preload --gc-percent 400 ./dist
+
 # Print version info
 static-web version
 ```
@@ -385,7 +392,7 @@ The CLI was implemented using Go stdlib `flag.FlagSet` — no external framework
 - **`--host` + `--port` merging**: `net.SplitHostPort` / `net.JoinHostPort` used to decompose and reconstruct `server.addr`.
 - **`parseBytes()`**: a small helper that parses `256MB`, `1GB`, etc. with `B`/`KB`/`MB`/`GB` suffixes (case-insensitive).
 - **`//go:embed config.toml.example`**: the example config is embedded in `cmd/static-web/` at compile time. The binary is fully self-contained.
-- **`--quiet`**: passes `io.Discard` to a `loggingMiddlewareWithWriter` variant, suppressing access log output with zero overhead.
+- **`--quiet`**: skips access-log middleware entirely, removing per-request logging overhead.
 - **`--verbose`**: calls `logConfig(cfg)` after all overrides are applied, so you see the final resolved values.
 - **Version injection**: `internal/version.Version`, `Commit`, `Date` are set via `-ldflags` at build time. Default to `"dev"`, `"none"`, `"unknown"` for `go run`.
 

README.md

@@ -53,7 +53,7 @@ static-web --help
 
 | Feature | Detail |
 |---------|--------|
-| **In-memory LRU cache** | Size-bounded, byte-accurate; zero-alloc hot path (~27 ns/op) |
+| **In-memory LRU cache** | Size-bounded, byte-accurate; ~28 ns/op lookup with 0 allocations. Optional startup preload for instant cache hits. |
 | **gzip compression** | On-the-fly via pooled `gzip.Writer`; pre-compressed `.gz`/`.br` sidecar support |
 | **HTTP/2** | Automatic ALPN negotiation when TLS is configured |
 | **Conditional requests** | ETag, `304 Not Modified`, `If-Modified-Since`, `If-None-Match` |
@@ -68,7 +68,7 @@ static-web --help
 | **Symlink escape prevention** | `EvalSymlinks` re-verified against root; symlinks pointing outside root are blocked |
 | **CORS** | Configurable per-origin or wildcard (`*` emits literal `*`, never reflected) |
 | **Graceful shutdown** | SIGTERM/SIGINT drains in-flight requests with configurable timeout |
-| **Live cache flush** | SIGHUP flushes the in-memory cache without downtime |
+| **Live cache flush** | SIGHUP flushes both the in-memory file cache and the path-safety cache without downtime |
 
 ---
 
@@ -91,18 +91,13 @@ HTTP request
 │  • Method whitelist (GET/HEAD/OPTIONS only)      │
 │  • Security headers (set BEFORE path check)      │
 │  • PathSafe: null bytes, path.Clean, EvalSymlinks│
+│  • Path-safety cache (sync.Map, pre-warmed)      │
 │  • Dotfile blocking                              │
 │  • CORS (preflight + per-origin or wildcard *)   │
 │  • Injects validated path into context           │
 └────────┬────────────────────────────────────────┘
          │
 ┌────────▼────────────────────────────────────────┐
-│ headers.Middleware                               │
-│  • 304 Not Modified (ETag, If-Modified-Since)    │
-│  • Cache-Control, immutable pattern matching     │
-└────────┬────────────────────────────────────────┘
-         │
-┌────────▼────────────────────────────────────────┐
 │ compress.Middleware                              │
 │  • lazyGzipWriter: decides at first Write()      │
 │  • Skips 1xx/204/304, non-compressible types     │
@@ -111,10 +106,12 @@ HTTP request
          │
 ┌────────▼────────────────────────────────────────┐
 │ handler.FileHandler                              │
-│  • Cache hit → serve from memory (zero os.Stat) │
+│  • Cache hit → direct w.Write() fast path        │
+│  • Range/conditional → http.ServeContent         │
 │  • Cache miss → os.Stat → disk read → cache put  │
 │  • Large files (> max_file_size) bypass cache    │
 │  • Encoding negotiation: brotli > gzip > plain   │
+│  • Preloaded files served instantly on startup   │
 │  • Custom 404 page (path-validated)              │
 └─────────────────────────────────────────────────┘
 ```
@@ -125,32 +122,49 @@ HTTP request
 GET /app.js
   │
   ├─ cache.Get("/app.js") hit?
-  │     YES → serveFromCache (no syscall) → done
+  │     YES → serveFromCache (direct w.Write, no syscall) → done
   │
   └─ NO → resolveIndexPath → cache.Get(canonicalURL) hit?
               YES → serveFromCache → done
               NO  → os.Stat → os.ReadFile → cache.Put → serveFromCache
 ```
 
+When `preload = true`, every eligible file is loaded into cache at startup. The path-safety cache (`sync.Map`) is also pre-warmed, so the very first request for any preloaded file skips both filesystem I/O and `EvalSymlinks`.
+
 ---
 
 ## Performance
 
-Benchmark numbers on Apple M2 Pro (`go test -bench=. -benchtime=5s`):
+### End-to-end HTTP benchmarks
+
+Measured on Apple M2 Pro, localhost (no Docker), serving 3 small static files via `bombardier -c 50 -n 100000`:
+
+| Server | Avg Req/sec | p50 Latency | p99 Latency |
+|--------|-------------|-------------|-------------|
+| **static-web** (preload + GC 400) | **~137,000** | **321 µs** | **1.18 ms** |
+| **static-web** (default config) | ~76,000 | 580 µs | 2.40 ms |
+| Bun (native static serve) | ~129,000 | 361 µs | 0.84 ms |
+
+With `preload = true` and `gc_percent = 400`, static-web beats Bun's native static serving by ~6% in throughput.
+
+### Micro-benchmarks
+
+Measured on Apple M2 Pro (`go test -bench=. -benchtime=5s`):
 
 | Benchmark | ops/s | ns/op | allocs/op |
 |-----------|-------|-------|-----------|
-| `BenchmarkCacheGet` | 87–131 M | 27 | 0 |
-| `BenchmarkCachePut` | 42–63 M | 57 | 0 |
-| `BenchmarkCacheGetParallel` | 15–25 M | 142–147 | 0 |
-| `BenchmarkHandler_CacheHit` | — | ~5,840 | — |
+| `BenchmarkCacheGet` | 35–42 M | 28–29 | 0 |
+| `BenchmarkCacheGetParallel` | 6–8 M | 139–148 | 0 |
 
-Key design decisions driving these numbers:
+### Key design decisions
 
+- **Preload at startup**: `preload = true` reads all eligible files into RAM before the first request — eliminating cold-miss latency.
+- **Direct `w.Write()` fast path**: cache hits bypass `http.ServeContent` entirely; pre-formatted `Content-Type` and `Content-Length` headers are assigned directly.
+- **Path-safety cache**: `sync.Map`-based cache eliminates per-request `filepath.EvalSymlinks` syscalls. Pre-warmed from preload.
+- **GC tuning**: `gc_percent = 400` reduces garbage collection frequency — the hot path is allocation-free, but `net/http` internals allocate per-request.
 - **Cache-before-stat**: `os.Stat` is never called on a cache hit — the hot path is pure memory.
 - **Zero-alloc `AcceptsEncoding`**: walks the `Accept-Encoding` header byte-by-byte without `strings.Split`.
 - **Pooled `sync.Pool`**: both `gzip.Writer` and `statusResponseWriter` are pooled.
-- **`filepath.Abs` at startup**: computed once during construction, never per-request.
 - **Pre-computed `ETagFull`**: the `W/"..."` string is built when the file is cached.
 
 ---
@@ -211,6 +225,7 @@ Copy `config.toml.example` to `config.toml` and edit as needed. The server start
 |-----|------|---------|-------------|
 | `addr` | string | `:8080` | HTTP listen address |
 | `tls_addr` | string | `:8443` | HTTPS listen address |
+| `redirect_host` | string | — | Canonical host used for HTTP→HTTPS redirects |
 | `tls_cert` | string | — | Path to TLS certificate (PEM) |
 | `tls_key` | string | — | Path to TLS private key (PEM) |
 | `read_header_timeout` | duration | `5s` | Slowloris protection |
@@ -232,9 +247,11 @@ Copy `config.toml.example` to `config.toml` and edit as needed. The server start
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
 | `enabled` | bool | `true` | Toggle in-memory LRU cache |
+| `preload` | bool | `false` | Load all eligible files into cache at startup |
 | `max_bytes` | int | `268435456` | Cache size cap (bytes) |
 | `max_file_size` | int | `10485760` | Max file size to cache (bytes) |
 | `ttl` | duration | `0` | Entry TTL (0 = no expiry; flush with SIGHUP) |
+| `gc_percent` | int | `0` | Go GC target percentage (0 = use Go default of 100) |
 
 ### `[compression]`
 
@@ -276,6 +293,7 @@ All environment variables override the corresponding TOML setting. Useful for co
 |----------|-------------|
 | `STATIC_SERVER_ADDR` | `server.addr` |
 | `STATIC_SERVER_TLS_ADDR` | `server.tls_addr` |
+| `STATIC_SERVER_REDIRECT_HOST` | `server.redirect_host` |
 | `STATIC_SERVER_TLS_CERT` | `server.tls_cert` |
 | `STATIC_SERVER_TLS_KEY` | `server.tls_key` |
 | `STATIC_SERVER_READ_HEADER_TIMEOUT` | `server.read_header_timeout` |
@@ -287,9 +305,11 @@ All environment variables override the corresponding TOML setting. Useful for co
 | `STATIC_FILES_INDEX` | `files.index` |
 | `STATIC_FILES_NOT_FOUND` | `files.not_found` |
 | `STATIC_CACHE_ENABLED` | `cache.enabled` |
+| `STATIC_CACHE_PRELOAD` | `cache.preload` |
 | `STATIC_CACHE_MAX_BYTES` | `cache.max_bytes` |
 | `STATIC_CACHE_MAX_FILE_SIZE` | `cache.max_file_size` |
 | `STATIC_CACHE_TTL` | `cache.ttl` |
+| `STATIC_CACHE_GC_PERCENT` | `cache.gc_percent` |
 | `STATIC_COMPRESSION_ENABLED` | `compression.enabled` |
 | `STATIC_COMPRESSION_MIN_SIZE` | `compression.min_size` |
 | `STATIC_COMPRESSION_LEVEL` | `compression.level` |
@@ -307,12 +327,13 @@ Set `tls_cert` and `tls_key` to enable HTTPS:
 [server]
 addr     = ":80"
 tls_addr = ":443"
+redirect_host = "static.example.com"
 tls_cert = "/etc/ssl/certs/server.pem"
 tls_key  = "/etc/ssl/private/server.key"
 ```
 
 When TLS is configured:
-- HTTP requests on `addr` are automatically **redirected** to `tls_addr` with `301 Moved Permanently`.
+- HTTP requests on `addr` are automatically **redirected** to HTTPS. Set `redirect_host` when `tls_addr` listens on all interfaces (for example `:443`) so redirects use a canonical host instead of the incoming `Host` header.
 - **HTTP/2** is enabled automatically via ALPN negotiation.
 - **HSTS** (`Strict-Transport-Security`) is added to all HTTPS responses (configurable max-age).
 - Minimum TLS version is **1.2**; preferred cipher suites are ECDHE+AES-256-GCM and ChaCha20-Poly1305.
@@ -348,9 +369,9 @@ make precompress   # runs gzip and brotli on all .js/.css/.html/.json/.svg
 |--------|--------|
 | `SIGTERM` | Graceful shutdown (drains in-flight requests up to `shutdown_timeout`) |
 | `SIGINT` | Graceful shutdown |
-| `SIGHUP` | Flush in-memory cache; re-reads config pointer in `main` |
+| `SIGHUP` | Flush in-memory file cache and path-safety cache; re-reads config pointer in `main` |
 
-> **Note**: SIGHUP reloads the config pointer in `main` but the live middleware chain holds references to the old config. A full restart is required for config changes to take effect. SIGHUP is useful for flushing the cache without downtime.
+> **Note**: SIGHUP reloads the config pointer in `main` but the live middleware chain holds references to the old config. A full restart is required for config changes to take effect. SIGHUP is useful for flushing both the file cache and the path-safety cache without downtime.
 
 ---
 
@@ -400,5 +421,4 @@ go test -race ./... # all tests, race-free
 | Limitation | Detail |
 |------------|--------|
 | **Brotli on-the-fly** | Not implemented. Only pre-compressed `.br` sidecar files are served. |
-| **Cache TTL not enforced** | `cache.ttl` is parsed but the expiry logic is not yet implemented. Use SIGHUP to flush manually. |
 | **SIGHUP config reload** | Reloads the config struct pointer in `main` only. Live middleware chains hold old references — full restart required for config changes to propagate. |