ci(h2spec): harden gate + restore mbedtls header trigger (Codex review)

Builds on the parallel fixes already on this branch (VEXE unset; server*.v /
http*.v added to the paths filter), addressing the remaining Codex items:

- run_h2spec.sh: a recorded baseline case that now PASSES fails the gate (was a
  soft warning), forcing its removal from h2spec_expected_failures.txt so the
  gate cannot silently keep allowing a since-fixed case (Codex P2).
- run_h2spec.sh: resolve $VEXE/$H2SPEC_BIN against the caller's cwd before the
  script cd's into its own dir, so relative values (e.g. VEXE=./vnew) work even
  if re-enabled, and a relative H2SPEC_BIN resolves correctly (Codex P1/P3).
- .github/workflows/h2spec.yml: mbedtls trigger back to `**` (not `*.v`) so the
  #insert'ed headers (mbedtls_helpers.h / mbedtls_threading.h), which affect
  TLS/ALPN, also fire the gate (Codex P2).
- run_h2spec.sh: run h2spec with --timeout 5 (H2SPEC_TIMEOUT). Several cases
  (CONTINUATION sequencing, unknown error codes) wait for the server's
  GOAWAY/close and flake at h2spec's 2s default under load; the 37-case baseline
  is stable at 5s across repeated runs.

Co-Authored-By: WOZCODE <contact@withwoz.com>

Author: quaesitor-scientiam

.github/workflows/h2spec.yml

@@ -12,7 +12,9 @@ on:
       - 'vlib/net/http/server*.v'
       - 'vlib/net/http/http*.v'
       - 'vlib/net/http/h2spec/**'
-      - 'vlib/net/mbedtls/*.v'
+      # `**` (not `*.v`): mbedtls.c.v #inserts mbedtls_helpers.h / mbedtls_threading.h,
+      # so TLS/ALPN behavior can change via the headers too (Codex P2).
+      - 'vlib/net/mbedtls/**'
       - '.github/workflows/h2spec.yml'
   pull_request:
     paths: *h2paths

vlib/net/http/h2spec/README.md

@@ -43,9 +43,15 @@ runner never installs anything — it expects `h2spec` to be provided.
   server driver `test_server_tls_h2_negotiation` exercises end-to-end).
 - ✅ **The harness was run end-to-end with a pinned h2spec v2.6.0**: 146 tests,
   **109 pass / 37 fail** against the server at this branch's base. The 37-failure
-  set was **identical across repeated runs** (deterministic), and is recorded in
-  `h2spec_expected_failures.txt` as the gate baseline. The JUnit parser is
-  validated against that real report.
+  set was **identical across four runs** (`--timeout 2` and `--timeout 5`, two
+  each) and is recorded in `h2spec_expected_failures.txt` as the gate baseline.
+  The JUnit parser is validated against those real reports.
+- ⚠️ **Timing flakiness — handled.** A *separate* handful of h2spec cases
+  (CONTINUATION sequencing, unknown error codes) wait for the server's GOAWAY/close
+  and flake at h2spec's 2s default under load. The runner therefore uses
+  `--timeout 5` (`H2SPEC_TIMEOUT`). The lesson: always confirm the failure set is
+  stable across repeated runs before trusting a per-case h2spec gate — a single
+  run can mis-attribute a flaky timeout as a real failure (or regression).
 - The baseline reflects genuine server-side conformance gaps (see the file's
   header). Each is a tracked item; remove a line as the server is hardened.
 - The baseline was generated locally; the first CI run on Linux validates it. If

vlib/net/http/h2spec/h2spec_expected_failures.txt

@@ -8,8 +8,13 @@
 # passing, run_h2spec.sh warns so the line can be removed and the gate tightened.
 #
 # Generated with h2spec v2.6.0 against the net.http server at this branch's base
-# (146 tests: 109 pass, 37 fail; the set was identical across repeated runs, i.e.
-# deterministic). These are genuine server-side conformance gaps: stricter request
+# (146 tests: 109 pass, 37 fail). The set was identical across four runs (h2spec
+# --timeout 2 and --timeout 5, two each) — stable. NOTE: a handful of OTHER h2spec
+# cases (CONTINUATION sequencing, unknown error codes) are timing-flaky at h2spec's
+# 2s default — they wait for the server's GOAWAY/close — so run_h2spec.sh uses
+# --timeout 5 (H2SPEC_TIMEOUT) to keep the gate stable. Do not add a flaky case to
+# this list; raise the timeout instead. These 37 are genuine server-side conformance
+# gaps: stricter request
 # validation (uppercase/duplicate/missing pseudo-headers, connection-specific & TE
 # headers, content-length vs DATA), HPACK decode error SCOPE (must be a
 # connection-level COMPRESSION_ERROR, not RST_STREAM), the stream state machine

