zeroserve: A Zero-Config Web Server Scriptable with Userspace eBPF

zeroserve is a high-performance, zero-config HTTPS server designed to replace traditional declarative configuration files with executable eBPF programs. By treating the program as the configuration, zeroserve allows developers to define routing, authentication, and rate-limiting logic in a single, linear script rather than splitting behavior across disparate configuration blocks and optional plugins.

Core Architecture: Tarball-Based Deployment and io_uring

zeroserve serves entire websites from a single tarball file without unpacking them to disk. Upon loading, the server builds a path-to-byte-range map and performs byte-range reads directly against the tarball. This approach ensures that deployments are atomic—replacing the tarball and sending a SIGHUP signal swaps the site content, scripts, and TLS material without dropping connections.

To optimize I/O performance, zeroserve utilizes io_uring for all network and disk operations via the monoio runtime. The server operates as a single-threaded event loop per process, allowing it to scale by running multiple processes across CPU cores.

Userspace eBPF Scripting

Instead of a configuration file, zeroserve uses eBPF programs (written in C) located in .zeroserve/scripts/. These scripts are JIT-compiled to native x86-64 machine code using async-ebpf (which vendors uBPF) and run entirely in userspace. This design removes the need for kernel-level CAP_BPF privileges.

Security and Execution

  • Pointer Caging: To replace the kernel verifier, zeroserve uses a pointer cage that masks every memory access into the script's own arena, preventing unauthorized memory reads or writes.
  • Preemption: The runtime is fully preemptible. A timer interrupts JIT-compiled code to prevent a single slow script from stalling the event loop.
  • Execution Flow: Scripts run in sorted filename order, sharing a per-request metadata map. If a script calls zs_respond or zs_reverse_proxy, the chain short-circuits.

Scripting Capabilities

Scripts have access to a broad helper surface, including:

  • Request Mutation: Reading and rewriting URIs, methods, and headers.
  • JSON Handling: Parsing request bodies and generating JSON responses via zs_json_respond.
  • Security: SHA-256, HMAC-SHA256, and a complete OIDC login flow (Authorization Code + PKCE) using sealed XChaCha20-Poly1305 cookies for stateless session management.
  • Infrastructure: Rate limiting via token buckets and AWS SigV4 signing for S3 integration.

Performance Benchmarks

In benchmarks conducted on an 8-core Ryzen 7 3700X against nginx 1.26 and Caddy 2.11 (all pinned to a single core), zeroserve demonstrated superior performance in several key areas.

Static File Serving (HTTPS)

For small static files (174 B), zeroserve achieved 36,681 req/s, outperforming nginx (31,226 req/s) and Caddy (12,830 req/s). For large files (100 KB), zeroserve and nginx performed similarly, with zeroserve reaching approximately 780 MB/s.

Scripting Throughput

When compared to nginx + LuaJIT, zeroserve's eBPF scripts showed significant performance gains when the preemption timer was tuned to 10ms:

  • Header Injection: zeroserve eBPF reached 43,709 req/s, compared to nginx Lua's 28,653 req/s.
  • Dynamic JSON: zeroserve eBPF reached 46,945 req/s, compared to nginx Lua's 41,231 req/s.

Reverse Proxying

For small responses (174 B), zeroserve's pooled io_uring proxy achieved 26,486 req/s, beating nginx (21,761 req/s) and Caddy (7,683 req/s). However, for large proxied bodies (100 KB), nginx remained the most efficient, achieving 5,882 req/s compared to zeroserve's 3,631 req/s.

Modern TLS Implementation

zeroserve includes a comprehensive transport security stack terminated by BoringSSL, featuring:

  • TLS 1.3 Only: Strict adherence to the latest standard.
  • Encrypted Client Hello (ECH): Prevents the SNI from appearing in cleartext.
  • JA4 Fingerprinting: Client fingerprinting exposed directly to eBPF scripts.
  • ECH Relay Mode: Forwards undecryptable handshakes to an upstream server to mask protected names.

Community Perspectives and Critique

Discussion among technical users highlights both the potential and the skepticism surrounding the project's approach:

"I think the bet is misplaced - people prefer configuration over code and long have. The built-ins meet enough peoples needs entirely and they don't need to write C code."

Other critics pointed to the "AI-generated" nature of the announcement and the lack of established community trust compared to industry standards like Nginx. Technical suggestions from the community included the addition of Rust support for eBPF scripts (via .rs files) and the implementation of kTLS to avoid pumping userspace SSL after the handshake.

Sources