h3-python-sdk-e2e-battery-43-43

Answer

The due-cycle E2E (tick #93, window #88-93, closing #98 non-deferrable) requires the canonical harness — a /tmp uvicorn runner composing FastAPI + create_router(EchoHarness()) + add_middleware on <ip-address>:8777 — not the example app (examples/echo_app.py) which binds :8000 under __main__. Two real bugs were found and fixed while standing this up.

1. Canonical runner (/tmp/echo_harness_runner.py) — uvicorn target, binds 8777:

from fastapi import FastAPI
from h3_shim import EchoHarness, add_harness_middleware, create_router

app = FastAPI(title="echo-harness-canonical")
app.include_router(create_router(EchoHarness()))
add_harness_middleware(app)

2. Fix A — HEAD/OPTIONS were 405. FastAPI 0.141 / Starlette 1.4 does not auto-register HEAD/OPTIONS on GET-only routes (verified empirically: 405, allow: GET). The canonical create_router must declare them explicitly; per-path OPTIONS return real Allow headers:

router.add_api_route("/health", h.health, methods=["GET", "HEAD"])     # HEAD on every GET
...
options_routes = {"/echo/echo": "GET, HEAD, POST, OPTIONS", "/echo/echo/raw": "GET, HEAD, POST, PUT, DELETE, OPTIONS", ...}
def make_options(allow: str) -> Callable[[], Response]:
    async def handler() -> Response:
        return Response(status_code=200, headers={"allow": allow})
    return handler
for path, allow in options_routes.items():
    router.add_api_route(path, make_options(allow), methods=["OPTIONS"])

3. Fix B — no catch-all OPTIONS route. A /{rest:path} OPTIONS catch-all partially matches unknown paths and turns their 404s into 405s (broke unknown route 404 and middleware covers 404s). Explicit per-path routes keep 404 semantics intact.

4. Middleware contract (in add_harness_middleware): every response gets X-Request-ID (honoring an incoming id, idempotent retries), X-Served-By: echo-harness, and X-Process-Time — including error responses (500/404).

5. Lifecycle (shim venv at /tmp/h3-shim-venv, SDK installed editable):

cd /tmp
setsid nohup /tmp/h3-shim-venv/bin/uvicorn echo_harness_runner:app \
    --host <ip-address> --port 8777 --log-level warning > /tmp/uvicorn_8777.log &
sleep 3 && ss -ltnp | grep 8777                    # verify listening
/tmp/h3-shim-venv/bin/h3-test --endpoint http://<ip-address>:8777 --json
fuser -k 8777/tcp && sleep 1 && ss -ltnp | grep 8777 || echo "port 8777 FREE"

h3-test runs the 43-test battery (ping/health/version, GET/POST/raw echo round-trips incl. unicode/binary/10k, status codes 204-503, 404/405/422 semantics, latency 5/25ms, meta/client-host, header passthrough, HEAD/OPTIONS, middleware coverage, post↔get integrity) and exits 0 only on 43/43.