vlib/net/http/h2spec/run_h2spec.sh

@@ -16,22 +16,43 @@
 # `go install` — the version must be pinned and reproducible.
 #
 # Env:
-#   VEXE        path to the V compiler (default: ./v then ./vnew)
-#   H2SPEC_BIN  path to the h2spec binary (default: h2spec on PATH)
-#   H2SPEC_PORT port for the target server (default: 18443)
-#   VFLAGS_CC   extra V flags, e.g. '-cc gcc' (mbedtls needs a real C compiler)
+#   VEXE           path to the V compiler (default: ./v then ./vnew)
+#   H2SPEC_BIN     path to the h2spec binary (default: h2spec on PATH)
+#   H2SPEC_PORT    port for the target server (default: 18443)
+#   H2SPEC_TIMEOUT h2spec per-case timeout, seconds (default: 5). Several h2spec
+#                  cases wait for the server's GOAWAY/close and FLAKE at h2spec's
+#                  2s default under load; 5s is comfortably stable here. Raise it
+#                  if a timing case still flakes on a slow runner.
+#   VFLAGS_CC      extra V flags, e.g. '-cc gcc' (mbedtls needs a real C compiler)
 
 set -uo pipefail
+orig_pwd="$(pwd)" # the caller's cwd, captured BEFORE we cd into the script dir
 cd "$(dirname "$0")"
 here="$(pwd)"
 repo_root="$(cd ../../../.. && pwd)"
 
+# resolve a caller-supplied path argument: an absolute path or a bare command name
+# (PATH lookup, e.g. "h2spec") is used as-is; a relative path is resolved against
+# the caller's original cwd, since we cd'd into the script dir above. Without this,
+# a documented value like `VEXE=./vnew` (relative to the repo root) would wrongly
+# resolve to vlib/net/http/h2spec/vnew and the build would fail. (Codex P1/P3.)
+resolve_path() {
+    case "$1" in
+        /*) printf '%s' "$1" ;;            # absolute path
+        */*) printf '%s' "$orig_pwd/$1" ;; # relative path containing a slash
+        *) printf '%s' "$1" ;;             # bare name -> PATH lookup
+    esac
+}
+
 VEXE="${VEXE:-}"
 if [ -z "$VEXE" ]; then
     if [ -x "$repo_root/v" ]; then VEXE="$repo_root/v"; elif [ -x "$repo_root/vnew" ]; then VEXE="$repo_root/vnew"; else VEXE="v"; fi
+else
+    VEXE="$(resolve_path "$VEXE")"
 fi
-H2SPEC_BIN="${H2SPEC_BIN:-h2spec}"
+H2SPEC_BIN="$(resolve_path "${H2SPEC_BIN:-h2spec}")"
 PORT="${H2SPEC_PORT:-18443}"
+TIMEOUT="${H2SPEC_TIMEOUT:-5}"
 SERVER_BIN="$here/h2spec_server.bin"
 EXPECTED="$here/h2spec_expected_failures.txt"
 
@@ -64,7 +85,7 @@ echo "==> running h2spec (TLS, insecure cert OK)"
 # contract, unlike the pretty console output. A failing case has a <failure>
 # (or <error>) child; we use "classname :: name" as the stable case ID.
 report_xml="$here/h2spec_report.xml"
-"$H2SPEC_BIN" -t -k -h 127.0.0.1 -p "$PORT" --junit-report "$report_xml" 2>&1 | tail -40 || true
+"$H2SPEC_BIN" -t -k -h 127.0.0.1 -p "$PORT" --timeout "$TIMEOUT" --junit-report "$report_xml" 2>&1 | tail -40 || true
 if [ ! -s "$report_xml" ]; then
     echo "ERROR: h2spec produced no JUnit report ($report_xml); check the flags/version." >&2
     exit 2
@@ -92,9 +113,13 @@ if [ -n "$new_failures" ]; then
     rc=1
 fi
 if [ -n "$now_passing" ]; then
-    echo "::warning:: these recorded failures now PASS — remove them from h2spec_expected_failures.txt:" >&2
+    # Fail too (not just warn): a recorded failure that now passes must be removed
+    # from the baseline, otherwise the gate keeps allowing that case and a later
+    # PR can reintroduce the failure unnoticed. (Codex P2.) The 37 baseline cases
+    # are deterministic at H2SPEC_TIMEOUT=5, so this does not flap.
+    echo "::error:: these recorded failures now PASS — remove them from h2spec_expected_failures.txt to keep the gate honest:" >&2
     echo "$now_passing" >&2
-    # Treat as a (soft) failure so the baseline is tightened; flip to rc=1 once green.
+    rc=1
 fi
 [ "$rc" -eq 0 ] && echo "==> h2spec: no regressions vs baseline"
 exit "$rc"