feat(server): add report-api server for dynamic metadata assembly

[meyer9]

Summary

Adds server/ — an HTTP server for the benchmark report UI — to this open-source repo. This implements the aggregation, comparison-synthesis, and caching logic.

No centralized metadata.json

The server never writes or reads a single merged metadata file. Instead:

1. Each benchmark run writes its results under its own S3 prefix (<outputDir>/metrics-*.json, then <outputDir>/metadata.json last as the commit signal).
2. The server lists all */metadata.json objects, merges them, applies retention, and serves the result dynamically.
3. A content-fingerprint cache (per-file keyed on ETag + merged result with 1h TTL) keeps the steady-state cost to one ListObjectsV2 call per request.

The legacy metadata/metadata-<timestamp>.json layout is ignored — the server skips that prefix.

What's in server/

server/
├── cmd/main.go                     HTTP server entry point (Gin, CLI flags)
├── internal/
│   ├── config/                     CLI flags + config struct
│   ├── handlers/                   HTTP handlers (metadata, metrics, load-tests, health)
│   └── services/
│       ├── s3.go                   S3 listing, per-file cache, merged-result cache, retention
│       ├── comparison.go           Synthetic [Compare: Time] + [Compare: Versions] groups
│       └── cache.go                In-memory TTL cache (for per-run metrics files)
└── README.md

Endpoints:

Endpoint	Description
GET /output/metadata.json	Merged, retained, comparison-enriched run list
GET /output/<outputDir>/metrics-<role>.json	Per-block timeseries for one run
GET /api/v1/load-tests/:network	Load test run list
GET /api/v1/load-tests/:network/:timestamp	Single load test result
GET /api/v1/health	Health check

The comparison groups ([Compare: Time] / [Compare: Versions]) are generated server-side and injected into the metadata response. The existing report UI surfaces them in the existing dropdown with no frontend changes. On the chart comparison page, Show Line Per: TimeBucket (1d/1w/1m) or Show Line Per: ClientVersion splits the overlay.

Cache design:

• Per-file byte cache keyed on <s3key>|<etag> — invalidated when a file is overwritten (new ETag), so a resubmitted or corrected run is never missed.
• Merged result cache keyed on fingerprint of {key, etag} pairs + 1h TTL — the TTL handles the time.Now() dependence in retention and comparison-bucket synthesis; without it, the 14-day window and 1d/1w/1m buckets would be frozen at the first rebuild indefinitely.

Tests

14 unit tests ported from base-benchmarking covering the comparison synthesizer: time-bucket grouping, version grouping, latest-per-variant, no source mutation, monthly-prefix regression, network scoping, stable IDs, TimeBucket stamping, createdAt=now on synthetic clones, and canonicalTestName/slugify.

All existing runner/ tests still pass. go vet and gofmt clean.

Data contract

See docs/report-data-contract.md for what producers must write for runs to appear in the report.

type=routine
risk=low
impact=sev5

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[meyer9]

Fixed in 0b51c7c.

All three CodeQL path-traversal findings addressed via a new safePath(rel string) helper on LocalService. It uses filepath.Clean + strings.HasPrefix to verify the resolved path stays within the root ls.dir:

func (ls *LocalService) safePath(rel string) (string, error) {
    abs := filepath.Clean(filepath.Join(ls.dir, rel))
    base := filepath.Clean(ls.dir) + string(filepath.Separator)
    if abs != filepath.Clean(ls.dir) && !strings.HasPrefix(abs, base) {
        return "", fmt.Errorf("path %q escapes root directory", rel)
    }
    return abs, nil
}

GetObject, ListLoadTests, and GetLoadTest all call safePath before any filesystem access. Added TestLocalService_PathTraversalBlocked covering ../etc/passwd, ../../secret, and run-a/../../outside — all correctly return errors.

[meyer9]

Updated in 346a48c.

The previous safePath implementation used strings.HasPrefix against a manually-constructed base path. CodeQL didn't recognize this as a sanitizer and continued flagging the call sites on the new scan.

Switched to filepath.Rel: if the resolved path has a relative path from the root that starts with ..., it's outside the root and the request is rejected. This is the idiomatic Go pattern for path-traversal defense and should be recognized by the scanner.

relPath, err := filepath.Rel(rootClean, abs)
if err != nil || strings.HasPrefix(relPath, "..") {
    return "", fmt.Errorf("path %q escapes root directory", rel)
}

All 7 LocalService tests still pass including TestLocalService_PathTraversalBlocked.