A minimalist, high-performance HTTP server written in V.
- Fast: Multi-threaded, non-blocking I/O, lock-free, copy-free, I/O multiplexing,
SO_REUSEPORT(native load balancing on Linux) - Modular: Easy to extend with custom controllers and handlers.
- Routing without allocation: route by
matchover the path's segments withhttp1_1.router, which reads the method and a zero-copy path cursor straight from the request line (the fastest,examples/router/), or declare@['GET /users/:id']methods and lethttp1_1.veb_likecompile them into a trie at startup (examples/veb_like/). Either way routing allocates nothing — a hit, a 404 or a 405 — and handlers keep the full contract (.suspendincluded). - Memory Safety: No race conditions.
- No Magic: Transparent and straightforward.
- E2E Testing: Test handlers in-process by passing raw requests directly to
handle_request(), or drive a running server — TCP or unix socket — with thevtestscripted client (raw fds viatransport.dial_tcp/dial_unix; seetests/backend_behaviors_test.v). - SSE Friendly: Built-in Server-Sent Events support (sync and async).
- ETag Friendly: Conditional GETs with
ETagandIf-None-Matchheaders. - Database Friendly: Example with PostgreSQL connection pool.
- Graceful Shutdown: Drain in-flight requests on
SIGTERM/SIGINTviasrv.shutdown(grace_ms). - Multiple Backends: epoll, io_uring (Linux), kqueue (macOS), IOCP (Windows).
- Local IPC: listen on a unix domain socket (
ServerConfig.unix_socket_path) instead of TCP — ≈2.5–3× lower RTT than TCP loopback (docs/LOCAL_IPC.md), filesystem permissions as access control, kernel-verified peer identity (socket.peer_cred: pid/uid/gid viaSO_PEERCRED/getpeereid); dial other local services withtransport.dial_unix/dial_tcp. - One Handler Contract: a single
handlersignature covers every use case, with every input as an explicit, self-describing parameter — append the response and return.done, suspend/resume on any fd (DB sockets, timers, upstream proxies) withevent_loop.watch_fd(...)+.suspend, and reach lock-free per-worker state (e.g. a per-thread DB connection — no shared pool, no mutex) via theworker_stateparameter. - Compliant with HTTP standards: Follows RFC 9112 and the IANA Field Name Registry. A dedicated
examples/conformance/handler is probed in CI by h1spec and Http11Probe — see Conformance Testing.
import server
import core
fn handle_request(request []u8, mut response []u8, client_fd int, worker_state voidptr, mut event_loop core.EventLoop) core.Step {
// Parse the request and APPEND the complete raw HTTP response
// (status line + headers + body) to `response`. The server owns it,
// reuses it across requests and batches pipelined responses into a
// single send — never free or keep it. Return `.done` when the
// response is complete, `.close` to flush-and-drop the connection, or
// `.suspend` after parking the request via `event_loop.watch_fd(...)`.
// The server never reads `Connection`: return `.close` when the
// request says `Connection: close`.
core.append_str(mut response, 'HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nok')
return .done
}
fn main() {
mut backend := unsafe { server.IOBackend(0) }
$if linux {
backend = server.IOBackend.epoll
}
$if darwin {
backend = server.IOBackend.kqueue
}
mut srv := server.new_server(server.ServerConfig{
port: 3000
handler: handle_request
io_multiplexing: backend
})!
srv.run()
}Call the handler directly — no server needed:
fn test_handle_request() {
request := 'GET / HTTP/1.1\r\nHost: localhost\r\n\r\n'.bytes()
mut response := []u8{}
mut event_loop := core.EventLoop{}
assert handle_request(request, mut response, -1, unsafe { nil }, mut event_loop) == .done
assert response.starts_with('HTTP/1.1 200 OK'.bytes())
}Or drive a running server over a real client socket — the vtest module owns
the whole lifecycle (ephemeral bind or unix socket, readiness, shutdown) and
dials raw non-blocking fds through transport, with scripts as data. This
exercises the full framing / keep-alive / suspend-resume path and
never hangs on a stalled stream. See
tests/backend_behaviors_test.v
for the pattern (pipelining, framing across TCP segments, timeouts, graceful
shutdown) and the *_end_to_end_test.v files under examples/ for
per-app end-to-end tests.
import server
import os
fn main() {
mut srv := server.new_server(server.ServerConfig{ ... })!
// A signal handler runs in async-signal context, on whichever thread the
// kernel interrupts (possibly a worker), so it only writes one byte to a
// pipe: write(2) is async-signal-safe.
wake := os.pipe()!
on_signal := fn [wake] (_ os.Signal) {
saved := C.errno // leave the interrupted code's errno untouched
C.write(wake.write_fd, c'x', 1)
C.errno = saved
}
os.signal_opt(.term, on_signal)!
os.signal_opt(.int, on_signal)!
// An ordinary thread waits for that byte, then drains and exits.
spawn fn [srv, wake] () {
os.fd_read(wake.read_fd, 1) // blocks until SIGTERM / SIGINT
srv.shutdown(2000) // stop accepting, drain up to 2 s
exit(0)
}()
srv.run()
}Don't call srv.shutdown() or exit() inside the signal handler itself.
Neither one is async-signal-safe. exit() runs atexit handlers and flushes
stdio, so it can deadlock on a lock that the interrupted thread holds. And if the
signal lands on a worker, that worker spins inside shutdown() and can't finish
its own in-flight request, so the drain waits out the whole grace period and the
request is dropped anyway. examples/graceful_shutdown/
is this pattern as a runnable program.
run() blocks in the accept loop, so there is no "server is up" return to hook
onto. after_server_start fills that gap: a callback that fires once, on the
main thread, the moment every listener is bound and the workers are spawned —
right before run() blocks. Works on every backend (epoll / io_uring / kqueue /
IOCP). Use it to log readiness, register in service discovery, write a
PID/health/ready file, notify a supervisor, or — in tests — signal a channel so a
client proceeds the instant the server is ready instead of polling for it:
ready := chan bool{cap: 1}
mut srv := server.new_server(server.ServerConfig{
handler: handle_request
after_server_start: fn [ready] () {
ready <- true
}
})!
spawn fn [mut srv] () {
srv.run()
}()
_ := <-ready // deterministic readiness — the server is now acceptingRun the example:
v -prod run examples/sse/srcSubscribe (front-end):
<script>
const es = new EventSource("http://localhost:3000/events");
es.onmessage = e => document.body.innerHTML += `<p>${e.data}</p>`;
</script>Broadcast a message:
curl -X POST http://localhost:3000/broadcastcurl -v http://localhost:3000/user/1
curl -v -H "If-None-Match: c4ca4238a0b923820dcc509a6f75849b" http://localhost:3000/user/1Start the database:
docker-compose -f examples/database/docker-compose.yml up -dRun the server:
v -prod run examples/database/srcExample handler (pool captured via closure):
fn main() {
mut pool := new_connection_pool(pg.Config{ ... }, 5) or { panic(err) }
mut srv := server.new_server(server.ServerConfig{
port: 3000
io_multiplexing: backend
handler: fn [mut pool] (request []u8, mut response []u8, client_fd int, worker_state voidptr, mut event_loop core.EventLoop) core.Step {
// Use pool.acquire() / pool.release() for DB access;
// append the raw HTTP response to `response`.
return .done
}
})!
srv.run()
}| Directory | Description |
|---|---|
examples/tiny/ |
Minimal "Hello, World!" — the benchmark target |
examples/simple/ |
Basic CRUD routing on string views of the request |
examples/simple2/ |
The same routes routed by byte offsets in place, the id a zero-copy []u8 view |
examples/simple3/ |
simple's routes as methods on an App struct that holds shared resources (a SQLite pool) |
examples/auth/ |
Argon2id password hashing (RFC 9106), JWT with exp (HMAC-SHA256), API key auth |
examples/chunked_streaming/ |
Chunked transfer encoding |
examples/compression/ |
Accept-Encoding negotiation over precompressed brotli/zstd/gzip const responses |
examples/conformance/ |
RFC 9112/9110-conformant handler (rejects malformed requests with the right 4xx/5xx); probed in CI by h1spec + Http11Probe |
examples/cookies_sessions/ |
Cookie-based sessions |
examples/cors/ |
CORS preflight and origin allowlist |
examples/csrf/ |
CSRF token protection |
examples/database/ |
PostgreSQL connection pool |
examples/date_header/ |
RFC 7231 Date header (shared cache, zero-alloc hot path) |
examples/efficient_date/ |
Cached Date header (per-worker, lazy 1×/s refresh) |
examples/etag/ |
ETag and conditional requests |
examples/graceful_shutdown/ |
SIGTERM/SIGINT drain |
examples/hexagonal/ |
Hexagonal architecture |
examples/ip_block/ |
IP allowlist / blocklist |
examples/json_api/ |
JSON API with multipart upload |
examples/mesh/ |
Local mesh: edge on TCP calling a backend on UDS via http1_1.client + a pooled per-worker connection + watch/suspend |
examples/https/ |
HTTPS server (-d vanilla_tls): a self-signed identity persisted across restarts, or a CA-issued PEM pair from HTTPS_CERT/HTTPS_KEY |
examples/https_upstream/ |
A handler calling a third-party HTTPS API without blocking its worker: the http1_1.upstream pooled client (TLS 1.3 verify-full, keep-alive reuse, deadlines, retries, DNS refreshed off the workers) |
examples/logging/ |
Access log that never writes on the request path: per-worker JSON lines flushed by the worker's timer, size rotation and reopen on SIGHUP, shipped to a collector over http1_1.upstream, drops counted |
examples/middleware/ |
Middleware chain (auth, RBAC, 404) |
examples/observability/ |
/healthz, /readyz, /metrics |
examples/proxy_aware/ |
X-Forwarded-For / real-IP extraction |
examples/rate_limit/ |
Token-bucket rate limiting |
examples/redirects/ |
301/303/308 redirects |
examples/request_limits/ |
413/431 body and header size limits, max connections, read/idle/write timeouts |
examples/security_headers/ |
HSTS, CSP, and other security headers |
examples/sse/ |
Server-Sent Events: a broadcast from any worker to every subscriber, with heartbeats (server push) |
examples/spa_static_assets/ |
CSR/WASM SPA bundle (application/wasm, .br/.gz, immutable caching, SPA fallback) |
examples/static_files/ |
Static file serving (MIME, Range, ETag, traversal safety) |
examples/url_form/ |
Query-string and URL-encoded form parsing |
examples/router/ |
Routing as code: match over path segments with http1_1.router's zero-copy cursor — the fastest option |
examples/veb_like/ |
Declarative routing with http1_1.veb_like: @['GET /users/:id'] methods compiled into a trie at startup, zero allocations per request |
examples/websocket_echo/ |
RFC 6455 WebSocket echo over the connection-takeover seam (core.queue_takeover — one engine, two protocols on one connection) |
examples/http2_cleartext/ |
HTTP/2 (cleartext, prior-knowledge, RFC 9113) over the same seam — the PRI * preface flips the connection, then the SAME handler serves h1 and http2 requests |
examples/video_stream/ |
HTTP video streaming |
examples/async_sse/ |
SSE from a timer: a finite chunked stream on wake_after (server push) |
examples/async_db_pg/ |
PostgreSQL queries via async handler |
examples/pg_transactions/ |
An atomic PostgreSQL transaction in one round trip (async_submit_batch), run again on a serialization failure (40001) as pg_async.TxRetry decides, after a jittered wait on a timerfd |
examples/async_timer/ |
Async per-request timer |
examples/async_fan_out/ |
Fan-out: one request waits on N operations in parallel through one aggregator fd (an epoll instance of its own), answering after the slowest, not the sum; a budget answers 504 with what arrived |
examples/io_uring_demo/ |
Backend selection through ServerConfig.io_multiplexing: io_uring on Linux where the process can use it, epoll otherwise |
Two layers, no bespoke test mode on the server:
- In-process — call the handler directly (
handle_request(req, mut out, ...)) and assert on the bytes it appends. Deterministic, no sockets, no threads; ideal for routing and response-shape assertions. - Over a real socket — drive the server with
vtest(scripts as data, lifecycle owned by the harness) or dial raw fds yourself withtransport.dial_tcp/dial_unix+testkit's deadline-boundedfd_*readers (so a broken stream fails fast instead of hanging). Either way this drives the real backend end to end — epoll / io_uring / kqueue — including pipelining, request framing across TCP segments, keep-alive,Expect: 100-continue, half-close, read/idle timeouts (not on kqueue, which does not enforce them yet), and the async suspend/resume path. Seetests/backend_behaviors_test.vand the*_end_to_end_test.vfiles underexamples/.
examples/conformance/ is a handler written to be
correct under an HTTP/1.1 conformance probe rather than to show off a feature:
it calls the stdlib request_parser.validate_http1() plus the field-syntax and
framing checks in validate.v, so
malformed requests get the RFC-mandated status instead of being served as valid.
Two probes drive it from CI — h1spec
(RFC 9112/9110, every push) and Http11Probe
(~215 tests incl. request-smuggling, on merge).
The scorecard below is the live h1spec --strict result, rewritten by CI on
every merge to main — 🟢 passed, ⚪ blocked (no response — transient or a
tracked backend edge), 🔴 a real conformance gap. Both the deterministic
v test examples/conformance/src layer and the live h1spec probe gate the
build: a merge is blocked by any handler-decision regression and by any 🔴 real
conformance failure over a live socket. (⚪ blocked does not gate — it can be
socket-timing noise on a hosted runner, and the v test layer already asserts
those decisions.)
Live h1spec --strict scorecard — 33/33 of the checks that get an answer pass.
🟢 33 pass
Tip
Fully conformant. Every h1spec --strict check passes over a live socket — #103 is fixed, so the probe is now a hard gate.
Request line — RFC 9112 §3
| Check | ||
|---|---|---|
| 🟢 | Simple GET accepted | pass |
| 🟢 | POST with Content-Length body | pass |
| 🟢 | OPTIONS * request-target accepted | pass |
| 🟢 | Absolute-form request-target accepted | pass |
| 🟢 | CONNECT authority-form accepted | pass |
| 🟢 | Invalid HTTP version rejected | pass |
| 🟢 | Malformed request line rejected | pass |
Headers — RFC 9112 §5
| Check | ||
|---|---|---|
| 🟢 | Missing Host header rejected | pass |
| 🟢 | Duplicate Host rejected | pass |
| 🟢 | Invalid Host value rejected | pass |
| 🟢 | Invalid header name rejected | pass |
| 🟢 | Obsolete line folding rejected | pass |
| 🟢 | Space before colon rejected | pass |
| 🟢 | Null byte in header rejected | pass |
Body — RFC 9112 §6–7
| Check | ||
|---|---|---|
| 🟢 | Chunked encoding accepted | pass |
| 🟢 | Chunked + HTTP/1.0 rejected | pass |
| 🟢 | Chunked + Content-Length rejected | pass |
| 🟢 | Chunked + Content-Length closes connection | pass |
| 🟢 | Unknown transfer-coding rejected | pass |
| 🟢 | Chunked not-final coding rejected | pass |
| 🟢 | Invalid Content-Length rejected | pass |
| 🟢 | Conflicting Content-Length rejected | pass |
| 🟢 | Invalid chunk-size rejected | pass |
| 🟢 | Missing chunk terminator rejected | pass |
| 🟢 | Expect: 100-continue handling | pass |
Response semantics — RFC 9110
| Check | ||
|---|---|---|
| 🟢 | HEAD response has no body | pass |
| 🟢 | Error response is self-delimiting | pass |
Connection — RFC 9112 §9
| Check | ||
|---|---|---|
| 🟢 | Keep-alive default (HTTP/1.1) | pass |
| 🟢 | Connection: close honored | pass |
| 🟢 | HTTP/1.0 closes by default | pass |
Hardening — implementation-defined limits
| Check | ||
|---|---|---|
| 🟢 | Oversized request line | pass |
| 🟢 | Header flood | pass |
| 🟢 | Oversized header | pass |
h1spec --strict, live socket · commit 8080253 · run log · regenerated by CI on every merge
The live-probe pass/blocked split can shift from run to run (⚪ blocked can be socket-timing noise on a hosted runner); the v test gate and examples/conformance/README.md are the stable references. The former core gaps #103 (half-close), #104 (CL+TE framing) and #109 (chunk-data CRLF) are fixed, and so are the framing gaps #184 (ambiguous framing), #185 (chunked trailers and chunk-size lines) and #186 (field-value whitespace).
- Create the target directory:
mkdir -p ~/.vmodules/enghitalo/vanilla- Copy this repository into it:
cp -r ./ ~/.vmodules/enghitalo/vanilla- Run an example:
v -prod crun examples/simple/srcv install https://github.com/enghitalo/vanillaNone on Linux: the io_uring backend drives the kernel ring through the raw
io_uring_setup / io_uring_enter / io_uring_register syscalls, not
liburing, so neither building nor running a vanilla binary needs liburing
(ldd lists only libc and libm). Minimal images (-slim, distroless) work
as they are.
# Basic throughput
wrk -H 'Connection: keep-alive' --connections 512 --threads 16 --duration 30s http://localhost:3000
# Conditional GET (ETag)
wrk -t16 -c512 -d30s -H "If-None-Match: c4ca4238a0b923820dcc509a6f75849b" http://localhost:3000/user/1See BENCHMARK_RESULTS_MACOS.md for full benchmark results on Apple M4, and docs/PERF_TUNING.md for the worker count, CPU split, kernel limits and load-generator setup that decide what a run measures.
| Resource | Description |
|---|---|
| Wiki | Architecture deep-dives, async reactor, memory management under -gc none, Postgres pipelining, and lessons learned |
| docs/ARCHITECTURE.md | The module tree, the one-direction dependency rule between modules, and where new protocols/platforms land |
| docs/BEST_PRACTICES.md | How to write handlers, build responses, allocate, handle concurrency, security, testing, and benchmarking |
| docs/V_PERF_TOOLBOX.md | V performance attributes, array flags, the C escape hatch, profiling allocations, and known gotchas |
| docs/LOCAL_IPC.md | HTTP over unix domain sockets: what loopback TCP costs, measured TCP-vs-UDS numbers, how unix_socket_path was built, peer credentials, fd passing, pitfalls |
| docs/PERF_GAP_ANALYSIS.md | Comparison against the fastest HTTP servers (tokio, io_uring C, Zig, Rust) and what was done to close the gaps |
| docs/PERF_TUNING.md | Running a server fast: build flags, VANILLA_WORKERS and taskset, ulimit -n, the listen backlog and somaxconn, buffer sizing, io_uring and kTLS host requirements, measuring your own box |
| CONTRIBUTING.md | Rules, raw-request testing with netcat/socat, benchmarking commands |
| CHECKLIST.md | Full improvement backlog with phases, priorities, and progress tracking |
- Parallelize the epoll central acceptor (#82) — one thread still accepts every connection and round-robins the fds to the workers, so under connection churn the workers sit idle behind it. The plan keeps the central-acceptor model, which has tested faster than per-worker
SO_REUSEPORTaccept on keep-alive: a small pool of acceptor threads sharing the one listener, withTCP_NODELAYmoved off the accept path. Related:shutdown()closes the listener under the live accept thread (#163) - Dynamic route matching (
/user/:id) —http1_1.router(segment cursor +match) andhttp1_1.veb_like(attribute routes compiled into a segment trie); zero allocations per request, 404/405/HEAD handled - Query-string parser (
?key=value&…) as a zero-copy slice view —HttpRequest.get_query_slice(key)returns aSliceinto the request buffer,has_query(key)also sees a bare?flag. Values are raw;request_parser.percent_decode_into(src, mut out, plus_as_space)decodes one into a reused buffer without allocating, andexamples/url_form/decodes once at the edge - Case-insensitive header lookup (IANA registry compliance) —
get_header_value_slice/count_headerfold ASCII case -
Hostheader validation (RFC 9112 §3.2) —validate_http1()(exactly-one Host); demonstrated end-to-end inexamples/conformance/ - Reject ambiguous framing at the framing layer —
Content-Length+Transfer-Encoding(#104), duplicateContent-Lengthand non-chunkedTransfer-Encoding(#184): the smuggling cases the conformance handler can't fix alone - Flush a queued response before tearing down a half-closed connection (#103) — unblocks the live h1spec/Http11Probe gate
- Request timeouts —
Limits.read_timeout_ms/write_timeout_ms/idle_timeout_ms, enforced by the per-worker deadline sweep. The first request's read deadline starts at accept (it bounds a silent connect and the TLS handshake); 408 only for a partial request, silent close otherwise; idle keep-alive connections are reaped afteridle_timeout_ms(0 = inheritread_timeout_ms, -1 = never). Not enforced on kqueue yet (#154) - Park deadlines (#200) —
Limits.park_timeout_msand per-watchwatch_fd_deadline/watch_fd_persistent_deadline: a parked request whose fd never becomes ready gets its continuation once withevent_loop.timed_out()(answer 504), from a per-worker heap that needs no other timeout; a pooled fd's late reply is drained in order by a tombstone, whose run seesevent_loop.orphaned(), as after a client disconnect (#349).pg_asynckeeps BackendKeyData andPgConn.cancelsends a non-blocking CancelRequest (over TLS when the session is). Epoll worker only (plain HTTP and HTTPS) - Server push (#230) — a taken-over connection subscribes (
event_loop.subscribe) and keeps reading its client while its wake fn gets posts from any thread (core.ConnHandle, generation-checked, through a per-worker lock-free mailbox:ServerConfig.push_mailbox_slots),wake_aftertimers,.shutdownand exactly one.closed; zero allocations per post;examples/websocket_chat,examples/sseandexamples/async_sse. Epoll worker only (plain HTTP and HTTPS) - Connection identity (#350) —
event_loop.conn_id()names the connection a handler or continuation serves: the same across a keep-alive connection's requests, never given to another connection in the process, so what belongs to the connection (peer credentials, the peer's address) can be cached under it rather than under the fd number the next connection reuses. No allocation, oneu64copied per burst: each worker takes ids from one process-wide counter 65,536 at a time. Epoll worker only (plain HTTP and HTTPS); 0, unknown, elsewhere - Chunked transfer-encoding in the request parser (
frame_chunked_total), trailer sections included (#185) - HTTP/2 — cleartext prior-knowledge via the takeover seam: HPACK (RFC 7541, Appendix C-verified), multiplexed streams, send-side flow control (
http2/+examples/http2_cleartext/) - HTTP/2 follow-ups — TLS + ALPN
h2(#142), the HTTP/1.1Upgrade: h2chandshake, and a native response path that drops the HTTP/1 round-trip (#146) - WebSocket upgrade (framing, ping/pong, close handshake) —
websocket/codec +examples/websocket_echo/over the takeover seam - Server push follow-ups (#230) — a per-connection outbound queue for backpressure (#23), and backends beyond epoll
- TLS/HTTPS — epoll backend via
ServerConfig.tls_config;tls.new_self_signed()issues a localhost/loopback certificate with proper SANs,sans: ['IP:203.0.113.5']targets a real host andpersist_dir:keeps the identity across restarts (ortls.new_from_pemfor CA-issued certs); the handshake is bounded from accept byread_timeout_ms(or, without one,idle_timeout_ms). HTTPS runs on the same epoll worker as plain HTTP, so.suspend, park deadlines, takeover, server push,on_worker_startand flush-then-close all work over TLS. After the handshake the record crypto moves into the kernel (kTLS) when the host supports it, andstatic_assetsthensendfile(2)s file bodies with no userspace copy (without kTLS they are encrypted a chunk at a time).new_serverrefuses atls_configon every other backend (#156) - PostgreSQL over TLS —
pg_async.ConnConfig.ssl_mode(.require/.verify_ca/.verify_full, withssl_root_certor the system CA bundle), TLS 1.3 through the same Mbed TLS 4 shim as the server (-d vanilla_tls); pooled connections re-dial over TLS without blocking, zero allocations per query - PostgreSQL token authentication (#197: Aurora DSQL, RDS IAM) — a cleartext password answered only over TLS and only when
ConnConfig.allowed_authlists it,password_fnfor a fresh credential on every connection attempt,max_lifetime_ms+lifetime_jitter_ms(connections recycled by the maintenance timer, never on the request path), StartupMessageparams(application_name), and re-dials and recycles that never resolve the host on the worker once the pool follows atransport.Resolver(PgPool.follow, #351). A SigV4 token generator is not included yet - HTTPS server example (
examples/https/) — a self-signed identity persisted across restarts (curl --cacert certs/cert.pem) or a CA-issued PEM pair;examples/https_upstream/covers the client side - Outbound HTTP/1.1 + HTTPS client for handlers (#229) —
http1_1.upstream: a per-worker pool parked on the reactor (watch_fd_persistent), TLS 1.3 verify-full + SNI, resumable framing (client.Framer: HEAD, 1xx, close-delimited bodies, keep-alive), pre-use liveness probe + one safe retry, connect/response deadlines from a maintenance timer (andLimits.park_timeout_ms, which bounds each wait, when it passes first, #322), DNS off the workers (Resolver, i.e.transport.Resolver, whichpg_asyncpools follow too: each origin looked up on its own, so one provider's slow DNS delays only its own refreshes, #366;allow_unresolvedstarts an origin whose DNS is down at boot, #348), IPv4/IPv6 dialing (transport.dial_addr), zero allocations per exchange;examples/https_upstream/ - Body-size cap + max-connections via
Limits(max_body_bytes→ 413,max_request_bytes,max_connections); pairmax_connectionswith a read or idle timeout — reaping silent and idle connections is what frees their slots. A per-connection request-count limit is still open - kqueue (macOS) parity (#154) —
max_connections, read/write/idle timeouts, a per-connection read buffer (split and pipelined requests), and no busy-spin whenaccepthitsEMFILE - IOCP (Windows) parity — the watch reactor for
.suspend(#117), TLS (#115),TransmitFilefor static assets (#114) -
Last-Modified/If-Modified-Since—static_assetsalready precomputes a strong ETag, a 304 andCache-Controlper file; no module sendsLast-Modifiedyet, and dynamic responses build their own ETag (examples/etag/) - Logging examples —
examples/logging/(per-worker JSON lines written by each worker's timer, size rotation and reopen onSIGHUP, shipped to a collector overhttp1_1.upstream, drops counted),examples/middleware/(access_log.v: a buffered, zero-alloc access log written to a file) andexamples/observability/(one structured line per request, plus/healthz,/readyzand/metrics) - API documentation (godoc-style, inline) — 573 of 707 public declarations carry a doc comment that starts with their name (81%,
scripts/doc_coverage.sh), andtls/,server/andpg_async/have all of theirs; the largest gaps areio_uring/(32 undocumented),http2/(23),websocket/(14),socket/(12) andkqueue/(11) - Architecture documentation — docs/ARCHITECTURE.md (the module tree, each module's role, the grep-enforced dependency rule) and server/README.md (the engine, its backends, limits and TLS)
- Security best-practices guide (injection, timing, header limits) — docs/BEST_PRACTICES.md §8 lists the defaults and points at the
auth,cors,csrf,rate_limit,request_limitsandsecurity_headersexamples; a dedicated guide is still open - Performance tuning guide — docs/PERF_TUNING.md for operators (build flags,
VANILLA_WORKERS+taskset,ulimit -n,net.core.somaxconnand other kernel parameters, buffer sizing, io_uring and kTLS requirements); docs/V_PERF_TOOLBOX.md for-gc nonevs the default GC and profiling - Example READMEs for every
examples/directory — each one says how to run it, shows real responses and links the code it explains - Tests for every example (#129), all run in CI — the 52 examples on Linux, the 28 that run on macOS there too
- Backend stress tests — connect storms, pipelined storms, slow readers with parked writes, large-upload drains, and fd exhaustion (
EMFILE) at listen and at accept (tests/accept_starved_test.v, #256) are covered; a sustained high-concurrency soak is not - Request-parser edge-case tests — split-point fuzzing over every prefix of a request, malformed and ambiguous framing (
tests/framing_ambiguity_test.v), chunked trailers (tests/chunked_trailer_test.v), requests split across TCP segments (tests/backend_behaviors_test.v), plus the h1spec/Http11Probe CI gates - End-to-end integration test suite across all backends —
tests/backend_behaviors_test.vruns the same behaviour checks on epoll, io_uring, poll and IOCP; kqueue joins once it enforces the limits (#154)
Limitations in the V compiler and standard library that vanilla's hot paths
exercised. We filed them upstream; as of the pinned V master build
(badd3466…) every one is fixed. Kept here as a record — and as a guide to
what the current pin buys and which workarounds it retires.
-
[]T{}allocated even atlen == 0, cap == 0— fixed:__new_arraynow guards oncap > 0, so a zero-length/zero-cap literal or default-initialized array field no longer callsalloc_array_data. The append-or-constworkaround is no longer needed. (vlang/v#27487) - GC allocation did not scale across cores — fixed by thread-local
allocation: Boehm's
GC_mallocno longer takes a process-global lock, so N workers allocate concurrently instead of serializing (16 cores ≈ 16×, not ≈ 1×). This removes the GC-lock penalty that was the main reason for-gc none;-gc noneis still used where the hot path is already alloc-free. (vlang/v#27488, #27486) -
error()boxed aMessageErroron every call — fixed: builtin now exportserror_sentinel, a cached allocation-freeIError; a hot "not found"!Tpath canreturn error_sentinel(likenonefor?T) instead of allocating. (TheOk-side Result construction is a separate cost — addressed in vanilla by the plain-intframing twinframe_request_length_lim_idx.) (vlang/v#27508) - No zero-alloc integer formatter in the stdlib — fixed:
strconv.write_dec(n i64, mut buf []u8)andwrite_dec_u(n u64, …)write decimal digits into a caller-provided buffer with no allocation — use these instead of.str()/${}on the response hot path. They write atbuf[0](they don't append): format into a stack scratch and append it, aswidoes in the examples. (vlang/v#27509) -
array.slice()marked the source buffer on every call — closed: V added a.noslicesarray flag, buta[start..]still marks by default, so vanilla keeps its hand-built non-markingbuf_viewwindow — now used by both the epoll and io_uring backends. (vlang/v#27507) -
&Struct{}in anif-expression branch miscompiled in some build modes — fixed in cgen; the statement-form (mut x := &T(unsafe{nil}); if … {}) workaround is no longer required. (vlang/v#27329) - stdlib formatter / KDF gaps —
strings.Builder.write_decimalgained an unsignedu64variant + JS-backend parity (vlang/v#27510); bcrypt/scrypt/pbkdf2 are now documented in the crypto README (vlang/v#27511). runtime.nr_cpus()ignores CPU affinity (not a V change — handled vanilla-side): it issysconf, blind totaskset/cpuset, so on a pinned or CPU-capped host it over-counts. vanilla sizes its pool fromcore.worker_count()=VANILLA_WORKERS→nr_cpus(); setVANILLA_WORKERSto pin the worker count inside a cpuset or CPU-limited container. (An affinity-aware auto-count was tried and reverted — it under-sized the DB profiles.)
