darkhttpd-rs

darkhttpd-rs is a Rust port of darkhttpd, built as a small proving ground for evidence-driven C-to-Rust ports before tackling larger infrastructure such as nginx.

The goal is not to invent a new HTTP server API. The goal is to preserve the observable behavior of the pinned C reference while making the porting process auditable: every claim is backed by an oracle, runner, benchmark, or evidence blob in the harness ledger.

Pinned upstream:

• Repo: https://github.com/emikulic/darkhttpd
• Commit: 7b9cafa48cf39f64342435eb029733c48f2cca01
• C source: one darkhttpd.c file, 3,200 LoC
• License: ISC

Status

Surface	C reference	darkhttpd-rs	How to reproduce
Upstream devel/test.py	reference	62 / 62	bash harness/oracle/run-official.sh
HTTP wire oracle	reference	4 / 4	bash harness/oracle/run-smoke.sh --diff
Security seed	reference	1 / 1	bash harness/security/run.sh
Static-small benchmark	reference	1.12x reference throughput	bash harness/bench/run.sh
ApacheBench keep-alive benchmark	reference	2.15x reference throughput	bash harness/bench/run-ab-keepalive.sh
Workspace tests	n/a	201 / 201	cargo test --workspace

Latest local benchmark row:

Workload	C reference	darkhttpd-rs	Ratio	C p99	Rust p99
1 KiB static file, new TCP connection per request	10,616 req/s	11,845 req/s	1.12x	0.187 ms	0.127 ms
ApacheBench keep-alive, 200k requests, 50 concurrency	47,558 req/s	102,290 req/s	2.15x	2 ms	1 ms

This is a small loopback microbenchmark, not a production performance claim. The first row is useful because it caught a real design bug: an earlier Rust accept loop used a non-blocking listener plus sleep(10ms) on WouldBlock, dropping new-connection throughput to about 0.01x the C reference. The second row is a more realistic concurrent keep-alive smoke using the system ApacheBench binary.

Supported Surface

Implemented and tested:

• static GET and HEAD
• path traversal rejection
• directory listing
• directory trailing-slash redirect
• range requests
• If-Modified-Since
• HTTP/1.1 keep-alive
• MIME lookup and custom MIME map parsing
• sendfile fast path where supported, with fallback
• signal-triggered graceful shutdown
• pidfile creation/removal
• daemonize
• chroot / numeric uid / numeric gid privilege drop

Known limits:

• Not a production replacement yet.
• Not all optional darkhttpd devel/test_*.py files are wired into the public conformance claim.
• Symbolic --uid name / --gid name resolution is deferred; numeric ids work.
• Performance coverage is intentionally narrow: one static-file comparative benchmark plus the correctness suites.

Quick Start

bash harness/bootstrap-upstream.sh
cargo build --release
cargo test --workspace

Run the Rust server:

target/release/darkhttpd-rs harness/corpus/www --addr 127.0.0.1 --port 8080

Run the core evidence gates:

bash harness/oracle/run-smoke.sh --diff
bash harness/oracle/run-official.sh
bash harness/bench/run.sh
bash harness/bench/run-ab-keepalive.sh

The productized harness completion checker lives in the sibling port-harness repo:

python3 ../port-harness/loop/check-completion.py --project . --run-commands

Harness

The harness is intentionally part of the repo. It contains:

• harness/work-packets.jsonl: the packet queue used by agents
• harness/envelope.toml: claimed capabilities
• harness/completion.toml: the actual "done" contract
• harness/runners.toml: typed runner definitions
• harness/evidence/ledger.jsonl: append-only evidence ledger
• harness/evidence/runs/: content-addressed run evidence
• harness/dashboard/index.html: static dashboard generated from the ledger

The dashboard is explanatory. The source of truth is the completion contract plus the evidence ledger.

Docs

• docs/CONFORMANCE.md: compatibility status and commands
• docs/BENCHMARKS.md: performance methodology and latest row
• docs/SECURITY.md: security and fuzzing plan
• docs/DARKHTTPD_SYSTEM_MAP.md: source-system map
• docs/PORT_STRATEGY.md: phase plan and acceptance gates
• docs/RUNNING_NOTES.md: operational notes from the run