Skip to content

perf: cache compiled path regexes and cut request validation allocations - #340

Open
emilien-puget wants to merge 1 commit into
pb33f:mainfrom
emilien-puget:path-regex-cache
Open

emilien-puget wants to merge 1 commit into
pb33f:mainfrom
emilien-puget:path-regex-cache

Conversation

@emilien-puget

Copy link
Copy Markdown
Contributor

Goal

Request validation called helpers.GetRegexForPath for every path template on every request and recompiled the same regex each time, although the template is constant per route. This PR caches compiled regexes by template and then applies the same cache discipline to the rest of the request and response hot path: stop rebuilding per-request state, hoist per-call allocations out of loops, and reuse what the validator already built.

It closes the gap with libopenapi, which already caches its compiled JSONPath expressions the same way; the validator's request path was still recompiling on every request.

What changed

Commit Change
01df353 Cache compiled path regexes by template in helpers.GetRegexForPath (package-level sync.Map, LoadOrStore, invalid templates uncached), plus ClearRegexCache()
5501815 Cache brace indices with the compiled regex (GetBraceIndicesForPath); ExtractParamsForOperation no longer appends onto the model's own slice
5f5262e ValidateRequestSchema / ValidateResponseSchema accept pre-built ValidationOptions instead of building defaults per call
a6a047d nonEmptyPathSegments walks the path once (strings.SplitSeq) instead of Split + copy
71259a3 ExtractRawQueryValues returns nil for an empty query
ff19efc GetRenderedSchema returns the cached ReferenceSchema string instead of copying bytes per call
b941576 ValidateResponseHeaders accepts pre-built options through an unexported core; exported signature unchanged
ce3ba8e, 46c57ee, 3150fb0 Benchmark suite: 12 gateway scenarios, including query-heavy, invalid-request, concurrent, format-assertions, strict-server, urlencoded, JSON-response-body and 200-route shapes

Evidence

Paired runs, 10 samples per side, compared with benchstat (i7-1265U, Go 1.26). All bench and perf commits were measured individually with back-to-back before/after runs; the table below compares main against the full branch on all 12 scenarios. Allocation counts are exact (±0%), time is p<0.001 for the shapes this PR touches.

Scenario allocs/op sec/op Δ sec/op
Plain GET (1 uuid path param) 97 → 35 11.1 → 5.7 µs −48%
Param-heavy GET (2 path, query, header) 324 → 94 37.7 → 14.6 µs −61%
POST, JSON body 75 → 63 9.1 → 8.1 µs −25%
Response 200 + header 40 → 33 5.0 → 4.4 µs −12%
Query-heavy GET (4 query + enum header) 122 → 111 18.0 → 17.2 µs ~
Invalid request (error path) 326 → 96 42.5 → 16.7 µs −61%
Concurrent GET, 12 goroutines 97 → 35 6.7 → 2.4 µs −64%
Format assertions on 98 → 36 14.0 → 5.6 µs −60%
Strict server matching 99 → 37 13.2 → 7.4 µs −44%
Form-urlencoded body 97 → 85 13.3 → 11.2 µs −16%
JSON response body 53 → 44 7.7 → 7.4 µs ~
Large route table (200 paths) 114 → 35 12.6 → 5.0 µs −61%
geomean 120 → 59 (−51%) 13.0 → 7.6 µs −42%

Reproduce:

go test -run='^$' -bench='BenchmarkValidateHttpRequestSync|BenchmarkValidateHttpResponse' \
  -count=10 -benchmem -benchtime=50000x ./ .

Mechanism and memory

