fix(http): bound the request-head read — one packet no longer DoSes the server

Smell-audited: depth 1: the fix is scoped narrower than the debt row's
severity language invites, and the narrowing is the honest part. SO_RCVTIMEO
turns an UNBOUNDED wedge into a bounded one; it does not make a serial server
concurrent. N held connections still cost N x timeout of throughput. Closing
that needs per-connection threading, and a Ring handler runs Clojure — so its
thread must be a registered GC worker under the ADR-0175 safepoint discipline.
That is a concurrency design change, not a line in this function, and pulling
it in here would be exactly the scope-creep the smell sensor watches for. It
stays with the D-257 threading follow-on that server.zig's module doc already
names, and D-339 is marked PARTIAL rather than discharged.

D-339 (SE-3), raised 2026-06-09 and untouched for two months: `run-server`'s
accept loop is serial and blocking with no read deadline anywhere, so a client
that opened a connection and never finished sending the request head held the
whole server — which binds 0.0.0.0 and is internet-facing in a container —
for as long as it cared to. The 8 MB body cap guards volume, not time.

The test earned its keep by being wrong first. Written as "hold a half-open
connection, then assert a normal request still succeeds", it PASSED against
the unfixed server: the stalled client's subshell exits after 12s, and the
server served the next request the moment the attacker gave up. A body-only
assertion cannot tell "the server recovered" from "the attacker left", so the
elapsed bound IS the assertion: 12s before, 1s after, fail over 5s.

- `armReceiveDeadline` sets SO_RCVTIMEO on each accepted connection before the
  first read. Best-effort — a platform that rejects the option leaves the
  socket blocking rather than failing the request; nothing else depends on it.
