Enabling the sendfile / direct_static_io fast paths safely

FlashLin v2.0 is a production release. This page is scoped narrowly to two opt-in flags — server.sendfile and server.direct_static_io — added and benchmarked in one working session (see Performance for the numbers). Both default to false and change nothing about FlashLin's existing behavior until you turn them on.

What server.sendfile actually changes

When enabled, on Linux, for connections with no virtual hosts configured, eligible plain-HTTP GET/HEAD requests for static files are served with sendfile(2) — a true zero-copy kernel-to-socket transfer that never copies the response body into FlashLin's own memory. Everything the fast path can't cleanly decide — TLS, virtual hosts, a request body, Range, a compression preference, rewrite rules, PHP, proxy routes, anything it fails to parse — falls back immediately to the ordinary request handler, with every byte already read from the socket replayed intact. Enabling this flag can only add a faster path for a narrow case; it never removes functionality, because anything outside that case is handled exactly as before.

server.direct_static_io is smaller in scope: it skips the blocking thread-pool handoff for files recently observed to be 16 KiB or smaller, running the read directly on the async worker instead. It's only safe when your document root is backed by fast, OS-cached local storage — a slow read (cold disk, network filesystem) then blocks that worker thread for every other request queued on it.

Before enabling either flag in production

1. Stage the rollout. Enable on a canary instance or a fraction of traffic first; compare error rates, p99 latency and memory against your baseline before widening.
2. sendfile only applies to plain HTTP with no virtual hosts. If you terminate TLS at FlashLin or run multiple domains from one process, it currently does nothing for that traffic — no risk from enabling it, but no benefit either. It's built for a plain-HTTP origin behind a TLS-terminating proxy/CDN, or a single-domain internal service.
3. Only enable direct_static_io when the document root is fast, OS-cached local storage (SSD with a resident working set, or tmpfs).
4. Soak test before trusting either under sustained load. The published benchmark is a handful of short bursts, not hours of realistic mixed traffic — watch for file-descriptor growth, memory drift and tail-latency creep over an extended run.
5. Test your actual traffic shape, not just single-file-type static GETs: mixed content, real client behavior, and whatever sits in front of FlashLin.
6. Know how to roll back. Both flags are plain config booleans — setting either back to false and restarting returns to the ordinary, more battle-tested request path immediately.

What the benchmark does and doesn't establish

The comparison on the homepage ran nginx, Apache and FlashLin under identical settings on a CPU-isolated Docker/Ubuntu harness with a warm page cache and a closed-loop HTTP/1.1 client. It's real, reproducible evidence the mechanism works — not a claim about your workload. It says nothing about TLS traffic, cold caches, sustained load, or real network conditions, which is exactly what the steps above are for.