GetRegexForPath checks a package-level sync.Map keyed by the template string, then compiles and stores with LoadOrStore (concurrent callers race once; the loser's regex is discarded). The original body moved unchanged to an internal compile function. Invalid templates are not cached. The existing config.RegexCache option keeps working; this PR makes the default path fast with no configuration.

For bounding, this follows the cache convention libopenapi introduced for content-keyed caches: utils.ClearJSONPathCache() documents "Call this between document lifecycles in long-running processes to bound memory" and is wired into ClearAllCaches(). This PR adds the same contract as helpers.ClearRegexCache(). An entry holds a few KB (measured 4.3 KB: key string plus compiled regex), so a 1,000-route API costs about 4 MB.

One candidate was measured and rejected, and the negative result is recorded in the commit message: hoisting the per-segment regex out of the parameter loop cost +9% sec/op on the single-parameter shape (three precompute slices, nothing to dedupe), so it was reverted.

Verification

  • go test -race -count=1 ./... — 21/21 packages PASS (run after every change).
  • make lint (golangci-lint, repo config) — 0 issues.
  • New tests: cached pointer identity, errors stay uncached, ClearRegexCache, cached brace indices (identity + invalid template).
  • Remaining allocation leads are documented in the benchmark analysis (router extractPathParams maps, FindStringSubmatchIndex variant, integer math/big fast path); they touch the exported Route shape or vendored-schema behavior and are deliberately out of this diff.

@codecov

codecov Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.82%. Comparing base (754a5b7) to head (d2edbce).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #340      +/-   ##
==========================================
+ Coverage   98.74%   98.82%   +0.07%     
==========================================
  Files          94       95       +1     
  Lines       12310    12462     +152     
==========================================
+ Hits        12156    12316     +160     
+ Misses        129      125       -4     
+ Partials       25       21       -4     
Flag Coverage Δ
unittests 98.82% <100.00%> (+0.07%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Request validation called helpers.GetRegexForPath for every path
template on every request and recompiled the same regex each time, and
the rest of the request hot path rebuilt per-request state it could
reuse. This closes the gap with libopenapi, which caches compiled
JSONPath expressions the same way.

Changes:

- Cache compiled path regexes by template in GetRegexForPath
  (package-level sync.Map, LoadOrStore, invalid templates uncached),
  with ClearRegexCache() following the libopenapi cache convention of
  ClearJSONPathCache(). The brace indices are cached with the compiled
  regex; GetBraceIndicesForPath reads them from the same entry.
- ExtractParamsForOperation returns the model slices untouched when one
  side is empty and merges into an exact-size slice otherwise: appending
  to item.Parameters can write into the model backing array, and the
  model stays shared across validators and requests.
- ValidateRequestSchema, ValidateResponseSchema and
  ValidateResponseHeaders accept pre-built options through an unexported
  core; internal callers stop building config.NewValidationOptions per
  request. Exported signatures are unchanged.
- nonEmptyPathSegments walks the path once with strings.SplitSeq.
- ExtractRawQueryValues returns nil for an empty query.
- GetRenderedSchema returns the cached ReferenceSchema string instead of
  copying bytes per call.
- compilePathRegexEntry assembles patterns with strings.Builder:
  bytes.Buffer writes cannot fail, so the unreachable error branch and
  the fmt call with its interface boxing are gone.

Evidence: paired runs, 10 samples per side, benchstat (i7-1265U, Go
1.26), all measured back-to-back per commit, main vs branch across 12
gateway scenarios including query-heavy, invalid-request, concurrent,
format-assertions, strict-server, urlencoded, JSON-response-body and
200-route shapes:

- plain GET: 97 -> 35 allocs/op (-64%), 11.1 -> 5.7 us (-48%)
- param-heavy GET: 324 -> 94 allocs/op (-71%), 37.7 -> 14.6 us (-61%)
- invalid request: 326 -> 96 allocs/op (-71%), 42.5 -> 16.7 us (-61%)
- concurrent GET, 12 goroutines: 97 -> 35 allocs/op, 6.7 -> 2.4 us
- large route table (200 paths): 114 -> 35 allocs/op (-69%), -61%
- format assertions: 98 -> 36 allocs/op; strict server: 99 -> 37
- urlencoded body: 97 -> 85; JSON response body: 53 -> 44
- geomean: -42% sec/op, -54% B/op, -51% allocs/op, p<0.001

Memory: an entry holds a few KB (measured 4.3 KB: key string plus
compiled regex), so a 1,000-route API costs about 4 MB. ClearRegexCache
bounds it for long-running processes, matching the ClearJSONPathCache
contract in libopenapi.

One candidate was measured and rejected, recorded here: hoisting the
per-segment regex out of the parameter loop cost +9% sec/op on the
single-parameter shape (three precompute slices, nothing to dedupe).

Verification: go test -race -count=1 ./... (21/21 packages), make lint
(0 issues), new tests for cache identity, errors staying uncached,
ClearRegexCache, cached brace indices, the merge and model-slice
safety, and the unbraced-segment skip; 12 benchmark scenarios in
validator_request_bench_test.go and validator_scenario_bench_test.go.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant