Built-in static file handler.

Configure via a 3-tuple route with #{dir => Path} opts and a *path wildcard segment carrying the relative file path:

{~"/static/*path", roadrunner_static, #{dir => ~"/var/www"}}

Reads the file from disk, sets Content-Type from the extension, returns 404 on a missing file or any path that contains ...

Precompressed-sibling serving

When a request's Accept-Encoding opts into a compressed encoding and the requested file has a matching precompressed sibling on disk, the sibling is served verbatim with the corresponding Content-Encoding plus Vary: Accept-Encoding. This matches nginx's gzip_static on behaviour and lets operators pre-compress build assets once instead of paying the compression cost per request.

Two encodings are negotiated, brotli first:

• Accept-Encoding: br with a <file>.br sibling on disk → Content-Encoding: br
• Accept-Encoding: gzip with a <file>.gz sibling on disk → Content-Encoding: gzip

Brotli wins when the client accepts both and the .br sibling exists; gzip is the fallback. With neither sibling on disk (or neither encoding accepted) the raw file is served. Roadrunner never compresses on the fly — it only sendfiles a sibling an operator placed on disk, so there is no brotli or gzip codec dependency.

Accept-Encoding is matched via plain substring (br, gzip) rather than full RFC 9110 §12.5.3 qvalue ranking. Browsers and clients that reach the static path send these tokens plainly.

The original file's ETag is reused for every variant, so a follow-up If-None-Match returns 304 regardless of which variant was first served. A Range request disables the precompressed path on that request — byte offsets over a compressed representation have subtle semantics and the simple "Range wins" rule matches what nginx does. The Content-Type always reflects the original file's extension, not the sibling's.

Cache-Control

#{cache_control => Value} sets a Cache-Control response header, verbatim, on every cacheable response for the file — the 200 (full file and any precompressed sibling), the 206 range, and the 304 Not Modified. A 404 or a 416 never carries it, so a missing file or an unsatisfiable range is never marked cacheable.

The value is an opaque binary the operator controls in full — roadrunner does not parse, validate, or merge directives. This mirrors nginx's add_header Cache-Control, where the operator writes the exact directive string.

The option is off by default. With no cache_control key the responses are byte-for-byte what they are without it, carrying no Cache-Control header at all. ETag and Last-Modified only enable conditional revalidation — a follow-up request that may come back 304 — whereas Cache-Control is what lets a browser or a CDN reuse the resource from its own cache without contacting the server at all.

A typical value for content-hashed build assets:

{~"/static/*path", roadrunner_static, #{
    dir => ~"/var/www",
    cache_control => ~"public, max-age=31536000, immutable"
}}

max-age caps how many seconds a cache may reuse the response, immutable tells browsers not to revalidate during that window, and public lets shared caches such as CDNs and proxies store it.

Symlink policy

#{symlink_policy => Policy} (default refuse_escapes) controls how symlinks inside the docroot are handled. The policy applies to the leaf of the requested path — symlinks in intermediate directories are still followed by the kernel.

• refuse_escapes (default) — symlinks whose target resolves inside dir are followed; symlinks pointing outside (e.g. an absolute target like /etc/passwd, or a relative target with .. segments) return 404. Stricter than nginx/Apache defaults but matches what an operator typically wants for a public docroot.
• follow — every symlink is followed regardless of where it points (nginx disable_symlinks off equivalent). Use only when the docroot's filesystem permissions prevent untrusted writes.
• refuse — every symlink returns 404, even safe in-docroot ones.

Metadata cache

#{cache_ttl_ms => N} caches the stat result (size, mtime) for each regular file in a node-global ETS table for N milliseconds. Hot paths skip the per-request read_link_info syscall after the first hit. Symlinks always bypass the cache because the policy gate needs the un-followed lookup.

The default is 0 (disabled). Enabling the cache assumes files are immutable during the TTL window: the cached size feeds the Content-Length header while sendfile reads the file fresh from disk, so a file replaced or resized mid-window produces a length / body mismatch (truncated or short response). Safe for deploy-then-restart workflows with versioned-by-hash assets; unsafe for mutable files (user uploads, dev hot-reload).

Set to a positive integer to opt in (e.g., cache_ttl_ms => 1000), or infinity for "cache for the lifetime of the listener; only a listener restart re-stats". nginx's open_file_cache makes the same trade-off and is also off by default.

Call roadrunner_static:cache_clear/0 to flush every cached entry without a listener restart — useful after a deploy that swaps files under an infinity (or long) TTL.