feat: add inbound header validation and tests to trace package

[daveseddon-runpod]

What

Harden and test the shared trace package — the cross-service X-Trace-* header contract that host, hapi, proxy, and the RunPod GraphQL API all speak.

Part of the end-to-end X-Trace-ID tracing effort (RunPod GraphQL → hapi/proxy → host, propagate-or-generate at every hop).

Changes

Go — trace/trace.go

• Inbound-header validation: an X-Trace-ID / X-Request-ID that is empty, over maxIDLen (200), or contains a byte outside [A-Za-z0-9._-] (CR/LF, control, space) is rejected and regenerated — prevents header/log injection (CWE-93). X-Trace-Source / X-Request-Source are validated and blanked (not regenerated) when invalid.
• Allocation-free byte-scan validator (validID) — 0 allocs/op.
• Guarded the X-Trace-Start parse so the common no-header path skips time.Parse.
• Removed the now-unused orelse generic.

Python — py/trace.py

• Fixed Trace.new() (datetime.now() AttributeError) and the save_to_headers tuple bug (X-Request-ID stored as a 1-tuple via a trailing comma); now emits the same five headers as Go with a fresh X-Request-ID.
• Mirrored the Go validation (_valid_id / _resolve_id / _resolve_source).

Tests

• trace/trace_test.go — table-driven ({description, input, expected}): validID, resolveID, resolveSource, FromHeaderOrNew (present/absent/poisoned/source-drop), trace-start (absent/past/invalid/future-clamp), SaveToHeader round-trip, ClientMiddleware/ServerMiddleware, New() uniqueness (10k), AllocsPerRun (0-alloc validID), plus benchmarks.
• py/trace_test.py — unittest table-driven mirror incl. a regression test per fixed bug.

Docs — README ## Tracing now carries the header contract table, Go inbound/outbound/response-echo usage, and the inbound-validation behavior.

Benchmarks (-benchmem)

BenchmarkFromHeaderOrNew/present     1057 ns/op    32 B/op    2 allocs/op
BenchmarkFromHeaderOrNew/absent      1899 ns/op   160 B/op    6 allocs/op
BenchmarkFromHeaderOrNew/invalid     2220 ns/op   160 B/op    6 allocs/op
BenchmarkValidID                      128 ns/op     0 B/op    0 allocs/op
BenchmarkSaveToHeader                1694 ns/op   136 B/op    8 allocs/op
BenchmarkClientMiddlewareRoundTrip   3982 ns/op   872 B/op   15 allocs/op

validID meets the 0-alloc requirement; the 6-alloc paths are unavoidable UUID generation. Negligible against network I/O.

Verification

• Go: go test -race ./... pass; benchmarks run.
• Python: unittest — 8 tests pass.

Follow-up

Tag a new module version (e.g. v0.1.2) so host / hapi / proxy can bump their require and pick up the inbound sanitization. Backward compatible — the only visible change is that a hostile inbound id is regenerated.

🤖 Generated with Claude Code