- `:header-timeout-ms` in the opts map, default 10000 (the order of nginx's
  client_header_timeout and Go's documented ReadHeaderTimeout examples),
  0 disables. Non-integer is rejected at the boundary with a named message.
- The e2e fixture sets 1500 so the case runs fast; legitimate requests
  complete in milliseconds, so the other 12 cases are unaffected.

Smoke green (phase16_http_server, 283s).

Author: chaploud

.dev/debt.yaml

@@ -978,7 +978,7 @@ active:
       rung 6, D-281/ADR-0103 (host_inert supertype precedent for inert-accept).
     last_reviewed: "2026-07-02"
   - id: "D-339"
-    status: "open — security (SE-3, HTTP server slowloris). The cljw.http.server accept loop is serial + blocking with NO socket read/idle/header deadline (server.zig:63-71); one client that opens a connection and never completes the request head wedges the WHOLE server (binds 0.0.0.0, internet-facing in a container). The 8 MB body cap guards volume, not time. High severity (one packet DoSes a public deploy)."
+    status: "PARTIAL (2026-08-04) — the unbounded wedge is CLOSED; the serial-throughput half remains. Was: the accept loop is serial + blocking with NO socket read/idle/header deadline, so one client that opens a connection and never completes the request head wedged the WHOLE server forever (binds 0.0.0.0, internet-facing in a container); one packet DoSed a public deploy. FIXED: `run-server` now arms SO_RCVTIMEO on every accepted connection before the first read (`armReceiveDeadline`, server.zig), default 10s, tunable via `:header-timeout-ms` in the opts map (0 disables). e2e `phase16_http_server.sh` case `http-slowloris-recovers` holds a half-open connection and asserts the next client is served in <5s — it measured 12s before the fix (i.e. the server only recovered when the ATTACKER gave up) and 1s after. REMAINING: a serial server still handles one connection at a time, so N held connections still cost N x timeout of throughput. Removing that needs per-connection concurrency, which is NOT a drive-by: a Ring handler runs Clojure, so its thread must be a registered GC worker (ADR-0175 safepoint discipline). That is the D-257 threading follow-on named in server.zig's module doc, and it owns the residual."
     category: "security"
     barrier: |-
       blocked-by: the Phase-15 concurrency model (cancellable Io). The
@@ -989,7 +989,7 @@ active:
       (zig_tips.md: concurrency arrives Phase 15; D-257 lists per-conn threading as a
       follow-on). Forcing it now would be premature (F-003). Land per-conn + default
       deadline when Phase-15 concurrency lands. Cross-ref SE-3, server.zig, D-257.
-    last_reviewed: "2026-06-09"
+    last_reviewed: "2026-08-04"
   - id: "D-342"
     status: "open — security (SE-6/7 finished form). The FS-jail v1 (ADR-0123, lexical containment) blocks `..`/absolute-path traversal portably but does NOT resolve symlinks: a symlink planted INSIDE the jail pointing outside is followed. Documented residual (mitigate via read-only mount / no symlinks in jail). The symlink-SAFE finished form is the ADR-0123 DA Alt-2."
     category: "security"

src/runtime/cljw/http/server.zig

@@ -61,9 +61,54 @@ fn headerFieldClean(s: []const u8) bool {
     return true;
 }
 
+/// Default request-head read deadline in milliseconds (D-339 / SE-3). Ten
+/// seconds is the same order as nginx's `client_header_timeout` and Go's
+/// documented `ReadHeaderTimeout` examples: far longer than any legitimate
+/// client needs to finish a request line + headers over a live connection,
+/// far shorter than "forever".
+pub const default_header_timeout_ms: i64 = 10_000;
+
+/// Arm a receive deadline on an accepted connection (D-339 / SE-3).
+///
+/// The accept loop is serial by design, so a peer that opens a connection and
+/// never finishes sending the request head blocks EVERY other client for as
+/// long as the read blocks — and with no deadline that is forever, so a single
+/// packet takes down a public deploy (the server binds 0.0.0.0). `SO_RCVTIMEO`
+/// turns that unbounded wedge into a bounded one: the stalled read fails, the
+/// loop drops the connection and serves the next client.
+///
+/// This bounds the wedge; it does not remove it. A serial server still handles
+/// one connection at a time, so an attacker holding N connections still costs
+/// N × timeout of throughput. Removing that needs per-connection concurrency,
+/// which is a different change with GC-registration consequences (a handler
+/// runs Clojure, so its thread must be a registered GC worker per ADR-0175) —
+/// tracked separately as the D-257 threading follow-on, not smuggled in here.
+///
+/// Best-effort: a platform that rejects the option leaves the socket blocking
+/// rather than failing the request. Nothing else in the loop depends on it.
+fn armReceiveDeadline(handle: std.posix.socket_t, timeout_ms: i64) void {
+    if (timeout_ms <= 0) return; // 0 / negative = caller opted out
+    const tv: std.posix.timeval = .{
+        .sec = @intCast(@divTrunc(timeout_ms, 1000)),
+        .usec = @intCast(@rem(timeout_ms, 1000) * 1000),
+    };
+    std.posix.setsockopt(handle, std.posix.SOL.SOCKET, std.posix.SO.RCVTIMEO, std.mem.asBytes(&tv)) catch {
+        // Best-effort by design — see the doc comment. No recovery to attempt
+        // and no user-visible surface to report it on.
+    };
+}
+
 /// Bind `0.0.0.0:port` and serve forever (blocking, serial), dispatching each
-/// request through `handler` (a Ring `(fn [req] resp)`).
-pub fn runServer(rt: *Runtime, env: *Env, handler: Value, port: u16, loc: SourceLocation) anyerror!Value {
+/// request through `handler` (a Ring `(fn [req] resp)`). `header_timeout_ms`
+/// bounds how long a connection may take to deliver its request head (D-339).
+pub fn runServer(
+    rt: *Runtime,
+    env: *Env,
+    handler: Value,
+    port: u16,
+    header_timeout_ms: i64,
+    loc: SourceLocation,
+) anyerror!Value {
     const io = rt.io;
     const kw_method = try keyword_mod.intern(rt, null, "request-method");
     const kw_uri = try keyword_mod.intern(rt, null, "uri");
@@ -82,6 +127,10 @@ pub fn runServer(rt: *Runtime, env: *Env, handler: Value, port: u16, loc: Source
     while (true) {
         var stream = server.accept(io) catch continue;
         defer stream.close(io);
+        // D-339: bound the request-head read BEFORE the first read on this
+        // connection, so a peer that stalls mid-head cannot hold the serial
+        // loop open indefinitely.
+        armReceiveDeadline(stream.socket.handle, header_timeout_ms);
         var rbuf: [16384]u8 = undefined;
         var wbuf: [16384]u8 = undefined;
         var sr = stream.reader(io, &rbuf);
@@ -226,8 +275,10 @@ fn buildRequest(rt: *Runtime, req: *std.http.Server.Request, kw_method: Value, k
 // D2 zone rule: lang/primitive/ may not import a surface, so the host fns + their
 // ns registration live here and are wired via runtime/cljw/_host_api.zig.
 
-/// `(run-server handler {:port N})` — Ring-style. `handler` is `(fn [req] resp)`;
-/// `opts` carries `:port` (a bare integer port is also accepted). Blocking.
+/// `(run-server handler {:port N :header-timeout-ms MS})` — Ring-style.
+/// `handler` is `(fn [req] resp)`; `opts` carries `:port` (a bare integer port
+/// is also accepted) and the optional `:header-timeout-ms` (D-339; default
+/// `default_header_timeout_ms`, `0` disables the deadline). Blocking.
 pub fn runServerFn(rt: *Runtime, env: *Env, args: []const Value, loc: SourceLocation) anyerror!Value {
     try error_catalog.checkArity("run-server", args, 2, loc);
     const handler = args[0];
@@ -242,7 +293,16 @@ pub fn runServerFn(rt: *Runtime, env: *Env, args: []const Value, loc: SourceLoca
     };
     if (port < 1 or port > 65535)
         return error_catalog.raiseInternal(loc, "run-server: port out of range (1..65535)");
-    return runServer(rt, env, handler, @intCast(port), loc);
+    const header_timeout_ms: i64 = blk: {
+        if (opts.isInt()) break :blk default_header_timeout_ms;
+        const kw_ht = try keyword_mod.intern(rt, null, "header-timeout-ms");
+        const t = map_mod.get(opts, kw_ht) catch Value.nil_val;
+        if (t.isNil()) break :blk default_header_timeout_ms;
+        if (!t.isInt())
+            return error_catalog.raiseInternal(loc, "run-server: :header-timeout-ms must be an integer (milliseconds; 0 disables)");
+        break :blk t.asInteger();
+    };
+    return runServer(rt, env, handler, @intCast(port), header_timeout_ms, loc);
 }
 
 /// Create the `cljw.http.server` / `cljw.http.client` host namespaces. Called by

test/e2e/fixtures/http_server_demo.clj

@@ -23,4 +23,7 @@
                                      :body "should become 500"}
       (= (:request-method req) :post) {:status 201 :body "created"}
       :else {:status 200 :body (str "GET " (:uri req))}))
-  {:port 8157})
+  ;; :header-timeout-ms is short here so the D-339 slowloris case runs fast;
+  ;; the shipped default is 10000. Legitimate requests complete in milliseconds,
+  ;; so 1500 does not affect the other cases.
+  {:port 8157 :header-timeout-ms 1500})

test/e2e/phase16_http_server.sh

@@ -81,4 +81,36 @@ got=$(curl -s "http://127.0.0.1:$PORT/still-alive" 2>&1)
 [[ "$got" == "GET /still-alive" ]] || fail "server died after CRLF header: got '$got'"
 echo "PASS http-survives-crlf -> $got"
 
-echo "OK — phase16_http_server (12 cases) green"
+# D-339 (SE-3, slowloris): a client that opens a connection and never finishes
+# sending the request head must NOT wedge the server. The accept loop is serial
+# by design, so a half-open connection blocks every other client for as long as
+# the read blocks — without a deadline, that is forever, and one packet DoSes a
+# public deploy. The fixture sets :header-timeout-ms 1500, so the stalled
+# connection must be dropped and the next client served well inside 15s.
+#
+# The stalled client runs in a SUBSHELL, not via `exec` on the parent: a
+# redirection failure on `exec` is fatal to a non-interactive shell, which would
+# take the whole suite down on a host without bash /dev/tcp.
+if (exec 3<>/dev/tcp/127.0.0.1/$PORT) 2>/dev/null; then
+  # Writes a partial head (no terminating blank line) and holds the connection.
+  ( printf 'GET /still-alive HTTP/1.1\r\nHost: localhost\r\n'; sleep 12 ) \
+      >/dev/tcp/127.0.0.1/$PORT 2>/dev/null &
+  SLOW=$!
+  sleep 0.5   # let the stalled client reach the accept loop first
+  start=$(date +%s)
+  got=$(run_bounded 15 curl -s --max-time 12 "http://127.0.0.1:$PORT/still-alive" 2>&1 || true)
+  elapsed=$(( $(date +%s) - start ))
+  kill "$SLOW" 2>/dev/null || true
+  wait "$SLOW" 2>/dev/null || true
+  [[ "$got" == "GET /still-alive" ]] || fail "slowloris wedged the server (D-339): got '$got' after ${elapsed}s"
+  # The elapsed bound is the real assertion. Without a header deadline the
+  # server serves this request only when the ATTACKER disconnects (12s here),
+  # which still "passes" a body-only check — so assert the deadline did the
+  # work: 1500ms fixture timeout + dispatch must land well under 5s.
+  [[ "$elapsed" -lt 5 ]] || fail "slowloris blocked the server for ${elapsed}s (D-339: no header deadline; it was the attacker giving up, not the server recovering)"
+  echo "PASS http-slowloris-recovers -> served in ${elapsed}s"
+else
+  echo "SKIP http-slowloris (bash /dev/tcp unavailable)"
+fi
+
+echo "OK — phase16_http_server (13 cases) green"