static-web

static-web

A production-grade, high-performance static web file server written in Go. Zero external runtime dependencies beyond BurntSushi/toml and hashicorp/golang-lru/v2.

Table of Contents

• Quick Start
• CLI
• Features
• Architecture
• Performance
• Security Model
• Configuration Reference
• Environment Variables
• TLS / HTTPS
• Pre-compressed Files
• HTTP Signals
• Building & Development
• Package Layout
• Known Limitations

Quick Start

# Go install (requires Go 1.26+)
go install github.com/BackendStack21/static-web/cmd/static-web@latest

# Serve the current directory
static-web .

# Serve a build output directory on port 3000
static-web --port 3000 ./dist

# Scaffold a config file
static-web init

CLI

For the full flag reference, subcommand documentation, and installation options, see CLI.md.

static-web --help

Features

Architecture

HTTP request
     │
     ▼
┌─────────────────┐
│ recoveryMiddleware │  ← panic → 500, log stack
└────────┬────────┘
         │
┌────────▼────────┐
│ loggingMiddleware │  ← pooled statusResponseWriter; logs method/path/status/duration
└────────┬────────┘
         │
┌────────▼────────────────────────────────────────┐
│ security.Middleware                              │
│  • Method whitelist (GET/HEAD/OPTIONS only)      │
│  • Security headers (set BEFORE path check)      │
│  • PathSafe: null bytes, path.Clean, EvalSymlinks│
│  • 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     │
│  • Respects q=0 explicit denial                  │
└────────┬────────────────────────────────────────┘
         │
┌────────▼────────────────────────────────────────┐
│ handler.FileHandler                              │
│  • Cache hit → serve from memory (zero os.Stat) │
│  • Cache miss → os.Stat → disk read → cache put  │
│  • Large files (> max_file_size) bypass cache    │
│  • Encoding negotiation: brotli > gzip > plain   │
│  • Custom 404 page (path-validated)              │
└─────────────────────────────────────────────────┘

Request path through the cache

GET /app.js
  │
  ├─ cache.Get("/app.js") hit?
  │     YES → serveFromCache (no syscall) → done
  │
  └─ NO → resolveIndexPath → cache.Get(canonicalURL) hit?
              YES → serveFromCache → done
              NO  → os.Stat → os.ReadFile → cache.Put → serveFromCache

Performance

Benchmark numbers on Apple M2 Pro (go test -bench=. -benchtime=5s):

Key design decisions driving these numbers:

• 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.

Security Model

Path Safety (internal/security)

Every request URL is validated through PathSafe before any filesystem access:

1. Null byte rejection — prevents C-level path truncation.
2. path.Clean normalisation — collapses /../, //, etc.
3. Prefix check — ensures the resolved path starts with the absolute root (separator-aware to prevent /rootsuffix collisions).
4. EvalSymlinks re-verification — resolves the canonical real path and re-checks the prefix. Symlinks pointing outside root return ErrPathTraversal. Non-existent paths (ENOENT) fall back to the already-checked candidate.
5. Dotfile blocking — each path segment is checked for a leading ..

HTTP Security Headers

Set on every response including 4xx/5xx errors:

Method Whitelist

Only GET, HEAD, and OPTIONS are accepted. All other methods (including TRACE, PUT, POST, DELETE, PATCH) receive 405 Method Not Allowed. This means TRACE-based XST attacks are impossible by design.

CORS

• Wildcard (["*"]): emits the literal string *. The request Origin is never reflected. Vary: Origin is not added (correct per RFC 6454).
• Specific origins: each allowed origin is compared exactly. Matching origins receive Access-Control-Allow-Origin: <origin> and Vary: Origin.
• Preflight (OPTIONS): returns 204 with Access-Control-Allow-Methods, Access-Control-Allow-Headers, and Access-Control-Max-Age: 86400.

DoS Mitigations

Configuration Reference

Copy config.toml.example to config.toml and edit as needed. The server starts without a config file using sensible defaults.

[server]

[files]

[cache]

[compression]

[headers]

[security]

Environment Variables

All environment variables override the corresponding TOML setting. Useful for containers.

TLS / HTTPS

Set tls_cert and tls_key to enable HTTPS:

[server]
addr     = ":80"
tls_addr = ":443"
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/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.

Pre-compressed Files

Place .gz and .br sidecar files alongside originals. The server serves them automatically when the client signals support:

public/
  app.js
  app.js.gz    ← served for Accept-Encoding: gzip
  app.js.br    ← served for Accept-Encoding: br (preferred over gzip)
  style.css
  style.css.gz

Generate sidecars from the Makefile:

make precompress   # runs gzip and brotli on all .js/.css/.html/.json/.svg

Note: On-the-fly brotli encoding is not implemented. Only .br sidecar files are served with brotli encoding.

HTTP Signals

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.

Building & Development

Prerequisites

• Go 1.26+
• GNU Make

Commands

make build        # compile → bin/static-web
make release      # compile stripped binary → bin/static-web
make install      # install to $(GOPATH)/bin
make run          # build + run with ./config.toml
make test         # go test -race ./...
make bench        # go test -bench=. -benchtime=5s ./...
make lint         # go vet ./...
make precompress  # generate .gz/.br sidecars for public/
make clean        # remove bin/

Running Tests

go test -race ./...                       # full suite with race detector
go test -run TestPathSafe ./internal/security/...  # specific test
go test -bench=BenchmarkCacheGet -benchtime=10s ./internal/cache/

Code Quality Gates

All PRs must pass:

go build ./...    # clean compile
go vet ./...      # static analysis
go test -race ./... # all tests, race-free

Known Limitations