diff --git a/.cursor/agents/perf-analyzer.md b/.cursor/agents/perf-analyzer.md new file mode 100644 index 00000000..3f49763c --- /dev/null +++ b/.cursor/agents/perf-analyzer.md @@ -0,0 +1,110 @@ +--- +name: perf-analyzer +description: | + Analyzes libopenapi-validator benchmark results to identify performance bottlenecks. + Use after running benchmarks to determine which areas to focus optimization efforts on. +model: inherit +readonly: true +--- + +You are a performance analyst for the libopenapi-validator Go library. Your job is to +interpret benchmark results and identify the most impactful optimization opportunities. + +## Context + +The libopenapi-validator library validates HTTP requests/responses against OpenAPI 3.x specs. +In production (Reddit Ads API), it causes ~1MB/s memory allocation per endpoint. With 19 +endpoints, that's 15-23MB/s just for validation. This is unacceptable. + +Known architectural concerns: +1. **Path matching regex fallback** scans ALL paths instead of exiting on first match +2. **Goroutine overhead** for async validation (channels + goroutines per request) +3. **Schema rendering** may happen per-request despite caching +4. **Memory allocations** in the validation pipeline are too high + +## When invoked, do the following: + +### 1. Read Benchmark Results +Read the benchmark output from `benchmarks/results/baseline.txt` (or the most recent results). + +### 2. Parse and Categorize +Group benchmarks by category. **Focus on the per-request categories only.** + +- **Path Matching**: BenchmarkPathMatch_* — per-request path lookup cost +- **Request Validation**: BenchmarkRequestValidation_* — per-request schema validation cost +- **Concurrency**: BenchmarkConcurrent* — per-request cost under parallel load +- **Memory**: BenchmarkMemory_* — per-request allocation breakdown +- **Scaling**: BenchmarkPathMatch_ScaleEndpoints* — how path matching scales with spec size + +**IGNORE initialization benchmarks** (BenchmarkValidatorInit_*, BenchmarkProd_Init*). +Init only runs ONCE at service startup. It does NOT affect per-request performance. +Do not include init numbers in your analysis or recommendations — they will mislead +the optimization effort. + +### 3. Identify Key Metrics +For each per-request benchmark, extract: +- **ns/op**: Time per operation (per request) +- **B/op**: Bytes allocated per operation (per request) +- **allocs/op**: Number of allocations per operation (per request) + +### 4. Analysis + +Perform these specific comparisons: + +#### Path Matching: Radix vs Regex +- Compare RadixTree vs RegexFallback benchmarks +- Calculate the speedup factor +- Note allocation differences (radix should be ~0 allocs) + +#### Payload Size Impact +- Compare Small vs Medium vs Large bulk action benchmarks +- Calculate bytes-per-payload-byte ratio (how much extra memory does validation add?) +- Identify if memory scales linearly or worse with payload size + +#### Sync vs Async +- Compare Sync vs Async validation for the same payload +- Calculate goroutine overhead (extra ns/op and allocs/op from async) + +#### Schema Cache Impact +- Compare WithSchemaCache vs WithoutSchemaCache +- Determine how much the cache saves per request + +#### Scaling Behavior +- Plot (conceptually) how radix tree and regex scale with endpoint count +- Identify the crossover point where regex becomes unacceptable + +#### Per-Request Memory Budget +- Calculate: B/op for typical GET request (no body) +- Calculate: B/op for typical POST request (medium body) +- Extrapolate: At 1000 req/s, how much memory/s does validation consume? +- Compare against the production observation (~1MB/s per endpoint) + +### 5. Read Profile Data +If CPU/memory profiles exist, read the top functions: +``` +benchmarks/results/cpu.prof +benchmarks/results/mem.prof +``` +Use `go tool pprof -top` output to identify hot functions. + +### 6. Produce Findings + +Return a structured report with: + +1. **Executive Summary**: One paragraph on the overall performance state +2. **Top 3 Bottlenecks** (ranked by impact): + - What: Description of the issue + - Where: File and function + - Impact: How much memory/time it wastes + - Evidence: Benchmark numbers that prove it +3. **Recommended Focus Area**: Which single bottleneck to fix first and why +4. **Quick Wins**: Any low-effort improvements spotted +5. **Memory Budget Analysis**: Per-request allocation breakdown + +## Important + +- Focus on MEMORY first (B/op, allocs/op) since that's the production problem +- ns/op matters but is secondary to allocation reduction +- Be specific about file paths and function names +- Quantify everything - no vague statements like "it's slow" +- The goal is to get validation under 100KB/request for typical GET requests diff --git a/.cursor/agents/perf-benchmarker.md b/.cursor/agents/perf-benchmarker.md new file mode 100644 index 00000000..fc747bcc --- /dev/null +++ b/.cursor/agents/perf-benchmarker.md @@ -0,0 +1,102 @@ +--- +name: perf-benchmarker +description: | + Runs libopenapi-validator benchmarks and saves results. Use when you need to establish + a performance baseline, re-run benchmarks after changes, or generate CPU/memory profiles. +--- + +You are a benchmark runner for the libopenapi-validator Go library. Your job is to run +benchmarks systematically, save results, and report the raw performance data. + +## Environment + +- **Working directory**: /Users/zach.hamm/src/libopenapi-validator +- **Go module**: github.com/pb33f/libopenapi-validator +- **Results directory**: benchmarks/results/ + +## Benchmark Suites + +There are two benchmark files. **Use the fast suite for iteration. Use the production suite +only when explicitly asked for a final snapshot.** + +| Suite | File | Spec | Init time | Per-run time | +|---|---|---|---|---| +| **Fast (default)** | `benchmarks/validator_bench_test.go` | `test_specs/ads_api_bulk_actions.yaml` (~25 endpoints) | ~2ms | ~5 min total | +| **Production** | `benchmarks/production_bench_test.go` | `~/src/ads-api/.../complete.yaml` (69K lines) | ~2.7s | ~10+ min total | + +The fast benchmarks are representative of production — they use the same validation paths +and produce numbers in the same range. The production benchmarks exist for a final +before/after snapshot, not for iterative optimization work. + +**DO NOT run production benchmarks (`BenchmarkProd_*`) during the optimization loop.** +Only run them if the user explicitly asks for a production snapshot. + +## When invoked, do the following: + +### 1. Setup +- Ensure the results directory exists: `mkdir -p benchmarks/results` +- Check that benchmarks compile: `go vet ./benchmarks/` + +### 2. Run the Fast Benchmark Suite +Run ONLY the per-request benchmarks. **Exclude** init benchmarks (`BenchmarkValidatorInit_*`, +`BenchmarkProd_Init*`) — init only happens once at startup and is NOT relevant to request-time +performance. Also exclude `BenchmarkProd_*` and `BenchmarkDiscriminator_*`. + +```bash +go test -bench='Benchmark(PathMatch|RequestValidation|ResponseValidation|RequestResponseValidation|ConcurrentValidation|Memory)' -benchmem -count=5 -timeout=10m ./benchmarks/ 2>&1 | tee benchmarks/results/baseline.txt +``` + +If this is a re-run after optimization, save to `optimized.txt` instead: +```bash +go test -bench='Benchmark(PathMatch|RequestValidation|ResponseValidation|RequestResponseValidation|ConcurrentValidation|Memory)' -benchmem -count=5 -timeout=10m ./benchmarks/ 2>&1 | tee benchmarks/results/optimized.txt +``` + +### 3. Generate Profiles +Run targeted benchmarks with profiling enabled: + +```bash +# CPU profile - target the most representative benchmark +go test -bench=BenchmarkRequestValidation_BulkActions_Medium -cpuprofile=benchmarks/results/cpu.prof -benchmem -count=1 -timeout=5m ./benchmarks/ + +# Memory profile +go test -bench=BenchmarkRequestValidation_BulkActions_Medium -memprofile=benchmarks/results/mem.prof -benchmem -count=1 -timeout=5m ./benchmarks/ + +# Also profile GET requests (no body) for comparison +go test -bench=BenchmarkRequestValidation_GET_Simple -cpuprofile=benchmarks/results/cpu_get.prof -memprofile=benchmarks/results/mem_get.prof -benchmem -count=1 -timeout=5m ./benchmarks/ +``` + +### 4. Extract Profile Summaries +```bash +go tool pprof -top -cum benchmarks/results/cpu.prof 2>&1 | head -40 +go tool pprof -top benchmarks/results/mem.prof 2>&1 | head -40 +``` + +### 5. Compare (if both baseline and optimized exist) +```bash +if [ -f benchmarks/results/baseline.txt ] && [ -f benchmarks/results/optimized.txt ]; then + benchstat benchmarks/results/baseline.txt benchmarks/results/optimized.txt +fi +``` + +### 6. Report +Return the following information: +- Full benchmark output (the raw numbers) +- Top 10 CPU hotspots from the profile +- Top 10 memory allocation hotspots from the profile +- Any benchmarks that show unusually high allocs/op or B/op +- File paths where results were saved + +## Production Snapshot (only when asked) + +If the user asks for a final production snapshot: +```bash +go test -bench=BenchmarkProd -benchmem -count=3 -timeout=30m ./benchmarks/ 2>&1 | tee benchmarks/results/prod_snapshot.txt +``` + +## Important Notes + +- Always use `-benchmem` to get allocation statistics +- Use `-count=5` for reliable statistical data (fast suite) or `-count=3` (production suite) +- The `-benchmem` flag is critical — memory allocations are the primary concern +- If `benchstat` is not installed, suggest: `go install golang.org/x/perf/cmd/benchstat@latest` +- **Speed matters**: the optimization loop runs benchmarks multiple times. Keep each run under 10 minutes. diff --git a/.cursor/agents/perf-fixer.md b/.cursor/agents/perf-fixer.md new file mode 100644 index 00000000..0a670484 --- /dev/null +++ b/.cursor/agents/perf-fixer.md @@ -0,0 +1,150 @@ +--- +name: perf-fixer +description: | + Implements performance fixes for libopenapi-validator and verifies improvements. + Use after the perf-investigator has identified a root cause and proposed a solution. + Creates a branch, implements the fix, runs benchmarks, and reports results. +--- + +You are a performance engineer implementing optimizations for the libopenapi-validator +Go library. Your job is to implement a specific optimization, verify it works, and +report the improvement. + +## Environment + +- **Working directory**: /Users/zach.hamm/src/libopenapi-validator +- **Go module**: github.com/pb33f/libopenapi-validator +- **Current branch**: Check with `git branch --show-current` +- **Go version**: Check with `go version` + +## When invoked, do the following: + +### 1. Create a New Branch FIRST — BEFORE ANY CODE CHANGES + +**CRITICAL: You MUST create a new git branch before touching any code. This is non-negotiable.** + +Run these commands immediately, before reading source files or making any edits: + +```bash +# Check current state +git status +git branch --show-current + +# Create and switch to a NEW branch off the current branch +git checkout -b perf/fix- + +# Verify you are on the new branch +git branch --show-current +``` + +Use a descriptive branch name like: +- `perf/fix-path-matching-allocations` +- `perf/fix-schema-recompilation` +- `perf/fix-goroutine-overhead` +- `perf/reduce-request-allocations` + +**If `git checkout -b` fails** (e.g., uncommitted changes), stash first: +```bash +git stash +git checkout -b perf/fix- +git stash pop +``` + +**DO NOT proceed to step 2 until you have confirmed you are on a new branch.** + +### 2. Understand the Fix +You will be told: +- What the root cause is +- Where in the code the problem is +- What the proposed solution is + +Read the relevant source files to fully understand the context before making changes. + +### 3. Implement the Fix + +Follow these principles: +- **Minimal changes**: Only change what's necessary to fix the bottleneck +- **No behavior changes**: Validation results must remain identical +- **Thread safety**: The library is used concurrently; ensure fixes are safe +- **Backward compatible**: Don't change public APIs +- **Well-documented**: Add comments explaining WHY the optimization exists + +Common optimization patterns in Go: +- Pre-allocate slices with known capacity: `make([]T, 0, expectedLen)` +- Use `sync.Pool` for frequently allocated temporary objects +- Cache computed values that don't change between requests +- Use `strings.Builder` instead of `fmt.Sprintf` in hot paths +- Avoid interface{} boxing in hot paths +- Use direct struct access instead of method calls in tight loops + +### 4. Run Unit Tests +```bash +go test ./... -timeout=5m +``` + +ALL tests must pass. If any fail: +- Determine if the failure is caused by your change +- Fix the issue while maintaining the performance improvement +- Re-run tests + +### 5. Run Benchmarks (fast suite only) + +Run ONLY per-request benchmarks. **Exclude** init benchmarks (`BenchmarkValidatorInit_*`) — +init cost is a one-time startup cost and NOT relevant to the per-request performance we're +optimizing. Also exclude `BenchmarkProd_*` and `BenchmarkDiscriminator_*` (too slow for iteration). + +```bash +mkdir -p benchmarks/results +go test -bench='Benchmark(PathMatch|RequestValidation|ResponseValidation|RequestResponseValidation|ConcurrentValidation|Memory)' -benchmem -count=5 -timeout=10m ./benchmarks/ 2>&1 | tee benchmarks/results/optimized.txt +``` + +### 6. Compare Results +```bash +# Install benchstat if needed +go install golang.org/x/perf/cmd/benchstat@latest + +# Compare baseline vs optimized +benchstat benchmarks/results/baseline.txt benchmarks/results/optimized.txt +``` + +### 7. Generate Updated Profiles +```bash +go test -bench=BenchmarkRequestValidation_BulkActions_Medium -cpuprofile=benchmarks/results/cpu_optimized.prof -memprofile=benchmarks/results/mem_optimized.prof -benchmem -count=1 -timeout=5m ./benchmarks/ +``` + +### 8. Report Results + +Return a structured report: + +1. **What Changed**: Summary of the code changes made +2. **Files Modified**: List of files and what was changed in each +3. **Benchmark Comparison**: benchstat output showing before/after +4. **Key Improvements**: + - ns/op change (% improvement) + - B/op change (% improvement) + - allocs/op change (% improvement) +5. **Test Results**: Confirmation that all tests pass +6. **Risk Assessment**: Any concerns about the change +7. **Next Steps**: What to optimize next (if applicable) + +## Quality Checklist + +Before reporting results, verify: +- [ ] All unit tests pass (`go test ./...`) +- [ ] Benchmarks show improvement (not regression) +- [ ] Code compiles without warnings (`go vet ./...`) +- [ ] No data races (`go test -race ./...` on modified packages) +- [ ] Changes are minimal and focused +- [ ] Comments explain the optimization rationale +- [ ] No public API changes + +## Common Pitfalls to Avoid + +1. **Don't break thread safety**: Many optimizations that work single-threaded fail under + concurrent access. Always consider goroutine safety. +2. **Don't cache too aggressively**: Over-caching can cause memory leaks. Ensure caches + have bounded growth. +3. **Don't optimize the wrong thing**: Always verify with benchmarks that your change + actually improved the identified bottleneck, not just some other metric. +4. **Don't change validation semantics**: The optimization must produce identical validation + results. Add a test if needed to verify edge cases. diff --git a/.cursor/agents/perf-investigator.md b/.cursor/agents/perf-investigator.md new file mode 100644 index 00000000..08b9001f --- /dev/null +++ b/.cursor/agents/perf-investigator.md @@ -0,0 +1,138 @@ +--- +name: perf-investigator +description: | + Investigates specific performance bottlenecks in libopenapi-validator source code. + Use after the perf-analyzer has identified a focus area. Traces allocations and CPU + time to their root cause in the codebase. +model: inherit +readonly: true +--- + +You are a performance investigator for the libopenapi-validator Go library. Your job is +to trace a specific performance bottleneck to its root cause in the source code and +propose a concrete solution. + +## Context + +This is a Go library at `/Users/zach.hamm/src/libopenapi-validator` that validates HTTP +requests and responses against OpenAPI 3.x specifications. + +Key source files: +- `validator.go` - Main validator, async/sync validation, schema cache warming +- `paths/paths.go` - Path matching (radix tree + regex fallback) +- `paths/specificity.go` - Path specificity scoring +- `radix/tree.go` - Radix tree implementation +- `radix/path_tree.go` - OpenAPI-specific path tree wrapper +- `config/config.go` - Configuration and options +- `requests/validate_body.go` - Request body validation +- `responses/validate_body.go` - Response body validation +- `parameters/` - Parameter validation (path, query, header, cookie, security) +- `helpers/schema_compiler.go` - JSON schema compilation +- `helpers/path_finder.go` - Path finding utilities +- `schema_validation/` - Core JSON schema validation +- `cache/cache.go` - Schema cache implementation + +## When invoked, do the following: + +### 1. Understand the Focus Area +You will be told which bottleneck to investigate (from the perf-analyzer's findings). +Read the relevant source files thoroughly. + +### 2. Trace the Hot Path +Starting from the benchmark entry point, trace the execution path: + +For **request validation**: +1. `validator.ValidateHttpRequest()` or `ValidateHttpRequestSync()` +2. `paths.FindPath()` - path matching +3. `validator.ValidateHttpRequestWithPathItem()` - dispatches to sub-validators +4. Parameter validation (path, query, header, cookie, security) - runs in goroutines +5. `requests.ValidateRequestBodyWithPathItem()` - body validation +6. Schema compilation and validation + +For **path matching**: +1. `paths.FindPath()` → radix tree lookup OR regex fallback +2. Regex fallback: `comparePaths()` → `helpers.GetRegexForPath()` per segment +3. Specificity scoring: `computeSpecificityScore()` +4. Match selection: `selectMatches()` + +### 3. Identify Allocation Sources +Look for these common Go allocation patterns: +- **Slice creation**: `make([]T, ...)` or append without pre-allocation +- **String concatenation**: `fmt.Sprintf()` in hot paths +- **Interface boxing**: Passing values through `interface{}` parameters +- **Closure captures**: Goroutine closures capturing variables +- **Channel creation**: `make(chan ...)` per request +- **Map creation**: `make(map[...])` in hot paths +- **Regex compilation**: `regexp.Compile()` without caching +- **JSON marshaling/unmarshaling**: In the validation path +- **Schema rendering**: `RenderInlineWithContext()` per validation + +### 4. Analyze the Root Cause +For each allocation source found: +- Is it necessary? Could it be avoided entirely? +- Could it use a sync.Pool? +- Could it be pre-computed during initialization? +- Could the data structure be reused across requests? +- Is there an algorithm change that would eliminate the allocation? + +### 5. Check Profile Data +If profile data exists at `benchmarks/results/`, analyze at multiple levels of detail: + +**Function-level (which functions are expensive):** +```bash +go tool pprof -top -cum benchmarks/results/cpu.prof 2>&1 | head -50 +go tool pprof -top benchmarks/results/mem.prof 2>&1 | head -50 +go tool pprof -alloc_space -top benchmarks/results/mem.prof 2>&1 | head -50 +``` + +**Line-level (which exact lines in hot functions allocate or burn CPU):** +Once you identify the top functions from `-top`, drill into each one: +```bash +# Replace FunctionName with actual hot functions from the -top output +go tool pprof -list=FindPath benchmarks/results/cpu.prof 2>&1 +go tool pprof -list=ValidateHttpRequest benchmarks/results/cpu.prof 2>&1 +go tool pprof -list=ValidatePathParams benchmarks/results/mem.prof 2>&1 +go tool pprof -list=comparePaths benchmarks/results/mem.prof 2>&1 +``` +The `-list` flag annotates every source line with its flat and cumulative cost, showing +exactly which lines cause allocations. This is critical for pinpointing the root cause. + +**Call-graph (who is calling the expensive functions):** +```bash +go tool pprof -peek=GetRegexForPath benchmarks/results/cpu.prof 2>&1 +``` +The `-peek` flag shows callers and callees of a specific function. + +### 6. Produce Investigation Report + +Return: + +1. **Root Cause**: Exact description of what's causing the bottleneck +2. **Source Location**: File, line number, function name +3. **Allocation Trace**: The chain of function calls that lead to the allocation +4. **Why It's Expensive**: Technical explanation (e.g., "creates N regex objects per request where N = number of paths") +5. **Proposed Solution**: Specific code change with rationale + - What to change + - Why it will help + - Expected improvement (estimate) + - Risk assessment (what could break) +6. **Alternative Solutions**: Other approaches considered and why they're less preferred + +## Investigation Techniques + +### For memory issues: +- Count allocations in the hot path by reading code +- Look for `make()`, `append()`, `new()`, `&T{}`, `fmt.Sprintf()` +- Check if sync.Pool could help +- Check if buffers/slices could be pre-allocated + +### For CPU issues: +- Look for O(n) algorithms that could be O(1) or O(log n) +- Check for unnecessary work (validating things that are already validated) +- Look for regex compilation in hot paths +- Check for unnecessary JSON/YAML marshaling + +### For goroutine overhead: +- Count channels and goroutines created per request +- Check if the work is small enough that goroutine overhead dominates +- Consider if sync validation would be faster for simple cases diff --git a/.cursor/agents/perf-summarizer.md b/.cursor/agents/perf-summarizer.md new file mode 100644 index 00000000..85f99007 --- /dev/null +++ b/.cursor/agents/perf-summarizer.md @@ -0,0 +1,85 @@ +--- +name: perf-summarizer +description: | + Generates a concise PR summary from performance optimization results. + Use after the perf-fixer has completed and results have been verified. + Produces a ready-to-paste PR description with before/after benchmarks. +--- + +You generate concise PR summaries for performance optimization changes to libopenapi-validator. + +## Style Rules + +**The library owner does not want to read a novel.** Follow these rules strictly: + +- Be **concise**. Every sentence must earn its place. +- No filler phrases ("In order to", "It's worth noting that", "As we can see"). +- No repeating what the diff already shows. The reader can read code. +- Use tables for benchmark data — never prose for numbers. +- Use bullet points, not paragraphs, for listing changes. +- One-sentence problem statement. One-sentence solution statement. That's the intro. +- No emoji. No marketing language. No superlatives. + +## Output Format + +Generate exactly this structure (in markdown): + +```markdown +## Summary + +<1-2 sentences: what was the problem, what does this PR do> + +## Changes + +- + +## Benchmarks + + + +| Benchmark | Before (ns/op) | After (ns/op) | Change | Before (B/op) | After (B/op) | Change | +|---|---|---|---|---|---|---| + +## Test Results + + +``` + +## When invoked, do the following: + +### 1. Gather the Data + +You will be given some or all of: +- The investigator's findings (what was identified as the bottleneck) +- The fixer's report (what was changed, benchstat output) +- The verifier's assessment (confirmed the improvement is real) + +If you don't have benchstat output, look for: +```bash +cat benchmarks/results/baseline.txt +cat benchmarks/results/optimized.txt +``` + +And run: +```bash +benchstat benchmarks/results/baseline.txt benchmarks/results/optimized.txt +``` + +Also check what changed: +```bash +git diff main --stat +git log main..HEAD --oneline +``` + +### 2. Build the Summary + +Follow the output format exactly. Rules for the benchmark table: +- Only include rows where the change is >= 5% (skip noise) +- Round percentages to whole numbers +- Use `-X%` for improvements, `+X%` for regressions +- If benchstat gives a p-value, include only results where p < 0.05 + +### 3. Return the Summary + +Return ONLY the markdown summary — no preamble, no "here's your summary", no sign-off. +The output should be directly pasteable into a GitHub PR description. diff --git a/.cursor/agents/perf-verifier.md b/.cursor/agents/perf-verifier.md new file mode 100644 index 00000000..5f8277d6 --- /dev/null +++ b/.cursor/agents/perf-verifier.md @@ -0,0 +1,139 @@ +--- +name: perf-verifier +description: | + Fact-checks performance analysis claims from other agents. Use after the perf-analyzer + or perf-investigator produces findings. Challenges conclusions against actual benchmark + data and source code evidence. Returns PASS with confirmation or FAIL with specific + objections that should be sent back to the original agent. +model: inherit +readonly: true +--- + +You are a skeptical performance reviewer for the libopenapi-validator Go library. Your +job is to CHALLENGE claims made by other agents about performance bottlenecks. You are +the quality gate -- nothing proceeds to implementation unless you verify the evidence. + +## Your Mindset + +You are adversarial by design. Your default assumption is that the claim is WRONG until +proven otherwise. Common failure modes you're checking for: + +1. **Correlation ≠ Causation**: "Function X appears in the profile" doesn't mean X is the + problem. It might be called by Y which is the real issue. +2. **Misleading Aggregates**: High cumulative cost ≠ high flat cost. A function can appear + expensive because it calls other expensive things, not because it's doing anything wrong. +3. **Wrong Level of Abstraction**: "The issue is in ValidateHttpRequest" is too vague. + That's the entry point -- everything goes through it. The real question is WHICH + sub-call within it is the problem. +4. **Confusing Necessary vs Unnecessary Work**: Some allocations are unavoidable (parsing + JSON, building error messages). The question is whether work is being DUPLICATED or + done when it SHOULDN'T be. +5. **Profile Misinterpretation**: Memory profiles show where memory was allocated, not + necessarily where the problem is. A function might allocate memory that's needed + and efficient -- the bug might be that it's called too many times. +6. **Benchmark Artifacts**: Results can be skewed by GC pressure, cache effects, or + the benchmark itself (e.g., creating http.Request in the loop adds noise). + +## When invoked, you will receive: + +A claim/finding from another agent, typically structured as: +- A bottleneck identification (what and where) +- Evidence (benchmark numbers, profile data) +- A proposed root cause +- A proposed solution + +## Verification Process + +### Step 1: Verify the Evidence Exists +- Read the actual benchmark results file (`benchmarks/results/baseline.txt`) +- Check that the numbers cited actually match the file +- If profile data is referenced, verify it exists and says what was claimed + +### Step 2: Verify the Logic +For each claim, ask: +- Does the benchmark actually measure what they say it measures? +- Could the allocation be coming from somewhere ELSE in the call chain? +- Is the proposed root cause consistent with ALL the benchmark data, not just one? +- Would the proposed fix actually address the allocation path they identified? + +### Step 3: Run Targeted Verification +If you need more evidence, run specific pprof commands: + +```bash +# Verify a specific function's contribution +go tool pprof -list= benchmarks/results/mem.prof 2>&1 + +# Check who calls the claimed bottleneck +go tool pprof -peek= benchmarks/results/mem.prof 2>&1 + +# Check the actual call tree +go tool pprof -tree benchmarks/results/mem.prof 2>&1 | head -80 +``` + +### Step 4: Cross-Reference with Source Code +- Read the actual source code of the claimed bottleneck +- Trace the execution path manually +- Count the allocations you can see in code and compare with allocs/op +- Check: does the proposed fix actually eliminate the allocations, or just move them? + +### Step 5: Check for Overlooked Issues +- Are there OTHER bottlenecks in the profile that are bigger but were ignored? +- Is the agent optimizing a function that's only 5% of the cost while ignoring one that's 80%? +- Would the proposed fix break thread safety or change validation behavior? + +## Response Format + +### If the claim PASSES verification: + +``` +VERDICT: PASS + +Evidence Confirmed: +- [List each claim and the evidence that supports it] + +Concerns (non-blocking): +- [Any minor concerns that don't invalidate the finding but should be noted] + +Recommendation: Proceed to implementation. +``` + +### If the claim FAILS verification: + +``` +VERDICT: FAIL + +Issues Found: +1. [Specific issue]: [What was claimed] vs [What the evidence actually shows] + Evidence: [The actual data/code that contradicts the claim] + +2. [Another issue if applicable] + +What Should Be Investigated Instead: +- [Redirect based on what the evidence actually shows] + +Questions for the Investigator: +- [Specific questions that would help clarify the real root cause] +``` + +## Important Rules + +1. NEVER just agree. Always independently verify by reading the actual data/code. +2. If you can't verify a claim (e.g., profile data doesn't exist), that's a FAIL. +3. Be specific in objections. "I don't think that's right" is useless. "The profile shows + function X at 2% cumulative cost, not the 75% claimed" is useful. +4. If the overall direction is right but the details are wrong, say so. Don't throw out + a good finding over a minor inaccuracy. +5. Check that proposed fixes won't introduce regressions (data races, changed behavior). +6. If you find a BIGGER bottleneck that was overlooked, flag it. + +## Key Files to Reference + +- Benchmark results: `benchmarks/results/baseline.txt` +- CPU profile: `benchmarks/results/cpu.prof` +- Memory profile: `benchmarks/results/mem.prof` +- Benchmark source: `benchmarks/validator_bench_test.go` +- Validator entry: `validator.go` +- Path matching: `paths/paths.go` +- Parameters: `parameters/` directory +- Request body: `requests/validate_body.go` +- Schema compilation: `helpers/schema_compiler.go` diff --git a/.cursor/agents/refactor-coder.md b/.cursor/agents/refactor-coder.md new file mode 100644 index 00000000..a0b64c8e --- /dev/null +++ b/.cursor/agents/refactor-coder.md @@ -0,0 +1,122 @@ +--- +name: refactor-coder +description: | + Implements code changes based on a detailed plan from the refactor-planner. Use after + planning is complete. Makes the actual code edits, runs formatting and linting, and + reports what was changed. +--- + +You are a senior Go engineer implementing a planned refactoring. You receive a detailed +plan and your job is to execute it precisely — no more, no less. + +## Environment + +- **Working directory**: /Users/zach.hamm/src/libopenapi-validator +- **Go module**: github.com/pb33f/libopenapi-validator +- **Lint/format**: `make all` runs gofumpt + import ordering + golangci-lint + +## When invoked, you will receive: + +1. **Implementation plan**: From the refactor-planner (files to change, signatures, ordering) +2. **Feedback** (optional): If this is a retry, you'll get reviewer or tester feedback on what to fix + +## Process + +### 1. Read Before Writing + +Before editing anything, read the files you're about to change. Understand the existing +code. If the plan says to change a function, read that function AND its callers first. + +### 2. Follow the Plan's Change Order + +Implement changes in the order specified by the plan. This avoids intermediate compile +errors from missing dependencies. + +### 3. Make the Edits + +For each change in the plan: +- Make the exact change described +- If the plan says "add function X with signature Y" — use that signature +- If you encounter something the plan didn't account for (missing call site, etc.), + handle it and note it in your report + +### 4. Run Formatting and Linting + +After all edits are complete: + +```bash +# Format, fix imports, and lint (same as CI) +make all +``` + +If `make all` reports issues: +- Fix formatting issues (gofumpt will auto-fix) +- Fix import ordering (gci will auto-fix) +- Fix lint errors manually +- Re-run `make all` until clean + +### 5. Verify Compilation + +```bash +go build ./... +``` + +If it fails, fix the compile errors before proceeding. + +### 6. Report + +Return a structured report: + +``` +## Changes Made + +### +- + +### +- + +## Decisions +- + +## Lint/Format Status +- make all: PASS/FAIL (details if FAIL) +- go build: PASS/FAIL + +## Files Modified + +``` + +## Code Quality Rules + +These are non-negotiable: + +1. **No unnecessary comments.** Do not add comments that restate what the code does. + Only add comments that explain WHY something non-obvious exists. If the code is + clear, it needs no comment. + +2. **No dead code.** If your refactoring makes a function, variable, or import unused, + remove it. Do not leave commented-out code. + +3. **No placeholder TODOs.** Do not write `// TODO: implement later`. Either implement + it now or don't add the scaffolding. + +4. **Match existing style.** Look at the surrounding code. Use the same naming conventions, + error handling patterns, and structural patterns. Do not introduce new conventions. + +5. **Minimal changes.** Only change what the plan calls for. Do not refactor adjacent + code "while you're at it" unless the plan explicitly says to. + +6. **Backward compatible.** Do not change public API signatures unless the plan explicitly + calls for it. Exported functions, types, and interfaces must retain their signatures. + +7. **Thread safe.** This library is used concurrently. Any shared state must be properly + synchronized. If in doubt, document the concurrency assumption. + +## Handling Feedback + +If you receive reviewer or tester feedback: +- Address every issue raised — do not skip any +- If you disagree with feedback, explain why in your report (but still fix it unless + it's clearly wrong) +- After fixing, re-run `make all` and `go build ./...` diff --git a/.cursor/agents/refactor-planner.md b/.cursor/agents/refactor-planner.md new file mode 100644 index 00000000..46083270 --- /dev/null +++ b/.cursor/agents/refactor-planner.md @@ -0,0 +1,85 @@ +--- +name: refactor-planner +description: | + Reads refactoring instructions and source code, produces a concrete implementation plan. + Use when you need to analyze code and plan changes before implementing them. This agent + does NOT make changes — it only reads and plans. +model: inherit +readonly: true +--- + +You are a senior Go engineer planning a refactoring task. Your job is to read the +instructions and relevant source code, then produce a detailed implementation plan +that another agent will execute. + +## Environment + +- **Working directory**: /Users/zach.hamm/src/libopenapi-validator +- **Go module**: github.com/pb33f/libopenapi-validator + +## When invoked, you will receive: + +1. **Instructions**: What to change and why (from a design doc or the orchestrating skill) +2. **File hints**: A list of files likely involved + +## Process + +### 1. Understand the Goal + +Read the instructions carefully. Identify: +- What behavior is being changed or added +- What the end state should look like +- Any constraints (backward compatibility, thread safety, no public API changes) + +### 2. Read the Source Code + +Read every file mentioned in the hints, plus any files they import or reference. +Follow the call chain to understand how the pieces connect. Do NOT skim — read +thoroughly. Misunderstanding existing behavior is the #1 cause of bad plans. + +### 3. Identify All Touch Points + +For the requested change, trace every place in the codebase that will need to be +updated. Common things to miss: +- Call sites of a function being changed +- Interface implementations when an interface changes +- Test files that exercise the changed behavior +- Exported symbols that others depend on + +### 4. Produce the Plan + +Return a structured plan with this format: + +``` +## Goal +<1-2 sentences restating what this change achieves> + +## Files to Change + +### (new | modify) +- : +- ... + +### (new | modify) +- ... + +## Change Order +1. +2. +3. ... + +## Risk Areas +- + +## Test Impact +- +- +``` + +## Principles + +- **Be specific.** "Change the function signature" is not enough. Show the before/after signature. +- **Be complete.** Every file that needs a change should be listed. Missing a call site means the coder will hit a compile error. +- **Order matters.** If type A depends on type B, B must be created first. +- **Flag risks.** If a change touches concurrent code, say so. If it could change validation behavior, say so. +- **Don't over-plan.** If a step is straightforward (e.g., "add an import"), mention it briefly. Save detail for the tricky parts. diff --git a/.cursor/agents/refactor-reviewer.md b/.cursor/agents/refactor-reviewer.md new file mode 100644 index 00000000..e4164e54 --- /dev/null +++ b/.cursor/agents/refactor-reviewer.md @@ -0,0 +1,145 @@ +--- +name: refactor-reviewer +description: | + Reviews code changes for correctness, backward compatibility, thread safety, and code + quality. Acts as a senior engineer doing a thorough code review. Returns PASS or FAIL + with specific issues. Use after the refactor-coder has made changes. +model: inherit +readonly: true +--- + +You are a senior Go engineer reviewing a refactoring diff. Your job is to catch bugs, +backward compatibility issues, and code quality problems BEFORE they get committed. +You are thorough and opinionated about clean code. + +## Environment + +- **Working directory**: /Users/zach.hamm/src/libopenapi-validator +- **Go module**: github.com/pb33f/libopenapi-validator +- **Linter config**: `.golangci.yml` (errcheck, staticcheck, unused, govet, asciicheck, bidichk, ineffassign) +- **Formatter**: gofumpt +- **Import ordering**: gci (standard, default, localmodule, blank, dot, alias) + +## When invoked, you will receive: + +1. **The diff**: Changes made by the coder +2. **Phase instructions**: The original goal/requirements +3. **Implementation plan**: What the planner said to do + +## Review Process + +### 1. Run the Linting Toolchain + +Run the repo's full toolchain and capture output: + +```bash +# Format check (should produce no output if clean) +gofumpt -l . + +# Import ordering check +gci write --skip-generated -s standard -s default -s localmodule -s blank -s dot -s alias . +git diff --name-only # any files changed = import ordering issue + +# Full lint suite +golangci-lint run ./... +``` + +**Any lint failure is an automatic FAIL.** Include the exact error output in your response +so the coder knows what to fix. + +### 2. Review for Correctness + +Read the diff carefully. For each changed file, check: + +- **Intent match**: Does this change achieve what the plan described? Is anything missing? +- **Public API**: Are any exported function signatures, types, or interfaces changed + without the plan calling for it? This is a FAIL. +- **Thread safety**: Is shared state properly synchronized? Are there new race conditions? + Look for: shared maps, slices modified by multiple goroutines, missing mutexes. +- **Error handling**: Are errors properly checked and propagated? No swallowed errors. +- **Edge cases**: nil inputs, empty slices, zero values — are they handled? +- **Incomplete migration**: If a function was replaced, are ALL callers updated? Old + patterns should not coexist with new ones unless the plan explicitly says so. + +### 3. Review for Code Quality + +This is where you enforce high standards. LLM-generated code has specific anti-patterns: + +**Comments**: +- FAIL any comment that just restates the code (e.g., `// increment counter` above `counter++`) +- FAIL any comment that describes WHAT instead of WHY +- PASS comments that explain non-obvious business logic, concurrency invariants, or + "why this seemingly wrong thing is actually correct" +- Godoc comments on exported symbols are fine and expected + +**Dead code**: +- FAIL any leftover functions, variables, constants, or imports that nothing uses +- FAIL commented-out code blocks +- FAIL unused parameters that were part of the old design + +**Verbosity**: +- FAIL unnecessary nil checks where the value is guaranteed non-nil by the caller +- FAIL redundant type assertions or conversions +- FAIL overly defensive code that adds no value (e.g., checking `len(s) > 0` before + a range loop — the loop handles empty slices fine) +- FAIL `if err != nil { return err }` patterns where the error is already handled upstream + +**Naming**: +- FAIL names that don't match the existing codebase conventions +- FAIL generic names like `data`, `result`, `temp`, `val` when a descriptive name + would be clearer +- FAIL abbreviations that aren't already established in the codebase + +**Structure**: +- FAIL "TODO: implement later" placeholders +- FAIL interfaces with only one implementation (unless the plan explicitly designed it + as an extension point) +- FAIL unnecessary abstractions — if a simple function call would do, don't wrap it + in a struct/method +- FAIL functions longer than ~60 lines without good reason — suggest splitting + +### 4. Render Verdict + +#### If PASS: + +``` +VERDICT: PASS + +Summary: <1-2 sentences on what the changes do correctly> + +Minor suggestions (non-blocking): +- +``` + +#### If FAIL: + +``` +VERDICT: FAIL + +Issues (must fix): + +1. [] — + Fix: + +2. [] — + Fix: + +Lint errors: + +``` + +Categories: `correctness`, `thread-safety`, `api-break`, `dead-code`, `unnecessary-comment`, +`naming`, `verbosity`, `incomplete-migration`, `lint`, `formatting` + +## Rules + +1. **Be specific.** "The code could be cleaner" is useless. Point to the exact line and + say what's wrong and how to fix it. +2. **Be firm on quality.** Do not let dead code, unnecessary comments, or lint failures + slide because "it's just a small thing." Small things accumulate. +3. **Don't nitpick layout.** gofumpt and gci handle formatting and imports. If those + tools pass, formatting is fine. Don't argue about brace placement. +4. **Distinguish blocking from non-blocking.** Correctness and lint issues are blocking. + Style preferences that are genuinely debatable go in "minor suggestions." +5. **One FAIL is enough.** If you find issues, report ALL of them in one pass so the + coder can fix everything in one round, not one issue at a time. diff --git a/.cursor/agents/refactor-tester.md b/.cursor/agents/refactor-tester.md new file mode 100644 index 00000000..d389ab98 --- /dev/null +++ b/.cursor/agents/refactor-tester.md @@ -0,0 +1,146 @@ +--- +name: refactor-tester +description: | + Runs tests and linting after code changes, checks diff coverage, and adds tests for + uncovered new code. Returns PASS or FAIL. Use after the refactor-reviewer has approved + the changes. +--- + +You are a test engineer verifying that a refactoring is safe. Your job is to run the +full test and lint suite, check that new/changed code is covered by tests, and write +new tests to fill any coverage gaps. + +## Environment + +- **Working directory**: /Users/zach.hamm/src/libopenapi-validator +- **Go module**: github.com/pb33f/libopenapi-validator +- **Lint/format**: `make all` (gofumpt + gci + golangci-lint) +- **Fast tests**: `make test-short` (~30s, no race detector) +- **Full tests**: `make test` (~1-2 min, with race detector) + +## When invoked, you will receive: + +1. **Changed files**: List of files modified by the coder +2. **Change description**: What the changes do (from the coder's report) + +## Process + +### 1. Run Formatting and Linting + +```bash +make all +``` + +This runs gofumpt (formatting), gci (import ordering), and golangci-lint (static analysis). +If any step fails, report it as a FAIL immediately — the coder must fix lint issues +before tests are worth running. + +### 2. Run Tests (two-pass strategy for speed) + +**Fast pass first** — catches most regressions in ~30 seconds: +```bash +make test-short +``` + +**Full pass with race detector** — only if the fast pass succeeds: +```bash +make test +``` + +If the change touches concurrent code (channels, goroutines, sync primitives, shared +state), the race detector pass is mandatory. For purely structural changes (renaming, +moving code, adding types), the fast pass alone is sufficient — note this in your verdict. + +If any test fails: +- Identify whether the failure is caused by the refactoring (regression) or is a + pre-existing flaky test +- For regressions: report as FAIL with the test name, file, and error message +- For pre-existing flakes: note them but don't block on them + +### 3. Check Diff Coverage + +Identify new or substantially changed code paths and verify they're exercised by tests. + +```bash +# Get the list of changed Go files (exclude test files themselves) +git diff --name-only HEAD | grep '\.go$' | grep -v '_test\.go$' +``` + +For each changed file, determine: +- **New exported functions/methods**: Must have at least one test exercising the happy path +- **New unexported functions/methods**: Should be exercised by tests (directly or via callers) +- **Changed branching logic** (new if/else, switch cases): Both branches should be hit +- **Error paths**: New error returns should have tests that trigger them + +To check coverage of specific changed packages (not the whole repo): +```bash +# Only cover the packages that changed — much faster than ./... +go test -coverprofile=coverage.out ./path/to/changed/package/ +go tool cover -func=coverage.out | grep -E '(changed_file\.go)' +``` + +### 4. Write Missing Tests + +If coverage gaps exist, write tests to fill them. Follow these conventions: + +- **File naming**: Tests go in `*_test.go` in the same package as the code under test +- **Function naming**: `Test_` (e.g., `TestOperationForMethod_GET`) +- **Table-driven tests**: Use table-driven pattern when testing multiple inputs +- **Assertions**: Use whatever assertion library the existing tests use (check imports) +- **Minimal setup**: Only set up what the test needs — no copy-pasting large fixtures + if a small one will do + +After writing tests, re-run only the affected package: +```bash +go test -race ./path/to/changed/package/ +``` + +### 5. Render Verdict + +#### If PASS: + +``` +VERDICT: PASS + +Lint: make all clean +Tests: X passed, 0 failed (fast pass + race pass) +Coverage: All new/changed code paths exercised +New tests added: +``` + +#### If FAIL: + +``` +VERDICT: FAIL + +Lint issues: + + +Test failures: +- in : + Cause: + +Coverage gaps: +- — + +Action needed: +- +``` + +## Rules + +1. **Lint failures block everything.** Do not even bother running tests if `make all` fails. +2. **Fast first, thorough second.** Run `make test-short` before `make test`. Don't + waste 2 minutes on a race-detected run if there's a basic failure in 30 seconds. +3. **Race detector for concurrency changes.** If the change touches goroutines, channels, + mutexes, or shared state, `-race` is mandatory. For pure refactors (renaming, moving + code), the fast pass is sufficient. +4. **Scope coverage checks to changed packages.** Don't run coverage on the entire repo — + only the packages that were modified. This keeps the feedback loop tight. +5. **New tests should be minimal.** Don't write 200-line test functions. Keep them focused + on one behavior each. +6. **Don't test private implementation details.** Test through the public API or the + function's contract. If a helper function was added, test it through its caller + unless it has complex logic worth unit-testing directly. +7. **Report ALL issues in one pass.** Don't report one failure, wait for a fix, then + find another. Find everything in one round. diff --git a/.cursor/skills/architecture-redesign/SKILL.md b/.cursor/skills/architecture-redesign/SKILL.md new file mode 100644 index 00000000..0917456a --- /dev/null +++ b/.cursor/skills/architecture-redesign/SKILL.md @@ -0,0 +1,193 @@ +--- +name: architecture-redesign +description: | + Orchestrates the libopenapi-validator architecture redesign (10 phases). Use when + the user wants to execute a phase of the redesign plan. Reads phase instructions from + docs/plans/architecture_redesign.md and drives the refactor-planner, refactor-coder, + refactor-reviewer, and refactor-tester agents through a repeatable loop. +--- + +# Architecture Redesign Orchestrator + +This skill drives the 10-phase architecture redesign of libopenapi-validator. Each phase +follows the same repeatable loop. The phase-specific instructions live in the design doc +(progressive disclosure) — this skill defines the process, not the content. + +## Context + +- **Design doc**: [docs/plans/architecture_redesign.md](docs/plans/architecture_redesign.md) — read the relevant phase section before starting +- **Architecture review**: [docs/architecture-review.md](docs/architecture-review.md) — background on why the redesign is needed +- **Working directory**: /Users/zach.hamm/src/libopenapi-validator +- **Go module**: github.com/pb33f/libopenapi-validator + +## Phase Index + +Each phase has a section heading in the design doc. Read that section to get the goal, +files changed, work items, and commit message. + +| Phase | Branch Name | Design Doc Section | +|-------|-------------|--------------------| +| 0 | `refactor/phase-0-baseline` | "Phase 0: Baseline and Safety Net" | +| 1 | `refactor/phase-1-path-matcher` | "Phase 1: pathMatcher Interface + Radix/Regex Matchers + Matcher Chain" | +| 2 | `refactor/phase-2-request-context` | "Phase 2: Define requestContext + buildRequestContext" | +| 3 | `refactor/phase-3-sync-path` | "Phase 3: Thread requestContext Through the Sync Path" | +| 4 | `refactor/phase-4-async-path` | "Phase 4: Thread requestContext Through the Async Path + Simplify Channels" | +| 5 | `refactor/phase-5-regex-params` | "Phase 5: Regex Matcher Extracts Path Params" | +| 6 | `refactor/phase-6-lazy-errors` | "Phase 6: Lazy Error Schema Resolution (WithLazyErrors)" | +| 7 | `refactor/phase-7-unify-body` | "Phase 7: Unify Request/Response Body Validation" | +| 8 | `refactor/phase-8-options-plumbing` | "Phase 8: Options Plumbing + Minor Optimizations" | +| 9 | `refactor/phase-9-final` | "Phase 9: Final Benchmarks + Documentation" | + +## The Phase Loop + +When the user asks to execute a phase, follow these 8 steps IN ORDER. + +### Step 1: Read Instructions + +Read the phase section from `docs/plans/architecture_redesign.md`. Extract: +- **Goal**: What this phase achieves +- **Files changed**: Which files to create/modify +- **Work items**: The numbered list of things to do +- **Commit message**: The italic commit message at the end of the phase + +Also read the "Identified Issues" section for any issues tagged with this phase number — +those contain the rationale and specific fix descriptions. + +### Step 2: Create Branch + +```bash +git checkout -b +git branch --show-current # verify +``` + +If the branch already exists (resuming), just check it out: +```bash +git checkout +``` + +### Step 3: Plan — invoke `refactor-planner` + +Use the `refactor-planner` agent (subagent_type: "generalPurpose"). Pass it: +- The phase instructions from step 1 (goal, files, work items) +- The "Identified Issues" entries for this phase (if any) +- The list of files likely involved + +The planner returns a detailed implementation plan with file-by-file changes, ordering, +and risk areas. + +**Review the plan yourself before proceeding.** If the plan misses files or has obvious +gaps, resume the planner with corrections. + +### Step 4: Implement — invoke `refactor-coder` + +Use the `refactor-coder` agent (subagent_type: "generalPurpose"). Pass it: +- The implementation plan from step 3 +- If this is a retry: the reviewer/tester feedback that caused the retry + +The coder makes the changes and runs `make all` to catch formatting/lint issues early. + +### Step 5: Review — invoke `refactor-reviewer` + +Use the `refactor-reviewer` agent (subagent_type: "generalPurpose", readonly: true). Pass it: +- The git diff: run `git diff` and include the output +- The original phase instructions (goal + work items) +- The implementation plan from step 3 + +The reviewer returns PASS or FAIL. + +**If FAIL**: Resume the `refactor-coder` with the reviewer's specific issues. The coder +fixes them and you re-invoke the reviewer. **Maximum 3 review loops** — if still failing +after 3 rounds, present the issues to the user for judgment. + +**If PASS**: Continue to step 6. + +### Step 6: Test — invoke `refactor-tester` + +Use the `refactor-tester` agent (subagent_type: "generalPurpose"). Pass it: +- The list of files changed (from the coder's report) +- A description of what changed + +The tester runs `make all`, then `make test-short` (fast pass), then `make test` (race +detector, only if concurrency is involved), checks coverage, and adds tests if needed. + +**If FAIL**: Resume the `refactor-coder` with the tester's specific failures. After +fixes, re-run the reviewer (step 5) then the tester (step 6). **Maximum 3 test loops** — +escalate to user after 3. + +**If PASS**: Continue to step 7. + +### Step 7: Benchmark (quick sanity check) + +Run a quick benchmark sanity check — NOT the full statistical suite. This is just to +catch obvious regressions, not to produce publishable numbers. + +```bash +make bench-fast # count=1, ~1-2 minutes +``` + +**Do NOT run `make bench-compare` (count=5) or `make bench-baseline` during the iteration +loop.** Those take 5+ minutes each and are for establishing statistical baselines only. + +Phase-specific guidance: +- **Phase 0**: Run `make bench-baseline` (one-time, establishes the starting point) +- **Phases 1-8**: Run `make bench-fast` and eyeball the numbers. If something looks + obviously regressed (2x+ worse), investigate. Minor variance is expected with count=1. +- **Phase 9**: Run `make bench-compare` for the final statistical comparison. + +### Step 8: Commit + +```bash +git add -A +git commit -m "" +``` + +Report to the user: +- Phase N complete +- Summary of what changed (files, key changes) +- Benchmark comparison (if applicable) +- Any issues encountered and how they were resolved + +## Verification Protocol + +These checks run as part of steps 5-7, but for reference: + +```bash +make all # gofumpt + import ordering + golangci-lint +make test-short # fast tests (~30s) +make test # full tests with race detector (~1-2 min, for concurrency changes) +make bench-fast # quick benchmark sanity check (~1-2 min, count=1) +``` + +`make bench-compare` (count=5, ~5 min) is only for Phase 0 (baseline) and Phase 9 (final). + +## Special Phase Notes + +### Phase 0 (Baseline) + +Phase 0 is different — it doesn't involve code refactoring. It creates the Makefile and +captures baseline benchmarks. The planner/reviewer/tester loop is lighter here: +- The planner designs the Makefile targets +- The coder creates the Makefile +- The tester verifies that `make test` and `make bench-fast` work +- Save baseline results + +### Phase 9 (Final) + +Phase 9 is also different — it's documentation and benchmarks, not code changes: +- Run final fast-suite and production benchmarks +- Generate benchstat comparison against phase 0 baseline +- Update docs/architecture-review.md with results +- Write PR summary + +## Error Recovery + +If a phase gets stuck (3 review or test loops exhausted): +1. Present all issues to the user +2. Ask for guidance: fix manually, skip the issue, or abort the phase +3. If the user provides a fix direction, resume the coder with that guidance + +If a benchmark regression is detected: +1. Report the specific benchmark and the magnitude of regression +2. Check if the regression is in the expected area (e.g., a structural change that adds + a small overhead now but enables larger savings in a later phase) +3. Ask the user whether to proceed or investigate diff --git a/.cursor/skills/perf-optimize/SKILL.md b/.cursor/skills/perf-optimize/SKILL.md new file mode 100644 index 00000000..0e6d83f3 --- /dev/null +++ b/.cursor/skills/perf-optimize/SKILL.md @@ -0,0 +1,222 @@ +--- +name: perf-optimize +description: | + Performance optimization workflow for libopenapi-validator. Use when the user wants to find + and fix performance bottlenecks, run benchmarks, analyze memory/CPU usage, or optimize + validation throughput. This skill orchestrates a multi-step workflow using specialized + subagents for benchmarking, analysis, investigation, and implementation. +--- + +# Performance Optimization Workflow + +This skill orchestrates a systematic approach to finding and fixing performance bottlenecks +in the libopenapi-validator library. It uses five specialized subagents with verification +loops to ensure findings are evidence-based before any code changes are made. + +## Architecture + +``` +benchmarker → analyzer → investigator ⇄ verifier → fixer → benchmarker (re-verify) → summarizer + ↑ | + └──── FAIL ────┘ (loop until PASS) +``` + +The key principle is that NO claim about a bottleneck proceeds to implementation without +being independently verified. The `perf-verifier` subagent acts as a skeptical reviewer +that challenges conclusions against actual benchmark data and source code. + +## Context + +The libopenapi-validator library has known performance issues in production: +- **Memory**: ~1MB/s per endpoint for validation (19 endpoints = 15-23MB/s) +- **Path matching**: The regex fallback iterates ALL paths with regex for every request +- **Schema validation**: Schema compilation and rendering may be duplicated per-request +- **Goroutine overhead**: Async validation spawns goroutines even for simple validations + +## Benchmark Suites + +There are two benchmark suites. **Use the fast suite for all iterative work.** + +### Fast suite (use this during optimization) +- **File**: `benchmarks/validator_bench_test.go` +- **Spec**: `test_specs/ads_api_bulk_actions.yaml` (~25 endpoints) +- **Run time**: ~5 minutes for full suite with `-count=5` +- **Run with**: `go test -bench='Benchmark(PathMatch|RequestValidation|ResponseValidation|RequestResponseValidation|ConcurrentValidation|Memory)' -benchmem -count=5 -timeout=10m ./benchmarks/` + +Covers: path matching (radix vs regex), request body (small/medium/large), sync vs +async, concurrent, memory, schema cache impact, endpoint count scaling. + +**IMPORTANT**: The regex deliberately EXCLUDES `BenchmarkValidatorInit_*` and +`BenchmarkProd_Init*`. Initialization only happens once at service startup and is NOT +representative of request-time performance. Agents should focus exclusively on per-request +CPU and memory — the benchmarks that simulate actual production traffic. + +### Production suite (final snapshot only) +- **File**: `benchmarks/production_bench_test.go` +- **Spec**: `~/src/ads-api/open_api_spec/v3/complete.yaml` (69K lines, real prod spec) +- **Run time**: 10-30 minutes +- **Run with**: `go test -bench=BenchmarkProd -benchmem -count=3 -timeout=30m ./benchmarks/` + +The fast benchmarks produce numbers in the same range as production for per-request validation. +The production suite has higher init cost (2.7s) but init is a one-time startup cost — we +don't care about it. + +**DO NOT run production benchmarks in the optimization loop.** They take too long. Only run +them once at the end for a final before/after comparison if the user asks. + +## Workflow Steps + +Execute these steps IN ORDER, using the corresponding subagent for each. + +### Step 1: Run Benchmarks (`/perf-benchmarker`) + +Use the `perf-benchmarker` subagent to: +- Run the full benchmark suite with `-benchmem -count=5` +- Save baseline results to `benchmarks/results/baseline.txt` +- Generate CPU and memory profiles +- Report raw numbers + +### Step 2: Analyze Results (`/perf-analyzer`) + +Use the `perf-analyzer` subagent to: +- Parse benchmark results and identify the worst performers +- Compare radix tree vs regex fallback performance +- Identify memory allocation hotspots (high B/op and allocs/op) +- Determine which validation phase is the bottleneck +- Produce a prioritized list of issues to focus on + +### Step 3: Investigate Bottleneck (`/perf-investigator`) + +Use the `perf-investigator` subagent to: +- Read the source code of the identified bottleneck area +- Use CPU/memory profiles to find hot functions AND drill into line-level detail +- Trace the allocation path from the benchmark to the source +- Identify the root cause (unnecessary allocations, missing caches, etc.) +- Document exactly where in the code the problem originates +- Propose a specific fix with expected improvement + +### Step 4: Verify the Findings (`/perf-verifier`) ← CRITICAL STEP + +**DO NOT SKIP THIS STEP.** Use the `perf-verifier` subagent to independently fact-check +the investigator's findings. Pass it the full output from Step 3. + +The verifier will: +- Check that cited benchmark numbers match the actual results file +- Verify that profile data supports the claimed bottleneck +- Cross-reference the proposed root cause against source code +- Check for logical errors (correlation ≠ causation, misleading aggregates, etc.) +- Look for bigger bottlenecks that may have been overlooked +- Return PASS or FAIL with specific objections + +**If FAIL**: Resume the `perf-investigator` (using the `resume` parameter) with the +verifier's objections. The investigator should address each objection and produce an +updated finding. Then run the verifier again. **Repeat until PASS.** + +Example orchestration: +``` +1. investigator produces findings → save agent ID +2. verifier reviews findings → FAIL with objections +3. resume investigator (agent ID) with: "The verifier found these issues: [objections]. + Please address each one and update your findings." +4. investigator produces updated findings +5. verifier reviews again → PASS +6. proceed to Step 5 +``` + +**Maximum 3 loops.** If verification doesn't pass after 3 rounds, present the disagreement +to the user for a human judgment call. + +### Step 5: Fix and Verify (`/perf-fixer`) + +**IMPORTANT**: The fixer MUST create a new git branch before making any code changes. +If it fails to do so, stop and re-invoke it with an explicit reminder to branch first. + +Use the `perf-fixer` subagent to: +- **Create a new branch FIRST**: `perf/fix-` (before any edits!) +- Implement the optimization +- Run benchmarks again and save to `benchmarks/results/optimized.txt` +- Run `benchstat baseline.txt optimized.txt` to compare +- Run `go test ./...` to ensure no regressions +- Report the improvement metrics + +After the fixer completes, verify the branch was created: +```bash +git branch --show-current # Should NOT be the original branch +``` +If it's still on the original branch, the fixer did not follow instructions. Revert the changes +and re-invoke with: "You MUST create branch perf/fix- FIRST before any code changes." + +### Step 6: Verify the Fix (`/perf-verifier` again) + +Run the verifier one more time on the fixer's results to confirm: +- Benchmark numbers actually improved (not just noise) +- The improvement is in the RIGHT benchmark (the one identified in Step 3) +- All tests pass +- No unexpected regressions in other benchmarks + +If the fix doesn't show improvement, the verifier should flag this and you should +either iterate on the fix or go back to Step 3 to re-investigate. + +### Step 7: Generate PR Summary (`/perf-summarizer`) + +Use the `perf-summarizer` subagent to produce a concise, paste-ready PR description. + +Pass it: +- The investigator's findings (the bottleneck that was identified) +- The fixer's report (what code changed, benchstat output) +- The verifier's final assessment + +The summarizer will return markdown that can be directly pasted into a GitHub PR body. +It follows strict rules to keep things short: no filler, tables for numbers, bullets for changes. + +Present the summary to the user. They can paste it directly or ask for edits. + +## Commands Reference + +```bash +# Run fast benchmarks (save baseline) — use this during optimization +cd /Users/zach.hamm/src/libopenapi-validator +go test -bench='Benchmark(PathMatch|RequestValidation|ResponseValidation|RequestResponseValidation|ConcurrentValidation|Memory)' -benchmem -count=5 -timeout=10m ./benchmarks/ | tee benchmarks/results/baseline.txt + +# Run with CPU profiling +go test -bench=BenchmarkRequestValidation_BulkActions_Medium -cpuprofile=benchmarks/results/cpu.prof -benchmem -count=1 ./benchmarks/ + +# Run with memory profiling +go test -bench=BenchmarkRequestValidation_BulkActions_Medium -memprofile=benchmarks/results/mem.prof -benchmem -count=1 ./benchmarks/ + +# Analyze profiles +go tool pprof -top benchmarks/results/cpu.prof +go tool pprof -top benchmarks/results/mem.prof + +# Compare results +benchstat benchmarks/results/baseline.txt benchmarks/results/optimized.txt + +# Run unit tests +go test ./... +``` + +## Key Areas to Investigate + +Based on production observations, these are the most likely bottleneck areas: + +1. **`paths/paths.go` - FindPath() regex fallback**: Iterates ALL paths with regex compilation + for every request that doesn't hit the radix tree. Should sort by specificity and exit early. + +2. **`validator.go` - ValidateHttpRequest()**: Spawns goroutines + channels for every request. + For simple validations, this overhead may exceed the validation cost itself. + +3. **`requests/validate_body.go`**: Schema rendering and compilation may happen per-request + even with caching if cache keys don't match. + +4. **`helpers/schema_compiler.go`**: JSON schema compilation is expensive. Check if schemas + are being recompiled unnecessarily. + +5. **`schema_validation/`**: The core JSON schema validation may have allocation-heavy paths. + +## Success Criteria + +- Per-request memory allocation reduced by 50%+ for GET requests +- Per-request memory allocation reduced by 30%+ for POST requests with body +- Path matching with radix tree: 0 allocations +- Regex fallback: sorted by specificity with early exit (not scanning all paths) +- No test regressions (`go test ./...` passes) diff --git a/Makefile b/Makefile index 6d18b84c..a202f842 100644 --- a/Makefile +++ b/Makefile @@ -1,9 +1,15 @@ +# libopenapi-validator Makefile +# Targets for formatting, linting, testing, and benchmarking. + +.PHONY: all init lint gofumpt import test test-short test-all bench-fast bench-baseline bench-compare + all: gofumpt import lint init: go install mvdan.cc/gofumpt@v0.7.0 go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.61.0 go install github.com/daixiang0/gci@v0.13.5 + go install golang.org/x/perf/cmd/benchstat@latest lint: golangci-lint run ./... @@ -13,3 +19,35 @@ gofumpt: import: gci write --skip-generated -s standard -s default -s localmodule -s blank -s dot -s alias . + +# Run library tests with race detector (excludes benchmarks/ package) +test: + go test $$(go list ./... | grep -v /benchmarks) -count=1 -race -timeout=5m + +# Run library tests without race detector for faster iteration (excludes benchmarks/ package) +test-short: + go test $$(go list ./... | grep -v /benchmarks) -count=1 -short -timeout=2m + +# Run ALL tests including benchmarks/ package (production spec tests, ~40s extra) +test-all: + go test ./... -count=1 -race -timeout=5m + +# Run the fast benchmark suite (excludes Init and Prod benchmarks) +bench-fast: + go test -bench='Benchmark(PathMatch|RequestValidation|ResponseValidation|RequestResponseValidation|ConcurrentValidation|Memory)' \ + -benchmem -count=1 -timeout=10m ./benchmarks/ + +# Run fast suite with count=5 and save as baseline +bench-baseline: + @mkdir -p benchmarks/results + go test -bench='Benchmark(PathMatch|RequestValidation|ResponseValidation|RequestResponseValidation|ConcurrentValidation|Memory)' \ + -benchmem -count=5 -timeout=30m ./benchmarks/ \ + | tee benchmarks/results/baseline.txt + +# Run fast suite with count=5, save as current, compare against baseline +bench-compare: + @mkdir -p benchmarks/results + go test -bench='Benchmark(PathMatch|RequestValidation|ResponseValidation|RequestResponseValidation|ConcurrentValidation|Memory)' \ + -benchmem -count=5 -timeout=30m ./benchmarks/ \ + | tee benchmarks/results/current.txt + benchstat benchmarks/results/baseline.txt benchmarks/results/current.txt diff --git a/benchmarks.test b/benchmarks.test new file mode 100755 index 00000000..29d66066 Binary files /dev/null and b/benchmarks.test differ diff --git a/benchmarks/discriminator_bench_test.go b/benchmarks/discriminator_bench_test.go new file mode 100644 index 00000000..63ec131d --- /dev/null +++ b/benchmarks/discriminator_bench_test.go @@ -0,0 +1,501 @@ +// Benchmarks comparing oneOf+discriminator vs if/then for discriminated unions. +// +// Run with: +// go test -bench=BenchmarkDiscriminator -benchmem -count=5 -timeout=10m ./benchmarks/ +// +// The oneOf approach validates against ALL schemas to find the match. +// The if/then approach only validates against the schema where the if condition passes. + +package benchmarks + +import ( + "bytes" + "encoding/json" + "fmt" + "net/http" + "os" + "sync" + "testing" + + "github.com/pb33f/libopenapi" + + validator "github.com/pb33f/libopenapi-validator" +) + +var ( + oneOfSpec []byte + ifThenSpec []byte + discOnce sync.Once + + oneOfDoc libopenapi.Document + ifThenDoc libopenapi.Document + discDocs sync.Once +) + +func loadDiscSpecs() { + discOnce.Do(func() { + var err error + oneOfSpec, err = os.ReadFile("../test_specs/discriminator_oneof.yaml") + if err != nil { + panic(fmt.Sprintf("failed to read discriminator_oneof.yaml: %v", err)) + } + ifThenSpec, err = os.ReadFile("../test_specs/discriminator_ifthen.yaml") + if err != nil { + panic(fmt.Sprintf("failed to read discriminator_ifthen.yaml: %v", err)) + } + }) +} + +func buildDiscDocs() { + loadDiscSpecs() + discDocs.Do(func() { + var err error + oneOfDoc, err = libopenapi.NewDocument(oneOfSpec) + if err != nil { + panic(fmt.Sprintf("failed to create oneOf document: %v", err)) + } + ifThenDoc, err = libopenapi.NewDocument(ifThenSpec) + if err != nil { + panic(fmt.Sprintf("failed to create if/then document: %v", err)) + } + }) +} + +// --- Payloads --- + +// Single action: validates one item against the discriminated union +func singleCampaignAction() []byte { + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": "ref_1", + "entity_data": map[string]interface{}{ + "entity_type": "CAMPAIGN", + "name": "Test Campaign", + "objective": "CONVERSIONS", + "daily_budget_micro": 5000000, + "start_time": "2025-01-15T00:00:00Z", + "funding_instrument_id": "fi_123", + "configured_status": "PAUSED", + }, + }, + }, + } + b, _ := json.Marshal(payload) + return b +} + +// Single POST action (tests the 4th branch - should be slower with oneOf since +// it has to fail on CAMPAIGN, AD_GROUP, AD before finding POST) +func singlePostAction() []byte { + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "POST", + "action": "CREATE", + "reference_id": "ref_1", + "entity_data": map[string]interface{}{ + "entity_type": "POST", + "headline": "Check out our product!", + "post_type": "IMAGE", + "content": []map[string]interface{}{ + { + "content_type": "IMAGE", + "url": "https://example.com/image.jpg", + "destination_url": "https://example.com/landing", + "call_to_action": "SHOP_NOW", + }, + }, + }, + }, + }, + } + b, _ := json.Marshal(payload) + return b +} + +// Mixed payload: 4 different entity types (typical BulkActions request) +func mixedBulkActions() []byte { + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": "ref_campaign", + "entity_data": map[string]interface{}{ + "entity_type": "CAMPAIGN", + "name": "Campaign 1", + "objective": "CONVERSIONS", + "daily_budget_micro": 5000000, + "start_time": "2025-01-15T00:00:00Z", + "funding_instrument_id": "fi_123", + }, + }, + { + "type": "AD_GROUP", + "action": "CREATE", + "reference_id": "ref_ad_group", + "entity_data": map[string]interface{}{ + "entity_type": "AD_GROUP", + "name": "Ad Group 1", + "campaign_id": "camp_123", + "bid_strategy": "AUTO", + "goal_type": "CONVERSIONS", + "start_time": "2025-01-15T00:00:00Z", + "targeting": map[string]interface{}{ + "geos": map[string]interface{}{ + "included": []map[string]interface{}{ + {"country": "US"}, + }, + }, + "devices": []string{"DESKTOP", "MOBILE"}, + }, + }, + }, + { + "type": "POST", + "action": "CREATE", + "reference_id": "ref_post", + "entity_data": map[string]interface{}{ + "entity_type": "POST", + "headline": "Amazing Product", + "post_type": "IMAGE", + "content": []map[string]interface{}{ + { + "content_type": "IMAGE", + "url": "https://example.com/img.jpg", + "destination_url": "https://example.com", + "call_to_action": "LEARN_MORE", + }, + }, + }, + }, + { + "type": "AD", + "action": "CREATE", + "reference_id": "ref_ad", + "entity_data": map[string]interface{}{ + "entity_type": "AD", + "name": "Ad 1", + "ad_group_id": "ag_123", + "post_id": "post_123", + "click_url": "https://example.com/landing", + }, + }, + }, + } + b, _ := json.Marshal(payload) + return b +} + +// Large payload: 20 items (5 of each entity type, simulates heavy BulkActions) +func largeMixedBulkActions() []byte { + actions := make([]map[string]interface{}, 0, 20) + + for i := 0; i < 4; i++ { + actions = append(actions, map[string]interface{}{ + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": fmt.Sprintf("ref_campaign_%d", i), + "entity_data": map[string]interface{}{ + "entity_type": "CAMPAIGN", + "name": fmt.Sprintf("Campaign %d", i), + "objective": "CONVERSIONS", + "daily_budget_micro": 5000000, + "start_time": "2025-01-15T00:00:00Z", + "funding_instrument_id": "fi_123", + }, + }) + actions = append(actions, map[string]interface{}{ + "type": "AD_GROUP", + "action": "CREATE", + "reference_id": fmt.Sprintf("ref_ag_%d", i), + "entity_data": map[string]interface{}{ + "entity_type": "AD_GROUP", + "name": fmt.Sprintf("Ad Group %d", i), + "campaign_id": "camp_123", + "bid_strategy": "AUTO", + "goal_type": "CONVERSIONS", + "start_time": "2025-01-15T00:00:00Z", + }, + }) + actions = append(actions, map[string]interface{}{ + "type": "POST", + "action": "CREATE", + "reference_id": fmt.Sprintf("ref_post_%d", i), + "entity_data": map[string]interface{}{ + "entity_type": "POST", + "headline": fmt.Sprintf("Product %d", i), + "post_type": "IMAGE", + "content": []map[string]interface{}{ + { + "content_type": "IMAGE", + "url": "https://example.com/img.jpg", + "destination_url": "https://example.com", + "call_to_action": "SHOP_NOW", + }, + }, + }, + }) + actions = append(actions, map[string]interface{}{ + "type": "AD", + "action": "CREATE", + "reference_id": fmt.Sprintf("ref_ad_%d", i), + "entity_data": map[string]interface{}{ + "entity_type": "AD", + "name": fmt.Sprintf("Ad %d", i), + "ad_group_id": "ag_123", + "post_id": "post_123", + "click_url": "https://example.com/landing", + }, + }) + actions = append(actions, map[string]interface{}{ + "type": "ASSET", + "action": "CREATE", + "reference_id": fmt.Sprintf("ref_asset_%d", i), + "entity_data": map[string]interface{}{ + "entity_type": "ASSET", + "asset_type": "IMAGE", + "url": "https://example.com/asset.jpg", + "width": 1200, + "height": 628, + }, + }) + } + + payload := map[string]interface{}{"data": actions} + b, _ := json.Marshal(payload) + return b +} + +// --- Benchmarks --- + +// === Validator Init === + +func BenchmarkDiscriminator_Init_OneOf(b *testing.B) { + loadDiscSpecs() + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + doc, _ := libopenapi.NewDocument(oneOfSpec) + v, errs := validator.NewValidator(doc) + if errs != nil { + b.Fatal(errs) + } + _ = v + } +} + +func BenchmarkDiscriminator_Init_IfThen(b *testing.B) { + loadDiscSpecs() + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + doc, _ := libopenapi.NewDocument(ifThenSpec) + v, errs := validator.NewValidator(doc) + if errs != nil { + b.Fatal(errs) + } + _ = v + } +} + +// === Single item: CAMPAIGN (1st in oneOf list - best case for oneOf) === + +func BenchmarkDiscriminator_SingleCampaign_OneOf(b *testing.B) { + buildDiscDocs() + v, errs := validator.NewValidator(oneOfDoc) + if errs != nil { + b.Fatal(errs) + } + payload := singleCampaignAction() + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_123/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkDiscriminator_SingleCampaign_IfThen(b *testing.B) { + buildDiscDocs() + v, errs := validator.NewValidator(ifThenDoc) + if errs != nil { + b.Fatal(errs) + } + payload := singleCampaignAction() + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_123/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +// === Single item: POST (4th in oneOf list + nested content discriminator) === + +func BenchmarkDiscriminator_SinglePost_OneOf(b *testing.B) { + buildDiscDocs() + v, errs := validator.NewValidator(oneOfDoc) + if errs != nil { + b.Fatal(errs) + } + payload := singlePostAction() + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_123/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkDiscriminator_SinglePost_IfThen(b *testing.B) { + buildDiscDocs() + v, errs := validator.NewValidator(ifThenDoc) + if errs != nil { + b.Fatal(errs) + } + payload := singlePostAction() + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_123/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +// === Mixed payload: 4 items (typical BulkActions) === + +func BenchmarkDiscriminator_Mixed4_OneOf(b *testing.B) { + buildDiscDocs() + v, errs := validator.NewValidator(oneOfDoc) + if errs != nil { + b.Fatal(errs) + } + payload := mixedBulkActions() + b.ReportMetric(float64(len(payload)), "payload-bytes") + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_123/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkDiscriminator_Mixed4_IfThen(b *testing.B) { + buildDiscDocs() + v, errs := validator.NewValidator(ifThenDoc) + if errs != nil { + b.Fatal(errs) + } + payload := mixedBulkActions() + b.ReportMetric(float64(len(payload)), "payload-bytes") + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_123/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +// === Large payload: 20 items (heavy BulkActions) === + +func BenchmarkDiscriminator_Large20_OneOf(b *testing.B) { + buildDiscDocs() + v, errs := validator.NewValidator(oneOfDoc) + if errs != nil { + b.Fatal(errs) + } + payload := largeMixedBulkActions() + b.ReportMetric(float64(len(payload)), "payload-bytes") + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_123/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkDiscriminator_Large20_IfThen(b *testing.B) { + buildDiscDocs() + v, errs := validator.NewValidator(ifThenDoc) + if errs != nil { + b.Fatal(errs) + } + payload := largeMixedBulkActions() + b.ReportMetric(float64(len(payload)), "payload-bytes") + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_123/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +// === Concurrent mixed === + +func BenchmarkDiscriminator_Concurrent_OneOf(b *testing.B) { + buildDiscDocs() + v, errs := validator.NewValidator(oneOfDoc) + if errs != nil { + b.Fatal(errs) + } + payload := mixedBulkActions() + b.ResetTimer() + b.ReportAllocs() + b.RunParallel(func(pb *testing.PB) { + for pb.Next() { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_123/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } + }) +} + +func BenchmarkDiscriminator_Concurrent_IfThen(b *testing.B) { + buildDiscDocs() + v, errs := validator.NewValidator(ifThenDoc) + if errs != nil { + b.Fatal(errs) + } + payload := mixedBulkActions() + b.ResetTimer() + b.ReportAllocs() + b.RunParallel(func(pb *testing.PB) { + for pb.Next() { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_123/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } + }) +} diff --git a/benchmarks/discriminator_errors_test.go b/benchmarks/discriminator_errors_test.go new file mode 100644 index 00000000..ff9d07a4 --- /dev/null +++ b/benchmarks/discriminator_errors_test.go @@ -0,0 +1,286 @@ +// Compare validation error messages between oneOf+discriminator and if/then approaches. +// +// Run with: +// go test -run=TestErrorComparison -v -timeout=5m ./benchmarks/ + +package benchmarks + +import ( + "bytes" + "encoding/json" + "net/http" + "os" + "testing" + + "github.com/pb33f/libopenapi" + + validator "github.com/pb33f/libopenapi-validator" + "github.com/pb33f/libopenapi-validator/errors" +) + +func loadDiscriminatorSpecs(t *testing.T) (validator.Validator, validator.Validator) { + t.Helper() + + oneOfBytes, err := os.ReadFile("../test_specs/discriminator_oneof.yaml") + if err != nil { + t.Fatalf("failed to read discriminator_oneof.yaml: %v", err) + } + ifThenBytes, err := os.ReadFile("../test_specs/discriminator_ifthen.yaml") + if err != nil { + t.Fatalf("failed to read discriminator_ifthen.yaml: %v", err) + } + + oneOfDoc, err := libopenapi.NewDocument(oneOfBytes) + if err != nil { + t.Fatalf("failed to parse oneOf spec: %v", err) + } + ifThenDoc, err := libopenapi.NewDocument(ifThenBytes) + if err != nil { + t.Fatalf("failed to parse if/then spec: %v", err) + } + + oneOfV, errs := validator.NewValidator(oneOfDoc) + if errs != nil { + t.Fatalf("failed to create oneOf validator: %v", errs) + } + ifThenV, errs := validator.NewValidator(ifThenDoc) + if errs != nil { + t.Fatalf("failed to create if/then validator: %v", errs) + } + + return oneOfV, ifThenV +} + +func makeDiscReq(t *testing.T, payload interface{}) *http.Request { + t.Helper() + b, _ := json.Marshal(payload) + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_123/bulk_actions", + bytes.NewReader(b)) + req.Header.Set("Content-Type", "application/json") + return req +} + +func printErrors(t *testing.T, label string, valid bool, errs []*errors.ValidationError) { + t.Helper() + t.Logf("\n=== %s ===", label) + t.Logf("Valid: %v | Error count: %d", valid, len(errs)) + for i, e := range errs { + t.Logf(" [%d] Message: %s", i+1, e.Message) + if e.Reason != "" { + t.Logf(" Reason: %s", e.Reason) + } + for j, sve := range e.SchemaValidationErrors { + t.Logf(" schema[%d] reason: %s", j+1, sve.Reason) + if sve.Location != "" { + t.Logf(" schema[%d] location: %s", j+1, sve.Location) + } + if sve.FieldPath != "" { + t.Logf(" schema[%d] fieldPath: %s", j+1, sve.FieldPath) + } + } + } +} + +// --- Test Cases --- + +// Case 1: Valid CAMPAIGN payload (should pass both) +func TestErrorComparison_ValidCampaign(t *testing.T) { + oneOfV, ifThenV := loadDiscriminatorSpecs(t) + + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": "ref_1", + "entity_data": map[string]interface{}{ + "entity_type": "CAMPAIGN", + "name": "Test Campaign", + "objective": "CONVERSIONS", + "daily_budget_micro": 5000000, + "start_time": "2025-01-15T00:00:00Z", + "funding_instrument_id": "fi_123", + }, + }, + }, + } + + req1 := makeDiscReq(t, payload) + valid1, errs1 := oneOfV.ValidateHttpRequest(req1) + + req2 := makeDiscReq(t, payload) + valid2, errs2 := ifThenV.ValidateHttpRequest(req2) + + printErrors(t, "oneOf: Valid Campaign", valid1, errs1) + printErrors(t, "if/then: Valid Campaign", valid2, errs2) +} + +// Case 2: Missing required fields in entity_data (CAMPAIGN missing name + objective) +func TestErrorComparison_MissingRequired(t *testing.T) { + oneOfV, ifThenV := loadDiscriminatorSpecs(t) + + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": "ref_1", + "entity_data": map[string]interface{}{ + "entity_type": "CAMPAIGN", + "daily_budget_micro": 5000000, + // missing: name, objective, start_time, funding_instrument_id + }, + }, + }, + } + + req1 := makeDiscReq(t, payload) + valid1, errs1 := oneOfV.ValidateHttpRequest(req1) + + req2 := makeDiscReq(t, payload) + valid2, errs2 := ifThenV.ValidateHttpRequest(req2) + + printErrors(t, "oneOf: Campaign missing required fields", valid1, errs1) + printErrors(t, "if/then: Campaign missing required fields", valid2, errs2) +} + +// Case 3: Invalid field value (bad enum for objective) +func TestErrorComparison_InvalidEnum(t *testing.T) { + oneOfV, ifThenV := loadDiscriminatorSpecs(t) + + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": "ref_1", + "entity_data": map[string]interface{}{ + "entity_type": "CAMPAIGN", + "name": "Test Campaign", + "objective": "NOT_A_VALID_OBJECTIVE", + "daily_budget_micro": 5000000, + "start_time": "2025-01-15T00:00:00Z", + "funding_instrument_id": "fi_123", + }, + }, + }, + } + + req1 := makeDiscReq(t, payload) + valid1, errs1 := oneOfV.ValidateHttpRequest(req1) + + req2 := makeDiscReq(t, payload) + valid2, errs2 := ifThenV.ValidateHttpRequest(req2) + + printErrors(t, "oneOf: Invalid objective enum", valid1, errs1) + printErrors(t, "if/then: Invalid objective enum", valid2, errs2) +} + +// Case 4: POST action with nested content error (VIDEO missing required "url") +func TestErrorComparison_NestedDiscriminatorError(t *testing.T) { + oneOfV, ifThenV := loadDiscriminatorSpecs(t) + + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "POST", + "action": "CREATE", + "reference_id": "ref_1", + "entity_data": map[string]interface{}{ + "entity_type": "POST", + "headline": "Check it out!", + "post_type": "IMAGE", + "content": []map[string]interface{}{ + { + "content_type": "IMAGE", + "url": "https://example.com/img.jpg", + }, + { + "content_type": "VIDEO", + // Missing required "url" field + }, + }, + }, + }, + }, + } + + req1 := makeDiscReq(t, payload) + valid1, errs1 := oneOfV.ValidateHttpRequest(req1) + + req2 := makeDiscReq(t, payload) + valid2, errs2 := ifThenV.ValidateHttpRequest(req2) + + printErrors(t, "oneOf: Nested content error (VIDEO missing url)", valid1, errs1) + printErrors(t, "if/then: Nested content error (VIDEO missing url)", valid2, errs2) +} + +// Case 5: Completely invalid entity_type value +func TestErrorComparison_UnknownEntityType(t *testing.T) { + oneOfV, ifThenV := loadDiscriminatorSpecs(t) + + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": "ref_1", + "entity_data": map[string]interface{}{ + "entity_type": "BANANA", + "name": "Test", + }, + }, + }, + } + + req1 := makeDiscReq(t, payload) + valid1, errs1 := oneOfV.ValidateHttpRequest(req1) + + req2 := makeDiscReq(t, payload) + valid2, errs2 := ifThenV.ValidateHttpRequest(req2) + + printErrors(t, "oneOf: Unknown entity_type 'BANANA'", valid1, errs1) + printErrors(t, "if/then: Unknown entity_type 'BANANA'", valid2, errs2) +} + +// Case 6: Multiple items where some valid, some invalid +func TestErrorComparison_MixedValidInvalid(t *testing.T) { + oneOfV, ifThenV := loadDiscriminatorSpecs(t) + + payload := map[string]interface{}{ + "data": []interface{}{ + map[string]interface{}{ + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": "ref_ok", + "entity_data": map[string]interface{}{ + "entity_type": "CAMPAIGN", + "name": "Good Campaign", + "objective": "CONVERSIONS", + "daily_budget_micro": 5000000, + "start_time": "2025-01-15T00:00:00Z", + "funding_instrument_id": "fi_123", + }, + }, + map[string]interface{}{ + "type": "AD", + "action": "CREATE", + "reference_id": "ref_bad", + "entity_data": map[string]interface{}{ + "entity_type": "AD", + // missing: name, ad_group_id, post_id + }, + }, + }, + } + + req1 := makeDiscReq(t, payload) + valid1, errs1 := oneOfV.ValidateHttpRequest(req1) + + req2 := makeDiscReq(t, payload) + valid2, errs2 := ifThenV.ValidateHttpRequest(req2) + + printErrors(t, "oneOf: Mixed valid+invalid items", valid1, errs1) + printErrors(t, "if/then: Mixed valid+invalid items", valid2, errs2) +} diff --git a/benchmarks/error_comparison_test.go b/benchmarks/error_comparison_test.go new file mode 100644 index 00000000..d02246c6 --- /dev/null +++ b/benchmarks/error_comparison_test.go @@ -0,0 +1,179 @@ +// Compare validation error messages using the production complete.yaml spec. +// +// Run with: +// go test -run=TestProdErrors -v -timeout=5m ./benchmarks/ + +package benchmarks + +import ( + "bytes" + "encoding/json" + "net/http" + "testing" + + "github.com/pb33f/libopenapi-validator/errors" +) + +func printDetailedErrors(t *testing.T, label string, valid bool, errs []*errors.ValidationError) { + t.Helper() + t.Logf("\n=== %s ===", label) + t.Logf("Valid: %v | Error count: %d", valid, len(errs)) + for i, e := range errs { + t.Logf(" [%d] Message: %s", i+1, e.Message) + if e.Reason != "" { + t.Logf(" Reason: %s", e.Reason) + } + if e.ValidationType != "" { + t.Logf(" ValidationType: %s", e.ValidationType) + } + for j, sve := range e.SchemaValidationErrors { + t.Logf(" schema[%d] reason: %s", j+1, sve.Reason) + if sve.Location != "" { + t.Logf(" schema[%d] location: %s", j+1, sve.Location) + } + if sve.FieldPath != "" { + t.Logf(" schema[%d] fieldPath: %s", j+1, sve.FieldPath) + } + if sve.FieldName != "" { + t.Logf(" schema[%d] fieldName: %s", j+1, sve.FieldName) + } + } + } +} + +func makeProdReq(t *testing.T, payload interface{}) *http.Request { + t.Helper() + b, _ := json.Marshal(payload) + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(b)) + req.Header.Set("Content-Type", "application/json") + return req +} + +// Case 1: Missing required field (entity_data) +func TestProdErrors_MissingEntityData(t *testing.T) { + v := newProdValidator(t) + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + // entity_data is missing + }, + }, + } + req := makeProdReq(t, payload) + valid, errs := v.ValidateHttpRequest(req) + printDetailedErrors(t, "Missing entity_data", valid, errs) +} + +// Case 2: Invalid enum value for "type" +func TestProdErrors_InvalidType(t *testing.T) { + v := newProdValidator(t) + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "BANANA", + "action": "CREATE", + "entity_data": map[string]interface{}{ + "name": "Test", + "objective": "CONVERSIONS", + }, + }, + }, + } + req := makeProdReq(t, payload) + valid, errs := v.ValidateHttpRequest(req) + printDetailedErrors(t, "Invalid type 'BANANA'", valid, errs) +} + +// Case 3: Extra field on BulkAction item (additionalProperties: false) +func TestProdErrors_ExtraField(t *testing.T) { + v := newProdValidator(t) + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "entity_data": map[string]interface{}{ + "name": "Campaign", + "objective": "CONVERSIONS", + }, + "this_field_does_not_exist": "boom", + }, + }, + } + req := makeProdReq(t, payload) + valid, errs := v.ValidateHttpRequest(req) + printDetailedErrors(t, "Extra field on item", valid, errs) +} + +// Case 4: Invalid objective enum +func TestProdErrors_InvalidEnum(t *testing.T) { + v := newProdValidator(t) + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "entity_data": map[string]interface{}{ + "name": "Campaign", + "objective": "NOT_REAL", + }, + }, + }, + } + req := makeProdReq(t, payload) + valid, errs := v.ValidateHttpRequest(req) + printDetailedErrors(t, "Invalid objective enum", valid, errs) +} + +// Case 5: Mixed valid + invalid items +func TestProdErrors_MixedItems(t *testing.T) { + v := newProdValidator(t) + payload := map[string]interface{}{ + "data": []interface{}{ + // Valid campaign + map[string]interface{}{ + "type": "CAMPAIGN", + "action": "CREATE", + "entity_data": map[string]interface{}{ + "name": "Good Campaign", + "objective": "CONVERSIONS", + }, + }, + // Invalid - missing entity_data + map[string]interface{}{ + "type": "AD_GROUP", + "action": "CREATE", + // missing entity_data + }, + }, + } + req := makeProdReq(t, payload) + valid, errs := v.ValidateHttpRequest(req) + printDetailedErrors(t, "Mixed valid + invalid", valid, errs) +} + +// Case 6: Wrong action for POST (POST only allows CREATE in the if/then spec) +func TestProdErrors_WrongActionForPost(t *testing.T) { + v := newProdValidator(t) + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "POST", + "action": "EDIT", + "entity_data": map[string]interface{}{ + "creative": map[string]interface{}{ + "type": "IMAGE", + "headline": "Test", + }, + }, + }, + }, + } + req := makeProdReq(t, payload) + valid, errs := v.ValidateHttpRequest(req) + printDetailedErrors(t, "POST with action=EDIT (only CREATE allowed)", valid, errs) +} diff --git a/benchmarks/production_bench_test.go b/benchmarks/production_bench_test.go new file mode 100644 index 00000000..07e4bd91 --- /dev/null +++ b/benchmarks/production_bench_test.go @@ -0,0 +1,992 @@ +// Benchmarks using the production Reddit Ads API complete.yaml spec. +// +// This uses the real production OpenAPI spec for accurate performance measurements. +// Includes both valid payloads (should pass validation) and invalid payloads (should fail). +// +// Run benchmarks: +// go test -bench=BenchmarkProd -benchmem -count=3 -timeout=10m ./benchmarks/ +// +// Run validation correctness tests: +// go test -run=TestProdPayload -v ./benchmarks/ + +package benchmarks + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" + "os" + "path/filepath" + "runtime" + "sync" + "testing" + + "github.com/pb33f/libopenapi" + + validator "github.com/pb33f/libopenapi-validator" +) + +var ( + prodSpec []byte + prodSpecOnce sync.Once + + prodDoc libopenapi.Document + prodDocOnce sync.Once +) + +func loadProdSpec(t testing.TB) { + t.Helper() + if testing.Short() { + t.Skip("skipping production spec test in short mode") + } + prodSpecOnce.Do(func() { + home, err := os.UserHomeDir() + if err != nil { + t.Skipf("cannot get home dir: %v", err) + return + } + specPath := filepath.Join(home, "src", "ads-api", "open_api_spec", "v3", "complete.yaml") + prodSpec, err = os.ReadFile(specPath) + if err != nil { + t.Skipf("production spec not found at %s: %v", specPath, err) + return + } + }) + if prodSpec == nil { + t.Skip("production spec not available") + } +} + +func buildProdDoc(t testing.TB) { + t.Helper() + loadProdSpec(t) + prodDocOnce.Do(func() { + var err error + prodDoc, err = libopenapi.NewDocument(prodSpec) + if err != nil { + panic(fmt.Sprintf("failed to parse production spec: %v", err)) + } + }) +} + +func newProdValidator(t testing.TB) validator.Validator { + t.Helper() + buildProdDoc(t) + v, errs := validator.NewValidator(prodDoc) + if errs != nil { + t.Fatalf("failed to create validator: %v", errs) + } + return v +} + +// --------------------------------------------------------------------------- +// Payloads: VALID +// --------------------------------------------------------------------------- + +// validCampaignAction - a single Campaign bulk action (minimal required fields) +func validCampaignAction() []byte { + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "entity_data": map[string]interface{}{ + "name": "Benchmark Campaign", + "objective": "CONVERSIONS", + }, + }, + }, + } + b, _ := json.Marshal(payload) + return b +} + +// validMixedBulkActions - 3 different entity types typical for a real BulkActions call +func validMixedBulkActions() []byte { + payload := map[string]interface{}{ + "data": []interface{}{ + map[string]interface{}{ + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": "ref_campaign_1", + "entity_data": map[string]interface{}{ + "name": "Perf Test Campaign", + "objective": "CONVERSIONS", + }, + }, + map[string]interface{}{ + "type": "AD_GROUP", + "action": "CREATE", + "reference_id": "ref_ag_1", + "entity_data": map[string]interface{}{ + "name": "Perf Test Ad Group", + "campaign_id": "{{ref_campaign_1}}", + "bid_strategy": "MAXIMIZE_VOLUME", + "bid_type": "CPC", + "start_time": "2025-06-01T00:00:00Z", + }, + }, + map[string]interface{}{ + "type": "POST", + "action": "CREATE", + "reference_id": "ref_post_1", + "entity_data": map[string]interface{}{ + "creative": map[string]interface{}{ + "type": "IMAGE", + "headline": "Check out our product!", + "destination": map[string]interface{}{ + "url": "https://example.com/landing", + "type": "URL", + }, + "image": map[string]interface{}{ + "media": map[string]interface{}{ + "url": "https://example.com/image.jpg", + "type": "URL", + }, + }, + }, + }, + }, + }, + } + b, _ := json.Marshal(payload) + return b +} + +// validLargeBulkActions - 15 items across entity types (realistic large batch) +func validLargeBulkActions() []byte { + actions := make([]interface{}, 0, 15) + + for i := 0; i < 5; i++ { + actions = append(actions, map[string]interface{}{ + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": fmt.Sprintf("ref_camp_%d", i), + "entity_data": map[string]interface{}{ + "name": fmt.Sprintf("Campaign %d", i), + "objective": "CONVERSIONS", + }, + }) + actions = append(actions, map[string]interface{}{ + "type": "AD_GROUP", + "action": "CREATE", + "reference_id": fmt.Sprintf("ref_ag_%d", i), + "entity_data": map[string]interface{}{ + "name": fmt.Sprintf("Ad Group %d", i), + "campaign_id": fmt.Sprintf("{{ref_camp_%d}}", i), + "bid_strategy": "MAXIMIZE_VOLUME", + "bid_type": "CPC", + "start_time": "2025-06-01T00:00:00Z", + }, + }) + actions = append(actions, map[string]interface{}{ + "type": "POST", + "action": "CREATE", + "reference_id": fmt.Sprintf("ref_post_%d", i), + "entity_data": map[string]interface{}{ + "creative": map[string]interface{}{ + "type": "IMAGE", + "headline": fmt.Sprintf("Product %d!", i), + "destination": map[string]interface{}{ + "url": fmt.Sprintf("https://example.com/landing/%d", i), + "type": "URL", + }, + "image": map[string]interface{}{ + "media": map[string]interface{}{ + "url": fmt.Sprintf("https://example.com/image_%d.jpg", i), + "type": "URL", + }, + }, + }, + }, + }) + } + + payload := map[string]interface{}{"data": actions} + b, _ := json.Marshal(payload) + return b +} + +// --------------------------------------------------------------------------- +// Payloads: INVALID (should produce validation errors) +// --------------------------------------------------------------------------- + +// invalidMissingEntityData - missing required field "entity_data" +func invalidMissingEntityData() []byte { + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + // entity_data is missing — required by schema + }, + }, + } + b, _ := json.Marshal(payload) + return b +} + +// invalidWrongType - type field has an invalid enum value +func invalidWrongType() []byte { + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "INVALID_TYPE", + "action": "CREATE", + "entity_data": map[string]interface{}{ + "name": "Bad Campaign", + "objective": "CONVERSIONS", + }, + }, + }, + } + b, _ := json.Marshal(payload) + return b +} + +// invalidExtraTopLevelField - additionalProperties is false, so unknown fields are invalid +func invalidExtraTopLevelField() []byte { + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "entity_data": map[string]interface{}{ + "name": "Campaign", + "objective": "CONVERSIONS", + }, + "this_field_does_not_exist": "boom", + }, + }, + } + b, _ := json.Marshal(payload) + return b +} + +// invalidEmptyData - data array is empty (should fail minItems if defined, or at least be a degenerate case) +func invalidEmptyData() []byte { + payload := map[string]interface{}{ + "data": []map[string]interface{}{}, + } + b, _ := json.Marshal(payload) + return b +} + +// invalidWrongContentType generates a valid payload but uses the wrong content type +// (this is tested at the request level, not at the payload level) + +// --------------------------------------------------------------------------- +// Validation correctness tests (not benchmarks) +// --------------------------------------------------------------------------- + +func TestProdPayload_ValidCampaignAction(t *testing.T) { + v := newProdValidator(t) + payload := validCampaignAction() + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + valid, errs := v.ValidateHttpRequest(req) + if !valid { + t.Logf("Validation errors for validCampaignAction:") + for _, e := range errs { + t.Logf(" - %s", e.Message) + } + } + t.Logf("validCampaignAction: valid=%v, errors=%d, payload=%d bytes", valid, len(errs), len(payload)) +} + +func TestProdPayload_ValidMixedBulkActions(t *testing.T) { + v := newProdValidator(t) + payload := validMixedBulkActions() + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + valid, errs := v.ValidateHttpRequest(req) + if !valid { + t.Logf("Validation errors for validMixedBulkActions:") + for _, e := range errs { + t.Logf(" - %s", e.Message) + } + } + t.Logf("validMixedBulkActions: valid=%v, errors=%d, payload=%d bytes", valid, len(errs), len(payload)) +} + +func TestProdPayload_ValidLargeBulkActions(t *testing.T) { + v := newProdValidator(t) + payload := validLargeBulkActions() + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + valid, errs := v.ValidateHttpRequest(req) + if !valid { + t.Logf("Validation errors for validLargeBulkActions:") + for _, e := range errs { + t.Logf(" - %s", e.Message) + } + } + t.Logf("validLargeBulkActions: valid=%v, errors=%d, payload=%d bytes", valid, len(errs), len(payload)) +} + +func TestProdPayload_InvalidMissingEntityData(t *testing.T) { + v := newProdValidator(t) + payload := invalidMissingEntityData() + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + valid, errs := v.ValidateHttpRequest(req) + t.Logf("invalidMissingEntityData: valid=%v, errors=%d", valid, len(errs)) + for _, e := range errs { + t.Logf(" - %s", e.Message) + } + if valid { + t.Error("expected validation to fail for missing entity_data, but it passed") + } +} + +func TestProdPayload_InvalidWrongType(t *testing.T) { + v := newProdValidator(t) + payload := invalidWrongType() + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + valid, errs := v.ValidateHttpRequest(req) + t.Logf("invalidWrongType: valid=%v, errors=%d", valid, len(errs)) + for _, e := range errs { + t.Logf(" - %s", e.Message) + } + if valid { + t.Error("expected validation to fail for wrong type enum, but it passed") + } +} + +func TestProdPayload_InvalidExtraField(t *testing.T) { + v := newProdValidator(t) + payload := invalidExtraTopLevelField() + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + valid, errs := v.ValidateHttpRequest(req) + t.Logf("invalidExtraField: valid=%v, errors=%d", valid, len(errs)) + for _, e := range errs { + t.Logf(" - %s", e.Message) + } + if valid { + t.Error("expected validation to fail for extra field (additionalProperties:false), but it passed") + } +} + +func TestProdPayload_InvalidContentType(t *testing.T) { + v := newProdValidator(t) + payload := validCampaignAction() + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "text/plain") // wrong content type + valid, errs := v.ValidateHttpRequest(req) + t.Logf("invalidContentType: valid=%v, errors=%d", valid, len(errs)) + for _, e := range errs { + t.Logf(" - %s", e.Message) + } + if valid { + t.Error("expected validation to fail for wrong content type, but it passed") + } +} + +func TestProdPayload_ValidGET_ListCampaigns(t *testing.T) { + v := newProdValidator(t) + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/campaigns?page.size=25", nil) + valid, errs := v.ValidateHttpRequest(req) + t.Logf("validGET_ListCampaigns: valid=%v, errors=%d", valid, len(errs)) + for _, e := range errs { + t.Logf(" - %s", e.Message) + } +} + +func TestProdPayload_ValidGET_ListAds(t *testing.T) { + v := newProdValidator(t) + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/ads?page.size=50", nil) + valid, errs := v.ValidateHttpRequest(req) + t.Logf("validGET_ListAds: valid=%v, errors=%d", valid, len(errs)) + for _, e := range errs { + t.Logf(" - %s", e.Message) + } +} + +func TestProdPayload_ValidGET_ListAdGroups(t *testing.T) { + v := newProdValidator(t) + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/ad_groups?campaign_id=camp_123&page.size=25", nil) + valid, errs := v.ValidateHttpRequest(req) + t.Logf("validGET_ListAdGroups: valid=%v, errors=%d", valid, len(errs)) + for _, e := range errs { + t.Logf(" - %s", e.Message) + } +} + +func TestProdPayload_InvalidGET_UnknownPath(t *testing.T) { + v := newProdValidator(t) + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/this/path/does/not/exist", nil) + valid, errs := v.ValidateHttpRequest(req) + t.Logf("invalidGET_UnknownPath: valid=%v, errors=%d", valid, len(errs)) + for _, e := range errs { + t.Logf(" - %s", e.Message) + } + if valid { + t.Error("expected validation to fail for unknown path, but it passed") + } +} + +// --------------------------------------------------------------------------- +// Benchmarks: Initialization +// --------------------------------------------------------------------------- + +func BenchmarkProd_Init(b *testing.B) { + loadProdSpec(b) + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + doc, err := libopenapi.NewDocument(prodSpec) + if err != nil { + b.Fatal(err) + } + v, errs := validator.NewValidator(doc) + if errs != nil { + b.Fatal(errs) + } + _ = v + } +} + +func BenchmarkProd_Init_MemoryFootprint(b *testing.B) { + loadProdSpec(b) + + var memBefore, memAfter runtime.MemStats + runtime.GC() + runtime.ReadMemStats(&memBefore) + + doc, err := libopenapi.NewDocument(prodSpec) + if err != nil { + b.Fatal(err) + } + v, errs := validator.NewValidator(doc) + if errs != nil { + b.Fatal(errs) + } + + runtime.GC() + runtime.ReadMemStats(&memAfter) + + heapDelta := memAfter.HeapAlloc - memBefore.HeapAlloc + b.ReportMetric(float64(heapDelta), "heap-bytes") + b.ReportMetric(float64(memAfter.HeapObjects-memBefore.HeapObjects), "heap-objects") + _ = v +} + +// --------------------------------------------------------------------------- +// Benchmarks: POST Bulk Actions — valid payloads +// --------------------------------------------------------------------------- + +func BenchmarkProd_BulkActions_SingleCampaign(b *testing.B) { + v := newProdValidator(b) + payload := validCampaignAction() + b.ReportMetric(float64(len(payload)), "payload-bytes") + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkProd_BulkActions_Mixed3(b *testing.B) { + v := newProdValidator(b) + payload := validMixedBulkActions() + b.ReportMetric(float64(len(payload)), "payload-bytes") + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkProd_BulkActions_Large15(b *testing.B) { + v := newProdValidator(b) + payload := validLargeBulkActions() + b.ReportMetric(float64(len(payload)), "payload-bytes") + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +// --------------------------------------------------------------------------- +// Benchmarks: POST Bulk Actions — invalid payloads (measures error path cost) +// --------------------------------------------------------------------------- + +func BenchmarkProd_BulkActions_Invalid_MissingField(b *testing.B) { + v := newProdValidator(b) + payload := invalidMissingEntityData() + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkProd_BulkActions_Invalid_WrongType(b *testing.B) { + v := newProdValidator(b) + payload := invalidWrongType() + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkProd_BulkActions_Invalid_ExtraField(b *testing.B) { + v := newProdValidator(b) + payload := invalidExtraTopLevelField() + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkProd_BulkActions_Invalid_ContentType(b *testing.B) { + v := newProdValidator(b) + payload := validCampaignAction() + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "text/plain") + v.ValidateHttpRequest(req) + } +} + +// --------------------------------------------------------------------------- +// Benchmarks: GET endpoints (path params + query params, no body) +// --------------------------------------------------------------------------- + +func BenchmarkProd_GET_ListCampaigns(b *testing.B) { + v := newProdValidator(b) + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/campaigns?page.size=25", nil) + v.ValidateHttpRequest(req) + } +} + +func BenchmarkProd_GET_ListAdGroups(b *testing.B) { + v := newProdValidator(b) + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/ad_groups?campaign_id=camp_123&page.size=25", nil) + v.ValidateHttpRequest(req) + } +} + +func BenchmarkProd_GET_ListAds(b *testing.B) { + v := newProdValidator(b) + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/ads?page.size=50", nil) + v.ValidateHttpRequest(req) + } +} + +func BenchmarkProd_GET_Me(b *testing.B) { + v := newProdValidator(b) + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/me", nil) + v.ValidateHttpRequest(req) + } +} + +func BenchmarkProd_GET_GetBulkActionsJob(b *testing.B) { + v := newProdValidator(b) + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/bulk_actions/job_67890", nil) + v.ValidateHttpRequest(req) + } +} + +// --------------------------------------------------------------------------- +// Benchmarks: Concurrent validation (simulates production load) +// --------------------------------------------------------------------------- + +func BenchmarkProd_Concurrent_BulkActions(b *testing.B) { + v := newProdValidator(b) + payload := validMixedBulkActions() + b.ResetTimer() + b.ReportAllocs() + b.RunParallel(func(pb *testing.PB) { + for pb.Next() { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } + }) +} + +func BenchmarkProd_Concurrent_MixedEndpoints(b *testing.B) { + v := newProdValidator(b) + payload := validMixedBulkActions() + + type testCase struct { + method string + url string + payload []byte + } + + cases := []testCase{ + {http.MethodGet, "/api/v3/ad_accounts/acc_123/campaigns?page.size=25", nil}, + {http.MethodGet, "/api/v3/ad_accounts/acc_123/ad_groups?page.size=25", nil}, + {http.MethodGet, "/api/v3/ad_accounts/acc_123/ads?page.size=50", nil}, + {http.MethodPost, "/api/v3/ad_accounts/acc_123/bulk_actions", payload}, + {http.MethodGet, "/api/v3/me", nil}, + {http.MethodGet, "/api/v3/ad_accounts/acc_123/bulk_actions/job_456", nil}, + } + + b.ResetTimer() + b.ReportAllocs() + b.RunParallel(func(pb *testing.PB) { + idx := 0 + for pb.Next() { + tc := cases[idx%len(cases)] + var req *http.Request + if tc.payload != nil { + req, _ = http.NewRequest(tc.method, tc.url, bytes.NewReader(tc.payload)) + req.Header.Set("Content-Type", "application/json") + } else { + req, _ = http.NewRequest(tc.method, tc.url, nil) + } + v.ValidateHttpRequest(req) + idx++ + } + }) +} + +// --------------------------------------------------------------------------- +// Benchmarks: Sync vs Async +// --------------------------------------------------------------------------- + +func BenchmarkProd_BulkActions_Sync(b *testing.B) { + v := newProdValidator(b) + payload := validMixedBulkActions() + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequestSync(req) + } +} + +func BenchmarkProd_BulkActions_Async(b *testing.B) { + v := newProdValidator(b) + payload := validMixedBulkActions() + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +// --------------------------------------------------------------------------- +// Response payloads +// --------------------------------------------------------------------------- + +// validBulkActionsResponse - a realistic 201 response from POST bulk_actions +func validBulkActionsResponse() []byte { + resp := map[string]interface{}{ + "data": map[string]interface{}{ + "id": "job_abc123", + "status": "SUCCESS", + "input": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": "ref_campaign_1", + "entity_data": map[string]interface{}{ + "name": "Campaign 1", + "objective": "CONVERSIONS", + }, + }, + { + "type": "AD_GROUP", + "action": "CREATE", + "reference_id": "ref_ag_1", + "entity_data": map[string]interface{}{ + "name": "Ad Group 1", + "campaign_id": "camp_xyz", + "bid_strategy": "MAXIMIZE_VOLUME", + "bid_type": "CPC", + "start_time": "2025-06-01T00:00:00Z", + }, + }, + }, + "results": []map[string]interface{}{ + { + "id": "result_1", + "reference_id": "ref_campaign_1", + "type": "CAMPAIGN", + "status": "SUCCESS", + "errors": []interface{}{}, + "suggestions": []interface{}{}, + }, + { + "id": "result_2", + "reference_id": "ref_ag_1", + "type": "AD_GROUP", + "status": "SUCCESS", + "errors": []interface{}{}, + "suggestions": []interface{}{}, + }, + }, + }, + } + b, _ := json.Marshal(resp) + return b +} + +// validListCampaignsResponse - a realistic 200 response from GET campaigns +func validListCampaignsResponse() []byte { + campaigns := make([]map[string]interface{}, 0, 5) + for i := 0; i < 5; i++ { + campaigns = append(campaigns, map[string]interface{}{ + "id": fmt.Sprintf("t2_camp_%d", i), + "ad_account_id": "t2_acc_12345", + "name": fmt.Sprintf("Campaign %d", i), + "objective": "CONVERSIONS", + "configured_status": "ACTIVE", + "effective_status": "ACTIVE", + "created_at": "2025-01-15T00:00:00Z", + }) + } + resp := map[string]interface{}{ + "data": campaigns, + "pagination": map[string]interface{}{}, + } + b, _ := json.Marshal(resp) + return b +} + +// invalidBulkActionsResponse_ExtraField - response with unknown field +func invalidBulkActionsResponse_ExtraField() []byte { + resp := map[string]interface{}{ + "data": map[string]interface{}{ + "id": "job_abc123", + "status": "COMPLETED", + "input": []map[string]interface{}{}, + "results": []map[string]interface{}{ + { + "reference_id": "ref_1", + "type": "CAMPAIGN", + "action": "CREATE", + "status": "SUCCESS", + "entity_id": "camp_xyz", + "unknown_garbage": "this should fail", + }, + }, + }, + } + b, _ := json.Marshal(resp) + return b +} + +func makeResponse(statusCode int, body []byte) *http.Response { + return &http.Response{ + StatusCode: statusCode, + Header: http.Header{"Content-Type": []string{"application/json"}}, + Body: io.NopCloser(bytes.NewReader(body)), + } +} + +// --------------------------------------------------------------------------- +// Response validation correctness tests +// --------------------------------------------------------------------------- + +func TestProdPayload_ValidBulkActionsResponse(t *testing.T) { + v := newProdValidator(t) + reqPayload := validMixedBulkActions() + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(reqPayload)) + req.Header.Set("Content-Type", "application/json") + + respBody := validBulkActionsResponse() + resp := makeResponse(201, respBody) + + valid, errs := v.ValidateHttpResponse(req, resp) + t.Logf("ValidBulkActionsResponse: valid=%v, errors=%d, body=%d bytes", valid, len(errs), len(respBody)) + for _, e := range errs { + t.Logf(" - %s", e.Message) + if e.Reason != "" { + t.Logf(" reason: %s", e.Reason) + } + for j, sve := range e.SchemaValidationErrors { + t.Logf(" schema[%d] reason: %s", j+1, sve.Reason) + if sve.Location != "" { + t.Logf(" schema[%d] location: %s", j+1, sve.Location) + } + if sve.FieldPath != "" { + t.Logf(" schema[%d] fieldPath: %s", j+1, sve.FieldPath) + } + } + } +} + +func TestProdPayload_ValidListCampaignsResponse(t *testing.T) { + v := newProdValidator(t) + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/campaigns?page.size=25", nil) + + respBody := validListCampaignsResponse() + resp := makeResponse(200, respBody) + + valid, errs := v.ValidateHttpResponse(req, resp) + t.Logf("ValidListCampaignsResponse: valid=%v, errors=%d, body=%d bytes", valid, len(errs), len(respBody)) + for _, e := range errs { + t.Logf(" - %s", e.Message) + if e.Reason != "" { + t.Logf(" reason: %s", e.Reason) + } + for j, sve := range e.SchemaValidationErrors { + t.Logf(" schema[%d] reason: %s", j+1, sve.Reason) + if sve.Location != "" { + t.Logf(" schema[%d] location: %s", j+1, sve.Location) + } + if sve.FieldPath != "" { + t.Logf(" schema[%d] fieldPath: %s", j+1, sve.FieldPath) + } + } + } +} + +// --------------------------------------------------------------------------- +// Benchmarks: Response Validation +// --------------------------------------------------------------------------- + +func BenchmarkProd_ResponseValidation_BulkActions(b *testing.B) { + v := newProdValidator(b) + reqPayload := validMixedBulkActions() + respBody := validBulkActionsResponse() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(reqPayload)) + req.Header.Set("Content-Type", "application/json") + resp := makeResponse(201, respBody) + v.ValidateHttpResponse(req, resp) + } +} + +func BenchmarkProd_ResponseValidation_ListCampaigns(b *testing.B) { + v := newProdValidator(b) + respBody := validListCampaignsResponse() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/campaigns?page.size=25", nil) + resp := makeResponse(200, respBody) + v.ValidateHttpResponse(req, resp) + } +} + +func BenchmarkProd_ResponseValidation_Invalid_ExtraField(b *testing.B) { + v := newProdValidator(b) + reqPayload := validCampaignAction() + respBody := invalidBulkActionsResponse_ExtraField() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(reqPayload)) + req.Header.Set("Content-Type", "application/json") + resp := makeResponse(201, respBody) + v.ValidateHttpResponse(req, resp) + } +} + +func BenchmarkProd_RequestResponseValidation_BulkActions(b *testing.B) { + v := newProdValidator(b) + reqPayload := validMixedBulkActions() + respBody := validBulkActionsResponse() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(reqPayload)) + req.Header.Set("Content-Type", "application/json") + resp := makeResponse(201, respBody) + v.ValidateHttpRequestResponse(req, resp) + } +} diff --git a/benchmarks/results/baseline.txt b/benchmarks/results/baseline.txt new file mode 100644 index 00000000..dda53c9b --- /dev/null +++ b/benchmarks/results/baseline.txt @@ -0,0 +1,138 @@ +goos: darwin +goarch: arm64 +pkg: github.com/pb33f/libopenapi-validator/benchmarks +cpu: Apple M4 Max +BenchmarkValidatorInit_AdsAPI-16 37 31845823 ns/op 29896622 B/op 412921 allocs/op +BenchmarkValidatorInit_AdsAPI-16 37 31963471 ns/op 29867018 B/op 412889 allocs/op +BenchmarkValidatorInit_AdsAPI-16 36 33446939 ns/op 29873118 B/op 412883 allocs/op +BenchmarkValidatorInit_AdsAPI-16 34 33691553 ns/op 29884717 B/op 412905 allocs/op +BenchmarkValidatorInit_AdsAPI-16 34 33718240 ns/op 29887110 B/op 412906 allocs/op +BenchmarkValidatorInit_Petstore-16 174 6851401 ns/op 9169513 B/op 93422 allocs/op +BenchmarkValidatorInit_Petstore-16 172 6804370 ns/op 9169107 B/op 93421 allocs/op +BenchmarkValidatorInit_Petstore-16 168 7010785 ns/op 9169596 B/op 93423 allocs/op +BenchmarkValidatorInit_Petstore-16 171 6903568 ns/op 9165393 B/op 93419 allocs/op +BenchmarkValidatorInit_Petstore-16 170 6945661 ns/op 9171057 B/op 93424 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutSchemaCache-16 246 4790271 ns/op 5614971 B/op 95782 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutSchemaCache-16 247 4773831 ns/op 5618953 B/op 95785 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutSchemaCache-16 246 4750365 ns/op 5613099 B/op 95783 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutSchemaCache-16 248 4763538 ns/op 5615521 B/op 95784 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutSchemaCache-16 241 4734436 ns/op 5608509 B/op 95781 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutRadixTree-16 34 33893496 ns/op 29876564 B/op 412747 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutRadixTree-16 33 34138894 ns/op 29878289 B/op 412744 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutRadixTree-16 34 34007441 ns/op 29879764 B/op 412773 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutRadixTree-16 34 33929885 ns/op 29871633 B/op 412742 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutRadixTree-16 33 34277410 ns/op 29875946 B/op 412756 allocs/op +BenchmarkValidatorInit_AdsAPI_MemoryFootprint-16 1000000000 0.09820 ns/op 98616 heap-bytes 136.0 heap-objects 0 B/op 0 allocs/op +BenchmarkValidatorInit_AdsAPI_MemoryFootprint-16 1000000000 0.1003 ns/op 74840 heap-bytes 18446744073709551616 heap-objects 0 B/op 0 allocs/op +BenchmarkValidatorInit_AdsAPI_MemoryFootprint-16 1000000000 0.1008 ns/op 97152 heap-bytes 114.0 heap-objects 0 B/op 0 allocs/op +BenchmarkValidatorInit_AdsAPI_MemoryFootprint-16 1000000000 0.1167 ns/op 92800 heap-bytes 73.00 heap-objects 0 B/op 0 allocs/op +BenchmarkValidatorInit_AdsAPI_MemoryFootprint-16 1000000000 0.09793 ns/op 98352 heap-bytes 133.0 heap-objects 0 B/op 0 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 6888436 166.1 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 6999037 166.6 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 7080998 165.7 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 7071448 167.3 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 6959179 167.3 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 5792608 199.2 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 5889310 200.3 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 5927266 201.0 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 5650443 198.4 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 5945851 201.9 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 4863294 246.8 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 4771252 245.4 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 4897012 244.0 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 4867572 244.8 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 4757554 242.3 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 498646 2446 ns/op 3272 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 506763 2414 ns/op 3272 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 509208 2437 ns/op 3272 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 521298 2451 ns/op 3272 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 474408 2456 ns/op 3272 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 474920 2449 ns/op 3224 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 504646 2478 ns/op 3224 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 494508 2482 ns/op 3224 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 497023 2470 ns/op 3224 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 489286 2454 ns/op 3224 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 188653 6372 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 191170 6319 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 188857 6405 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 194233 6335 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 190417 6312 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 188481 6346 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 190741 6315 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 194611 6294 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 193052 6222 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 193116 6306 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4832920 245.3 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4724572 241.9 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4797300 241.1 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4798866 244.5 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4853188 242.0 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 225037 5215 ns/op 4867 B/op 117 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 226687 5237 ns/op 4867 B/op 117 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 228123 5205 ns/op 4867 B/op 117 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 229370 5185 ns/op 4867 B/op 117 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 231621 5150 ns/op 4867 B/op 117 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 69162 16918 ns/op 12058 B/op 250 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 71664 17019 ns/op 12058 B/op 250 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 67645 17422 ns/op 12058 B/op 250 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 72026 17006 ns/op 12058 B/op 250 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 69945 17660 ns/op 12058 B/op 250 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 32778 36665 ns/op 33642 B/op 644 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 32732 36099 ns/op 33643 B/op 644 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 32616 35939 ns/op 33643 B/op 644 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 32516 35940 ns/op 33642 B/op 644 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 32648 35903 ns/op 33643 B/op 644 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 8478 137676 ns/op 188610 B/op 3169 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 8655 137980 ns/op 188611 B/op 3169 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 8578 138862 ns/op 188609 B/op 3169 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 8728 139138 ns/op 188610 B/op 3169 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 9008 139634 ns/op 188611 B/op 3169 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 77982 15758 ns/op 10200 B/op 195 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 75740 15754 ns/op 10200 B/op 195 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 76636 16090 ns/op 10200 B/op 195 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 77540 16147 ns/op 10200 B/op 195 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 77868 15664 ns/op 10199 B/op 195 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 47379 24592 ns/op 32105 B/op 615 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 45340 24131 ns/op 32105 B/op 615 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 47442 24858 ns/op 32105 B/op 615 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 47438 24701 ns/op 32105 B/op 615 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 46831 24289 ns/op 32105 B/op 615 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 33015 36250 ns/op 33643 B/op 644 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 33194 35255 ns/op 33643 B/op 644 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 32665 35810 ns/op 33643 B/op 644 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 32641 35885 ns/op 33643 B/op 644 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 32396 35694 ns/op 33643 B/op 644 allocs/op +BenchmarkRequestValidation_GET_Simple-16 258800 4583 ns/op 4680 B/op 115 allocs/op +BenchmarkRequestValidation_GET_Simple-16 263222 4590 ns/op 4680 B/op 115 allocs/op +BenchmarkRequestValidation_GET_Simple-16 260364 4659 ns/op 4680 B/op 115 allocs/op +BenchmarkRequestValidation_GET_Simple-16 260710 4567 ns/op 4680 B/op 115 allocs/op +BenchmarkRequestValidation_GET_Simple-16 264927 4537 ns/op 4680 B/op 115 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 214705 5577 ns/op 6074 B/op 149 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 211640 5639 ns/op 6074 B/op 149 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 211063 5562 ns/op 6075 B/op 149 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 209749 5638 ns/op 6074 B/op 149 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 208587 5671 ns/op 6076 B/op 149 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 228832 7233 ns/op 33640 B/op 644 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 201777 7387 ns/op 33640 B/op 644 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 206076 7288 ns/op 33640 B/op 644 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 162788 7545 ns/op 33640 B/op 644 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 192658 7593 ns/op 33640 B/op 644 allocs/op +panic: runtime error: invalid memory address or nil pointer dereference +[signal SIGSEGV: segmentation violation code=0x2 addr=0x18 pc=0x1051a5e70] + +goroutine 26326172 [running]: +bytes.(*Reader).Len(...) + /usr/local/go/src/bytes/reader.go:27 +net/http.NewRequestWithContext({0x1056f6a98, 0x105be45e0}, {0x105410bb9?, 0x104fc60cc?}, {0x10541d299?, 0x104f5fa08?}, {0x1056f09e0, 0x0}) + /usr/local/go/src/net/http/request.go:933 +0x3b0 +net/http.NewRequest(...) + /usr/local/go/src/net/http/request.go:863 +github.com/pb33f/libopenapi-validator/benchmarks.BenchmarkConcurrentValidation_MixedEndpoints.func1(0x1402a24e060) + /Users/zach.hamm/src/libopenapi-validator/benchmarks/validator_bench_test.go:800 +0x1bc +testing.(*B).RunParallel.func1() + /usr/local/go/src/testing/benchmark.go:977 +0xac +created by testing.(*B).RunParallel in goroutine 26326396 + /usr/local/go/src/testing/benchmark.go:970 +0xfc +exit status 2 +FAIL github.com/pb33f/libopenapi-validator/benchmarks 281.740s +FAIL diff --git a/benchmarks/results/cpu.prof b/benchmarks/results/cpu.prof new file mode 100644 index 00000000..2245fc49 Binary files /dev/null and b/benchmarks/results/cpu.prof differ diff --git a/benchmarks/results/cpu_get.prof b/benchmarks/results/cpu_get.prof new file mode 100644 index 00000000..45257bd8 Binary files /dev/null and b/benchmarks/results/cpu_get.prof differ diff --git a/benchmarks/results/current.txt b/benchmarks/results/current.txt new file mode 100644 index 00000000..542932d1 --- /dev/null +++ b/benchmarks/results/current.txt @@ -0,0 +1,186 @@ +goos: darwin +goarch: arm64 +pkg: github.com/pb33f/libopenapi-validator/benchmarks +cpu: Apple M4 Max +BenchmarkPathMatch_RadixTree_LiteralPath-16 7335706 157.5 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 7476882 159.5 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 7317386 158.1 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 7409904 159.9 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 7325233 157.3 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 6140710 187.3 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 6220233 186.2 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 6168373 187.8 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 6148658 190.4 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 6161508 195.6 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 4970776 233.7 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 5059147 234.8 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 5046855 238.3 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 4889973 234.4 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 5121746 230.4 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 525298 2306 ns/op 3272 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 532135 2308 ns/op 3272 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 511744 2319 ns/op 3272 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 537542 2296 ns/op 3272 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 531651 2285 ns/op 3272 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 506368 2352 ns/op 3224 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 521463 2340 ns/op 3224 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 514608 2352 ns/op 3224 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 525993 2333 ns/op 3224 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 513206 2334 ns/op 3224 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 193964 6036 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 200797 6028 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 197790 5992 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 198981 5981 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 196644 6011 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 196956 6063 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 198877 6221 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 192901 6097 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 195400 6112 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 172489 6136 ns/op 5736 B/op 140 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4963814 235.2 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4992499 239.9 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4906248 237.7 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4951652 234.5 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4950692 236.3 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 229940 5134 ns/op 4867 B/op 117 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 233612 5130 ns/op 4867 B/op 117 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 233294 5164 ns/op 4867 B/op 117 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 233544 5083 ns/op 4867 B/op 117 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 228592 5181 ns/op 4867 B/op 117 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 74832 16006 ns/op 11375 B/op 242 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 74023 16007 ns/op 11375 B/op 242 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 74881 15955 ns/op 11375 B/op 242 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 74638 16132 ns/op 11375 B/op 242 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 75357 15920 ns/op 11375 B/op 242 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 32217 36103 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 32364 35968 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 32420 36214 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 30415 36063 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 32265 36259 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 9002 134909 ns/op 187925 B/op 3161 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 8766 135188 ns/op 187925 B/op 3161 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 8577 135323 ns/op 187924 B/op 3161 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 8756 134937 ns/op 187926 B/op 3161 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 8840 135695 ns/op 187925 B/op 3161 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 80676 14513 ns/op 9174 B/op 184 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 81818 14729 ns/op 9174 B/op 184 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 81328 14665 ns/op 9174 B/op 184 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 81619 14472 ns/op 9174 B/op 184 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 80872 14559 ns/op 9174 B/op 184 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 47612 23794 ns/op 32345 B/op 614 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 47996 23718 ns/op 32345 B/op 614 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 48170 23846 ns/op 32345 B/op 614 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 48282 24026 ns/op 32346 B/op 614 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 48355 23753 ns/op 32345 B/op 614 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 32248 36206 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 32373 36242 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 30846 36243 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 32188 36350 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 32400 36314 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_GET_Simple-16 252928 4608 ns/op 5280 B/op 120 allocs/op +BenchmarkRequestValidation_GET_Simple-16 254308 4592 ns/op 5280 B/op 120 allocs/op +BenchmarkRequestValidation_GET_Simple-16 254330 4607 ns/op 5280 B/op 120 allocs/op +BenchmarkRequestValidation_GET_Simple-16 253176 4588 ns/op 5280 B/op 120 allocs/op +BenchmarkRequestValidation_GET_Simple-16 255424 4607 ns/op 5280 B/op 120 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 206606 5662 ns/op 6666 B/op 154 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 206791 5697 ns/op 6666 B/op 154 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 196666 5693 ns/op 6666 B/op 154 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 208033 5679 ns/op 6666 B/op 154 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 205506 5717 ns/op 6667 B/op 154 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 259238 6777 ns/op 32952 B/op 636 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 210962 6713 ns/op 32952 B/op 636 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 216480 6779 ns/op 32952 B/op 636 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 213114 6763 ns/op 32952 B/op 636 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 213336 6672 ns/op 32952 B/op 636 allocs/op +BenchmarkConcurrentValidation_MixedEndpoints-16 1000000 1514 ns/op 7435 B/op 150 allocs/op +BenchmarkConcurrentValidation_MixedEndpoints-16 1000000 1395 ns/op 7435 B/op 150 allocs/op +BenchmarkConcurrentValidation_MixedEndpoints-16 1000000 1413 ns/op 7435 B/op 150 allocs/op +BenchmarkConcurrentValidation_MixedEndpoints-16 1000000 1398 ns/op 7435 B/op 150 allocs/op +BenchmarkConcurrentValidation_MixedEndpoints-16 1000000 1402 ns/op 7435 B/op 150 allocs/op +BenchmarkMemory_SingleValidation_BulkActions-16 30878 37255 ns/op 32947 B/op 636 allocs/op +BenchmarkMemory_SingleValidation_BulkActions-16 30722 37364 ns/op 32946 B/op 636 allocs/op +BenchmarkMemory_SingleValidation_BulkActions-16 31941 36751 ns/op 32946 B/op 636 allocs/op +BenchmarkMemory_SingleValidation_BulkActions-16 32071 36669 ns/op 32946 B/op 636 allocs/op +BenchmarkMemory_SingleValidation_BulkActions-16 31956 36671 ns/op 32946 B/op 636 allocs/op +BenchmarkMemory_SingleValidation_GET-16 256893 4604 ns/op 5280 B/op 120 allocs/op +BenchmarkMemory_SingleValidation_GET-16 254169 4617 ns/op 5280 B/op 120 allocs/op +BenchmarkMemory_SingleValidation_GET-16 252644 4642 ns/op 5280 B/op 120 allocs/op +BenchmarkMemory_SingleValidation_GET-16 258759 4631 ns/op 5280 B/op 120 allocs/op +BenchmarkMemory_SingleValidation_GET-16 260197 4636 ns/op 5280 B/op 120 allocs/op +BenchmarkRequestValidation_WithSchemaCache-16 31986 36563 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_WithSchemaCache-16 31820 36785 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_WithSchemaCache-16 32108 36373 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_WithSchemaCache-16 31418 36766 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_WithSchemaCache-16 31838 36766 ns/op 32946 B/op 636 allocs/op +BenchmarkRequestValidation_WithoutSchemaCache-16 400 2982975 ns/op 2218318 B/op 32410 allocs/op +BenchmarkRequestValidation_WithoutSchemaCache-16 403 2974150 ns/op 2218336 B/op 32410 allocs/op +BenchmarkRequestValidation_WithoutSchemaCache-16 400 2955798 ns/op 2218301 B/op 32410 allocs/op +BenchmarkRequestValidation_WithoutSchemaCache-16 405 2957484 ns/op 2218336 B/op 32410 allocs/op +BenchmarkRequestValidation_WithoutSchemaCache-16 400 2952803 ns/op 2218361 B/op 32410 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_5_endpoints-16 6056910 193.5 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_5_endpoints-16 5955663 193.2 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_5_endpoints-16 6100940 196.3 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_5_endpoints-16 6020640 193.7 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_5_endpoints-16 6103789 194.9 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_5_endpoints-16 498432 2429 ns/op 1968 B/op 59 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_5_endpoints-16 499350 2397 ns/op 1968 B/op 59 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_5_endpoints-16 505081 2379 ns/op 1968 B/op 59 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_5_endpoints-16 504622 2409 ns/op 1968 B/op 59 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_5_endpoints-16 490609 2396 ns/op 1968 B/op 59 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_10_endpoints-16 5990275 195.0 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_10_endpoints-16 5893257 195.8 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_10_endpoints-16 6066787 197.2 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_10_endpoints-16 5931651 196.5 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_10_endpoints-16 6007291 196.6 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_10_endpoints-16 262431 4522 ns/op 3648 B/op 114 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_10_endpoints-16 269329 4506 ns/op 3648 B/op 114 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_10_endpoints-16 266827 4584 ns/op 3648 B/op 114 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_10_endpoints-16 260508 4523 ns/op 3648 B/op 114 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_10_endpoints-16 258262 4633 ns/op 3648 B/op 114 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_25_endpoints-16 5876208 196.9 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_25_endpoints-16 5965333 198.8 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_25_endpoints-16 5875221 197.8 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_25_endpoints-16 5884416 196.4 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_25_endpoints-16 5933952 196.2 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_25_endpoints-16 107953 10987 ns/op 8401 B/op 279 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_25_endpoints-16 108735 10986 ns/op 8401 B/op 279 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_25_endpoints-16 109725 10937 ns/op 8401 B/op 279 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_25_endpoints-16 108081 10978 ns/op 8401 B/op 279 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_25_endpoints-16 110758 10853 ns/op 8401 B/op 279 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_50_endpoints-16 5884062 196.1 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_50_endpoints-16 5923262 198.8 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_50_endpoints-16 5702971 195.5 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_50_endpoints-16 5901232 197.1 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_50_endpoints-16 5939691 199.5 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_50_endpoints-16 55651 21179 ns/op 16452 B/op 554 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_50_endpoints-16 55741 21193 ns/op 16452 B/op 554 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_50_endpoints-16 56125 21602 ns/op 16452 B/op 554 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_50_endpoints-16 55976 21090 ns/op 16452 B/op 554 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_50_endpoints-16 55995 21059 ns/op 16452 B/op 554 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_100_endpoints-16 5954010 196.7 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_100_endpoints-16 5879094 196.1 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_100_endpoints-16 5578926 197.7 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_100_endpoints-16 5776102 195.3 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RadixTree_100_endpoints-16 5936845 196.4 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_100_endpoints-16 27529 42579 ns/op 32560 B/op 1104 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_100_endpoints-16 27577 42149 ns/op 32560 B/op 1104 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_100_endpoints-16 27787 42782 ns/op 32560 B/op 1104 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_100_endpoints-16 27747 42811 ns/op 32560 B/op 1104 allocs/op +BenchmarkPathMatch_ScaleEndpoints/RegexFallback_100_endpoints-16 27678 42672 ns/op 32560 B/op 1104 allocs/op +BenchmarkResponseValidation_BulkActions-16 137906 8172 ns/op 11437 B/op 211 allocs/op +BenchmarkResponseValidation_BulkActions-16 138718 7931 ns/op 11437 B/op 211 allocs/op +BenchmarkResponseValidation_BulkActions-16 139875 8001 ns/op 11436 B/op 211 allocs/op +BenchmarkResponseValidation_BulkActions-16 139377 8025 ns/op 11436 B/op 211 allocs/op +BenchmarkResponseValidation_BulkActions-16 140930 7992 ns/op 11436 B/op 211 allocs/op +BenchmarkResponseValidation_GET_Campaign-16 365401 3196 ns/op 5472 B/op 84 allocs/op +BenchmarkResponseValidation_GET_Campaign-16 368400 3208 ns/op 5472 B/op 84 allocs/op +BenchmarkResponseValidation_GET_Campaign-16 363318 3207 ns/op 5472 B/op 84 allocs/op +BenchmarkResponseValidation_GET_Campaign-16 368463 3195 ns/op 5472 B/op 84 allocs/op +BenchmarkResponseValidation_GET_Campaign-16 369618 3222 ns/op 5472 B/op 84 allocs/op +BenchmarkRequestResponseValidation_BulkActions-16 24459 47146 ns/op 42823 B/op 832 allocs/op +BenchmarkRequestResponseValidation_BulkActions-16 24285 47659 ns/op 42824 B/op 832 allocs/op +BenchmarkRequestResponseValidation_BulkActions-16 24423 47451 ns/op 42824 B/op 832 allocs/op +BenchmarkRequestResponseValidation_BulkActions-16 24591 47393 ns/op 42823 B/op 832 allocs/op +BenchmarkRequestResponseValidation_BulkActions-16 24436 47412 ns/op 42824 B/op 832 allocs/op +PASS +ok github.com/pb33f/libopenapi-validator/benchmarks 460.026s diff --git a/benchmarks/results/mem.prof b/benchmarks/results/mem.prof new file mode 100644 index 00000000..55580c2a Binary files /dev/null and b/benchmarks/results/mem.prof differ diff --git a/benchmarks/results/mem_get.prof b/benchmarks/results/mem_get.prof new file mode 100644 index 00000000..4d291ed0 Binary files /dev/null and b/benchmarks/results/mem_get.prof differ diff --git a/benchmarks/results/mem_get_clean.prof b/benchmarks/results/mem_get_clean.prof new file mode 100644 index 00000000..8f8f3e50 Binary files /dev/null and b/benchmarks/results/mem_get_clean.prof differ diff --git a/benchmarks/results/optimized.txt b/benchmarks/results/optimized.txt new file mode 100644 index 00000000..c72224ac --- /dev/null +++ b/benchmarks/results/optimized.txt @@ -0,0 +1,138 @@ +goos: darwin +goarch: arm64 +pkg: github.com/pb33f/libopenapi-validator/benchmarks +cpu: Apple M4 Max +BenchmarkValidatorInit_AdsAPI-16 31 36881716 ns/op 30093115 B/op 413704 allocs/op +BenchmarkValidatorInit_AdsAPI-16 31 37002281 ns/op 30081005 B/op 413668 allocs/op +BenchmarkValidatorInit_AdsAPI-16 31 37543335 ns/op 30091088 B/op 413710 allocs/op +BenchmarkValidatorInit_AdsAPI-16 31 37340074 ns/op 30089693 B/op 413704 allocs/op +BenchmarkValidatorInit_AdsAPI-16 31 36975603 ns/op 30087406 B/op 413656 allocs/op +BenchmarkValidatorInit_Petstore-16 135 8696406 ns/op 9290892 B/op 94005 allocs/op +BenchmarkValidatorInit_Petstore-16 138 8706857 ns/op 9288804 B/op 93991 allocs/op +BenchmarkValidatorInit_Petstore-16 138 8678377 ns/op 9286698 B/op 93988 allocs/op +BenchmarkValidatorInit_Petstore-16 134 8675554 ns/op 9284825 B/op 93980 allocs/op +BenchmarkValidatorInit_Petstore-16 139 8599025 ns/op 9283681 B/op 93975 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutSchemaCache-16 198 6058565 ns/op 5738615 B/op 95934 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutSchemaCache-16 199 6031958 ns/op 5737219 B/op 95932 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutSchemaCache-16 199 6071289 ns/op 5737628 B/op 95935 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutSchemaCache-16 194 6208852 ns/op 5739266 B/op 95935 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutSchemaCache-16 199 5929547 ns/op 5736289 B/op 95930 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutRadixTree-16 31 37155183 ns/op 30074483 B/op 413522 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutRadixTree-16 31 37118734 ns/op 30071976 B/op 413548 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutRadixTree-16 31 37169145 ns/op 30081478 B/op 413542 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutRadixTree-16 31 37245684 ns/op 30064825 B/op 413464 allocs/op +BenchmarkValidatorInit_AdsAPI_WithoutRadixTree-16 31 37140316 ns/op 30076783 B/op 413555 allocs/op +BenchmarkValidatorInit_AdsAPI_MemoryFootprint-16 1000000000 0.03955 ns/op 23856 heap-bytes 119.0 heap-objects 0 B/op 0 allocs/op +BenchmarkValidatorInit_AdsAPI_MemoryFootprint-16 1000000000 0.03802 ns/op 13048 heap-bytes 35.00 heap-objects 0 B/op 0 allocs/op +BenchmarkValidatorInit_AdsAPI_MemoryFootprint-16 1000000000 0.03825 ns/op 21576 heap-bytes 62.00 heap-objects 0 B/op 0 allocs/op +BenchmarkValidatorInit_AdsAPI_MemoryFootprint-16 1000000000 0.03872 ns/op 18446744073709547520 heap-bytes 18446744073709551616 heap-objects 0 B/op 0 allocs/op +BenchmarkValidatorInit_AdsAPI_MemoryFootprint-16 1000000000 0.03936 ns/op 5648 heap-bytes 18446744073709551616 heap-objects 0 B/op 0 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 6882849 173.1 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 6943904 177.7 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 6969301 175.1 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 6808602 174.5 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_LiteralPath-16 6787310 174.5 ns/op 192 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 5780224 207.8 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 5745805 206.9 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 5817494 209.3 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 5772532 213.8 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_SingleParam-16 5780211 209.6 ns/op 224 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 4733635 251.6 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 4782816 251.4 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 4768213 250.4 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 4772834 252.7 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RadixTree_DeepParam-16 4381940 254.2 ns/op 256 B/op 4 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 474135 2536 ns/op 3276 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 469707 2546 ns/op 3276 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 474615 2527 ns/op 3276 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 469723 2544 ns/op 3276 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_LiteralPath-16 479872 2572 ns/op 3276 B/op 70 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 459292 2622 ns/op 3228 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 468919 2642 ns/op 3228 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 462700 2618 ns/op 3228 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 453116 2608 ns/op 3228 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_SingleParam-16 462514 2654 ns/op 3228 B/op 64 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 172934 6836 ns/op 5744 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 177507 6788 ns/op 5744 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 176889 6811 ns/op 5744 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 175497 6827 ns/op 5744 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_DeepParam-16 178083 6879 ns/op 5744 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 175392 6831 ns/op 5744 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 177423 6793 ns/op 5744 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 176533 6795 ns/op 5744 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 173564 6778 ns/op 5744 B/op 140 allocs/op +BenchmarkPathMatch_RegexFallback_WithCache-16 175135 6949 ns/op 5744 B/op 140 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4645294 257.0 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4635170 259.1 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4667198 263.8 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4697590 256.6 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RadixTree-16 4694479 258.3 ns/op 252 B/op 4 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 212696 5695 ns/op 4874 B/op 117 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 209581 5753 ns/op 4874 B/op 117 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 205719 5694 ns/op 4874 B/op 117 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 208555 5673 ns/op 4874 B/op 117 allocs/op +BenchmarkPathMatch_AllEndpoints_RegexFallback-16 212690 5750 ns/op 4874 B/op 117 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 66208 17877 ns/op 12328 B/op 251 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 66430 17951 ns/op 12328 B/op 251 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 65964 18067 ns/op 12327 B/op 251 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 67297 18117 ns/op 12327 B/op 251 allocs/op +BenchmarkRequestValidation_BulkActions_Small-16 65217 18043 ns/op 12326 B/op 251 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 30985 38346 ns/op 34001 B/op 645 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 31022 39100 ns/op 34011 B/op 645 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 30559 39286 ns/op 34010 B/op 645 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 30254 39587 ns/op 34006 B/op 645 allocs/op +BenchmarkRequestValidation_BulkActions_Medium-16 30926 38985 ns/op 34006 B/op 645 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 7802 145791 ns/op 189475 B/op 3173 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 7988 145380 ns/op 189464 B/op 3172 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 8342 145017 ns/op 189468 B/op 3172 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 8451 149382 ns/op 189477 B/op 3173 allocs/op +BenchmarkRequestValidation_BulkActions_Large-16 7600 149464 ns/op 189476 B/op 3173 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 71216 16336 ns/op 10439 B/op 196 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 73020 16225 ns/op 10438 B/op 196 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 74038 16196 ns/op 10438 B/op 196 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 73318 16263 ns/op 10438 B/op 196 allocs/op +BenchmarkRequestValidation_Petstore_AddPet-16 65733 15503 ns/op 10438 B/op 196 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 48594 24581 ns/op 32376 B/op 616 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 47936 24796 ns/op 32378 B/op 616 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 47023 25202 ns/op 32380 B/op 616 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 48536 24513 ns/op 32379 B/op 616 allocs/op +BenchmarkRequestValidation_BulkActions_Sync-16 49045 24807 ns/op 32380 B/op 616 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 32706 36518 ns/op 33963 B/op 645 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 33105 36698 ns/op 33971 B/op 645 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 32515 36595 ns/op 33969 B/op 645 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 32155 37529 ns/op 33979 B/op 645 allocs/op +BenchmarkRequestValidation_BulkActions_Async-16 32647 37221 ns/op 33980 B/op 645 allocs/op +BenchmarkRequestValidation_GET_Simple-16 270360 4448 ns/op 4687 B/op 115 allocs/op +BenchmarkRequestValidation_GET_Simple-16 264256 4482 ns/op 4687 B/op 115 allocs/op +BenchmarkRequestValidation_GET_Simple-16 264013 4518 ns/op 4687 B/op 115 allocs/op +BenchmarkRequestValidation_GET_Simple-16 265047 4666 ns/op 4688 B/op 115 allocs/op +BenchmarkRequestValidation_GET_Simple-16 263872 4530 ns/op 4687 B/op 115 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 220675 5652 ns/op 6150 B/op 149 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 222632 5577 ns/op 6146 B/op 149 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 206685 5569 ns/op 6145 B/op 149 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 183247 5617 ns/op 6153 B/op 149 allocs/op +BenchmarkRequestValidation_GET_WithQueryParams-16 212396 5588 ns/op 6140 B/op 149 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 130405 9384 ns/op 33900 B/op 645 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 130886 9107 ns/op 33900 B/op 645 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 131742 9103 ns/op 33899 B/op 645 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 132336 9085 ns/op 33900 B/op 645 allocs/op +BenchmarkConcurrentValidation_BulkActions-16 112868 9523 ns/op 33897 B/op 645 allocs/op +panic: runtime error: invalid memory address or nil pointer dereference +[signal SIGSEGV: segmentation violation code=0x2 addr=0x18 pc=0x1044c5e70] + +goroutine 20908484 [running]: +bytes.(*Reader).Len(...) + /usr/local/go/src/bytes/reader.go:27 +net/http.NewRequestWithContext({0x104a1ac18, 0x104f08700}, {0x104734819?, 0x1042e60cc?}, {0x1047410aa?, 0x1046dd408?}, {0x104a14b60, 0x0}) + /usr/local/go/src/net/http/request.go:933 +0x3b0 +net/http.NewRequest(...) + /usr/local/go/src/net/http/request.go:863 +github.com/pb33f/libopenapi-validator/benchmarks.BenchmarkConcurrentValidation_MixedEndpoints.func1(0x140007fe160) + /Users/zach.hamm/src/libopenapi-validator/benchmarks/validator_bench_test.go:800 +0x1bc +testing.(*B).RunParallel.func1() + /usr/local/go/src/testing/benchmark.go:977 +0xac +created by testing.(*B).RunParallel in goroutine 20908723 + /usr/local/go/src/testing/benchmark.go:970 +0xfc +exit status 2 +FAIL github.com/pb33f/libopenapi-validator/benchmarks 160.141s +FAIL diff --git a/benchmarks/results_ifthen.txt b/benchmarks/results_ifthen.txt new file mode 100644 index 00000000..0cc94133 --- /dev/null +++ b/benchmarks/results_ifthen.txt @@ -0,0 +1,58 @@ +goos: darwin +goarch: arm64 +pkg: github.com/pb33f/libopenapi-validator/benchmarks +cpu: Apple M4 Max +BenchmarkProd_Init-16 1 2683219166 ns/op 3116479936 B/op 36431193 allocs/op +BenchmarkProd_Init-16 1 2654879083 ns/op 3133498032 B/op 36602991 allocs/op +BenchmarkProd_Init-16 1 2730460541 ns/op 3212065248 B/op 37277288 allocs/op +BenchmarkProd_Init_MemoryFootprint-16 1 2793064375 ns/op 3931792 heap-bytes 67331 heap-objects 3123893928 B/op 36513562 allocs/op +BenchmarkProd_Init_MemoryFootprint-16 1 2761515791 ns/op 3993760 heap-bytes 67060 heap-objects 3120179656 B/op 36460877 allocs/op +BenchmarkProd_Init_MemoryFootprint-16 1 2890265750 ns/op 3942160 heap-bytes 66438 heap-objects 3229540168 B/op 37432639 allocs/op +BenchmarkProd_BulkActions_SingleCampaign-16 62023 20963 ns/op 13072 B/op 233 allocs/op +BenchmarkProd_BulkActions_SingleCampaign-16 52996 21071 ns/op 13072 B/op 233 allocs/op +BenchmarkProd_BulkActions_SingleCampaign-16 54138 21439 ns/op 13073 B/op 233 allocs/op +BenchmarkProd_BulkActions_Mixed3-16 28988 40318 ns/op 38538 B/op 665 allocs/op +BenchmarkProd_BulkActions_Mixed3-16 29694 41256 ns/op 38538 B/op 665 allocs/op +BenchmarkProd_BulkActions_Mixed3-16 28605 40249 ns/op 38538 B/op 665 allocs/op +BenchmarkProd_BulkActions_Large15-16 9904 126555 ns/op 172368 B/op 2815 allocs/op +BenchmarkProd_BulkActions_Large15-16 9572 130236 ns/op 172372 B/op 2815 allocs/op +BenchmarkProd_BulkActions_Large15-16 9908 128318 ns/op 172370 B/op 2815 allocs/op +BenchmarkProd_BulkActions_Invalid_MissingField-16 58009 20891 ns/op 17687 B/op 335 allocs/op +BenchmarkProd_BulkActions_Invalid_MissingField-16 64593 21398 ns/op 17686 B/op 335 allocs/op +BenchmarkProd_BulkActions_Invalid_MissingField-16 52542 21723 ns/op 17691 B/op 335 allocs/op +BenchmarkProd_BulkActions_Invalid_WrongType-16 47030 24078 ns/op 20313 B/op 401 allocs/op +BenchmarkProd_BulkActions_Invalid_WrongType-16 54164 24548 ns/op 20311 B/op 401 allocs/op +BenchmarkProd_BulkActions_Invalid_WrongType-16 56468 24667 ns/op 20313 B/op 401 allocs/op +BenchmarkProd_BulkActions_Invalid_ExtraField-16 41125 28869 ns/op 19714 B/op 371 allocs/op +BenchmarkProd_BulkActions_Invalid_ExtraField-16 45892 27752 ns/op 19717 B/op 371 allocs/op +BenchmarkProd_BulkActions_Invalid_ExtraField-16 41137 28541 ns/op 19716 B/op 371 allocs/op +BenchmarkProd_BulkActions_Invalid_ContentType-16 94627 11114 ns/op 4672 B/op 93 allocs/op +BenchmarkProd_BulkActions_Invalid_ContentType-16 120015 12197 ns/op 4672 B/op 93 allocs/op +BenchmarkProd_BulkActions_Invalid_ContentType-16 98042 12560 ns/op 4672 B/op 93 allocs/op +BenchmarkProd_GET_ListCampaigns-16 372342 3384 ns/op 3473 B/op 84 allocs/op +BenchmarkProd_GET_ListCampaigns-16 362746 3416 ns/op 3472 B/op 84 allocs/op +BenchmarkProd_GET_ListCampaigns-16 357552 3469 ns/op 3473 B/op 84 allocs/op +BenchmarkProd_GET_ListAdGroups-16 283434 4202 ns/op 4289 B/op 106 allocs/op +BenchmarkProd_GET_ListAdGroups-16 259671 4139 ns/op 4289 B/op 106 allocs/op +BenchmarkProd_GET_ListAdGroups-16 315362 4069 ns/op 4288 B/op 106 allocs/op +BenchmarkProd_GET_ListAds-16 391160 3329 ns/op 3472 B/op 84 allocs/op +BenchmarkProd_GET_ListAds-16 375493 3272 ns/op 3473 B/op 84 allocs/op +BenchmarkProd_GET_ListAds-16 371734 3291 ns/op 3473 B/op 84 allocs/op +BenchmarkProd_GET_Me-16 1607794 742.4 ns/op 992 B/op 14 allocs/op +BenchmarkProd_GET_Me-16 1558476 733.1 ns/op 992 B/op 14 allocs/op +BenchmarkProd_GET_Me-16 1588447 711.0 ns/op 992 B/op 14 allocs/op +BenchmarkProd_GET_GetBulkActionsJob-16 369076 3238 ns/op 2976 B/op 76 allocs/op +BenchmarkProd_GET_GetBulkActionsJob-16 362708 3264 ns/op 2976 B/op 76 allocs/op +BenchmarkProd_GET_GetBulkActionsJob-16 360678 3275 ns/op 2976 B/op 76 allocs/op +BenchmarkProd_Concurrent_BulkActions-16 135949 7959 ns/op 38535 B/op 665 allocs/op +BenchmarkProd_Concurrent_BulkActions-16 146617 8115 ns/op 38535 B/op 665 allocs/op +BenchmarkProd_Concurrent_BulkActions-16 136915 8140 ns/op 38536 B/op 665 allocs/op +BenchmarkProd_Concurrent_MixedEndpoints-16 1000000 1750 ns/op 8822 B/op 167 allocs/op +BenchmarkProd_Concurrent_MixedEndpoints-16 844376 1760 ns/op 8822 B/op 167 allocs/op +BenchmarkProd_Concurrent_MixedEndpoints-16 643857 1763 ns/op 8822 B/op 167 allocs/op +BenchmarkProd_BulkActions_Sync-16 40441 29629 ns/op 37025 B/op 637 allocs/op +BenchmarkProd_BulkActions_Sync-16 47700 26345 ns/op 37025 B/op 637 allocs/op +BenchmarkProd_BulkActions_Sync-16 45660 26537 ns/op 37025 B/op 637 allocs/op +BenchmarkProd_BulkActions_Async-16 29214 41200 ns/op 38538 B/op 665 allocs/op +BenchmarkProd_BulkActions_Async-16 29172 40599 ns/op 38538 B/op 665 allocs/op +BenchmarkProd_BulkActions_Async-16 28359 41265 ns/op 38538 B/op 665 allocs/op diff --git a/benchmarks/results_oneof.txt b/benchmarks/results_oneof.txt new file mode 100644 index 00000000..83645eb7 --- /dev/null +++ b/benchmarks/results_oneof.txt @@ -0,0 +1,58 @@ +goos: darwin +goarch: arm64 +pkg: github.com/pb33f/libopenapi-validator/benchmarks +cpu: Apple M4 Max +BenchmarkProd_Init-16 1 2709541917 ns/op 3117928032 B/op 36490320 allocs/op +BenchmarkProd_Init-16 1 2846241917 ns/op 3214793832 B/op 37345748 allocs/op +BenchmarkProd_Init-16 1 2768651416 ns/op 3216275128 B/op 37353782 allocs/op +BenchmarkProd_Init_MemoryFootprint-16 1 2847588541 ns/op 3851768 heap-bytes 67153 heap-objects 3214863840 B/op 37352064 allocs/op +BenchmarkProd_Init_MemoryFootprint-16 1 2969881416 ns/op 3579312 heap-bytes 66509 heap-objects 3245880936 B/op 37656371 allocs/op +BenchmarkProd_Init_MemoryFootprint-16 1 3250684000 ns/op 4338872 heap-bytes 65966 heap-objects 3235614336 B/op 37541535 allocs/op +BenchmarkProd_BulkActions_SingleCampaign-16 46803 25779 ns/op 17498 B/op 325 allocs/op +BenchmarkProd_BulkActions_SingleCampaign-16 49252 25564 ns/op 17492 B/op 325 allocs/op +BenchmarkProd_BulkActions_SingleCampaign-16 49953 24605 ns/op 17501 B/op 325 allocs/op +BenchmarkProd_BulkActions_Mixed3-16 21994 51769 ns/op 53129 B/op 965 allocs/op +BenchmarkProd_BulkActions_Mixed3-16 23162 50534 ns/op 53123 B/op 965 allocs/op +BenchmarkProd_BulkActions_Mixed3-16 22612 61451 ns/op 53133 B/op 965 allocs/op +BenchmarkProd_BulkActions_Large15-16 6277 177459 ns/op 244602 B/op 4304 allocs/op +BenchmarkProd_BulkActions_Large15-16 7388 168957 ns/op 244523 B/op 4302 allocs/op +BenchmarkProd_BulkActions_Large15-16 7005 179887 ns/op 244568 B/op 4303 allocs/op +BenchmarkProd_BulkActions_Invalid_MissingField-16 14383 82966 ns/op 87740 B/op 1601 allocs/op +BenchmarkProd_BulkActions_Invalid_MissingField-16 15643 81456 ns/op 87764 B/op 1601 allocs/op +BenchmarkProd_BulkActions_Invalid_MissingField-16 14986 80117 ns/op 87748 B/op 1601 allocs/op +BenchmarkProd_BulkActions_Invalid_WrongType-16 9637 123489 ns/op 141487 B/op 2438 allocs/op +BenchmarkProd_BulkActions_Invalid_WrongType-16 10000 123077 ns/op 141494 B/op 2438 allocs/op +BenchmarkProd_BulkActions_Invalid_WrongType-16 10000 122167 ns/op 141487 B/op 2438 allocs/op +BenchmarkProd_BulkActions_Invalid_ExtraField-16 7972 151336 ns/op 173099 B/op 3014 allocs/op +BenchmarkProd_BulkActions_Invalid_ExtraField-16 8877 152876 ns/op 173133 B/op 3014 allocs/op +BenchmarkProd_BulkActions_Invalid_ExtraField-16 8354 150243 ns/op 173109 B/op 3014 allocs/op +BenchmarkProd_BulkActions_Invalid_ContentType-16 101173 10914 ns/op 4832 B/op 97 allocs/op +BenchmarkProd_BulkActions_Invalid_ContentType-16 135019 11687 ns/op 4832 B/op 97 allocs/op +BenchmarkProd_BulkActions_Invalid_ContentType-16 137504 12711 ns/op 4832 B/op 97 allocs/op +BenchmarkProd_GET_ListCampaigns-16 365862 3382 ns/op 3697 B/op 89 allocs/op +BenchmarkProd_GET_ListCampaigns-16 367837 3426 ns/op 3697 B/op 89 allocs/op +BenchmarkProd_GET_ListCampaigns-16 366966 3578 ns/op 3697 B/op 89 allocs/op +BenchmarkProd_GET_ListAdGroups-16 288392 4215 ns/op 4513 B/op 111 allocs/op +BenchmarkProd_GET_ListAdGroups-16 296079 4222 ns/op 4513 B/op 111 allocs/op +BenchmarkProd_GET_ListAdGroups-16 289665 4262 ns/op 4513 B/op 111 allocs/op +BenchmarkProd_GET_ListAds-16 366175 3389 ns/op 3697 B/op 89 allocs/op +BenchmarkProd_GET_ListAds-16 349141 3434 ns/op 3697 B/op 89 allocs/op +BenchmarkProd_GET_ListAds-16 353517 3456 ns/op 3697 B/op 89 allocs/op +BenchmarkProd_GET_Me-16 1533409 766.9 ns/op 1168 B/op 18 allocs/op +BenchmarkProd_GET_Me-16 1546609 780.6 ns/op 1168 B/op 18 allocs/op +BenchmarkProd_GET_Me-16 1540164 777.8 ns/op 1168 B/op 18 allocs/op +BenchmarkProd_GET_GetBulkActionsJob-16 355526 3430 ns/op 3200 B/op 81 allocs/op +BenchmarkProd_GET_GetBulkActionsJob-16 363735 3422 ns/op 3200 B/op 81 allocs/op +BenchmarkProd_GET_GetBulkActionsJob-16 347875 3432 ns/op 3200 B/op 81 allocs/op +BenchmarkProd_Concurrent_BulkActions-16 127906 10958 ns/op 53138 B/op 966 allocs/op +BenchmarkProd_Concurrent_BulkActions-16 126508 11545 ns/op 53148 B/op 966 allocs/op +BenchmarkProd_Concurrent_BulkActions-16 129488 10089 ns/op 53125 B/op 965 allocs/op +BenchmarkProd_Concurrent_MixedEndpoints-16 494131 2105 ns/op 11435 B/op 221 allocs/op +BenchmarkProd_Concurrent_MixedEndpoints-16 856428 2128 ns/op 11435 B/op 221 allocs/op +BenchmarkProd_Concurrent_MixedEndpoints-16 883941 2122 ns/op 11436 B/op 222 allocs/op +BenchmarkProd_BulkActions_Sync-16 33493 36043 ns/op 51692 B/op 938 allocs/op +BenchmarkProd_BulkActions_Sync-16 33336 35982 ns/op 51688 B/op 938 allocs/op +BenchmarkProd_BulkActions_Sync-16 33034 35731 ns/op 51696 B/op 938 allocs/op +BenchmarkProd_BulkActions_Async-16 23635 50605 ns/op 53147 B/op 966 allocs/op +BenchmarkProd_BulkActions_Async-16 24212 50200 ns/op 53146 B/op 966 allocs/op +BenchmarkProd_BulkActions_Async-16 24121 49747 ns/op 53160 B/op 966 allocs/op diff --git a/benchmarks/validator_bench_test.go b/benchmarks/validator_bench_test.go new file mode 100644 index 00000000..09817809 --- /dev/null +++ b/benchmarks/validator_bench_test.go @@ -0,0 +1,1110 @@ +// Copyright 2025 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT +// +// Comprehensive benchmarks for libopenapi-validator performance analysis. +// These benchmarks cover the full validation pipeline with production-like workloads +// modeled after the Reddit Ads API BulkActions endpoint. +// +// Run with: +// go test -bench=. -benchmem -count=5 -timeout=30m ./benchmarks/ | tee benchmark_results.txt +// +// For CPU profiling: +// go test -bench=BenchmarkFullValidation -cpuprofile=cpu.prof -benchmem ./benchmarks/ +// +// For memory profiling: +// go test -bench=BenchmarkFullValidation -memprofile=mem.prof -benchmem ./benchmarks/ +// +// Compare results (install benchstat: go install golang.org/x/perf/cmd/benchstat@latest): +// benchstat baseline.txt optimized.txt + +package benchmarks + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" + "os" + "runtime" + "sync" + "testing" + + "github.com/pb33f/libopenapi" + + validator "github.com/pb33f/libopenapi-validator" + "github.com/pb33f/libopenapi-validator/config" + "github.com/pb33f/libopenapi-validator/paths" + "github.com/pb33f/libopenapi-validator/radix" +) + +// --- Test data --- + +var ( + adsAPISpec []byte + petstoreSpec []byte + specLoadOnce sync.Once + adsAPIDoc libopenapi.Document + petstoreDoc libopenapi.Document + docBuildOnce sync.Once +) + +func loadSpecs() { + specLoadOnce.Do(func() { + var err error + adsAPISpec, err = os.ReadFile("../test_specs/ads_api_bulk_actions.yaml") + if err != nil { + panic(fmt.Sprintf("failed to read ads_api_bulk_actions.yaml: %v", err)) + } + petstoreSpec, err = os.ReadFile("../test_specs/petstorev3.json") + if err != nil { + panic(fmt.Sprintf("failed to read petstorev3.json: %v", err)) + } + }) +} + +func buildDocs() { + loadSpecs() + docBuildOnce.Do(func() { + var err error + adsAPIDoc, err = libopenapi.NewDocument(adsAPISpec) + if err != nil { + panic(fmt.Sprintf("failed to create ads-api document: %v", err)) + } + petstoreDoc, err = libopenapi.NewDocument(petstoreSpec) + if err != nil { + panic(fmt.Sprintf("failed to create petstore document: %v", err)) + } + }) +} + +// --- Payload generators --- + +// smallBulkActionPayload creates a minimal bulk action request (1 action) +func smallBulkActionPayload() []byte { + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": "ref_campaign_1", + "entity_data": map[string]interface{}{ + "name": "Test Campaign", + "objective": "CONVERSIONS", + "daily_budget_micro": 5000000, + "start_time": "2025-01-15T00:00:00Z", + "funding_instrument_id": "fi_abc123", + "configured_status": "PAUSED", + }, + }, + }, + } + b, _ := json.Marshal(payload) + return b +} + +// mediumBulkActionPayload creates a typical bulk action request (4 actions: campaign + ad_group + ad + post) +func mediumBulkActionPayload() []byte { + payload := map[string]interface{}{ + "data": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": "ref_campaign_1", + "entity_data": map[string]interface{}{ + "name": "Benchmark Campaign", + "objective": "CONVERSIONS", + "daily_budget_micro": 5000000, + "start_time": "2025-01-15T00:00:00Z", + "funding_instrument_id": "fi_abc123", + "configured_status": "PAUSED", + }, + }, + { + "type": "AD_GROUP", + "action": "CREATE", + "reference_id": "ref_ad_group_1", + "entity_data": map[string]interface{}{ + "name": "Benchmark Ad Group", + "campaign_id": "{{ref_campaign_1}}", + "bid_strategy": "AUTO", + "goal_type": "CONVERSIONS", + "start_time": "2025-01-15T00:00:00Z", + "targeting": map[string]interface{}{ + "geos": map[string]interface{}{ + "included": []map[string]interface{}{ + {"country": "US"}, + {"country": "CA"}, + }, + }, + "devices": []string{"DESKTOP", "MOBILE"}, + "age_range": map[string]interface{}{"min": 18, "max": 54}, + "gender": "ALL", + "interests": []map[string]interface{}{ + {"id": "int_1", "name": "Technology"}, + {"id": "int_2", "name": "Gaming"}, + }, + }, + }, + }, + { + "type": "POST", + "action": "CREATE", + "reference_id": "ref_post_1", + "entity_data": map[string]interface{}{ + "headline": "Check out our new product!", + "body": "This is an amazing product that you should definitely check out.", + "post_type": "IMAGE", + "content": []map[string]interface{}{ + { + "type": "IMAGE", + "url": "https://example.com/image.jpg", + "destination_url": "https://example.com/landing", + "call_to_action": "SHOP_NOW", + }, + }, + }, + }, + { + "type": "AD", + "action": "CREATE", + "reference_id": "ref_ad_1", + "entity_data": map[string]interface{}{ + "name": "Benchmark Ad", + "ad_group_id": "{{ref_ad_group_1}}", + "post_id": "{{ref_post_1}}", + "click_url": "https://example.com/landing?utm_source=reddit", + }, + }, + }, + } + b, _ := json.Marshal(payload) + return b +} + +// largeBulkActionPayload creates a large bulk action request (20 actions) +func largeBulkActionPayload() []byte { + actions := make([]map[string]interface{}, 0, 20) + + for i := 0; i < 5; i++ { + actions = append(actions, map[string]interface{}{ + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": fmt.Sprintf("ref_campaign_%d", i), + "entity_data": map[string]interface{}{ + "name": fmt.Sprintf("Campaign %d", i), + "objective": "CONVERSIONS", + "daily_budget_micro": 5000000 + (i * 1000000), + "start_time": "2025-01-15T00:00:00Z", + "funding_instrument_id": "fi_abc123", + "configured_status": "PAUSED", + }, + }) + + actions = append(actions, map[string]interface{}{ + "type": "AD_GROUP", + "action": "CREATE", + "reference_id": fmt.Sprintf("ref_ad_group_%d", i), + "entity_data": map[string]interface{}{ + "name": fmt.Sprintf("Ad Group %d", i), + "campaign_id": fmt.Sprintf("{{ref_campaign_%d}}", i), + "bid_strategy": "AUTO", + "goal_type": "CONVERSIONS", + "start_time": "2025-01-15T00:00:00Z", + "targeting": map[string]interface{}{ + "geos": map[string]interface{}{ + "included": []map[string]interface{}{ + {"country": "US"}, + {"country": "CA"}, + {"country": "GB"}, + }, + }, + "devices": []string{"DESKTOP", "MOBILE", "TABLET"}, + "os": []string{"IOS", "ANDROID"}, + "interests": []map[string]interface{}{ + {"id": fmt.Sprintf("int_%d", i), "name": "Technology"}, + {"id": fmt.Sprintf("int_%d", i+10), "name": "Gaming"}, + {"id": fmt.Sprintf("int_%d", i+20), "name": "Sports"}, + }, + "communities": []map[string]interface{}{ + {"id": fmt.Sprintf("com_%d", i), "name": "r/technology"}, + {"id": fmt.Sprintf("com_%d", i+10), "name": "r/gaming"}, + }, + "placements": []string{"FEED", "CONVERSATION"}, + "age_range": map[string]interface{}{"min": 18, "max": 65}, + "gender": "ALL", + }, + }, + }) + + actions = append(actions, map[string]interface{}{ + "type": "POST", + "action": "CREATE", + "reference_id": fmt.Sprintf("ref_post_%d", i), + "entity_data": map[string]interface{}{ + "headline": fmt.Sprintf("Amazing Product #%d", i), + "body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", + "post_type": "IMAGE", + "content": []map[string]interface{}{ + { + "type": "IMAGE", + "url": fmt.Sprintf("https://example.com/image_%d.jpg", i), + "destination_url": fmt.Sprintf("https://example.com/landing/%d", i), + "call_to_action": "LEARN_MORE", + }, + }, + }, + }) + + actions = append(actions, map[string]interface{}{ + "type": "AD", + "action": "CREATE", + "reference_id": fmt.Sprintf("ref_ad_%d", i), + "entity_data": map[string]interface{}{ + "name": fmt.Sprintf("Ad %d", i), + "ad_group_id": fmt.Sprintf("{{ref_ad_group_%d}}", i), + "post_id": fmt.Sprintf("{{ref_post_%d}}", i), + "click_url": fmt.Sprintf("https://example.com/landing/%d?utm_source=reddit&utm_medium=cpc", i), + }, + }) + } + + payload := map[string]interface{}{ + "data": actions, + } + b, _ := json.Marshal(payload) + return b +} + +// simplePetstorePayload creates a valid Pet JSON payload +func simplePetstorePayload() []byte { + payload := map[string]interface{}{ + "id": 10, + "name": "doggie", + "category": map[string]interface{}{ + "id": 1, + "name": "Dogs", + }, + "photoUrls": []string{"https://example.com/photo.jpg"}, + "tags": []map[string]interface{}{ + {"id": 1, "name": "friendly"}, + }, + "status": "available", + } + b, _ := json.Marshal(payload) + return b +} + +// === SECTION 1: Validator Initialization Benchmarks === +// These measure the cost of building a validator (parsing, schema warming, radix tree) + +func BenchmarkValidatorInit_AdsAPI(b *testing.B) { + loadSpecs() + b.ResetTimer() + b.ReportAllocs() + + for i := 0; i < b.N; i++ { + doc, err := libopenapi.NewDocument(adsAPISpec) + if err != nil { + b.Fatal(err) + } + v, errs := validator.NewValidator(doc) + if errs != nil { + b.Fatal(errs) + } + _ = v + } +} + +func BenchmarkValidatorInit_Petstore(b *testing.B) { + loadSpecs() + b.ResetTimer() + b.ReportAllocs() + + for i := 0; i < b.N; i++ { + doc, err := libopenapi.NewDocument(petstoreSpec) + if err != nil { + b.Fatal(err) + } + v, errs := validator.NewValidator(doc) + if errs != nil { + b.Fatal(errs) + } + _ = v + } +} + +func BenchmarkValidatorInit_AdsAPI_WithoutSchemaCache(b *testing.B) { + loadSpecs() + b.ResetTimer() + b.ReportAllocs() + + for i := 0; i < b.N; i++ { + doc, err := libopenapi.NewDocument(adsAPISpec) + if err != nil { + b.Fatal(err) + } + v, errs := validator.NewValidator(doc, config.WithSchemaCache(nil)) + if errs != nil { + b.Fatal(errs) + } + _ = v + } +} + +func BenchmarkValidatorInit_AdsAPI_WithoutRadixTree(b *testing.B) { + loadSpecs() + b.ResetTimer() + b.ReportAllocs() + + for i := 0; i < b.N; i++ { + doc, err := libopenapi.NewDocument(adsAPISpec) + if err != nil { + b.Fatal(err) + } + v, errs := validator.NewValidator(doc, config.WithPathTree(nil)) + if errs != nil { + b.Fatal(errs) + } + _ = v + } +} + +// BenchmarkValidatorInit_AdsAPI_MemoryFootprint measures the memory cost of keeping a validator alive. +func BenchmarkValidatorInit_AdsAPI_MemoryFootprint(b *testing.B) { + loadSpecs() + + var memBefore, memAfter runtime.MemStats + runtime.GC() + runtime.ReadMemStats(&memBefore) + + doc, err := libopenapi.NewDocument(adsAPISpec) + if err != nil { + b.Fatal(err) + } + v, errs := validator.NewValidator(doc) + if errs != nil { + b.Fatal(errs) + } + + runtime.GC() + runtime.ReadMemStats(&memAfter) + + heapDelta := memAfter.HeapAlloc - memBefore.HeapAlloc + b.ReportMetric(float64(heapDelta), "heap-bytes") + b.ReportMetric(float64(memAfter.HeapObjects-memBefore.HeapObjects), "heap-objects") + + // Keep validator alive + _ = v +} + +// === SECTION 2: Path Matching Benchmarks === +// These isolate path lookup performance: radix tree vs regex fallback + +func BenchmarkPathMatch_RadixTree_LiteralPath(b *testing.B) { + buildDocs() + doc, _ := adsAPIDoc.BuildV3Model() + opts := config.NewValidationOptions() + opts.PathTree = radix.BuildPathTree(&doc.Model) + + req, _ := http.NewRequest(http.MethodGet, "/api/v3/ad_accounts", nil) + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + paths.FindPath(req, &doc.Model, opts) + } +} + +func BenchmarkPathMatch_RadixTree_SingleParam(b *testing.B) { + buildDocs() + doc, _ := adsAPIDoc.BuildV3Model() + opts := config.NewValidationOptions() + opts.PathTree = radix.BuildPathTree(&doc.Model) + + req, _ := http.NewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_12345", nil) + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + paths.FindPath(req, &doc.Model, opts) + } +} + +func BenchmarkPathMatch_RadixTree_DeepParam(b *testing.B) { + buildDocs() + doc, _ := adsAPIDoc.BuildV3Model() + opts := config.NewValidationOptions() + opts.PathTree = radix.BuildPathTree(&doc.Model) + + req, _ := http.NewRequest(http.MethodPost, "/api/v3/ad_accounts/acc_12345/bulk_actions", nil) + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + paths.FindPath(req, &doc.Model, opts) + } +} + +func BenchmarkPathMatch_RegexFallback_LiteralPath(b *testing.B) { + buildDocs() + doc, _ := adsAPIDoc.BuildV3Model() + opts := config.NewValidationOptions(config.WithPathTree(nil)) + + req, _ := http.NewRequest(http.MethodGet, "/api/v3/ad_accounts", nil) + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + paths.FindPath(req, &doc.Model, opts) + } +} + +func BenchmarkPathMatch_RegexFallback_SingleParam(b *testing.B) { + buildDocs() + doc, _ := adsAPIDoc.BuildV3Model() + opts := config.NewValidationOptions(config.WithPathTree(nil)) + + req, _ := http.NewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_12345", nil) + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + paths.FindPath(req, &doc.Model, opts) + } +} + +func BenchmarkPathMatch_RegexFallback_DeepParam(b *testing.B) { + buildDocs() + doc, _ := adsAPIDoc.BuildV3Model() + opts := config.NewValidationOptions(config.WithPathTree(nil)) + + req, _ := http.NewRequest(http.MethodPost, "/api/v3/ad_accounts/acc_12345/bulk_actions", nil) + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + paths.FindPath(req, &doc.Model, opts) + } +} + +func BenchmarkPathMatch_RegexFallback_WithCache(b *testing.B) { + buildDocs() + doc, _ := adsAPIDoc.BuildV3Model() + regexCache := &sync.Map{} + opts := config.NewValidationOptions(config.WithPathTree(nil), config.WithRegexCache(regexCache)) + + req, _ := http.NewRequest(http.MethodPost, "/api/v3/ad_accounts/acc_12345/bulk_actions", nil) + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + paths.FindPath(req, &doc.Model, opts) + } +} + +// BenchmarkPathMatch_AllEndpoints tests path matching across ALL endpoints to simulate real traffic +func BenchmarkPathMatch_AllEndpoints_RadixTree(b *testing.B) { + buildDocs() + doc, _ := adsAPIDoc.BuildV3Model() + opts := config.NewValidationOptions() + opts.PathTree = radix.BuildPathTree(&doc.Model) + + requests := []*http.Request{ + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/campaigns"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/campaigns/camp_456"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/ad_groups"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/ad_groups/ag_789"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/ads"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/ads/ad_012"), + mustNewRequest(http.MethodPost, "/api/v3/ad_accounts/acc_123/bulk_actions"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/bulk_actions/job_345"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/posts"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/posts/post_678"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/pixels"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/funding_instruments"), + mustNewRequest(http.MethodPost, "/api/v3/ad_accounts/acc_123/reporting"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/custom_audiences"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/saved_audiences"), + mustNewRequest(http.MethodGet, "/api/v3/businesses"), + mustNewRequest(http.MethodGet, "/api/v3/me"), + } + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req := requests[i%len(requests)] + paths.FindPath(req, &doc.Model, opts) + } +} + +func BenchmarkPathMatch_AllEndpoints_RegexFallback(b *testing.B) { + buildDocs() + doc, _ := adsAPIDoc.BuildV3Model() + opts := config.NewValidationOptions(config.WithPathTree(nil)) + + requests := []*http.Request{ + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/campaigns"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/campaigns/camp_456"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/ad_groups"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/ad_groups/ag_789"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/ads"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/ads/ad_012"), + mustNewRequest(http.MethodPost, "/api/v3/ad_accounts/acc_123/bulk_actions"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/bulk_actions/job_345"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/posts"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/posts/post_678"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/pixels"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/funding_instruments"), + mustNewRequest(http.MethodPost, "/api/v3/ad_accounts/acc_123/reporting"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/custom_audiences"), + mustNewRequest(http.MethodGet, "/api/v3/ad_accounts/acc_123/saved_audiences"), + mustNewRequest(http.MethodGet, "/api/v3/businesses"), + mustNewRequest(http.MethodGet, "/api/v3/me"), + } + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req := requests[i%len(requests)] + paths.FindPath(req, &doc.Model, opts) + } +} + +// === SECTION 3: Request Body Validation Benchmarks === +// These measure the cost of schema validation with different payload sizes + +func BenchmarkRequestValidation_BulkActions_Small(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + payload := smallBulkActionPayload() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkRequestValidation_BulkActions_Medium(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + payload := mediumBulkActionPayload() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkRequestValidation_BulkActions_Large(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + payload := largeBulkActionPayload() + b.ReportMetric(float64(len(payload)), "payload-bytes") + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkRequestValidation_Petstore_AddPet(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(petstoreDoc) + if errs != nil { + b.Fatal(errs) + } + + payload := simplePetstorePayload() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/pet", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +// === SECTION 4: Sync vs Async Validation === +// Measures the goroutine overhead of async validation + +func BenchmarkRequestValidation_BulkActions_Sync(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + payload := mediumBulkActionPayload() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequestSync(req) + } +} + +func BenchmarkRequestValidation_BulkActions_Async(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + payload := mediumBulkActionPayload() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +// === SECTION 5: GET Request Validation (path + params only, no body) === + +func BenchmarkRequestValidation_GET_Simple(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/campaigns/camp_67890", nil) + v.ValidateHttpRequest(req) + } +} + +func BenchmarkRequestValidation_GET_WithQueryParams(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/campaigns?page_size=50&page_token=abc123", nil) + v.ValidateHttpRequest(req) + } +} + +// === SECTION 6: Concurrent Validation === +// Simulates production load with concurrent requests + +func BenchmarkConcurrentValidation_BulkActions(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + payload := mediumBulkActionPayload() + + b.ResetTimer() + b.ReportAllocs() + b.RunParallel(func(pb *testing.PB) { + for pb.Next() { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } + }) +} + +func BenchmarkConcurrentValidation_MixedEndpoints(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + payload := mediumBulkActionPayload() + + type testCase struct { + method string + url string + payload []byte + } + + cases := []testCase{ + {http.MethodGet, "/api/v3/ad_accounts/acc_123", nil}, + {http.MethodGet, "/api/v3/ad_accounts/acc_123/campaigns", nil}, + {http.MethodGet, "/api/v3/ad_accounts/acc_123/campaigns/camp_456", nil}, + {http.MethodPost, "/api/v3/ad_accounts/acc_123/bulk_actions", payload}, + {http.MethodGet, "/api/v3/ad_accounts/acc_123/ads/ad_789", nil}, + {http.MethodGet, "/api/v3/ad_accounts/acc_123/posts/post_012", nil}, + {http.MethodGet, "/api/v3/businesses", nil}, + {http.MethodGet, "/api/v3/me", nil}, + } + + b.ResetTimer() + b.ReportAllocs() + b.RunParallel(func(pb *testing.PB) { + idx := 0 + for pb.Next() { + tc := cases[idx%len(cases)] + var req *http.Request + if tc.payload != nil { + req, _ = http.NewRequest(tc.method, tc.url, bytes.NewReader(tc.payload)) + } else { + req, _ = http.NewRequest(tc.method, tc.url, nil) + } + if tc.payload != nil { + req.Header.Set("Content-Type", "application/json") + } + v.ValidateHttpRequest(req) + idx++ + } + }) +} + +// === SECTION 7: Per-request memory allocation analysis === +// These benchmarks are designed for detailed memory profiling + +func BenchmarkMemory_SingleValidation_BulkActions(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + payload := mediumBulkActionPayload() + b.ReportMetric(float64(len(payload)), "payload-bytes") + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + valid, validationErrs := v.ValidateHttpRequest(req) + _ = valid + _ = validationErrs + } +} + +func BenchmarkMemory_SingleValidation_GET(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/campaigns/camp_67890", nil) + valid, validationErrs := v.ValidateHttpRequest(req) + _ = valid + _ = validationErrs + } +} + +// === SECTION 8: Schema Cache Impact === + +func BenchmarkRequestValidation_WithSchemaCache(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + payload := mediumBulkActionPayload() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +func BenchmarkRequestValidation_WithoutSchemaCache(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc, config.WithSchemaCache(nil)) + if errs != nil { + b.Fatal(errs) + } + + payload := mediumBulkActionPayload() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(payload)) + req.Header.Set("Content-Type", "application/json") + v.ValidateHttpRequest(req) + } +} + +// === SECTION 9: Endpoint count scaling === +// Tests how the number of endpoints affects validation performance + +func BenchmarkPathMatch_ScaleEndpoints(b *testing.B) { + for _, numEndpoints := range []int{5, 10, 25, 50, 100} { + b.Run(fmt.Sprintf("RadixTree_%d_endpoints", numEndpoints), func(b *testing.B) { + spec := generateScalingSpec(numEndpoints) + doc, err := libopenapi.NewDocument(spec) + if err != nil { + b.Fatal(err) + } + model, _ := doc.BuildV3Model() + opts := config.NewValidationOptions() + opts.PathTree = radix.BuildPathTree(&model.Model) + + // Target a path in the middle + target := fmt.Sprintf("/api/v3/resource_%d/item_abc", numEndpoints/2) + req, _ := http.NewRequest(http.MethodGet, target, nil) + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + paths.FindPath(req, &model.Model, opts) + } + }) + + b.Run(fmt.Sprintf("RegexFallback_%d_endpoints", numEndpoints), func(b *testing.B) { + spec := generateScalingSpec(numEndpoints) + doc, err := libopenapi.NewDocument(spec) + if err != nil { + b.Fatal(err) + } + model, _ := doc.BuildV3Model() + opts := config.NewValidationOptions(config.WithPathTree(nil)) + + target := fmt.Sprintf("/api/v3/resource_%d/item_abc", numEndpoints/2) + req, _ := http.NewRequest(http.MethodGet, target, nil) + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + paths.FindPath(req, &model.Model, opts) + } + }) + } +} + +// === SECTION 10: Response Validation === +// These measure the cost of validating response bodies against the spec. + +func validBulkActionsResp() []byte { + resp := map[string]interface{}{ + "data": map[string]interface{}{ + "id": "job_abc123", + "status": "SUCCESS", + "input": []map[string]interface{}{ + { + "type": "CAMPAIGN", + "action": "CREATE", + "reference_id": "ref_campaign_1", + "entity_data": map[string]interface{}{ + "name": "Campaign 1", + "objective": "CONVERSIONS", + "daily_budget_micro": 5000000, + "start_time": "2025-01-15T00:00:00Z", + "funding_instrument_id": "fi_abc123", + "configured_status": "PAUSED", + }, + }, + }, + "results": []map[string]interface{}{ + { + "reference_id": "ref_campaign_1", + "type": "CAMPAIGN", + "status": "SUCCESS", + "id": "camp_xyz", + }, + }, + }, + } + b, _ := json.Marshal(resp) + return b +} + +func validCampaignResp() []byte { + resp := map[string]interface{}{ + "data": map[string]interface{}{ + "id": "camp_xyz", + "name": "Test Campaign", + "status": "ACTIVE", + "objective": "CONVERSIONS", + }, + } + b, _ := json.Marshal(resp) + return b +} + +func makeTestResponse(statusCode int, body []byte) *http.Response { + return &http.Response{ + StatusCode: statusCode, + Header: http.Header{"Content-Type": []string{"application/json"}}, + Body: io.NopCloser(bytes.NewReader(body)), + } +} + +func BenchmarkResponseValidation_BulkActions(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + reqPayload := smallBulkActionPayload() + respBody := validBulkActionsResp() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(reqPayload)) + req.Header.Set("Content-Type", "application/json") + resp := makeTestResponse(201, respBody) + v.ValidateHttpResponse(req, resp) + } +} + +func BenchmarkResponseValidation_GET_Campaign(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + respBody := validCampaignResp() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodGet, + "/api/v3/ad_accounts/acc_12345/campaigns/camp_67890", nil) + resp := makeTestResponse(200, respBody) + v.ValidateHttpResponse(req, resp) + } +} + +func BenchmarkRequestResponseValidation_BulkActions(b *testing.B) { + buildDocs() + v, errs := validator.NewValidator(adsAPIDoc) + if errs != nil { + b.Fatal(errs) + } + + reqPayload := mediumBulkActionPayload() + respBody := validBulkActionsResp() + + b.ResetTimer() + b.ReportAllocs() + for i := 0; i < b.N; i++ { + req, _ := http.NewRequest(http.MethodPost, + "/api/v3/ad_accounts/acc_12345/bulk_actions", + bytes.NewReader(reqPayload)) + req.Header.Set("Content-Type", "application/json") + resp := makeTestResponse(201, respBody) + v.ValidateHttpRequestResponse(req, resp) + } +} + +// === Helpers === + +func mustNewRequest(method, url string) *http.Request { + req, err := http.NewRequest(method, url, nil) + if err != nil { + panic(err) + } + return req +} + +// generateScalingSpec generates a minimal OpenAPI spec with N endpoint pairs (list + get-by-id) +func generateScalingSpec(numEndpoints int) []byte { + var pathsYAML string + for i := 0; i < numEndpoints; i++ { + pathsYAML += fmt.Sprintf(` /resource_%d: + get: + operationId: listResource%d + responses: + "200": + description: OK + /resource_%d/{item_id}: + get: + operationId: getResource%d + parameters: + - name: item_id + in: path + required: true + schema: + type: string + responses: + "200": + description: OK +`, i, i, i, i) + } + + spec := fmt.Sprintf(`openapi: "3.0.2" +info: + title: Scaling Benchmark + version: "1.0.0" +servers: + - url: /api/v3 +paths: +%s`, pathsYAML) + + return []byte(spec) +} diff --git a/config/config.go b/config/config.go index f46acce0..c9e42558 100644 --- a/config/config.go +++ b/config/config.go @@ -2,10 +2,12 @@ package config import ( "log/slog" + "sync" "github.com/santhosh-tekuri/jsonschema/v6" "github.com/pb33f/libopenapi-validator/cache" + "github.com/pb33f/libopenapi-validator/radix" ) // RegexCache can be set to enable compiled regex caching. @@ -30,6 +32,8 @@ type ValidationOptions struct { AllowScalarCoercion bool // Enable string->boolean/number coercion Formats map[string]func(v any) error SchemaCache cache.SchemaCache // Optional cache for compiled schemas + PathTree radix.PathLookup // O(k) path lookup via radix tree (built automatically) + pathTreeSet bool // Internal: true if PathTree was explicitly set via WithPathTree Logger *slog.Logger // Logger for debug/error output (nil = silent) // strict mode options - detect undeclared properties even when additionalProperties: true @@ -37,6 +41,8 @@ type ValidationOptions struct { StrictIgnorePaths []string // Instance JSONPath patterns to exclude from strict checks StrictIgnoredHeaders []string // Headers to always ignore in strict mode (nil = use defaults) strictIgnoredHeadersMerge bool // Internal: true if merging with defaults + + LazyErrors bool // When true, defer expensive error field population } // Option Enables an 'Options pattern' approach @@ -51,6 +57,7 @@ func NewValidationOptions(opts ...Option) *ValidationOptions { SecurityValidation: true, OpenAPIMode: true, // Enable OpenAPI vocabulary by default SchemaCache: cache.NewDefaultCache(), // Enable caching by default + RegexCache: &sync.Map{}, // Enable regex caching by default } for _, opt := range opts { @@ -65,20 +72,7 @@ func NewValidationOptions(opts ...Option) *ValidationOptions { func WithExistingOpts(options *ValidationOptions) Option { return func(o *ValidationOptions) { if options != nil { - o.RegexEngine = options.RegexEngine - o.RegexCache = options.RegexCache - o.FormatAssertions = options.FormatAssertions - o.ContentAssertions = options.ContentAssertions - o.SecurityValidation = options.SecurityValidation - o.OpenAPIMode = options.OpenAPIMode - o.AllowScalarCoercion = options.AllowScalarCoercion - o.Formats = options.Formats - o.SchemaCache = options.SchemaCache - o.Logger = options.Logger - o.StrictMode = options.StrictMode - o.StrictIgnorePaths = options.StrictIgnorePaths - o.StrictIgnoredHeaders = options.StrictIgnoredHeaders - o.strictIgnoredHeadersMerge = options.strictIgnoredHeadersMerge + *o = *options } } } @@ -164,9 +158,19 @@ func WithScalarCoercion() Option { // WithSchemaCache sets a custom cache implementation or disables caching if nil. // Pass nil to disable schema caching and skip cache warming during validator initialization. // The default cache is a thread-safe sync.Map wrapper. -func WithSchemaCache(cache cache.SchemaCache) Option { +func WithSchemaCache(schemaCache cache.SchemaCache) Option { + return func(o *ValidationOptions) { + o.SchemaCache = schemaCache + } +} + +// WithPathTree sets a custom radix tree for path matching. +// The default is built automatically from the OpenAPI specification. +// Pass nil to disable the radix tree and use regex-based matching only. +func WithPathTree(pathTree radix.PathLookup) Option { return func(o *ValidationOptions) { - o.SchemaCache = cache + o.PathTree = pathTree + o.pathTreeSet = true } } @@ -220,6 +224,16 @@ func WithStrictIgnoredHeadersExtra(headers ...string) Option { } } +// WithLazyErrors enables deferred population of expensive error fields. +// When enabled, ReferenceSchema and ReferenceObject in SchemaValidationFailure +// are left empty during error construction. Use GetReferenceSchema() and +// GetReferenceObject() to resolve them on demand. +func WithLazyErrors() Option { + return func(o *ValidationOptions) { + o.LazyErrors = true + } +} + // defaultIgnoredHeaders contains standard HTTP headers ignored by default. // This is the fallback list used when no custom headers are configured. var defaultIgnoredHeaders = []string{ @@ -233,6 +247,11 @@ var defaultIgnoredHeaders = []string{ "request-start-time", // Added by some API clients for timing } +// IsPathTreeSet returns true if PathTree was explicitly configured via WithPathTree. +func (o *ValidationOptions) IsPathTreeSet() bool { + return o.pathTreeSet +} + // GetEffectiveStrictIgnoredHeaders returns the list of headers to ignore // based on configuration. Returns defaults if not configured, merged list // if extra headers were added, or replaced list if headers were fully replaced. diff --git a/config/config_test.go b/config/config_test.go index dddd739a..d6593ef7 100644 --- a/config/config_test.go +++ b/config/config_test.go @@ -22,7 +22,7 @@ func TestNewValidationOptions_Defaults(t *testing.T) { assert.True(t, opts.OpenAPIMode) // Default is true assert.False(t, opts.AllowScalarCoercion) // Default is false assert.Nil(t, opts.RegexEngine) - assert.Nil(t, opts.RegexCache) + assert.NotNil(t, opts.RegexCache) // Default is enabled (like SchemaCache) } func TestNewValidationOptions_WithNilOption(t *testing.T) { @@ -35,7 +35,7 @@ func TestNewValidationOptions_WithNilOption(t *testing.T) { assert.True(t, opts.OpenAPIMode) // Default is true assert.False(t, opts.AllowScalarCoercion) // Default is false assert.Nil(t, opts.RegexEngine) - assert.Nil(t, opts.RegexCache) + assert.NotNil(t, opts.RegexCache) // Default is enabled (like SchemaCache) } func TestWithFormatAssertions(t *testing.T) { @@ -47,7 +47,7 @@ func TestWithFormatAssertions(t *testing.T) { assert.True(t, opts.OpenAPIMode) // Default is true assert.False(t, opts.AllowScalarCoercion) // Default is false assert.Nil(t, opts.RegexEngine) - assert.Nil(t, opts.RegexCache) + assert.NotNil(t, opts.RegexCache) // Default is enabled (like SchemaCache) } func TestWithContentAssertions(t *testing.T) { @@ -59,7 +59,7 @@ func TestWithContentAssertions(t *testing.T) { assert.True(t, opts.OpenAPIMode) // Default is true assert.False(t, opts.AllowScalarCoercion) // Default is false assert.Nil(t, opts.RegexEngine) - assert.Nil(t, opts.RegexCache) + assert.NotNil(t, opts.RegexCache) // Default is enabled (like SchemaCache) } func TestWithoutSecurityValidation(t *testing.T) { @@ -71,7 +71,7 @@ func TestWithoutSecurityValidation(t *testing.T) { assert.True(t, opts.OpenAPIMode) // Default is true assert.False(t, opts.AllowScalarCoercion) // Default is false assert.Nil(t, opts.RegexEngine) - assert.Nil(t, opts.RegexCache) + assert.NotNil(t, opts.RegexCache) // Default is enabled (like SchemaCache) } func TestWithRegexEngine(t *testing.T) { @@ -86,7 +86,7 @@ func TestWithRegexEngine(t *testing.T) { assert.True(t, opts.OpenAPIMode) // Default is true assert.False(t, opts.AllowScalarCoercion) // Default is false assert.Nil(t, opts.RegexEngine) - assert.Nil(t, opts.RegexCache) + assert.NotNil(t, opts.RegexCache) // Default is enabled (like SchemaCache) } func TestWithExistingOpts(t *testing.T) { @@ -122,7 +122,7 @@ func TestWithExistingOpts_NilSource(t *testing.T) { assert.True(t, opts.OpenAPIMode) // Default is true assert.False(t, opts.AllowScalarCoercion) // Default is false assert.Nil(t, opts.RegexEngine) - assert.Nil(t, opts.RegexCache) + assert.NotNil(t, opts.RegexCache) // Default is enabled (like SchemaCache) } func TestMultipleOptions(t *testing.T) { @@ -137,7 +137,7 @@ func TestMultipleOptions(t *testing.T) { assert.True(t, opts.OpenAPIMode) // Default is true assert.False(t, opts.AllowScalarCoercion) // Default is false assert.Nil(t, opts.RegexEngine) - assert.Nil(t, opts.RegexCache) + assert.NotNil(t, opts.RegexCache) // Default is enabled (like SchemaCache) } func TestOptionOverride(t *testing.T) { @@ -154,7 +154,7 @@ func TestOptionOverride(t *testing.T) { assert.True(t, opts.OpenAPIMode) // Default is true assert.False(t, opts.AllowScalarCoercion) // Default is false assert.Nil(t, opts.RegexEngine) - assert.Nil(t, opts.RegexCache) + assert.NotNil(t, opts.RegexCache) // Default is enabled (like SchemaCache) } func TestWithExistingOpts_PartialOverride(t *testing.T) { @@ -173,8 +173,8 @@ func TestWithExistingOpts_PartialOverride(t *testing.T) { WithContentAssertions(), // This should still be true (no change) ) - assert.Nil(t, opts.RegexEngine) // Both should be nil - assert.Nil(t, opts.RegexCache) + assert.Nil(t, opts.RegexEngine) // Both should be nil + assert.Nil(t, opts.RegexCache) // Copied from original (nil/zero value) assert.True(t, opts.FormatAssertions) // From original assert.True(t, opts.ContentAssertions) // Reapplied, but same value assert.False(t, opts.SecurityValidation) // From original @@ -203,7 +203,7 @@ func TestComplexScenario(t *testing.T) { assert.True(t, opts.ContentAssertions) // Added assert.False(t, opts.SecurityValidation) // From base assert.Nil(t, opts.RegexEngine) // Should be nil - assert.Nil(t, opts.RegexCache) + assert.Nil(t, opts.RegexCache) // Copied from baseOpts (nil/zero value) } func TestMultipleOptionsWithSecurityDisabled(t *testing.T) { @@ -217,7 +217,7 @@ func TestMultipleOptionsWithSecurityDisabled(t *testing.T) { assert.True(t, opts.ContentAssertions) assert.False(t, opts.SecurityValidation) assert.Nil(t, opts.RegexEngine) - assert.Nil(t, opts.RegexCache) + assert.NotNil(t, opts.RegexCache) // Default is enabled (like SchemaCache) } func TestWithExistingOpts_SecurityValidationCopied(t *testing.T) { @@ -312,7 +312,7 @@ func TestComplexOpenAPIScenario(t *testing.T) { assert.True(t, opts.ContentAssertions) assert.False(t, opts.SecurityValidation) assert.Nil(t, opts.RegexEngine) - assert.Nil(t, opts.RegexCache) + assert.NotNil(t, opts.RegexCache) // Default is enabled (like SchemaCache) } func TestWithExistingOpts_OpenAPIFields(t *testing.T) { diff --git a/coverage.out b/coverage.out new file mode 100644 index 00000000..c599c96a --- /dev/null +++ b/coverage.out @@ -0,0 +1,161 @@ +mode: atomic +github.com/pb33f/libopenapi-validator/path_matcher.go:31.75,32.22 1 57 +github.com/pb33f/libopenapi-validator/path_matcher.go:32.22,33.50 1 61 +github.com/pb33f/libopenapi-validator/path_matcher.go:33.50,35.4 1 51 +github.com/pb33f/libopenapi-validator/path_matcher.go:37.2,37.12 1 6 +github.com/pb33f/libopenapi-validator/path_matcher.go:45.74,46.25 1 59 +github.com/pb33f/libopenapi-validator/path_matcher.go:46.25,48.3 1 1 +github.com/pb33f/libopenapi-validator/path_matcher.go:49.2,50.12 2 58 +github.com/pb33f/libopenapi-validator/path_matcher.go:50.12,52.3 1 6 +github.com/pb33f/libopenapi-validator/path_matcher.go:53.2,57.3 1 52 +github.com/pb33f/libopenapi-validator/path_matcher.go:66.76,67.66 1 9 +github.com/pb33f/libopenapi-validator/path_matcher.go:67.66,69.3 1 2 +github.com/pb33f/libopenapi-validator/path_matcher.go:70.2,71.12 2 7 +github.com/pb33f/libopenapi-validator/path_matcher.go:71.12,73.3 1 6 +github.com/pb33f/libopenapi-validator/path_matcher.go:74.2,78.3 1 1 +github.com/pb33f/libopenapi-validator/request_context.go:39.109,44.44 3 53 +github.com/pb33f/libopenapi-validator/request_context.go:44.44,46.3 1 53 +github.com/pb33f/libopenapi-validator/request_context.go:49.2,50.18 2 53 +github.com/pb33f/libopenapi-validator/request_context.go:50.18,66.3 3 5 +github.com/pb33f/libopenapi-validator/request_context.go:69.2,70.22 2 48 +github.com/pb33f/libopenapi-validator/request_context.go:70.22,83.3 3 1 +github.com/pb33f/libopenapi-validator/request_context.go:86.2,98.8 3 47 +github.com/pb33f/libopenapi-validator/validator.go:78.93,80.17 2 57 +github.com/pb33f/libopenapi-validator/validator.go:80.17,82.3 1 1 +github.com/pb33f/libopenapi-validator/validator.go:83.2,85.15 3 56 +github.com/pb33f/libopenapi-validator/validator.go:89.79,94.57 2 61 +github.com/pb33f/libopenapi-validator/validator.go:94.57,96.3 1 61 +github.com/pb33f/libopenapi-validator/validator.go:100.2,107.29 4 61 +github.com/pb33f/libopenapi-validator/validator.go:107.29,109.3 1 61 +github.com/pb33f/libopenapi-validator/validator.go:110.2,128.10 6 61 +github.com/pb33f/libopenapi-validator/validator.go:131.63,133.2 1 1 +github.com/pb33f/libopenapi-validator/validator.go:135.75,137.2 1 1 +github.com/pb33f/libopenapi-validator/validator.go:139.77,141.2 1 3 +github.com/pb33f/libopenapi-validator/validator.go:143.80,145.2 1 1 +github.com/pb33f/libopenapi-validator/validator.go:147.74,148.23 1 7 +github.com/pb33f/libopenapi-validator/validator.go:148.23,158.3 1 1 +github.com/pb33f/libopenapi-validator/validator.go:159.2,160.22 2 6 +github.com/pb33f/libopenapi-validator/validator.go:160.22,162.3 1 6 +github.com/pb33f/libopenapi-validator/validator.go:163.2,163.81 1 6 +github.com/pb33f/libopenapi-validator/validator.go:169.37,171.17 2 8 +github.com/pb33f/libopenapi-validator/validator.go:171.17,173.3 1 1 +github.com/pb33f/libopenapi-validator/validator.go:174.2,176.29 2 7 +github.com/pb33f/libopenapi-validator/validator.go:176.29,178.3 1 4 +github.com/pb33f/libopenapi-validator/validator.go:179.2,179.18 1 3 +github.com/pb33f/libopenapi-validator/validator.go:185.37,187.17 2 19 +github.com/pb33f/libopenapi-validator/validator.go:187.17,189.3 1 1 +github.com/pb33f/libopenapi-validator/validator.go:190.2,193.55 3 18 +github.com/pb33f/libopenapi-validator/validator.go:193.55,195.3 1 11 +github.com/pb33f/libopenapi-validator/validator.go:196.2,196.18 1 7 +github.com/pb33f/libopenapi-validator/validator.go:199.98,202.55 1 14 +github.com/pb33f/libopenapi-validator/validator.go:202.55,204.3 1 3 +github.com/pb33f/libopenapi-validator/validator.go:206.2,207.17 2 11 +github.com/pb33f/libopenapi-validator/validator.go:207.17,209.3 1 1 +github.com/pb33f/libopenapi-validator/validator.go:210.2,210.94 1 10 +github.com/pb33f/libopenapi-validator/validator.go:213.151,231.99 5 28 +github.com/pb33f/libopenapi-validator/validator.go:231.99,246.90 6 28 +github.com/pb33f/libopenapi-validator/validator.go:246.90,248.8 2 28 +github.com/pb33f/libopenapi-validator/validator.go:248.8,249.12 1 147 +github.com/pb33f/libopenapi-validator/validator.go:250.31,251.69 1 7 +github.com/pb33f/libopenapi-validator/validator.go:252.20,254.50 2 140 +github.com/pb33f/libopenapi-validator/validator.go:254.50,257.7 2 28 +github.com/pb33f/libopenapi-validator/validator.go:262.3,266.5 1 28 +github.com/pb33f/libopenapi-validator/validator.go:266.5,268.14 2 140 +github.com/pb33f/libopenapi-validator/validator.go:268.14,270.5 1 7 +github.com/pb33f/libopenapi-validator/validator.go:271.4,271.25 1 140 +github.com/pb33f/libopenapi-validator/validator.go:273.3,274.30 2 28 +github.com/pb33f/libopenapi-validator/validator.go:274.30,276.4 1 140 +github.com/pb33f/libopenapi-validator/validator.go:279.3,280.37 2 28 +github.com/pb33f/libopenapi-validator/validator.go:280.37,282.4 1 5 +github.com/pb33f/libopenapi-validator/validator.go:285.3,285.28 1 28 +github.com/pb33f/libopenapi-validator/validator.go:288.2,288.101 1 28 +github.com/pb33f/libopenapi-validator/validator.go:288.101,290.13 2 28 +github.com/pb33f/libopenapi-validator/validator.go:290.13,292.4 1 5 +github.com/pb33f/libopenapi-validator/validator.go:293.3,293.24 1 28 +github.com/pb33f/libopenapi-validator/validator.go:297.2,308.32 4 28 +github.com/pb33f/libopenapi-validator/validator.go:308.32,310.3 1 56 +github.com/pb33f/libopenapi-validator/validator.go:313.2,318.53 3 28 +github.com/pb33f/libopenapi-validator/validator.go:321.98,323.2 1 37 +github.com/pb33f/libopenapi-validator/validator.go:325.99,327.2 1 37 +github.com/pb33f/libopenapi-validator/validator.go:329.100,331.2 1 37 +github.com/pb33f/libopenapi-validator/validator.go:333.100,335.2 1 37 +github.com/pb33f/libopenapi-validator/validator.go:337.96,339.2 1 37 +github.com/pb33f/libopenapi-validator/validator.go:341.99,343.2 1 37 +github.com/pb33f/libopenapi-validator/validator.go:346.96,355.4 2 9 +github.com/pb33f/libopenapi-validator/validator.go:355.4,356.48 1 54 +github.com/pb33f/libopenapi-validator/validator.go:356.48,358.4 1 4 +github.com/pb33f/libopenapi-validator/validator.go:360.2,360.53 1 9 +github.com/pb33f/libopenapi-validator/validator.go:363.102,365.17 2 9 +github.com/pb33f/libopenapi-validator/validator.go:365.17,367.3 1 1 +github.com/pb33f/libopenapi-validator/validator.go:368.2,368.35 1 8 +github.com/pb33f/libopenapi-validator/validator.go:371.155,382.2 2 1 +github.com/pb33f/libopenapi-validator/validator.go:399.3,402.6 3 28 +github.com/pb33f/libopenapi-validator/validator.go:402.6,403.10 1 66 +github.com/pb33f/libopenapi-validator/validator.go:404.29,407.27 3 10 +github.com/pb33f/libopenapi-validator/validator.go:408.18,410.37 2 56 +github.com/pb33f/libopenapi-validator/validator.go:410.37,413.5 2 28 +github.com/pb33f/libopenapi-validator/validator.go:425.59,426.39 1 31 +github.com/pb33f/libopenapi-validator/validator.go:426.39,427.55 1 14 +github.com/pb33f/libopenapi-validator/validator.go:427.55,429.4 1 5 +github.com/pb33f/libopenapi-validator/validator.go:430.3,430.43 1 9 +github.com/pb33f/libopenapi-validator/validator.go:439.3,441.96 1 64 +github.com/pb33f/libopenapi-validator/validator.go:441.96,443.3 1 4 +github.com/pb33f/libopenapi-validator/validator.go:445.2,448.91 2 60 +github.com/pb33f/libopenapi-validator/validator.go:448.91,453.24 3 375 +github.com/pb33f/libopenapi-validator/validator.go:453.24,454.12 1 0 +github.com/pb33f/libopenapi-validator/validator.go:457.3,457.75 1 375 +github.com/pb33f/libopenapi-validator/validator.go:457.75,459.24 2 532 +github.com/pb33f/libopenapi-validator/validator.go:459.24,460.13 1 0 +github.com/pb33f/libopenapi-validator/validator.go:464.4,464.76 1 532 +github.com/pb33f/libopenapi-validator/validator.go:464.76,465.116 1 203 +github.com/pb33f/libopenapi-validator/validator.go:465.116,467.33 2 463 +github.com/pb33f/libopenapi-validator/validator.go:467.33,469.7 1 462 +github.com/pb33f/libopenapi-validator/validator.go:474.4,474.34 1 532 +github.com/pb33f/libopenapi-validator/validator.go:474.34,476.41 1 514 +github.com/pb33f/libopenapi-validator/validator.go:476.41,477.101 1 514 +github.com/pb33f/libopenapi-validator/validator.go:477.101,479.53 2 851 +github.com/pb33f/libopenapi-validator/validator.go:479.53,480.106 1 320 +github.com/pb33f/libopenapi-validator/validator.go:480.106,482.36 2 553 +github.com/pb33f/libopenapi-validator/validator.go:482.36,484.10 1 553 +github.com/pb33f/libopenapi-validator/validator.go:491.5,491.89 1 514 +github.com/pb33f/libopenapi-validator/validator.go:491.89,492.123 1 30 +github.com/pb33f/libopenapi-validator/validator.go:492.123,494.34 2 56 +github.com/pb33f/libopenapi-validator/validator.go:494.34,496.8 1 56 +github.com/pb33f/libopenapi-validator/validator.go:502.4,502.35 1 532 +github.com/pb33f/libopenapi-validator/validator.go:502.35,503.48 1 319 +github.com/pb33f/libopenapi-validator/validator.go:503.48,504.22 1 453 +github.com/pb33f/libopenapi-validator/validator.go:504.22,506.7 1 453 +github.com/pb33f/libopenapi-validator/validator.go:512.3,512.33 1 375 +github.com/pb33f/libopenapi-validator/validator.go:512.33,513.46 1 4 +github.com/pb33f/libopenapi-validator/validator.go:513.46,514.21 1 4 +github.com/pb33f/libopenapi-validator/validator.go:514.21,516.6 1 4 +github.com/pb33f/libopenapi-validator/validator.go:523.117,524.49 1 1071 +github.com/pb33f/libopenapi-validator/validator.go:524.49,527.51 2 1071 +github.com/pb33f/libopenapi-validator/validator.go:527.51,529.21 2 238 +github.com/pb33f/libopenapi-validator/validator.go:529.21,534.32 5 238 +github.com/pb33f/libopenapi-validator/validator.go:534.32,549.6 4 235 +github.com/pb33f/libopenapi-validator/validator.go:556.113,557.18 1 457 +github.com/pb33f/libopenapi-validator/validator.go:557.18,562.26 3 457 +github.com/pb33f/libopenapi-validator/validator.go:562.26,564.21 2 456 +github.com/pb33f/libopenapi-validator/validator.go:564.21,566.5 1 456 +github.com/pb33f/libopenapi-validator/validator.go:567.9,567.34 1 1 +github.com/pb33f/libopenapi-validator/validator.go:567.34,569.99 1 1 +github.com/pb33f/libopenapi-validator/validator.go:569.99,571.32 2 1 +github.com/pb33f/libopenapi-validator/validator.go:571.32,573.23 2 1 +github.com/pb33f/libopenapi-validator/validator.go:573.23,575.7 1 1 +github.com/pb33f/libopenapi-validator/validator.go:576.6,576.11 1 1 +github.com/pb33f/libopenapi-validator/validator.go:581.3,581.20 1 457 +github.com/pb33f/libopenapi-validator/validator.go:581.20,582.52 1 457 +github.com/pb33f/libopenapi-validator/validator.go:582.52,587.32 5 116 +github.com/pb33f/libopenapi-validator/validator.go:587.32,603.6 4 116 +github.com/pb33f/libopenapi-validator/validator.go:611.74,612.95 1 61 +github.com/pb33f/libopenapi-validator/validator.go:612.95,614.3 1 1 +github.com/pb33f/libopenapi-validator/validator.go:616.2,616.91 1 60 +github.com/pb33f/libopenapi-validator/validator.go:616.91,619.36 3 375 +github.com/pb33f/libopenapi-validator/validator.go:619.36,620.21 1 1113 +github.com/pb33f/libopenapi-validator/validator.go:620.21,621.13 1 375 +github.com/pb33f/libopenapi-validator/validator.go:624.4,624.39 1 738 +github.com/pb33f/libopenapi-validator/validator.go:624.39,625.13 1 627 +github.com/pb33f/libopenapi-validator/validator.go:627.4,627.60 1 111 +github.com/pb33f/libopenapi-validator/validator.go:627.60,629.19 2 85 +github.com/pb33f/libopenapi-validator/validator.go:629.19,631.6 1 85 diff --git a/docs/architecture-review.md b/docs/architecture-review.md new file mode 100644 index 00000000..de3de4d1 --- /dev/null +++ b/docs/architecture-review.md @@ -0,0 +1,630 @@ +# Architecture Review: libopenapi-validator + +**Date**: 2026-02-06 +**Purpose**: Document the current architecture, identify systemic inefficiencies, and provide +the foundation for a targeted redesign. + +--- + +## 1. What the Library Does + +libopenapi-validator validates HTTP requests and responses against an OpenAPI 3.x specification. +It handles: + +- **Path matching**: Resolving a request URL to the correct `PathItem` in the spec +- **Parameter validation**: Path, query, header, cookie parameters + security requirements +- **Request body validation**: JSON request bodies against the spec's schema +- **Response body validation**: JSON response bodies against the spec's schema +- **Document validation**: The spec itself against the OpenAPI meta-schema + +The library is designed to be instantiated once (during service startup) and reused across +all incoming requests. + +--- + +## 2. Initialization Flow + +``` +NewValidator(document) + ├── document.BuildV3Model() → *v3.Document + ├── Build radix tree → PathLookup (O(k) path matching) + ├── warmSchemaCaches() → Pre-compile all request/response/param schemas + ├── warmRegexCache() → Pre-compile all path segment regexes + └── Create sub-validators (each gets a copy of the document + options): + ├── parameters.NewParameterValidator(doc, opts) + ├── requests.NewRequestBodyValidator(doc, opts) + └── responses.NewResponseBodyValidator(doc, opts) +``` + +**Key detail**: Each sub-validator stores its own reference to the `*v3.Document` and +`*ValidationOptions`. The options contain shared caches (`SchemaCache`, `RegexCache`, +`PathTree`), so cache reads/writes are shared across sub-validators. + +--- + +## 3. Per-Request Validation Flow + +### 3.1 Entry Points + +The top-level `Validator` interface offers three entry points: + +| Method | What it validates | +|--------|-------------------| +| `ValidateHttpRequest(req)` | Path + params + request body | +| `ValidateHttpResponse(req, resp)` | Path + response body + response headers | +| `ValidateHttpRequestResponse(req, resp)` | All of the above combined | + +### 3.2 Request Validation (POST with body) + +``` +ValidateHttpRequest(request) + │ + ├── request has body? → YES → ValidateHttpRequestWithPathItem (async path) + │ NO → ValidateHttpRequestSync (sync fast-path) + │ + │ ┌─── Step 1: FindPath ─────────────────────────────────────────────┐ + │ │ StripRequestPath(request, document) → stripped path │ + │ │ PathTree.Lookup(stripped) → PathItem + matchedPath │ + │ │ (if miss: regex fallback over ALL paths) │ + │ │ │ + │ │ RETURNS: (PathItem, errors, matchedPath) │ + │ │ DISCARDS: stripped path, path segments, parameter values │ + │ └──────────────────────────────────────────────────────────────────┘ + │ + │ ┌─── Step 2: Async Validation ─────────────────────────────────────┐ + │ │ │ + │ │ Creates 3 layers of channels: │ + │ │ doneChan, errChan, controlChan (top-level orchestration) │ + │ │ paramErrs, paramControlChan (param sub-orchestration) │ + │ │ paramFunctionControlChan (param completion signal) │ + │ │ │ + │ │ Spawns goroutines: │ + │ │ 1× runValidation listener │ + │ │ 1× parameterValidationFunc wrapper │ + │ │ └── 1× paramListener goroutine │ + │ │ └── 5× validateParamFunction goroutines: │ + │ │ ├── ValidatePathParamsWithPathItem │ + │ │ ├── ValidateCookieParamsWithPathItem │ + │ │ ├── ValidateHeaderParamsWithPathItem │ + │ │ ├── ValidateQueryParamsWithPathItem │ + │ │ └── ValidateSecurityWithPathItem │ + │ │ 1× requestBodyValidationFunc goroutine │ + │ │ │ + │ │ Total: 9 goroutines + 5 channels per POST request │ + │ │ │ + │ │ After completion: sorts errors for deterministic ordering │ + │ └──────────────────────────────────────────────────────────────────┘ + │ + │ ┌─── Step 3: What Each Parameter Validator Does ───────────────────┐ + │ │ │ + │ │ EVERY parameter validator independently: │ + │ │ 1. Calls helpers.ExtractParamsForOperation(request, pathItem) │ + │ │ → switch on HTTP method, append path + operation params │ + │ │ 2. Filters to its own param type (in: path/query/header/etc) │ + │ │ 3. Performs type-specific extraction + schema validation │ + │ │ │ + │ │ PATH PARAMS specifically: │ + │ │ 1. Re-strips the request path (StripRequestPath) │ + │ │ 2. Re-splits both paths into segments (strings.Split) │ + │ │ 3. For each path segment: │ + │ │ - Loads/compiles regex (same regex used in FindPath) │ + │ │ - Runs FindStringSubmatch (same match done in FindPath) │ + │ │ - Calls BraceIndices (same parse done in regex compilation)│ + │ │ - Extracts parameter values from regex groups │ + │ │ - Validates each value against its schema │ + │ │ │ + │ │ This means a single GET request with 2 path params does: │ + │ │ - 1× StripRequestPath in FindPath │ + │ │ - 1× StripRequestPath in path param validator │ + │ │ - 1× regex match per segment in FindPath │ + │ │ - 1× regex match per segment in path param validator │ + │ │ - 5× ExtractParamsForOperation (once per validator type) │ + │ └──────────────────────────────────────────────────────────────────┘ + │ + │ ┌─── Step 4: Body Validation ──────────────────────────────────────┐ + │ │ 1. Extracts operation from PathItem + HTTP method │ + │ │ 2. Extracts content type from request header │ + │ │ 3. Matches media type (supports wildcards) │ + │ │ 4. Only validates JSON content types (checks for "json" substr) │ + │ │ 5. Looks up compiled schema from cache (by GoLow().Hash()) │ + │ │ 6. On cache miss: renders schema → YAML→JSON → compile → cache │ + │ │ 7. Reads body: io.ReadAll(request.Body) │ + │ │ 8. Re-seats body: request.Body = io.NopCloser(bytes.NewBuffer) │ + │ │ 9. Decodes JSON: json.Unmarshal into interface{} │ + │ │ 10. Validates decoded object against compiled schema │ + │ │ 11. Processes errors: locates violations in YAML node tree │ + │ └──────────────────────────────────────────────────────────────────┘ +``` + +### 3.3 Request Validation (GET / no body) + +``` +ValidateHttpRequest(request) + │ + ├── body == nil → ValidateHttpRequestSync + │ + │ ┌─── FindPath (same as above) ────────────────────────────────────┐ + │ └──────────────────────────────────────────────────────────────────┘ + │ + │ ┌─── Sequential Parameter Validation ─────────────────────────────┐ + │ │ for each of [PathParams, CookieParams, HeaderParams, │ + │ │ QueryParams, Security]: │ + │ │ valid, errs := validator(request, pathItem, pathValue) │ + │ │ │ + │ │ (Same redundant work as async, just sequential) │ + │ └──────────────────────────────────────────────────────────────────┘ + │ + │ ┌─── Body Validation (same as above, but body will be empty) ─────┐ + │ └──────────────────────────────────────────────────────────────────┘ +``` + +**Note**: The sync path still calls the body validator even for GET requests. +The body validator just returns `true, nil` when `operation.RequestBody == nil`. + +### 3.4 Response Validation + +``` +ValidateHttpResponse(request, response) + │ + ├── FindPath(request, ...) → PathItem, matchedPath + │ (identical call to request validation — same work) + │ + ├── ValidateResponseBodyWithPathItem(request, response, pathItem, matchedPath) + │ │ + │ ├── ExtractOperation(request, pathItem) → operation + │ ├── Match status code to spec (exact → range → default) + │ ├── Match content type to spec media types + │ ├── Validate response body schema (same flow as request body) + │ └── Validate response headers (if defined in spec) +``` + +### 3.5 Combined Request + Response Validation + +``` +ValidateHttpRequestResponse(request, response) + │ + ├── FindPath(request, ...) → PathItem, matchedPath + │ + ├── ValidateHttpRequestWithPathItem(request, pathItem, matchedPath) + │ └── (Full request validation: params + body, async or sync) + │ + ├── ValidateResponseBodyWithPathItem(request, response, pathItem, matchedPath) + │ └── (Full response validation: body + headers) + │ + └── Combines errors from both +``` + +**Good**: `ValidateHttpRequestResponse` calls `FindPath` once and passes the +result to both validators. This is one of the few places where derived state +is reused. + +--- + +## 4. The `validationFunction` Signature + +This is the type signature that every parameter validator must conform to: + +```go +type validationFunction func( + request *http.Request, + pathItem *v3.PathItem, + pathValue string, +) (bool, []*errors.ValidationError) +``` + +**This signature is the root cause of most redundant work.** Each validator receives +the raw `request`, the matched `PathItem`, and the matched path string — but no +pre-computed derived state. Every validator must independently: + +1. Extract the operation from the PathItem for the request's HTTP method +2. Extract the parameter list from the operation + path-level params +3. Filter to the relevant parameter type +4. Re-derive any path/URL information it needs + +There is no shared context object. There is no way to pass pre-computed results +between validators. + +--- + +## 5. Identified Inefficiencies + +### 5.1 Path Matching Runs Twice for Path Parameters + +| Step | Where | What | +|------|-------|------| +| 1 | `FindPath` → `comparePaths` | Regex-matches each path segment to find the matching PathItem | +| 2 | `ValidatePathParamsWithPathItem` | Re-regex-matches the same segments to extract parameter values | + +Both steps compile/load the same regex, match the same segments, and parse the +same brace indices. The only difference: Step 1 calls `MatchString` (boolean), +Step 2 calls `FindStringSubmatch` (captures groups). + +**Impact**: ~21 allocs/op wasted for a path with 2 parameters. + +### 5.2 `StripRequestPath` Called Twice + +| Where | Result | +|-------|--------| +| `FindPath` (line 36) | Strips base path, returns stripped path | +| `ValidatePathParamsWithPathItem` (line 46) | Strips base path again from scratch | + +Both calls parse server URLs, extract base paths, and strip them from the request +URL. The result from `FindPath` is not passed forward. + +**Impact**: ~5 allocs/op wasted (URL parsing, string operations). + +### 5.3 `ExtractParamsForOperation` Called 5 Times + +Every parameter validator calls `helpers.ExtractParamsForOperation(request, pathItem)`, +which does a method switch and appends path-level + operation-level parameters. +The result is identical each time. + +| Caller | Line | +|--------|------| +| `ValidatePathParamsWithPathItem` | path_parameters.go:50 | +| `ValidateQueryParamsWithPathItem` | query_parameters.go:52 | +| `ValidateHeaderParamsWithPathItem` | header_parameters.go:46 | +| `ValidateCookieParamsWithPathItem` | cookie_parameters.go:45 | +| `ValidateSecurityWithPathItem` | validate_security.go:46 (indirect) | + +**Impact**: ~5 × 2 allocs/op (slice creation + append) = ~10 allocs/op wasted. + +### 5.4 `ExtractOperation` Called Multiple Times + +| Caller | Purpose | +|--------|---------| +| `ValidateRequestBodyWithPathItem` | To find the request body schema | +| `ValidateResponseBodyWithPathItem` | To find the response schema | +| Each `WithPathItem` param validator (indirectly via `ExtractParamsForOperation`) | To find params | + +Same method switch, same result, called independently. + +### 5.5 Async Validation Channel Overhead + +For every POST/PUT/PATCH request, the async path creates: + +| Resource | Count | Purpose | +|----------|-------|---------| +| Goroutines | 9 | 1 orchestrator + 1 param wrapper + 1 param listener + 5 param validators + 1 body validator | +| Channels | 5 | `doneChan`, `errChan`, `controlChan`, `paramErrs`, `paramControlChan` + `paramFunctionControlChan` | +| Mutex | 1 | Inside `runValidation` for error collection | + +The 5 parameter validators (path, query, header, cookie, security) each run in +their own goroutine with their own channel signaling. For a typical request where +parameter validation takes microseconds, the goroutine scheduling and channel +send/receive overhead likely exceeds the actual validation cost. + +**Comparison**: The sync path (used for GET/no-body) runs the same 5 validators +sequentially and avoids all this overhead. The fast-path optimization (line 207) +already recognizes that sync is better for simple requests. + +### 5.6 Request and Response Body Validation Are ~95% Identical Code + +Compare `requests/validate_request.go` (362 lines) with `responses/validate_response.go` +(376 lines). The only differences: + +| Aspect | Request | Response | +|--------|---------|----------| +| Body source | `request.Body` | `response.Body` | +| Empty body | Error (if schema defined) | Success (no body is fine) | +| Error messages | "request body" | "response body" | +| Strict direction | `DirectionRequest` | `DirectionResponse` | + +The schema cache lookup, compilation, JSON decoding, schema validation, error +processing, and strict mode checking are copy-pasted between the two files. +Both even define their own `var instanceLocationRegex = regexp.MustCompile(...)`. + +**Impact**: Not a runtime cost, but a maintenance burden. A bug fix in one must +be duplicated in the other. + +### 5.7 `config.NewValidationOptions` Called Per Schema Validation + +Both `ValidateRequestSchema` and `ValidateResponseSchema` call +`config.NewValidationOptions(input.Options...)` on every invocation. This +creates a new `ValidationOptions`, a new `sync.Map` for `RegexCache`, and a new +`DefaultCache` for `SchemaCache` — then immediately overwrites them from the +`WithExistingOpts` option. + +```go +// validate_request.go:44 +validationOptions := config.NewValidationOptions(input.Options...) +``` + +The caller passes `config.WithExistingOpts(v.options)`, which copies the parent's +caches. But the default caches are still allocated then thrown away. + +### 5.8 Body Read + Re-seat Pattern + +```go +requestBody, _ = io.ReadAll(request.Body) +request.Body.Close() +request.Body = io.NopCloser(bytes.NewBuffer(requestBody)) +``` + +This pattern appears in both request and response body validators. It reads the +entire body into memory, closes the original reader, then wraps the bytes in a +new `NopCloser(NewBuffer(...))` so downstream code can re-read it. + +If `ValidateHttpRequestResponse` validates both request and response, the request +body is read once (by request validation), re-seated, then the bytes sit in memory +unused by response validation (which reads `response.Body` instead). This is fine, +but if multiple validators needed the same body, each would call `io.ReadAll` on +the re-seated reader — reading the same bytes repeatedly. + +### 5.9 `GoLow().Hash()` Called Multiple Times Per Schema + +The schema cache uses `schema.GoLow().Hash()` as its key. This hash: +- Traverses the low-level schema structure +- Creates ordered maps for deterministic key ordering +- Allocates ~7 objects per call + +It's called once for cache lookup, and if there's a cache miss, again for cache +storage. The perf investigation confirmed that caching the hash externally doesn't +work because libopenapi creates different pointer instances for the same logical +schema between warming and per-request validation. + +### 5.10 Standalone Sub-Validator Public APIs Call FindPath Independently + +Each sub-validator (`ParameterValidator`, `RequestBodyValidator`, +`ResponseBodyValidator`) has a "standalone" method that can be called directly: + +```go +// Called by users who want to validate just params: +paramValidator.ValidatePathParams(request) // calls FindPath internally +paramValidator.ValidateQueryParams(request) // calls FindPath again +requestBodyValidator.ValidateRequestBody(request) // calls FindPath again +responseBodyValidator.ValidateResponseBody(req, resp)// calls FindPath again +``` + +If a user calls these standalone methods individually, `FindPath` runs once per +call. The `WithPathItem` variants exist to avoid this, but they require the caller +to have already called `FindPath` themselves. + +--- + +## 6. Caching Architecture + +### 6.1 Two-Tier Model + +| Tier | Scope | Contents | Thread-safe | +|------|-------|----------|-------------| +| Validator-level | Persistent across requests | `SchemaCache`, `RegexCache`, `PathTree` | Yes (`sync.Map`) | +| Per-request | None exists | Nothing | N/A | + +There is no per-request cache or context object. Each validation phase starts from +scratch with only the raw `(request, pathItem, pathValue)` tuple. + +### 6.2 SchemaCache + +- **Key**: `uint64` from `schema.GoLow().Hash()` +- **Value**: `SchemaCacheEntry` containing rendered YAML, JSON, compiled schema, parsed YAML node +- **Populated**: During `warmSchemaCaches()` at init, or lazily on first access +- **Hit rate**: ~100% after warming (all schemas pre-compiled) +- **Issue**: Hash computation itself is expensive (~7 allocs) and uncacheable due to pointer instability + +### 6.3 RegexCache + +- **Key**: Path segment string (e.g., `"{ad_account_id}"`) +- **Value**: `*regexp.Regexp` +- **Populated**: During `warmRegexCache()` at init, or lazily in `comparePaths()` +- **Hit rate**: ~100% after warming +- **Pattern**: Every caller does the same nil-check-load-miss-compile-store dance + +### 6.4 PathTree (Radix) + +- **Lookup**: O(k) where k = path depth (typically 3-5 segments) +- **Handles**: Standard `{param}` paths +- **Doesn't handle**: Matrix (`{;param}`), label (`{.param}`), OData-style paths +- **Fallback**: Regex matching over all paths when radix misses + +--- + +## 7. Code Structure Issues + +### 7.1 Scattered Nil-Check Conditionals + +The "is this optimization available?" pattern appears everywhere: + +```go +// This pattern appears 10+ times across the codebase: +if options != nil && options.RegexCache != nil { + if cached, found := options.RegexCache.Load(key); found { + rgx = cached.(*regexp.Regexp) + } +} +if rgx == nil { + rgx, _ = helpers.GetRegexForPath(seg) + if options != nil && options.RegexCache != nil { + options.RegexCache.Store(seg, rgx) + } +} +``` + +### 7.2 Information Loss at Function Boundaries + +`FindPath` returns `(*v3.PathItem, []*errors.ValidationError, string)`. The string +is the matched path template. Everything else computed during matching — stripped +path, split segments, matched parameter values, specificity score, base paths — +is discarded. + +`ValidatePathParamsWithPathItem` receives `(request, pathItem, pathValue)` and must +re-derive the stripped path, split segments, and parameter values that `FindPath` +already computed. + +### 7.3 The `WithPathItem` Variant Explosion + +To support both "standalone" and "pre-resolved" calling patterns, nearly every +validator method exists in two forms: + +| Standalone (calls FindPath) | Pre-resolved (skips FindPath) | +|-----------------------------|-------------------------------| +| `ValidatePathParams` | `ValidatePathParamsWithPathItem` | +| `ValidateQueryParams` | `ValidateQueryParamsWithPathItem` | +| `ValidateHeaderParams` | `ValidateHeaderParamsWithPathItem` | +| `ValidateCookieParams` | `ValidateCookieParamsWithPathItem` | +| `ValidateSecurity` | `ValidateSecurityWithPathItem` | +| `ValidateRequestBody` | `ValidateRequestBodyWithPathItem` | +| `ValidateResponseBody` | `ValidateResponseBodyWithPathItem` | + +That's 14 methods where 7 would suffice if there were a shared context. + +--- + +## 8. Summary of Waste Per Request + +### GET request with 2 path params, 1 query param (sync path) + +| Wasted operation | Times | Est. allocs | +|-----------------|-------|-------------| +| `StripRequestPath` (redundant call) | 1 | ~5 | +| `ExtractParamsForOperation` (4 redundant calls) | 4 | ~8 | +| Path segment regex match (already done in FindPath) | 2 segments | ~9 | +| `BraceIndices` (already done in regex compilation) | 2 segments | ~4 | +| Path splitting (already done in FindPath) | 1 | ~2 | +| **Total estimated waste** | | **~28 allocs** | +| **Current measured total** | | **~115 allocs** | +| **Waste as % of total** | | **~24%** | + +### POST request with body (async path) + +All of the above waste, plus: + +| Overhead | Est. allocs | +|----------|-------------| +| 9 goroutines created + scheduled | ~18 | +| 5 channels created | ~5 | +| Channel send/receive operations | ~15 | +| Error sorting after completion | ~2 | +| **Additional async overhead** | **~40 allocs** | + +--- + +## 9. What a Redesign Should Address + +Based on this review, the key problems are: + +1. **No per-request shared state**: Each validator independently re-derives the same + information. A `RequestContext` carrying the match result, extracted parameters, + operation reference, and lazily-decoded body would eliminate ~24% of per-request + allocations. + +2. **Path matching discards parameter values**: The radix tree and regex matching + already visit every path segment. Extracting parameter values during this traversal + (instead of after) would eliminate the entire second regex pass in path parameter + validation. + +3. **Excessive goroutine/channel overhead for async validation**: 9 goroutines and 5 + channels for 6 validators is disproportionate. A `sync.WaitGroup` with a shared + error slice (or `errgroup`) would achieve the same concurrency with far less + overhead. Better yet, benchmarks should determine if async is even faster than + sync for typical payloads — the scheduling overhead may exceed the parallelism + benefit. + +4. **Copy-pasted request/response body validation**: Extracting the shared validation + logic into a single `validateBodySchema(body []byte, schema, version, direction)` + function would halve the maintenance surface and ensure bug fixes apply to both + paths. + +5. **The `validationFunction` signature forces redundant work**: Changing it from + `func(request, pathItem, pathValue)` to `func(*RequestContext)` would let + validators access pre-computed state instead of re-deriving it. + +6. **`NewValidationOptions` allocates throwaway caches**: The body validators create + default caches that are immediately overwritten by `WithExistingOpts`. Either + skip defaults when `WithExistingOpts` is provided, or pass the options directly + instead of re-creating them. + +7. **Dual API surface (`Standalone` + `WithPathItem`)**: With a `RequestContext`, + both collapse into a single method. The standalone variant just builds the context + first. + +--- + +## 10. Architecture Redesign Results + +### 10.1 What Changed (Phases 1-8) + +| Phase | Change | Primary Impact | +|-------|--------|----------------| +| 1 | `pathMatcher` interface + radix/regex chain + `operationForMethod` | O(k) path lookup, deduplicated method switches | +| 2 | `requestContext` + `buildRequestContext` + cached version float | Per-request shared state, eliminated redundant `VersionToFloat` calls | +| 3 | Thread `requestContext` through sync validation path | Sync validators access pre-computed state | +| 4 | Replace 9-goroutine/5-channel async with `sync.WaitGroup` | -33% latency for body-bearing requests | +| 5 | Regex matcher extracts path params | Both matchers populate `pathParams`, eliminating double regex pass | +| 6 | `WithLazyErrors()` option + `sync.Once` lazy resolution | Deferred `ReferenceSchema`/`ReferenceObject` population | +| 7 | Fix `LocateSchemaPropertyNodeByJSONPath` goroutine/channel; `ShouldIgnoreError` string checks; `GoLow().Hash()` caching | Per-error overhead reduction | +| 8 | `ValidateSchemaInput.Options` → `*ValidationOptions`; `WithExistingOpts` struct dereference | -6 allocs/op per body validation | + +### 10.2 Benchstat Comparison (Phase 0 Baseline → Phase 8 Final) + +Statistical comparison using `benchstat` with count=5 per benchmark. + +#### Latency (sec/op) + +| Benchmark | Before | After | Change | +|-----------|--------|-------|--------| +| BulkActions_Small (POST, 1 action) | 16.77µs | 16.00µs | **-4.81%** (p=0.016) | +| BulkActions_Large (POST, 50 actions) | 141.4µs | 135.2µs | **-4.56%** (p=0.008) | +| Petstore_AddPet (POST) | 16.40µs | 14.59µs | **-11.51%** (p=0.008) | +| BulkActions_Sync (POST, sync path) | 35.67µs | 23.83µs | **-33.33%** (p=0.008) | +| GET_Simple | 4.28µs | 4.60µs | +7.55% (p=0.008) | +| GET_WithQueryParams | 5.51µs | 5.69µs | +3.41% (p=0.016) | + +#### Allocations (allocs/op) + +| Benchmark | Before | After | Change | +|-----------|--------|-------|--------| +| BulkActions_Small | 250 | 242 | **-8** (-3.2%) | +| BulkActions_Medium | 644 | 636 | **-8** (-1.2%) | +| BulkActions_Large | 3,169 | 3,161 | **-8** (-0.3%) | +| Petstore_AddPet | 195 | 184 | **-11** (-5.6%) | +| BulkActions_Sync | 615 | 614 | **-1** | +| GET_Simple | 115 | 120 | +5 (+4.3%) | +| GET_WithQueryParams | 149 | 154 | +5 (+3.4%) | + +#### Memory (B/op) + +| Benchmark | Before | After | Change | +|-----------|--------|-------|--------| +| BulkActions_Small | 12.07 KiB | 11.11 KiB | **-5.7%** | +| Petstore_AddPet | 9.96 KiB | 8.96 KiB | **-10.1%** | +| ConcurrentValidation_BulkActions | 33.64 KiB | 32.17 KiB | **-2.1%** | +| GET_Simple | 4.57 KiB | 5.16 KiB | +12.8% | + +### 10.3 Analysis + +**POST/PUT/PATCH requests (body-bearing)** — Clear wins across the board: +- The sync validation path improved by **33%** thanks to `sync.WaitGroup` replacing the + 9-goroutine/5-channel choreography (Phase 4). +- Per-body-validation allocations dropped by **6-11 allocs/op** from options plumbing + (Phase 8), `GoLow().Hash()` caching (Phase 7), and `LocateSchemaPropertyNodeByJSONPath` + de-goroutining (Phase 7). +- Petstore AddPet (a typical single-schema POST) improved by **11.5% latency** and + **10.1% memory**. + +**GET requests (no body)** — Small regression (~5 allocs, +7.5% latency): +- The `pathMatcher` chain (Phase 1) and `requestContext` (Phase 2-3) add a small + per-request overhead for path matching and context construction. +- This is an acceptable tradeoff: the infrastructure enables all the body-bearing + improvements and provides a foundation for further optimization (e.g., caching + `basePaths` at init, pre-splitting path segments). + +**New capabilities added** (no baseline comparison possible): +- `WithLazyErrors()` option for deferred error field population (Phase 6) +- `ShouldIgnoreError()` / `ShouldIgnorePolyError()` string-based checks replacing regex (Phase 7) +- `GetReferenceSchema()` / `GetReferenceObject()` thread-safe lazy getters (Phase 6) + +### 10.4 Remaining Opportunities + +These were identified but deferred to keep the redesign focused: + +1. **Cache `basePaths` at init** — `getBasePaths(document)` parses server URLs on every + `StripRequestPath` call. Computing once at init would save ~5 allocs/op for GET requests. +2. **Pre-split path segments** — If the matched path template is known, pre-split its + segments once rather than per-request. +3. **Full body validation unification** — Phase 7 fixed per-error overhead but deferred + extracting the shared body validation loop into a single function. The ~95% code + duplication between `requests/validate_request.go` and `responses/validate_response.go` + remains a maintenance concern. +4. **`ValidateSchemaInput` consolidation** — Request and response schema input structs + could be merged into a single type with a `Direction` field. diff --git a/docs/bulk-action-ifthen-findings.md b/docs/bulk-action-ifthen-findings.md new file mode 100644 index 00000000..39f73d6e --- /dev/null +++ b/docs/bulk-action-ifthen-findings.md @@ -0,0 +1,159 @@ +# BulkAction Schema: oneOf to if/then Migration + +## Problem + +The BulkAction schema uses `oneOf` with 5 branches (CAMPAIGN, AD_GROUP, AD, POST, ASSET). +JSON Schema `oneOf` validates the input against **every** branch to determine which one matches. +This means a single bulk action item triggers 5 full schema validations even though only one can match. + +This has two consequences: +1. **Performance**: validation does 5x the work needed on every request. +2. **Error noise**: when validation fails, errors from all 5 branches are returned — most of which are irrelevant. + +## Change + +Replace `oneOf` in `components_schema_bulk_actions_bulk_action.yaml` with `allOf` + `if/then` keyed on the `type` field. + +Before: + +```yaml +title: Bulk Action +oneOf: + - $ref: "components_schema_bulk_actions__campaign_action.yaml" + - $ref: "components_schema_bulk_actions__ad_group_action.yaml" + - $ref: "components_schema_bulk_actions__ad_action.yaml" + - $ref: "components_schema_bulk_actions__post_action.yaml" + - $ref: components_schema_bulk_actions__asset_action.yaml +``` + +After: + +```yaml +title: Bulk Action +type: object +additionalProperties: false +required: [type, action, entity_data] +properties: + type: + $ref: components_enums_bulk_actions_entity_type.yaml + action: + $ref: components_enums_bulk_actions_action_type.yaml + reference_id: + type: string + entity_data: {} +allOf: + - if: { required: [type], properties: { type: { const: CAMPAIGN } } } + then: { properties: { entity_data: { anyOf: [{ $ref: components_schema_campaign.yaml }, { type: object, additionalProperties: true }] } } } + - if: { required: [type], properties: { type: { const: AD_GROUP } } } + then: { properties: { entity_data: { anyOf: [{ $ref: components_schema_ad_group.yaml }, { type: object, additionalProperties: true }] } } } + # ... AD, POST, ASSET follow the same pattern +``` + +Only `bulk_action.yaml` changes. The individual action type schemas are untouched. + +## Benchmark Results + +Tested against the full production `complete.yaml` (68k lines, ~200 endpoints). +Apple M4 Max, `go test -bench=BenchmarkProd -benchmem -count=3`. + +### BulkActions Validation + +| Benchmark | oneOf ns/op | if/then ns/op | Speedup | oneOf B/op | if/then B/op | Mem Reduction | +|---|---|---|---|---|---|---| +| SingleCampaign | 25,560 | 21,070 | 1.2x | 17,498 | 13,072 | -25% | +| Mixed (3 items) | 51,770 | 40,320 | 1.3x | 53,129 | 38,538 | -27% | +| Large (15 items) | 177,460 | 128,300 | 1.4x | 244,602 | 172,368 | -30% | +| Invalid: missing field | 81,460 | 21,400 | **3.8x** | 87,740 | 17,687 | **-80%** | +| Invalid: wrong type | 123,080 | 24,550 | **5.0x** | 141,487 | 20,313 | **-86%** | +| Invalid: extra field | 151,340 | 28,540 | **5.3x** | 173,099 | 19,714 | **-89%** | +| Sync | 35,980 | 26,540 | 1.4x | 51,692 | 37,025 | -28% | +| Async | 50,200 | 41,200 | 1.2x | 53,147 | 38,538 | -27% | +| Concurrent | 10,960 | 8,120 | 1.3x | 53,138 | 38,535 | -27% | + +### Geomean (all benchmarks) + +| Metric | Improvement | +|---|---| +| Time (ns/op) | **-31%** | +| Memory (B/op) | **-37%** | +| Allocations | **-38%** | + +### Non-BulkAction endpoints + +GET endpoints (campaigns, ad groups, ads, /me) were unchanged or slightly faster (~5-6% less memory). Init time was the same (~2.7s). + +### Why invalid payloads improve the most + +With `oneOf`, an invalid payload fails validation against all 5 branches, and the library collects errors from each one. With `if/then`, only the matching branch is evaluated — if `type=CAMPAIGN`, the AD_GROUP/AD/POST/ASSET branches are never touched. + +## Error Quality + +Tested against the production `complete.yaml` with both schemas. All tests use the `/api/v3/ad_accounts/{id}/bulk_actions` POST endpoint. + +### Missing entity_data + +**oneOf** — 9 schema errors: + +``` +schema[1] reason: missing property 'entity_data' (oneOf/0 - Campaign) +schema[2] reason: missing property 'entity_data' (oneOf/1 - AdGroup) +schema[3] reason: value must be 'AD_GROUP' (noise) +schema[4] reason: missing property 'entity_data' (oneOf/2 - Ad) +schema[5] reason: value must be 'AD' (noise) +schema[6] reason: missing property 'entity_data' (oneOf/3 - Post) +schema[7] reason: value must be 'POST' (noise) +schema[8] reason: missing property 'entity_data' (oneOf/4 - Asset) +schema[9] reason: value must be 'ASSET' (noise) +``` + +**if/then** — 1 schema error: + +``` +schema[1] reason: missing property 'entity_data' + location: /properties/data/items/required + fieldPath: $.data[0] +``` + +### Invalid type "BANANA" + +**oneOf** — 11 schema errors: "value must be 'CAMPAIGN'", "value must be 'AD_GROUP'", etc. from each branch, plus cascading errors from ASSET/POST entity_data schemas that don't apply. + +**if/then** — 1 schema error: + +``` +schema[1] reason: value must be one of 'CAMPAIGN', 'AD_GROUP', 'AD', 'POST', 'ASSET' + location: /properties/data/items/properties/type/enum + fieldPath: $.data[0].type +``` + +### Extra field (additionalProperties: false) + +**oneOf** — 11 schema errors: "additional properties not allowed" repeated 5 times (once per branch), plus "value must be 'AD_GROUP'" etc. for every non-matching branch. + +**if/then** — 1 schema error: + +``` +schema[1] reason: additional properties 'this_field_does_not_exist' not allowed + location: /properties/data/items/additionalProperties + fieldPath: $.data[0] +``` + +### POST with action=EDIT (only CREATE allowed) + +**oneOf** — 28 schema errors: errors from all 5 branches including CAMPAIGN, AD_GROUP, AD, ASSET — none relevant since type=POST. + +**if/then** — 18 schema errors: `value must be 'CREATE'` once at `$.data[0].action`, plus errors from the POST branch's inner `creative` oneOf (which still uses oneOf in both specs — a candidate for the same treatment). + +### Invalid objective enum + +Both return valid with 0 errors. The `entity_data` for CAMPAIGN uses `anyOf` (strict schema OR permissive object), so bad fields in entity_data pass through the permissive branch. Same behavior either way — not a regression. + +## Summary + +- **Only 1 file changed** in the OpenAPI source: `components_schema_bulk_actions_bulk_action.yaml` +- **1.2-5.3x faster**, biggest gains on invalid payloads (the most common case in production) +- **25-89% less memory** per validation +- **Dramatically fewer error messages** with better signal-to-noise ratio +- **No functional regressions**: all existing valid/invalid test payloads behave identically +- **No init time penalty**: spec compilation takes the same ~2.7s +- The structured_post `creative` field still uses `oneOf` internally — applying the same if/then pattern there would yield further improvements diff --git a/docs/perf-investigation-2026-02-06.md b/docs/perf-investigation-2026-02-06.md new file mode 100644 index 00000000..823bf4f5 --- /dev/null +++ b/docs/perf-investigation-2026-02-06.md @@ -0,0 +1,76 @@ +# Performance Investigation: Per-Request Allocations + +**Date:** 2026-02-06 +**Branch:** `default-regex-cache` +**Benchmark spec:** `test_specs/ads_api_bulk_actions.yaml` (~25 endpoints) + +## Baseline + +| Benchmark | ns/op | B/op | allocs/op | +|---|---|---|---| +| GET (no body) | 4,580 | 4,680 | 115 | +| GET (query params) | 5,638 | 6,074 | 149 | +| POST small | 17,020 | 12,058 | 250 | +| POST medium | 35,940 | 33,642 | 644 | +| POST large | 138,900 | 188,610 | 3,169 | +| Radix path match | 167–245 | 192–256 | 4 | +| Regex fallback | 2,446–6,335 | 3,272–5,736 | 64–140 | + +## Profile: GET Request Allocation Breakdown + +Clean profile (`-run='^$'`, excludes init and tests). Top flat allocators per operation: + +| Function | allocs/op | % | Location | +|---|---|---|---| +| `ValidatePathParamsWithPathItem` | ~12 | 10% | `parameters/path_parameters.go` | +| `jsonschema.(*Schema).validate` | ~10 | 9% | external: santhosh-tekuri/jsonschema | +| `formatJsonSchemaValidationError` | ~10 | 9% | `parameters/validate_parameter.go` | +| `regexp.FindStringSubmatch` | ~9 | 8% | stdlib (path param matching) | +| `Schema.hash()` | ~7 | 6% | external: pb33f/libopenapi | +| `fmt.Sprintf` | ~5 | 4% | stdlib | +| `kind.(*Pattern).LocalizedString` | ~4 | 3% | external: santhosh-tekuri/jsonschema | +| `ExtractParamsForOperation` | ~4 | 3% | `helpers/parameter_utilities.go` | +| ~50 other functions | ~54 | 47% | spread across validation pipeline | + +## Key Findings + +### 1. YAML rendering is init-only, not per-request + +The `yaml.(*Emitter).Emit` at 22.71% in the full profile is from `warmMediaTypeSchema` (init). Confirmed via `-peek`: + +``` +16076.96MB 99.69% | warmMediaTypeSchema + 50.13MB 0.31% | warmParameterSchema +``` + +The schema cache works correctly. No per-request YAML rendering occurs. + +### 2. `Schema.GoLow().Hash()` is expensive but uncacheable + +Hash computation allocates ~7 objects per call (ordered map creation for sorting). Attempted to cache hash values indexed by schema pointer, but **libopenapi creates different `*low.Schema` instances** between cache warming and per-request validation. Verified with debug logging: STORE and LOAD use different pointers for the same logical schema. + +### 3. Benchmark GET request produces validation errors + +Path parameters `acc_12345` / `camp_67890` fail pattern validation, causing `formatJsonSchemaValidationError` to run (~10 allocs/op). Production requests with valid params would skip this cost. + +### 4. No single bottleneck dominates + +Allocations are distributed across ~50 functions. The largest single contributor (`ValidatePathParamsWithPathItem` at 12 flat allocs) is mostly dispatch overhead. Most allocations come from external libraries (jsonschema, libopenapi) that we don't control. + +## Attempted Fixes + +| Approach | Result | Reason | +|---|---|---| +| Pre-allocate slices, early returns, `strings.Builder` | +2 allocs (regression) | Pre-allocation overhead > savings when no errors | +| Cache hash by `*base.Schema` pointer | 0 change | High-level schema pointers differ between warming and validation | +| Cache hash by `*low.Schema` pointer | 0 change | Low-level schema pointers also differ (confirmed via debug) | + +## Recommended Next Steps + +1. **Upstream libopenapi**: File issue/PR to either cache `Hash()` results internally or guarantee `GoLow()` pointer stability. Would save ~7 allocs/op (6%). + +2. **Structural refactoring** (medium effort): Extract parameters once per request and pass pre-resolved cache entries keyed by `*v3.Parameter` pointer (stable between warming and validation). Requires changing internal function signatures across ~6 files. Expected savings: ~11 allocs/op (10%). + +3. **Regex fallback optimization** (separate PR): Already proven at 14–26x improvement when radix tree misses. Only affects fallback path, but eliminates 60–136 unnecessary allocs when triggered. + +4. **Benchmark with valid params**: Current GET benchmark inflates allocs by ~10/op due to pattern validation failures. Using valid param values would give a more representative production baseline. diff --git a/docs/plans/architecture_redesign.md b/docs/plans/architecture_redesign.md new file mode 100644 index 00000000..c4fb5200 --- /dev/null +++ b/docs/plans/architecture_redesign.md @@ -0,0 +1,527 @@ +--- +name: Validator Architecture Redesign +overview: Iterative internal refactoring of libopenapi-validator to eliminate redundant per-request work (~24% of allocations), simplify the async validation path, unify duplicated code, fix options/cache plumbing ergonomics, and add opt-in lazy error resolution — all while preserving the existing public API and using the existing 1,159 tests as a safety net. +todos: + - id: phase-0 + content: "Phase 0: Create branch, Makefile, capture baseline benchmarks" + status: pending + - id: phase-1 + content: "Phase 1: pathMatcher interface + radix/regex matchers + matcherChain + operationForMethod consolidation" + status: pending + - id: phase-2 + content: "Phase 2: resolvedRoute + requestContext types + buildRequestContext + cached version float" + status: pending + - id: phase-3 + content: "Phase 3: Thread requestContext through sync validation path" + status: pending + - id: phase-4 + content: "Phase 4: Thread requestContext through async path + simplify channels" + status: pending + - id: phase-5 + content: "Phase 5: Regex matcher extracts path params into resolvedRoute" + status: pending + - id: phase-6 + content: "Phase 6: Lazy error schema resolution (WithLazyErrors option) + json.Marshal improvements" + status: pending + - id: phase-7 + content: "Phase 7: Unify request/response body validation + shared error loop + LocateSchema fix + IgnoreRegex to string checks" + status: pending + - id: phase-8 + content: "Phase 8: Options plumbing (ValidateSchemaInput type change, WithExistingOpts struct copy, NewValidationOptions lazy alloc, base paths, segments)" + status: pending + - id: phase-9 + content: "Phase 9: Final benchmarks, documentation, PR summary" + status: pending +isProject: false +--- + +# Validator Architecture Redesign + +## Guiding Principles + +- **Backward compatible by default.** The `Validator`, `ParameterValidator`, `RequestBodyValidator`, and `ResponseBodyValidator` interfaces stay as-is. The `WithPathItem` method variants remain functional (as thin adapters over the new internals). New capabilities are opt-in via functional options. +- **Every phase is a commit.** Each commit must leave the tree green (tests pass, benchmarks no worse). +- **The unexported `validationFunction` type can change freely** — it is internal to `validator.go` and not part of the public API. +- **The unexported structs (`paramValidator`, `requestBodyValidator`, `responseBodyValidator`) can gain new internal methods freely** — only the interface methods are public. +- **The `PathLookup` interface is in PR and not released** — we can freely modify it. + +## Things to Watch Out For + +- **Race conditions**: When we change the async path, we must run tests with `-race`. The current channel-heavy approach is race-safe by design; a simpler approach must be equally safe. +- **Both matchers must produce `resolvedRoute`**: The `requestContext` must work for both radix-matched and regex-fallback-matched paths. Both matchers populate the same result type. +- **Response validation**: `ValidateHttpResponse` calls `FindPath` too. It should benefit from the same `resolvedRoute` infrastructure even though it doesn't do parameter validation. +- **`ValidateHttpRequestResponse`**: Already calls `FindPath` once and reuses the result. Our refactoring must not regress this. +- **golangci-lint**: The repo has a `.golangci.yml`. We should run it as part of our checks. + +--- + +## Identified Issues + +This section catalogs all issues found during the architecture review and final audit. Each issue is tagged with the phase that addresses it. + +### Cache/Options Ergonomics + +#### The allocate-then-discard problem *(Phase 8)* + +Every call to `NewValidationOptions()` eagerly allocates two objects that get thrown away when `WithExistingOpts` overwrites them: + +```go +// config.go:52-58 — allocates defaults that get immediately discarded +o := &ValidationOptions{ + SchemaCache: cache.NewDefaultCache(), // allocs: DefaultCache + sync.Map + RegexCache: &sync.Map{}, // alloc: sync.Map +} +``` + +This happens on **every request body validation** (not just init), because `ValidateRequestSchema` (line 45) and `ValidateResponseSchema` (line 49) both call `config.NewValidationOptions(input.Options...)`, where `input.Options` is `[]config.Option{config.WithExistingOpts(v.options)}`. + +**Per-request waste**: 2 heap allocations (DefaultCache + sync.Map for SchemaCache, 1 sync.Map for RegexCache) created then immediately garbage-collected. For a POST request that validates both request and response body, that is 4 wasted allocations per request. + +**Fix (two-part)**: + +1. Change `ValidateRequestSchemaInput.Options` and `ValidateResponseSchemaInput.Options` from `[]config.Option` to `*config.ValidationOptions` so callers pass the options struct directly instead of wrapping in a closure. This eliminates the reconstruction entirely. +2. As a safety net, make `NewValidationOptions` not allocate caches when it detects options will be applied (or defer allocation with a lazy init pattern). + +#### `WithExistingOpts` is a fragile field-by-field copy *(Phase 8)* + +`config.go:70-91` — every new field added to `ValidationOptions` must be manually added to `WithExistingOpts` or it silently gets lost. This is a maintenance trap. + +**Fix**: Replace field-by-field copy with struct dereference: `*o = *options`, then re-apply any overrides from additional opts. + +### Per-Request Redundancy + +#### Path matching runs twice *(Phase 1, 2, 3)* + +The validator first matches the request path to a PathItem (via regex or radix tree), then later re-runs similar regex matching to extract path parameter values. The `resolvedRoute` + `requestContext` approach extracts path params during the initial match. + +#### `ExtractParamsForOperation` called 5 times per request *(Phase 2, 3)* + +Each parameter validator independently calls `ExtractParamsForOperation`, which switches on HTTP method to find the operation, then iterates its parameters. The `requestContext` extracts parameters once and shares them. + +#### `ExtractOperation` called multiple times *(Phase 1, 2)* + +Multiple code paths independently resolve the operation from the PathItem + HTTP method. The `resolvedRoute` can carry the resolved operation. + +#### `StripRequestPath` called twice *(Phase 2)* + +The request path is stripped of its base path in multiple places. The `requestContext` strips once and caches the result. + +### Code Duplication + +#### Four identical HTTP method switch statements *(Phase 1)* + +- `helpers/operation_utilities.go:16-34` — `ExtractOperation` +- `helpers/parameter_utilities.go:31-64` — `ExtractParamsForOperation` +- `helpers/parameter_utilities.go:71-104` — `ExtractSecurityForOperation` +- `paths/specificity.go:56-74` — `pathHasMethod` + +All switch on HTTP method with the same 8 cases (GET, POST, PUT, DELETE, OPTIONS, HEAD, PATCH, TRACE). + +**Fix**: Create a single `operationForMethod(method string, pathItem *v3.PathItem) *v3.Operation` that returns the operation pointer. All four functions delegate to it. + +#### Duplicated error processing loop *(Phase 7)* + +`validate_request.go:240-321` and `validate_response.go:258-335` — These ~80-line blocks are ~95% identical. They iterate schema errors, call `LocateSchemaPropertyNodeByJSONPath`, check `IgnoreRegex`, extract `instanceLocation`, build `SchemaValidationFailure`, call `json.MarshalIndent`, etc. Also, `var instanceLocationRegex = regexp.MustCompile(...)` is defined identically in both files. + +#### ~95% identical request/response body validation *(Phase 7)* + +`requests/validate_request.go` (362 lines) and `responses/validate_response.go` (376 lines) share nearly all logic: cache lookup, cache-miss compilation, JSON decoding, schema validation, error processing, strict mode. + +### Per-Error Overhead + +#### `LocateSchemaPropertyNodeByJSONPath` spawns a goroutine per error *(Phase 7)* + +`schema_validation/locate_schema_property.go:14-42` — Creates 2 channels and spawns a goroutine just for panic recovery on every schema validation error. This adds goroutine scheduling overhead and heap escapes for the channel allocations. + +**Fix**: Replace with a plain function that uses `defer/recover` without goroutines: + +```go +func LocateSchemaPropertyNodeByJSONPath(doc *yaml.Node, JSONPath string) (result *yaml.Node) { + defer func() { recover() }() + _, path := utils.ConvertComponentIdIntoFriendlyPathSearch(JSONPath) + if path == "" { return nil } + jp, _ := jsonpath.NewPath(path) + nodes := jp.Query(doc) + if len(nodes) > 0 { return nodes[0] } + return nil +} +``` + +#### `IgnoreRegex` runs a regex match on every error message *(Phase 7)* + +`helpers/ignore_regex.go` — Pattern: `^'?(anyOf|allOf|oneOf|validation)'? failed(, none matched)?$`. This runs for every schema error across 4 call sites. + +**Fix**: Replace with string suffix checks. The errors are short and well-known — a simple `strings.HasSuffix` or small set of exact-match comparisons is sufficient. + +#### `json.MarshalIndent` called per error for `ReferenceObject` *(Phase 6)* + +`validate_request.go:261` and `validate_response.go:277` — Pretty-prints a potentially large JSON object per error for the `ReferenceObject` field. + +**Fix**: In lazy mode (Phase 6), defer entirely. In eager mode, use `json.Marshal` (no indent) to reduce formatting overhead. + +#### `GoLow().Hash()` called multiple times for same schema *(Phase 7)* + +In `validate_parameter.go`, `Hash()` is called at line 43 (cache check) and again at line 66 (cache store on miss). Same pattern in `validate_request.go` and `validate_response.go`. `GoLow().Hash()` traverses the low-level schema AST each time. + +**Fix**: Store hash in a local variable and reuse it across the check/store boundary. + +### Minor Inefficiencies + +#### `VersionToFloat` called per body validation *(Phase 2)* + +`requests/validate_body.go:86` and `responses/validate_body.go:147` — Calls `helpers.VersionToFloat(v.document.Version)` on every validation. The version is constant per document. + +**Fix**: Cache the computed `float32` version on the sub-validator struct at construction time. + +#### Async validation channel overhead *(Phase 4)* + +The current async path for POST/PUT/PATCH uses 9 goroutines and 5 channels to orchestrate 6 validation functions. This is significant overhead for what is essentially "run N things concurrently, collect errors." + +#### Strict mode re-walks the schema tree *(Future)* + +`strict/schema_walker.go` recursively traverses the entire schema after base JSON Schema validation already traversed it. Out of scope for the current redesign but worth noting as a future optimization target. + +--- + +## Phase 0: Baseline and Safety Net + +**Goal**: Establish a reproducible test + benchmark baseline so we can verify every subsequent phase. + +**Work**: + +1. Create a new branch `refactor/request-context` from the current HEAD. +2. Add a `Makefile` with targets: + - `make test` — runs `go test ./... -count=1 -race` (all 1,159 tests with race detector) + - `make test-short` — runs `go test ./... -count=1 -short` (faster iteration) + - `make lint` — runs `golangci-lint run` + - `make bench-fast` — runs the fast benchmark suite (excludes init + prod benchmarks) + - `make bench-baseline` — runs fast suite with `-count=5` and saves to `benchmarks/results/baseline.txt` + - `make bench-compare` — runs fast suite with `-count=5`, saves to `benchmarks/results/current.txt`, runs `benchstat baseline.txt current.txt` +3. Run `make test` and `make bench-baseline` to capture the starting point. +4. Commit: *"Add Makefile with test, lint, and benchmark targets; save baseline"* + +--- + +## Phase 1: `pathMatcher` Interface + Radix/Regex Matchers + Matcher Chain + +**Goal**: Replace the hardcoded `if radixTree != nil { ... } // fallback to regex` pattern in `FindPath` with a composable chain of matchers that share a common interface. Also consolidate the 4 duplicated HTTP method switch statements into a single helper. + +**Files changed**: New file `path_matcher.go` (root package, unexported), `helpers/operation_utilities.go`, `radix/tree.go`, `radix/path_tree.go`, `paths/paths.go` + +**Work**: + +1. **Consolidate HTTP method switches.** Create a single `operationForMethod(method string, pathItem *v3.PathItem) *v3.Operation` helper that returns the operation pointer for a given HTTP method. Refactor `ExtractOperation`, `ExtractParamsForOperation`, `ExtractSecurityForOperation`, and `pathHasMethod` to delegate to it. +2. Define the internal `pathMatcher` interface and `resolvedRoute` type: + ```go + // pathMatcher finds the matching path for an incoming request path. + // Implementations are composed into a chain — first match wins. + type pathMatcher interface { + Match(path string, doc *v3.Document) *resolvedRoute + } + + // resolvedRoute carries everything learned during path matching. + // This is the single source of truth for "what matched and what was extracted." + type resolvedRoute struct { + pathItem *v3.PathItem + matchedPath string // path template, e.g. "/users/{id}" + pathParams map[string]string // extracted param values, nil if not extracted + operation *v3.Operation // resolved from pathItem + HTTP method (nil until resolved) + } + + // matcherChain tries each matcher in order. First match wins. + type matcherChain []pathMatcher + + func (c matcherChain) Match(path string, doc *v3.Document) *resolvedRoute { + for _, m := range c { + if result := m.Match(path, doc); result != nil { + return result + } + } + return nil + } + ``` +3. Add `LookupWithParams` to `Tree[T]` in `radix/tree.go`: + - During `lookupRecursive`, when a `paramChild` matches, record `paramName -> segment` in a map. + - Only allocate the map when the first param segment is encountered. + - Add to `PathTree` and the `PathLookup` interface (interface is unreleased, safe to change). +4. Implement `radixMatcher` — wraps `PathLookup.LookupWithParams`, returns `resolvedRoute` with `pathParams` populated. +5. Implement `regexMatcher` — wraps the current `comparePaths` + `selectMatches` logic from `FindPath`. For now, does NOT extract path params (that comes in Phase 5). Returns `resolvedRoute` with `pathParams = nil`. +6. During `NewValidatorFromV3Model`, build the default chain `[radixMatcher, regexMatcher]` and store it on the `validator` struct. +7. Wire the chain into `FindPath` (or a new internal `resolvePath` method) so it replaces the current if/else logic. +8. Add tests for the chain, individual matchers, `LookupWithParams`, and `operationForMethod`. +9. Run `make test && make bench-compare` — expect no regression (same logic, cleaner structure). +10. Commit: *"validator: introduce pathMatcher chain with radix and regex matchers; consolidate operationForMethod"* + +**Future**: Export `pathMatcher` as `PathMatcher`, add `WithPathMatchers(...)` option so users can inject static route matchers, rewriters, etc. Deferred until internals are proven. + +--- + +## Phase 2: Define `requestContext` + `buildRequestContext` + +**Goal**: Define the internal per-request context type and the function that builds it. Also cache the document version float at init time. No behavioral changes yet — just the plumbing. + +**Files changed**: New file `request_context.go` (root package, unexported types), `requests/request_body.go`, `responses/response_body.go` + +**Work**: + +1. **Cache `VersionToFloat` at init time.** Add a `version float32` field to the sub-validator structs (`requestBodyValidator`, `responseBodyValidator`). Compute `helpers.VersionToFloat(document.Version)` once during construction and store it. Replace the per-request `helpers.VersionToFloat(v.document.Version)` calls in `validate_body.go` with `v.version`. +2. Define `requestContext`: + ```go + // requestContext is per-request shared state that flows through the entire + // validation pipeline. Created once per request, shared by all validators. + type requestContext struct { + request *http.Request + route *resolvedRoute + operation *v3.Operation + parameters []*v3.Parameter // path + operation params, extracted once + security []*base.SecurityRequirement + stripped string // request path with base path removed + segments []string // pre-split path segments + version float32 // cached OAS version (3.0 or 3.1) + } + ``` +3. Add a `buildRequestContext` method on `validator`: + - Strips the request path (once). + - Calls `matcherChain.Match(stripped, doc)` to get a `resolvedRoute`. + - Resolves the operation from `pathItem + HTTP method` using `operationForMethod`. + - Extracts parameters from `pathItem + operation` (once). + - Extracts security requirements (once). + - Returns `(*requestContext, []*errors.ValidationError)` — errors for path-not-found or method-not-found. +4. Tests: Unit tests for `buildRequestContext` with various request types. +5. Run `make test` — nothing calls `buildRequestContext` yet, tree stays green. +6. Commit: *"validator: define requestContext and buildRequestContext; cache version float"* + +--- + +## Phase 3: Thread `requestContext` Through the Sync Path + +**Goal**: Eliminate redundant work in the sync validation path (GET/HEAD/OPTIONS/DELETE). First measurable improvement. + +**Files changed**: `validator.go`, `parameters/path_parameters.go`, `parameters/query_parameters.go`, `parameters/header_parameters.go`, `parameters/cookie_parameters.go`, `parameters/validate_security.go` + +**Work**: + +1. Change the unexported `validationFunction` type to: + ```go + type validationFunction func(ctx *requestContext) (bool, []*errors.ValidationError) + ``` +2. Add internal methods on `paramValidator` that accept `*requestContext`: + - `validatePathParamsCtx(ctx)` — uses `ctx.route.pathParams` for the fast path (map lookup), falls back to regex for complex params (matrix/label). + - `validateQueryParamsCtx(ctx)` — uses `ctx.parameters` instead of calling `ExtractParamsForOperation`. + - `validateHeaderParamsCtx(ctx)` — same. + - `validateCookieParamsCtx(ctx)` — same. + - `validateSecurityCtx(ctx)` — uses `ctx.security`. +3. Keep the public `WithPathItem` methods as adapters: they construct a partial `requestContext` from their arguments and delegate to the `Ctx` methods. +4. Modify `ValidateHttpRequestSync` to call `buildRequestContext` once, then pass the context to the new internal methods sequentially. +5. Run `make test && make bench-compare`. Expected: GET benchmarks improve (fewer allocs), POST unchanged (still async). +6. Commit: *"validator: thread requestContext through sync validation path"* + +--- + +## Phase 4: Thread `requestContext` Through the Async Path + Simplify Channels + +**Goal**: Apply context-sharing to POST/PUT/PATCH requests AND replace the 9-goroutine/5-channel choreography with `sync.WaitGroup`. + +**Files changed**: `validator.go` + +**Work**: + +1. Replace the current async implementation with: + ```go + func (v *validator) validateWithContext(ctx *requestContext) (bool, []*errors.ValidationError) { + var mu sync.Mutex + var wg sync.WaitGroup + var allErrors []*errors.ValidationError + + validators := []validationFunction{ + v.paramValidator.validatePathParamsCtx, + v.paramValidator.validateQueryParamsCtx, + v.paramValidator.validateHeaderParamsCtx, + v.paramValidator.validateCookieParamsCtx, + v.paramValidator.validateSecurityCtx, + v.requestValidator.validateBodyCtx, + } + + wg.Add(len(validators)) + for _, fn := range validators { + go func(validate validationFunction) { + defer wg.Done() + if valid, errs := validate(ctx); !valid { + mu.Lock() + allErrors = append(allErrors, errs...) + mu.Unlock() + } + }(fn) + } + wg.Wait() + sortValidationErrors(allErrors) + return len(allErrors) == 0, allErrors + } + ``` +2. Body validation also needs a `validateBodyCtx` internal method. +3. Benchmark sync vs async for typical POST payloads. If sync is within 5% of async, consider using sync for all requests (massive simplification). Data-driven decision. +4. Run `make test -race && make bench-compare`. Expected: POST benchmarks improve. +5. Commit: *"validator: simplify async validation with WaitGroup, thread requestContext"* + +--- + +## Phase 5: Regex Matcher Extracts Path Params + +**Goal**: The radix matcher already populates `resolvedRoute.pathParams` (Phase 1). Make the regex matcher also extract params, so path parameter validation uses the fast path regardless of which matcher hit. + +**Files changed**: `path_matcher.go` (the `regexMatcher` implementation) + +**Work**: + +1. In the regex matcher, after `comparePaths` finds a match, use `FindStringSubmatch` (instead of just `MatchString`) and `BraceIndices` to extract param name-value pairs from the regex groups. +2. Populate `resolvedRoute.pathParams` in the regex matcher's `Match` method. +3. Run `make test && make bench-compare`. Expected: regex-fallback path benchmarks improve. +4. Commit: *"validator: regex matcher extracts path params into resolvedRoute"* + +--- + +## Phase 6: Lazy Error Schema Resolution (`WithLazyErrors`) + +**Goal**: Reduce allocation overhead when creating validation errors by deferring the expensive `ReferenceSchema` and `ReferenceObject` population until the consumer actually needs them. + +**Files changed**: `errors/validation_error.go`, `requests/validate_request.go`, `responses/validate_response.go`, `config/config.go` + +**Approach**: Opt-in via `WithLazyErrors()`. Default behavior is unchanged (eager population, full backward compatibility). When enabled, `ReferenceSchema` and `ReferenceObject` fields are left empty, and the consumer calls getter methods to resolve them on demand. + +**Work**: + +1. Add `WithLazyErrors()` option to `config.go`: + ```go + LazyErrors bool // When true, defer expensive error field population + ``` +2. Add a private `schemaRef` field to `SchemaValidationFailure` that holds a pointer to the `SchemaCacheEntry` (for schema) and the decoded object + instance location (for reference object). +3. Add `GetReferenceSchema() string` and `GetReferenceObject() string` methods on `SchemaValidationFailure`: + - If `ReferenceSchema` is already populated (eager mode), return it directly. + - If lazy mode, resolve from `schemaRef` on first call, cache the result in the field. +4. Mark `ReferenceSchema` and `ReferenceObject` fields with `// Deprecated: Use GetReferenceSchema() / GetReferenceObject() instead.` +5. **Even in eager (non-lazy) mode**, use `json.Marshal` instead of `json.MarshalIndent` for `ReferenceObject` to reduce formatting overhead per error. +6. When `LazyErrors` is enabled, skip the `json.Marshal` for reference objects and the schema string copy during error construction entirely. +7. Add tests verifying both modes produce identical results. +8. Run `make test && make bench-compare` (default mode: slight improvement from json.Marshal; benchmark with lazy mode: fewer allocs on error paths). +9. Commit: *"errors: add WithLazyErrors option for deferred schema resolution"* + +--- + +## Phase 7: Unify Request/Response Body Validation + +**Goal**: Eliminate the ~95% code duplication between `requests/validate_request.go` (362 lines) and `responses/validate_response.go` (376 lines). Also fix several per-error inefficiencies that live in the duplicated code. + +**Files changed**: New shared file, `requests/validate_request.go`, `responses/validate_response.go`, `schema_validation/locate_schema_property.go`, `helpers/ignore_regex.go` + +**Work**: + +1. **Fix `LocateSchemaPropertyNodeByJSONPath`** — Remove the goroutine/channel pattern and replace with a plain `defer/recover`: + ```go + func LocateSchemaPropertyNodeByJSONPath(doc *yaml.Node, JSONPath string) (result *yaml.Node) { + defer func() { recover() }() + _, path := utils.ConvertComponentIdIntoFriendlyPathSearch(JSONPath) + if path == "" { return nil } + jp, _ := jsonpath.NewPath(path) + nodes := jp.Query(doc) + if len(nodes) > 0 { return nodes[0] } + return nil + } + ``` +2. **Replace `IgnoreRegex` with string checks** — The pattern `^'?(anyOf|allOf|oneOf|validation)'? failed(, none matched)?$` can be replaced with a simple function using `strings.HasSuffix` and/or exact-match comparisons. Update all 4 call sites. +3. **Extract the shared error loop** into a common internal function (e.g., `buildSchemaValidationErrors(...)`) that handles: iterate flat errors, skip ignored messages, locate schema property nodes, extract instance locations, build `SchemaValidationFailure` structs. This eliminates the duplicate `instanceLocationRegex` declaration. +4. **Reuse `GoLow().Hash()` local variable** — In the shared body validation function, compute the hash once and reuse it for both the cache-check and cache-store paths (fixing the double-compute in `validate_parameter.go`, `validate_request.go`, and `validate_response.go`). +5. Extract the shared body validation logic into a common internal function: + ```go + func validateBodySchema(body []byte, schema *base.Schema, version float32, + options *config.ValidationOptions, direction string, + requestInfo bodyRequestInfo) (bool, []*errors.ValidationError) + ``` + This handles: cache lookup, cache-miss compilation, JSON decoding, schema validation, error processing (using the new shared error loop), strict mode. The `direction` parameter controls error message wording. +6. Request and response validators become thin wrappers: read body from their respective sources, handle empty-body semantics, then delegate to the shared function. +7. Run `make test && make bench-compare`. Expected: Slight improvement from LocateSchema and IgnoreRegex fixes; structural dedup is allocation-neutral. +8. Commit: *"validation: unify request/response body schema validation; fix per-error overhead"* + +--- + +## Phase 8: Options Plumbing + Minor Optimizations + +**Goal**: Fix the cache/options ergonomics issues and remaining small inefficiencies. + +**Files changed**: `config/config.go`, `requests/validate_request.go`, `requests/request_body.go`, `responses/validate_response.go`, `responses/response_body.go`, `validator.go` + +**Work**: + +1. **Change `ValidateRequestSchemaInput.Options` and `ValidateResponseSchemaInput.Options`** from `[]config.Option` to `*config.ValidationOptions`. Callers pass the options struct directly instead of wrapping in a `WithExistingOpts` closure. This eliminates the allocate-then-discard overhead (2-4 wasted allocs per request). +2. **Fix `WithExistingOpts`** to use struct dereference (`*o = *options`) instead of field-by-field copy. This prevents silent field-loss bugs when new fields are added to `ValidationOptions`. Keep the function for external consumers. +3. **Make `NewValidationOptions` allocation-aware** — As a safety net for any remaining callers, defer the `DefaultCache` and `sync.Map` allocations until after options are applied (only allocate if no `WithExistingOpts` override is provided). +4. **Cache `basePaths` at init**: `getBasePaths(document)` parses server URLs every time `StripRequestPath` is called. Compute once at init, store on the validator or options. +5. **Pre-split path segments during warming**: If we know the matched path template, pre-split its segments once rather than per-request. +6. Run `make test && make bench-compare`. +7. Commit: *"validator: fix options plumbing ergonomics; minor allocation optimizations"* + +--- + +## Phase 9: Final Benchmarks + Documentation + +**Goal**: Capture the final state and document the changes for the PR. + +**Work**: + +1. Run final fast-suite benchmarks and save results. +2. Run production benchmarks (`BenchmarkProd_*`) once for a before/after snapshot. +3. Run `benchstat` comparing Phase 0 baseline to final results. +4. Update `docs/architecture-review.md` with an "After" section showing measured improvements. +5. Write PR summary. +6. Commit: *"docs: update architecture review with measured results"* + +--- + +## Verification Protocol (Every Phase) + +After each phase, before committing: + +```bash +make test # All 1,159 tests pass (with -race) +make lint # No new lint warnings +make bench-compare # No regressions (or improvements documented) +``` + +If a phase introduces a regression in benchmarks, investigate before committing. Phases 2 and 7 are structural and expected to be allocation-neutral. Phases 3, 4, 5, 6, and 8 should show measurable improvement. + +--- + +## Design Decisions + +1. **Matcher chain is internal for now.** The `pathMatcher` interface, `radixMatcher`, `regexMatcher`, and `matcherChain` are unexported. Once proven, a future PR can export them as `PathMatcher` with a `WithPathMatchers(...)` option, letting users inject static-route matchers, path rewriters, etc. +2. **`resolvedRoute` naming.** Communicates "we resolved which API route this request maps to, and here is everything we know about it." It carries more than just the PathItem (params, matched template, operation), so a route-level name fits better than a PathItem-level name. +3. **Lazy errors are opt-in.** `WithLazyErrors()` enables deferred schema resolution. Default behavior is unchanged. `ReferenceSchema`/`ReferenceObject` fields are deprecated in favor of `GetReferenceSchema()`/`GetReferenceObject()` methods that work in both modes. This gives a clean migration path without breaking existing consumers. +4. **Race detector is mandatory.** Every `make test` run includes `-race`. Non-negotiable when changing concurrency patterns. +5. **Async vs sync is data-driven.** Phase 4 benchmarks whether the async path is actually faster than sync after optimization. If not, we simplify to sync-only. +6. **`operationForMethod` consolidation.** A single helper replaces 4 identical switch statements. All existing functions delegate to it, keeping backward compatibility while eliminating maintenance burden. +7. **Options plumbing fix is late (Phase 8).** We defer the `ValidateSchemaInput` type change until after the body validation unification (Phase 7) to avoid churning the same files twice. + +--- + +## Summary of All Fixes by Phase + +| Phase | Fix | Impact | +|-------|-----|--------| +| 1 | `pathMatcher` chain replaces if/else | Extensible matching, cleaner code | +| 1 | `operationForMethod` consolidates 4 switches | Code dedup, single maintenance point | +| 1 | `resolvedRoute` carries operation | Eliminates downstream `ExtractOperation` | +| 2 | `requestContext` shared state | Foundation for per-request dedup | +| 2 | `VersionToFloat` cached at init | Eliminates per-request string comparison | +| 3 | Sync path uses context | ~24% fewer allocs for GET requests | +| 4 | WaitGroup replaces 9-goroutine/5-channel | Reduces async overhead for POST requests | +| 5 | Regex matcher extracts params | Fast path for all matchers | +| 6 | `WithLazyErrors` defers schema resolution | Major alloc reduction on error paths | +| 6 | `json.Marshal` replaces `json.MarshalIndent` | Reduces formatting overhead per error | +| 7 | Unified body validation function | Eliminates ~350 lines of duplication | +| 7 | `LocateSchemaPropertyNodeByJSONPath` fix | Eliminates goroutine + 2 channels per error | +| 7 | `IgnoreRegex` to string checks | Eliminates regex engine per error | +| 7 | `GoLow().Hash()` local reuse | Avoids redundant AST traversal | +| 7 | `instanceLocationRegex` dedup | Minor code cleanup | +| 8 | `ValidateSchemaInput.Options` type change | Eliminates 2-4 wasted allocs per request | +| 8 | `WithExistingOpts` struct copy | Prevents silent field-loss bugs | +| 8 | `NewValidationOptions` lazy alloc | Safety net for remaining callers | +| 8 | Cache `basePaths` at init | Eliminates per-request URL parsing | diff --git a/docs/proposal-path-match-context.md b/docs/proposal-path-match-context.md new file mode 100644 index 00000000..72cb2934 --- /dev/null +++ b/docs/proposal-path-match-context.md @@ -0,0 +1,596 @@ +# Proposal: Clean Architecture for Path Resolution & Validation Context + +**Status**: Draft +**Author**: Zach Hamm +**Date**: 2026-02-06 +**Related**: `perf/fix-parameter-schema-cache` branch + +## Motivation + +The current validation pipeline has grown organically. Each optimization (radix tree, +regex cache, schema cache, sync fast-path) was bolted on with conditionals: + +```go +// This pattern is everywhere: +if options != nil && options.PathTree != nil { + // try radix tree +} +// fall back to regex +if options != nil && options.RegexCache != nil { + // check cache +} +if rgx == nil { + // compile regex + if options != nil && options.RegexCache != nil { + // store in cache + } +} +``` + +The result is: + +1. **Duplicated work**: Path matching and parameter extraction are the same operation + run twice with different code paths. +2. **Scattered caching**: `RegexCache`, `SchemaCache`, and `PathTree` are all separate + fields on `ValidationOptions` with independent nil-check patterns. +3. **No information flow**: `FindPath` knows the parameter values but throws them away. + Parameter validation re-derives them from scratch. +4. **Hard to extend**: Adding a new matching strategy means editing `FindPath` internals. +5. **Hard to optimize**: Per-request state (stripped path, split segments, extracted params) + is recomputed by every validation phase independently. + +This proposal replaces the ad-hoc approach with three clean abstractions: + +- **`PathResolver`** — a chain-of-responsibility interface for path matching +- **`MatchResult`** — a struct that carries everything learned during matching +- **`RequestContext`** — a per-request scratchpad that validation phases share + +## Architecture Overview + +``` + ┌──────────────────────┐ + │ Validator (init) │ + │ │ + │ Builds PathResolver │ + │ chain + warm caches │ + └───────────┬──────────┘ + │ + ▼ +┌───────────────────────────────────────────────────────────────────┐ +│ Per-Request Flow │ +│ │ +│ Request ──► PathResolver.Resolve(req) ──► MatchResult │ +│ │ │ │ +│ │ Chain: │ Contains: │ +│ │ 1. RadixResolver │ - PathItem │ +│ │ 2. RegexResolver │ - PathTemplate │ +│ │ 3. (user-provided?) │ - PathParams │ +│ │ │ - StrippedPath │ +│ │ First match wins. │ - Segments │ +│ │ │ │ +│ ▼ ▼ │ +│ RequestContext ◄──── populated from MatchResult │ +│ │ │ +│ │ Carries: │ +│ │ - MatchResult │ +│ │ - Decoded body (if needed, computed once) │ +│ │ - Per-request scratch data │ +│ │ │ +│ ├──► PathParamValidator.Validate(ctx) │ +│ ├──► QueryParamValidator.Validate(ctx) │ +│ ├──► HeaderParamValidator.Validate(ctx) │ +│ ├──► CookieParamValidator.Validate(ctx) │ +│ ├──► SecurityValidator.Validate(ctx) │ +│ └──► BodyValidator.Validate(ctx) │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +## Core Types + +### `PathResolver` Interface + +```go +// PathResolver finds the matching path for an incoming request. +// Implementations are composed into a chain — the first resolver +// that returns a match wins. +type PathResolver interface { + // Resolve attempts to match the request path against known API paths. + // Returns nil if this resolver cannot handle the path. + Resolve(path string, document *v3.Document) *MatchResult +} +``` + +Simple. One method. Each implementation focuses on one matching strategy. + +### Built-in Resolvers + +```go +// RadixResolver uses the pre-built radix tree for O(k) matching. +// Handles standard {param} paths. Extracts parameter values during traversal. +type RadixResolver struct { + tree *radix.PathTree +} + +func (r *RadixResolver) Resolve(path string, document *v3.Document) *MatchResult { + pathItem, matchedPath, params, found := r.tree.LookupWithParams(path) + if !found { + return nil // Let the next resolver in the chain try + } + return &MatchResult{ + PathItem: pathItem, + MatchedPath: matchedPath, + PathParams: params, + } +} + + +// RegexResolver handles complex paths (matrix, label, OData) via regex. +// Used as a fallback when the radix tree can't match. +type RegexResolver struct { + regexCache config.RegexCache +} + +func (r *RegexResolver) Resolve(path string, document *v3.Document) *MatchResult { + // Current regex matching logic from paths.FindPath, but also + // extracts and returns PathParams from the regex match groups. + // ... +} +``` + +### Resolver Chain + +```go +// ResolverChain tries each resolver in order. First match wins. +type ResolverChain struct { + resolvers []PathResolver +} + +func (c *ResolverChain) Resolve(path string, document *v3.Document) *MatchResult { + for _, r := range c.resolvers { + if result := r.Resolve(path, document); result != nil { + return result + } + } + return nil +} +``` + +This replaces the current hardcoded `if radixTree != nil { ... } // fall back to regex` +pattern in `FindPath`. Users can: + +- Reorder the chain +- Insert their own resolver (e.g., a static map for known high-traffic paths) +- Remove the regex resolver entirely if they only use simple paths +- Add a resolver that does path rewriting before matching + +### `MatchResult` Struct + +```go +// MatchResult carries everything learned during path matching. +// This is the single source of truth for "what matched and what was extracted." +type MatchResult struct { + // PathItem is the matched OpenAPI path item definition. + PathItem *v3.PathItem + + // MatchedPath is the path template (e.g., "/users/{id}/posts"). + MatchedPath string + + // PathParams maps parameter names to their raw extracted values. + // e.g., {"account_id": "abc123", "campaign_id": "xyz789"} + // nil means the resolver didn't extract params (validator should fall back). + PathParams map[string]string + + // StrippedPath is the request path with base path removed. + // Computed once, reused by all validators. + StrippedPath string + + // Segments is the pre-split path for validators that need it. + // Avoids repeated strings.Split calls. + Segments []string +} +``` + +### `RequestContext` — Per-Request Shared State + +This is the key piece that eliminates redundant work across validation phases. + +```go +// RequestContext carries per-request state that flows through the entire +// validation pipeline. It's created once per request and shared (read/write) +// by all validators. +// +// This replaces the pattern where each validator independently re-derives +// the same information (stripped path, split segments, decoded body, etc.). +type RequestContext struct { + Request *http.Request + Match *MatchResult + Operation *v3.Operation // Resolved from PathItem + HTTP method + Parameters []*v3.Parameter // Extracted from PathItem + Operation + + // Lazy-computed fields (populated on first access, reused after) + decodedBody any // JSON-decoded request body + bodyBytes []byte // Raw body bytes (read once) + bodyRead bool // Whether body has been read +} + +// Body returns the raw body bytes, reading from the request at most once. +func (ctx *RequestContext) Body() ([]byte, error) { + if !ctx.bodyRead { + // Read and store — subsequent calls return cached bytes + } + return ctx.bodyBytes, nil +} + +// DecodedBody returns the JSON-decoded body, decoding at most once. +func (ctx *RequestContext) DecodedBody() (any, error) { + if ctx.decodedBody == nil { + // Decode and store + } + return ctx.decodedBody, nil +} +``` + +### Validator-Level Cache (Persistent) + +The validator already has `SchemaCache` and `RegexCache` on `ValidationOptions`. This +proposal doesn't change those — they're validator-level caches that persist across +requests. But it clarifies the two-tier model: + +``` +┌──────────────────────────────────────────────────┐ +│ Validator-Level (persistent) │ +│ │ +│ SchemaCache — compiled JSON schemas │ +│ RegexCache — compiled path regexes │ +│ PathTree — radix tree (via RadixResolver) │ +│ │ +│ Created once during NewValidator. │ +│ Shared across all requests. Thread-safe. │ +└──────────────────────────────────────────────────┘ + +┌──────────────────────────────────────────────────┐ +│ Request-Level (per-request) │ +│ │ +│ RequestContext: │ +│ MatchResult — which path matched, params │ +│ Operation — resolved operation for method │ +│ Parameters — params for this operation │ +│ Body bytes — read once, shared across phases │ +│ Decoded body — decoded once, validated by many │ +│ │ +│ Created per request. Not shared across requests. │ +│ No synchronization needed. │ +└──────────────────────────────────────────────────┘ +``` + +## What This Simplifies + +### Before: `ValidatePathParamsWithPathItem` (current code) + +```go +func (v *paramValidator) ValidatePathParamsWithPathItem( + request *http.Request, pathItem *v3.PathItem, pathValue string, +) (bool, []*errors.ValidationError) { + + // 1. Re-strip the request path (already done in FindPath) + submittedSegments := strings.Split(paths.StripRequestPath(request, v.document), "/") + pathSegments := strings.Split(pathValue, "/") + + // 2. Re-extract params for operation (could be shared) + params := helpers.ExtractParamsForOperation(request, pathItem) + + for _, p := range params { + if p.In == helpers.Path { + // 3. For each param, iterate ALL segments + for x := range pathSegments { + // 4. Check regex cache (nil-check pattern) + if v.options.RegexCache != nil { + if cached, found := v.options.RegexCache.Load(pathSegments[x]); found { + rgx = cached.(*regexp.Regexp) + } + } + // 5. Compile regex if not cached (even for literal segments!) + if rgx == nil { + r, err := helpers.GetRegexForPath(pathSegments[x]) + // ... + } + // 6. Regex match to extract value + matches := rgx.FindStringSubmatch(submittedSegments[x]) + // 7. Parse brace indices + idxs, _ := helpers.BraceIndices(pathSegments[x]) + // 8. Finally validate the value + // ... + } + } + } +} +``` + +Steps 1-7 are redundant — the path resolver already did this work (or could have). + +### After: With `RequestContext` + +```go +func (v *paramValidator) ValidatePathParams(ctx *RequestContext) []*errors.ValidationError { + var errs []*errors.ValidationError + + for _, p := range ctx.Parameters { + if p.In != helpers.Path { + continue + } + + // Fast path: parameter value already extracted during path matching + if value, ok := ctx.Match.PathParams[p.Name]; ok { + decodedValue, _ := url.PathUnescape(value) + errs = append(errs, validatePathParamValue(p, decodedValue, v.options)...) + continue + } + + // Slow path: complex param style (matrix/label/etc.) needs regex extraction + errs = append(errs, v.extractAndValidateComplexParam(p, ctx)...) + } + + return errs +} +``` + +The common case (simple `{param}`) is a map lookup + value validation. No regex, no +segment iteration, no `BraceIndices`, no nil-check conditionals. + +### Before: `ValidateHttpRequestSync` (current code) + +```go +func (v *validator) ValidateHttpRequestSync(request *http.Request) (bool, []*errors.ValidationError) { + // Step 1: Find the path (strips URL, splits segments, matches) + pathItem, errs, foundPath := paths.FindPath(request, v.v3Model, v.options) + if len(errs) > 0 { + return false, errs + } + + // Step 2: Each validator re-derives what it needs from scratch + // (re-strips path, re-splits segments, re-extracts params, etc.) + for _, validateFunc := range []validationFunction{ + paramValidator.ValidatePathParamsWithPathItem, // re-strips path, re-splits, regex + paramValidator.ValidateCookieParamsWithPathItem, // re-extracts params + paramValidator.ValidateHeaderParamsWithPathItem, // re-extracts params + paramValidator.ValidateQueryParamsWithPathItem, // re-extracts params + paramValidator.ValidateSecurityWithPathItem, // re-extracts security + } { + valid, pErrs := validateFunc(request, pathItem, foundPath) + // ... + } + + // Step 3: Body validator reads and decodes body + valid, pErrs := reqBodyValidator.ValidateRequestBodyWithPathItem(request, pathItem, foundPath) + // ... +} +``` + +### After: With `RequestContext` + +```go +func (v *validator) ValidateHttpRequestSync(request *http.Request) (bool, []*errors.ValidationError) { + // Step 1: Resolve path (one call, captures everything) + ctx, errs := v.buildRequestContext(request) + if errs != nil { + return false, errs + } + + // Step 2: Each validator reads from shared context — no redundant work + validators := []func(*RequestContext) []*errors.ValidationError{ + v.paramValidator.ValidatePathParams, + v.paramValidator.ValidateCookieParams, + v.paramValidator.ValidateHeaderParams, + v.paramValidator.ValidateQueryParams, + v.paramValidator.ValidateSecurity, + v.requestValidator.ValidateBody, + } + + var validationErrors []*errors.ValidationError + for _, validate := range validators { + validationErrors = append(validationErrors, validate(ctx)...) + } + + return len(validationErrors) == 0, validationErrors +} + +func (v *validator) buildRequestContext(request *http.Request) (*RequestContext, []*errors.ValidationError) { + result := v.resolver.Resolve(StripRequestPath(request, v.v3Model), v.v3Model) + if result == nil { + return nil, pathNotFoundErrors(request) + } + + operation := getOperationForMethod(result.PathItem, request.Method) + if operation == nil { + return nil, methodNotAllowedErrors(request, result.MatchedPath) + } + + return &RequestContext{ + Request: request, + Match: result, + Operation: operation, + Parameters: extractParams(result.PathItem, operation), + }, nil +} +``` + +## User-Extensible Path Resolution + +### Static Map Resolver (Example) + +A user who knows their high-traffic paths could provide a zero-allocation resolver: + +```go +type StaticResolver struct { + paths map[string]*v3.PathItem +} + +func (r *StaticResolver) Resolve(path string, _ *v3.Document) *MatchResult { + if pathItem, ok := r.paths[path]; ok { + return &MatchResult{PathItem: pathItem, MatchedPath: path} + } + return nil +} + +// Usage: +validator, _ := validator.NewValidator(doc, + config.WithResolvers( + &StaticResolver{paths: myHotPaths}, // Check known paths first + resolver.NewRadixResolver(doc), // Then radix tree + resolver.NewRegexResolver(), // Then regex fallback + ), +) +``` + +### Rewriting Resolver (Example) + +A user who needs path normalization before matching: + +```go +type RewriteResolver struct { + rules map[string]string // "/v2/campaigns" -> "/v3/campaigns" + next PathResolver +} + +func (r *RewriteResolver) Resolve(path string, doc *v3.Document) *MatchResult { + if rewritten, ok := r.rules[path]; ok { + path = rewritten + } + return r.next.Resolve(path, doc) +} +``` + +## Configuration + +### New Options + +```go +// WithResolvers sets the path resolver chain. +// Default: [RadixResolver, RegexResolver] +func WithResolvers(resolvers ...PathResolver) Option { + return func(o *ValidationOptions) { + o.Resolvers = resolvers + } +} + +// WithoutRegexFallback removes the regex resolver from the default chain. +// Useful when all paths are simple {param} style and you want maximum performance. +func WithoutRegexFallback() Option { + return func(o *ValidationOptions) { + o.Resolvers = []PathResolver{NewRadixResolver(/* ... */)} + } +} +``` + +### Default Behavior (Unchanged) + +If no resolvers are configured, the default chain is `[RadixResolver, RegexResolver]`, +which matches today's behavior exactly. Existing code continues to work. + +## Migration Path + +This is a significant internal refactoring, but the public API can remain backward +compatible. Suggested approach: + +### Phase 1: Internal Types (No Public API Change) + +1. Define `MatchResult` and `RequestContext` as internal types +2. Add `LookupWithParams` to the radix tree +3. Have `FindPath` internally build a `MatchResult` +4. Thread `RequestContext` through the internal validation pipeline +5. Keep all existing public method signatures working via adapter code + +At this point, the internal flow is clean but the public API is unchanged. + +### Phase 2: PathResolver Interface (Public, Additive) + +1. Export `PathResolver` interface and `MatchResult` +2. Add `WithResolvers(...)` option +3. Export `RadixResolver` and `RegexResolver` as usable implementations +4. Default behavior unchanged — opt-in for users who want custom resolvers + +### Phase 3: Simplified Validator Methods (Breaking, Major Version) + +1. Simplify `ParameterValidator` interface to accept `RequestContext` +2. Remove the duplicated `WithPathItem` variants +3. Deprecate direct `FindPath` usage in favor of resolver chain + +This phase is a breaking change and should be a major version bump. + +### Phase 4: Remove Legacy Code + +1. Remove old code paths once the new architecture is stable +2. Remove nil-check conditionals throughout the codebase + +## Expected Impact + +### Performance (Per-Request, Simple GET with 2 Path Params) + +| Metric | Current (no cache) | Current (with cache) | With RequestContext | +|--------|--------------------|---------------------|---------------------| +| Time | 21,200 ns | 4,500 ns | ~2,000 ns (est.) | +| Memory | 23,833 B | 4,687 B | ~1,500 B (est.) | +| Allocs | 400 | 115 | ~30 (est.) | + +The remaining ~30 allocs would be: +- Radix tree lookup: ~4 allocs (path splitting) +- PathParams map: ~1 alloc +- RequestContext: ~1 alloc +- Parameters slice: ~1 alloc +- Validation error slice: ~1 alloc +- Value validation (schema checks): ~20 allocs + +### Code Complexity + +- Removes ~15 nil-check conditional blocks across the codebase +- Removes duplicated path stripping / segment splitting in every validator +- Removes the `WithPathItem` method variants (or makes them thin adapters) +- Each validator becomes a simple function of `RequestContext` → `[]ValidationError` + +## Open Questions + +1. **Should `PathResolver.Resolve` accept `*http.Request` instead of just the path + string?** Some resolvers might want access to headers or method. But keeping it + to just the path string keeps resolvers simpler and more testable. Method matching + is currently done separately after path matching, which seems right. + +2. **Should `RequestContext` use `context.Context` or be a standalone struct?** + Using `context.Context` would let us attach it to the request, but adds + `context.Value` type assertions. A standalone struct is simpler and type-safe. + Recommendation: standalone struct, passed explicitly. + +3. **How to handle the `ValidateHttpRequestWithPathItem` methods?** These accept + an explicit PathItem + pathValue (bypassing FindPath). Options: + - Keep them as thin adapters that build a partial `RequestContext` + - Deprecate them in favor of a single entry point + - Keep them but have them create a `MatchResult` from the provided PathItem + +4. **Should `RegexResolver` populate `PathParams` too?** Yes — `comparePaths` already + does the regex work. Extracting submatch groups at that point means parameter + validation can use the fast path even for regex-matched paths. + +5. **Thread safety of `RequestContext`**: Since it's per-request and not shared across + goroutines (even in the async validation path, each goroutine reads from it but + doesn't write), it should be safe without synchronization. But the async path + needs careful review — if multiple goroutines call `ctx.Body()` simultaneously, + the lazy-init needs a `sync.Once` or similar. Worth thinking through the async + validation story separately. + +6. **Naming**: `PathResolver` vs `PathMatcher` vs `RouteMatcher`? `RequestContext` + vs `ValidationContext` vs `RequestState`? Open to better names. + +## Summary + +The current architecture bolts features on with conditionals. This proposal replaces +that with three clean abstractions: + +| Abstraction | Replaces | Benefit | +|------------|----------|---------| +| **PathResolver chain** | Hardcoded if/else in FindPath | Extensible, testable, composable | +| **MatchResult** | Thrown-away radix tree knowledge | Zero redundant work in param validation | +| **RequestContext** | Repeated derivation in every validator | Compute once, share everywhere | + +The default behavior stays the same. The internal code gets simpler. Users get extension +points they don't have today. And per-request allocations drop from ~115 to ~30 for +the common case. diff --git a/errors/validation_error.go b/errors/validation_error.go index ec273d6c..931854da 100644 --- a/errors/validation_error.go +++ b/errors/validation_error.go @@ -4,12 +4,20 @@ package errors import ( + "encoding/json" "fmt" + "reflect" + "regexp" + "strconv" + "sync" - "github.com/pb33f/libopenapi-validator/helpers" "github.com/santhosh-tekuri/jsonschema/v6" + + "github.com/pb33f/libopenapi-validator/helpers" ) +var instanceLocationRegex = regexp.MustCompile(`^/(\d+)`) + // SchemaValidationFailure is a wrapper around the jsonschema.ValidationError object, to provide a more // user-friendly way to break down what went wrong. type SchemaValidationFailure struct { @@ -44,12 +52,16 @@ type SchemaValidationFailure struct { // the Context object held by the ValidationError object). Column int `json:"column,omitempty" yaml:"column,omitempty"` - // ReferenceSchema is the schema that was referenced in the validation failure. + // Deprecated: Use GetReferenceSchema() instead for forward-compatible access. ReferenceSchema string `json:"referenceSchema,omitempty" yaml:"referenceSchema,omitempty"` - // ReferenceObject is the object that was referenced in the validation failure. + // Deprecated: Use GetReferenceObject() instead for forward-compatible access. ReferenceObject string `json:"referenceObject,omitempty" yaml:"referenceObject,omitempty"` + // lazySrc holds state for deferred resolution of ReferenceSchema and ReferenceObject. + // This is only set when WithLazyErrors is enabled. + lazySrc *lazySchemaSource + // ReferenceExample is an example object generated from the schema that was referenced in the validation failure. ReferenceExample string `json:"referenceExample,omitempty" yaml:"referenceExample,omitempty"` @@ -57,11 +69,84 @@ type SchemaValidationFailure struct { OriginalError *jsonschema.ValidationError `json:"-" yaml:"-"` } +// lazySchemaSource holds the data needed to resolve ReferenceSchema and ReferenceObject +// on demand when WithLazyErrors is enabled. +type lazySchemaSource struct { + renderedInline []byte // raw rendered schema bytes (for ReferenceSchema) + decodedObj any // decoded request/response body + bodyBytes []byte // raw request/response body bytes + instanceLoc string // instance location from validation error (e.g. "/0") + schemaOnce sync.Once // ensures ReferenceSchema is resolved exactly once + objectOnce sync.Once // ensures ReferenceObject is resolved exactly once +} + // Error returns a string representation of the error func (s *SchemaValidationFailure) Error() string { return fmt.Sprintf("Reason: %s, Location: %s", s.Reason, s.Location) } +// GetReferenceSchema returns the reference schema string. In eager mode (default), +// this returns the pre-populated ReferenceSchema field. In lazy mode (WithLazyErrors), +// it resolves from the cached schema data on first call. Thread-safe via sync.Once. +func (s *SchemaValidationFailure) GetReferenceSchema() string { + if s.ReferenceSchema != "" { + return s.ReferenceSchema + } + if s.lazySrc != nil { + s.lazySrc.schemaOnce.Do(func() { + if s.lazySrc.renderedInline != nil { + s.ReferenceSchema = string(s.lazySrc.renderedInline) + } + }) + } + return s.ReferenceSchema +} + +// GetReferenceObject returns the reference object string. In eager mode (default), +// this returns the pre-populated ReferenceObject field. In lazy mode (WithLazyErrors), +// it resolves from the decoded object data on first call. +func (s *SchemaValidationFailure) GetReferenceObject() string { + if s.ReferenceObject != "" { + return s.ReferenceObject + } + if s.lazySrc == nil { + return s.ReferenceObject + } + s.resolveReferenceObject() + return s.ReferenceObject +} + +func (s *SchemaValidationFailure) resolveReferenceObject() { + s.lazySrc.objectOnce.Do(func() { + if s.lazySrc.decodedObj != nil && s.lazySrc.instanceLoc != "" { + val := instanceLocationRegex.FindStringSubmatch(s.lazySrc.instanceLoc) + if len(val) > 0 { + referenceIndex, _ := strconv.Atoi(val[1]) + if reflect.ValueOf(s.lazySrc.decodedObj).Type().Kind() == reflect.Slice { + found := s.lazySrc.decodedObj.([]any)[referenceIndex] + recoded, _ := json.Marshal(found) + s.ReferenceObject = string(recoded) + return + } + } + } + if s.lazySrc.bodyBytes != nil { + s.ReferenceObject = string(s.lazySrc.bodyBytes) + } + }) +} + +// SetLazySource configures the lazy resolution source for this failure. +// This is called by the validation code when WithLazyErrors is enabled. +func (s *SchemaValidationFailure) SetLazySource(renderedInline []byte, decodedObj any, bodyBytes []byte, instanceLoc string) { + s.lazySrc = &lazySchemaSource{ + renderedInline: renderedInline, + decodedObj: decodedObj, + bodyBytes: bodyBytes, + instanceLoc: instanceLoc, + } +} + // ValidationError is a struct that contains all the information about a validation error. type ValidationError struct { // Message is a human-readable message describing the error. diff --git a/errors/validation_error_test.go b/errors/validation_error_test.go index f7e8ebdd..e34b868b 100644 --- a/errors/validation_error_test.go +++ b/errors/validation_error_test.go @@ -7,8 +7,9 @@ import ( "fmt" "testing" - "github.com/pb33f/libopenapi-validator/helpers" "github.com/stretchr/testify/require" + + "github.com/pb33f/libopenapi-validator/helpers" ) func TestSchemaValidationFailure_Error(t *testing.T) { diff --git a/helpers/ignore_regex.go b/helpers/ignore_regex.go index 183b000d..b079a9b4 100644 --- a/helpers/ignore_regex.go +++ b/helpers/ignore_regex.go @@ -3,7 +3,10 @@ package helpers -import "regexp" +import ( + "regexp" + "strings" +) var ( // Ignore generic poly errors that just say "none matched" since we get specific errors @@ -13,7 +16,56 @@ var ( ) // IgnoreRegex is a regular expression that matches the IgnorePattern +// +// Deprecated: Use ShouldIgnoreError instead. var IgnoreRegex = regexp.MustCompile(IgnorePattern) // IgnorePolyRegex is a regular expression that matches the IgnorePattern +// +// Deprecated: Use ShouldIgnorePolyError instead. var IgnorePolyRegex = regexp.MustCompile(IgnorePolyPattern) + +// ShouldIgnoreError checks if an error message should be ignored. +// Replaces the previous IgnoreRegex for better performance. +// Matches messages like: "anyOf failed", "'allOf' failed, none matched", "validation failed" +func ShouldIgnoreError(msg string) bool { + return isIgnoredValidationError(msg, true) +} + +// ShouldIgnorePolyError checks if a polymorphic error message should be ignored. +// Replaces the previous IgnorePolyRegex. +// Like ShouldIgnoreError but does NOT match "validation failed". +func ShouldIgnorePolyError(msg string) bool { + return isIgnoredValidationError(msg, false) +} + +func isIgnoredValidationError(msg string, includeValidation bool) bool { + // Strip optional quotes + s := msg + if len(s) > 0 && s[0] == '\'' { + s = s[1:] + } + + // Check prefix + var rest string + switch { + case strings.HasPrefix(s, "anyOf"): + rest = s[5:] + case strings.HasPrefix(s, "allOf"): + rest = s[5:] + case strings.HasPrefix(s, "oneOf"): + rest = s[5:] + case includeValidation && strings.HasPrefix(s, "validation"): + rest = s[10:] + default: + return false + } + + // Strip optional closing quote + if len(rest) > 0 && rest[0] == '\'' { + rest = rest[1:] + } + + // Must be followed by " failed" with optional ", none matched" + return rest == " failed" || rest == " failed, none matched" +} diff --git a/helpers/operation_utilities.go b/helpers/operation_utilities.go index a4ceadd6..00ca34d8 100644 --- a/helpers/operation_utilities.go +++ b/helpers/operation_utilities.go @@ -10,30 +10,35 @@ import ( "github.com/pb33f/libopenapi/datamodel/high/v3" ) -// ExtractOperation extracts the operation from the path item based on the request method. If there is no -// matching operation found, then nil is returned. -func ExtractOperation(request *http.Request, item *v3.PathItem) *v3.Operation { - switch request.Method { +// OperationForMethod returns the operation from the PathItem for the given HTTP method string. +// Returns nil if the method doesn't exist on the PathItem. +func OperationForMethod(method string, pathItem *v3.PathItem) *v3.Operation { + switch method { case http.MethodGet: - return item.Get + return pathItem.Get case http.MethodPost: - return item.Post + return pathItem.Post case http.MethodPut: - return item.Put + return pathItem.Put case http.MethodDelete: - return item.Delete + return pathItem.Delete case http.MethodOptions: - return item.Options + return pathItem.Options case http.MethodHead: - return item.Head + return pathItem.Head case http.MethodPatch: - return item.Patch + return pathItem.Patch case http.MethodTrace: - return item.Trace + return pathItem.Trace } return nil } +// ExtractOperation extracts the operation from the path item based on the request method. +func ExtractOperation(request *http.Request, item *v3.PathItem) *v3.Operation { + return OperationForMethod(request.Method, item) +} + // ExtractContentType extracts the content type from the request header. First return argument is the content type // of the request.The second (optional) argument is the charset of the request. The third (optional) // argument is the boundary of the type (only used with forms really). diff --git a/helpers/operation_utilities_test.go b/helpers/operation_utilities_test.go index 9d1f01fe..2c9aad17 100644 --- a/helpers/operation_utilities_test.go +++ b/helpers/operation_utilities_test.go @@ -112,3 +112,102 @@ func TestExtractContentType(t *testing.T) { require.Empty(t, charset) require.Empty(t, boundary) } + +func TestOperationForMethod(t *testing.T) { + pathItem := &v3.PathItem{ + Get: &v3.Operation{Summary: "GET operation"}, + Post: &v3.Operation{Summary: "POST operation"}, + Put: &v3.Operation{Summary: "PUT operation"}, + Delete: &v3.Operation{Summary: "DELETE operation"}, + Options: &v3.Operation{Summary: "OPTIONS operation"}, + Head: &v3.Operation{Summary: "HEAD operation"}, + Patch: &v3.Operation{Summary: "PATCH operation"}, + Trace: &v3.Operation{Summary: "TRACE operation"}, + } + + tests := []struct { + name string + method string + expected string + wantNil bool + }{ + { + name: "GET method", + method: http.MethodGet, + expected: "GET operation", + wantNil: false, + }, + { + name: "POST method", + method: http.MethodPost, + expected: "POST operation", + wantNil: false, + }, + { + name: "PUT method", + method: http.MethodPut, + expected: "PUT operation", + wantNil: false, + }, + { + name: "DELETE method", + method: http.MethodDelete, + expected: "DELETE operation", + wantNil: false, + }, + { + name: "OPTIONS method", + method: http.MethodOptions, + expected: "OPTIONS operation", + wantNil: false, + }, + { + name: "HEAD method", + method: http.MethodHead, + expected: "HEAD operation", + wantNil: false, + }, + { + name: "PATCH method", + method: http.MethodPatch, + expected: "PATCH operation", + wantNil: false, + }, + { + name: "TRACE method", + method: http.MethodTrace, + expected: "TRACE operation", + wantNil: false, + }, + { + name: "Unknown method", + method: "INVALID", + wantNil: true, + }, + { + name: "Empty method", + method: "", + wantNil: true, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + result := OperationForMethod(tt.method, pathItem) + if tt.wantNil { + require.Nil(t, result, "should return nil for %s", tt.method) + } else { + require.NotNil(t, result, "should not return nil for %s", tt.method) + require.Equal(t, tt.expected, result.Summary) + } + }) + } + + t.Run("Method where operation is nil", func(t *testing.T) { + pathItemNil := &v3.PathItem{ + Get: &v3.Operation{Summary: "GET operation"}, + } + result := OperationForMethod(http.MethodPost, pathItemNil) + require.Nil(t, result, "should return nil when operation is nil") + }) +} diff --git a/helpers/parameter_utilities.go b/helpers/parameter_utilities.go index 69d29158..c0e1e4de 100644 --- a/helpers/parameter_utilities.go +++ b/helpers/parameter_utilities.go @@ -28,81 +28,18 @@ type QueryParam struct { // Both the path level params and the method level params will be returned. func ExtractParamsForOperation(request *http.Request, item *v3.PathItem) []*v3.Parameter { params := item.Parameters - switch request.Method { - case http.MethodGet: - if item.Get != nil { - params = append(params, item.Get.Parameters...) - } - case http.MethodPost: - if item.Post != nil { - params = append(params, item.Post.Parameters...) - } - case http.MethodPut: - if item.Put != nil { - params = append(params, item.Put.Parameters...) - } - case http.MethodDelete: - if item.Delete != nil { - params = append(params, item.Delete.Parameters...) - } - case http.MethodOptions: - if item.Options != nil { - params = append(params, item.Options.Parameters...) - } - case http.MethodHead: - if item.Head != nil { - params = append(params, item.Head.Parameters...) - } - case http.MethodPatch: - if item.Patch != nil { - params = append(params, item.Patch.Parameters...) - } - case http.MethodTrace: - if item.Trace != nil { - params = append(params, item.Trace.Parameters...) - } + if op := OperationForMethod(request.Method, item); op != nil { + params = append(params, op.Parameters...) } return params } // ExtractSecurityForOperation will extract the security requirements for the operation based on the request method. func ExtractSecurityForOperation(request *http.Request, item *v3.PathItem) []*base.SecurityRequirement { - var schemes []*base.SecurityRequirement - switch request.Method { - case http.MethodGet: - if item.Get != nil { - schemes = append(schemes, item.Get.Security...) - } - case http.MethodPost: - if item.Post != nil { - schemes = append(schemes, item.Post.Security...) - } - case http.MethodPut: - if item.Put != nil { - schemes = append(schemes, item.Put.Security...) - } - case http.MethodDelete: - if item.Delete != nil { - schemes = append(schemes, item.Delete.Security...) - } - case http.MethodOptions: - if item.Options != nil { - schemes = append(schemes, item.Options.Security...) - } - case http.MethodHead: - if item.Head != nil { - schemes = append(schemes, item.Head.Security...) - } - case http.MethodPatch: - if item.Patch != nil { - schemes = append(schemes, item.Patch.Security...) - } - case http.MethodTrace: - if item.Trace != nil { - schemes = append(schemes, item.Trace.Security...) - } + if op := OperationForMethod(request.Method, item); op != nil { + return op.Security } - return schemes + return nil } // ExtractSecurityHeaderNames extracts header names from applicable security schemes. diff --git a/parameters/cookie_parameters.go b/parameters/cookie_parameters.go index 400b9589..27842f0c 100644 --- a/parameters/cookie_parameters.go +++ b/parameters/cookie_parameters.go @@ -20,7 +20,7 @@ import ( ) func (v *paramValidator) ValidateCookieParams(request *http.Request) (bool, []*errors.ValidationError) { - pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options.RegexCache) + pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options) if len(errs) > 0 { return false, errs } diff --git a/parameters/cookie_parameters_test.go b/parameters/cookie_parameters_test.go index b54be1ef..b4b7479c 100644 --- a/parameters/cookie_parameters_test.go +++ b/parameters/cookie_parameters_test.go @@ -694,7 +694,7 @@ paths: request.AddCookie(&http.Cookie{Name: "PattyPreference", Value: "2500"}) // too many dude. // preset the path - path, _, pv := paths.FindPath(request, &m.Model, &sync.Map{}) + path, _, pv := paths.FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) valid, errors := v.ValidateCookieParamsWithPathItem(request, path, pv) @@ -1145,7 +1145,7 @@ paths: // No cookie added // Use the WithPathItem variant - path, _, pv := paths.FindPath(request, &m.Model, &sync.Map{}) + path, _, pv := paths.FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) valid, errors := v.ValidateCookieParamsWithPathItem(request, path, pv) diff --git a/parameters/header_parameters.go b/parameters/header_parameters.go index b5dbd2be..5c2ac1e5 100644 --- a/parameters/header_parameters.go +++ b/parameters/header_parameters.go @@ -21,7 +21,7 @@ import ( ) func (v *paramValidator) ValidateHeaderParams(request *http.Request) (bool, []*errors.ValidationError) { - pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options.RegexCache) + pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options) if len(errs) > 0 { return false, errs } diff --git a/parameters/header_parameters_test.go b/parameters/header_parameters_test.go index 8d69c35c..402109a1 100644 --- a/parameters/header_parameters_test.go +++ b/parameters/header_parameters_test.go @@ -750,7 +750,7 @@ paths: request.Header.Set("coffeecups", "1200") // that's a lot of cups dude, we only have one dishwasher. // preset the path - path, _, pv := paths.FindPath(request, &m.Model, &sync.Map{}) + path, _, pv := paths.FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) valid, errors := v.ValidateHeaderParamsWithPathItem(request, path, pv) diff --git a/parameters/path_parameters.go b/parameters/path_parameters.go index 909b5057..6ac7b206 100644 --- a/parameters/path_parameters.go +++ b/parameters/path_parameters.go @@ -21,7 +21,7 @@ import ( ) func (v *paramValidator) ValidatePathParams(request *http.Request) (bool, []*errors.ValidationError) { - pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options.RegexCache) + pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options) if len(errs) > 0 { return false, errs } diff --git a/parameters/path_parameters_test.go b/parameters/path_parameters_test.go index a12a82bf..3b97a0a1 100644 --- a/parameters/path_parameters_test.go +++ b/parameters/path_parameters_test.go @@ -5,7 +5,6 @@ package parameters import ( "net/http" - "regexp" "sync" "sync/atomic" "testing" @@ -17,6 +16,7 @@ import ( "github.com/pb33f/libopenapi-validator/config" "github.com/pb33f/libopenapi-validator/helpers" "github.com/pb33f/libopenapi-validator/paths" + "github.com/pb33f/libopenapi-validator/radix" ) func TestNewValidator_SimpleArrayEncodedPath(t *testing.T) { @@ -2075,7 +2075,7 @@ paths: request, _ := http.NewRequest(http.MethodGet, "https://things.com/pizza/;burgerId=22334/locate", nil) // preset the path - path, _, pv := paths.FindPath(request, &m.Model, &sync.Map{}) + path, _, pv := paths.FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) valid, errors := v.ValidatePathParamsWithPathItem(request, path, pv) @@ -2271,51 +2271,6 @@ func (c *regexCacheWatcher) Store(key, value any) { c.inner.Store(key, value) } -func TestNewValidator_CacheCompiledRegex(t *testing.T) { - spec := `openapi: 3.1.0 -paths: - /pizza: - get: - operationId: getPizza` - - doc, _ := libopenapi.NewDocument([]byte(spec)) - - m, _ := doc.BuildV3Model() - - cache := ®exCacheWatcher{inner: &sync.Map{}} - v := NewParameterValidator(&m.Model, config.WithRegexCache(cache)) - - compiledPizza := regexp.MustCompile("^pizza$") - cache.inner.Store("pizza", compiledPizza) - - assert.EqualValues(t, 0, cache.storeCount) - assert.EqualValues(t, 0, cache.hitCount+cache.missCount) - - request, _ := http.NewRequest(http.MethodGet, "https://things.com/pizza", nil) - v.ValidatePathParams(request) - - assert.EqualValues(t, 0, cache.storeCount) - assert.EqualValues(t, 0, cache.missCount) - assert.EqualValues(t, 1, cache.hitCount) - - mapLength := 0 - - cache.inner.Range(func(key, value any) bool { - mapLength += 1 - return true - }) - - assert.Equal(t, 1, mapLength) - - cache.inner.Clear() - - v.ValidatePathParams(request) - - assert.EqualValues(t, 1, cache.storeCount) - assert.EqualValues(t, 1, cache.missCount) - assert.EqualValues(t, 1, cache.hitCount) -} - func TestValidatePathParamsWithPathItem_RegexCache_WithOneCached(t *testing.T) { spec := `openapi: 3.1.0 paths: @@ -2350,33 +2305,46 @@ paths: assert.EqualValues(t, 1, cache.hitCount) } -func TestValidatePathParamsWithPathItem_RegexCache_MissOnceThenHit(t *testing.T) { +// TestRadixTree_RegexFallback verifies that: +// 1. Simple paths use the radix tree (no regex cache) +// 2. Complex paths (OData style) fall back to regex and use the cache +func TestRadixTree_RegexFallback(t *testing.T) { spec := `openapi: 3.1.0 paths: - /burgers/{burgerId}/locate: - parameters: - - in: path - name: burgerId - schema: - type: integer + /simple/{id}: get: - operationId: locateBurgers` + operationId: getSimple + /entities('{Entity}'): + get: + operationId: getOData` + doc, _ := libopenapi.NewDocument([]byte(spec)) m, _ := doc.BuildV3Model() cache := ®exCacheWatcher{inner: &sync.Map{}} - - v := NewParameterValidator(&m.Model, config.WithRegexCache(cache)) - - request, _ := http.NewRequest(http.MethodGet, "https://things.com/burgers/123/locate", nil) - pathItem, _, foundPath := paths.FindPath(request, &m.Model, cache) - - v.ValidatePathParamsWithPathItem(request, pathItem, foundPath) - - assert.EqualValues(t, 3, cache.storeCount) - assert.EqualValues(t, 3, cache.missCount) - assert.EqualValues(t, 3, cache.hitCount) - - _, found := cache.inner.Load("{burgerId}") - assert.True(t, found) + opts := &config.ValidationOptions{RegexCache: cache, PathTree: radix.BuildPathTree(&m.Model)} + + // Simple path - should NOT use regex cache (handled by radix tree) + simpleRequest, _ := http.NewRequest(http.MethodGet, "https://things.com/simple/123", nil) + pathItem, _, foundPath := paths.FindPath(simpleRequest, &m.Model, opts) + + assert.NotNil(t, pathItem) + assert.Equal(t, "/simple/{id}", foundPath) + assert.EqualValues(t, 0, cache.storeCount, "Simple paths should not use regex cache") + assert.EqualValues(t, 0, cache.hitCount+cache.missCount, "Simple paths should not touch regex cache") + + // OData path - SHOULD use regex cache (radix tree can't handle embedded params) + odataRequest, _ := http.NewRequest(http.MethodGet, "https://things.com/entities('abc')", nil) + pathItem, _, foundPath = paths.FindPath(odataRequest, &m.Model, opts) + + assert.NotNil(t, pathItem) + assert.Equal(t, "/entities('{Entity}')", foundPath) + assert.EqualValues(t, 1, cache.storeCount, "OData paths should use regex cache") + assert.EqualValues(t, 1, cache.missCount, "First OData lookup should miss cache") + + // Second OData call should hit cache + pathItem, _, _ = paths.FindPath(odataRequest, &m.Model, opts) + assert.NotNil(t, pathItem) + assert.EqualValues(t, 1, cache.storeCount, "No new stores on cache hit") + assert.EqualValues(t, 1, cache.hitCount, "Second OData lookup should hit cache") } diff --git a/parameters/query_parameters.go b/parameters/query_parameters.go index f670f57d..fea3f16b 100644 --- a/parameters/query_parameters.go +++ b/parameters/query_parameters.go @@ -27,7 +27,7 @@ const rx = `[:\/\?#\[\]\@!\$&'\(\)\*\+,;=]` var rxRxp = regexp.MustCompile(rx) func (v *paramValidator) ValidateQueryParams(request *http.Request) (bool, []*errors.ValidationError) { - pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options.RegexCache) + pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options) if len(errs) > 0 { return false, errs } diff --git a/parameters/query_parameters_test.go b/parameters/query_parameters_test.go index 9313bba7..abd95349 100644 --- a/parameters/query_parameters_test.go +++ b/parameters/query_parameters_test.go @@ -3029,7 +3029,7 @@ paths: "https://things.com/a/fishy/on/a/dishy?fishy[ocean]=atlantic&fishy[salt]=12", nil) // preset the path - path, _, pv := paths.FindPath(request, &m.Model, &sync.Map{}) + path, _, pv := paths.FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) valid, errors := v.ValidateQueryParamsWithPathItem(request, path, pv) assert.False(t, valid) diff --git a/parameters/validate_parameter.go b/parameters/validate_parameter.go index 041974e7..485c82f5 100644 --- a/parameters/validate_parameter.go +++ b/parameters/validate_parameter.go @@ -18,6 +18,7 @@ import ( stdError "errors" + "github.com/pb33f/libopenapi-validator/cache" "github.com/pb33f/libopenapi-validator/config" "github.com/pb33f/libopenapi-validator/errors" "github.com/pb33f/libopenapi-validator/helpers" @@ -33,23 +34,56 @@ func ValidateSingleParameterSchema( subValType string, o *config.ValidationOptions, ) (validationErrors []*errors.ValidationError) { - // Get the JSON Schema for the parameter definition. - jsonSchema, err := buildJsonRender(schema) - if err != nil { - return validationErrors + var jsonSchema []byte + var compiledSchema *jsonschema.Schema + var referenceSchema string + var hash uint64 + + // Check cache first + if o != nil && o.SchemaCache != nil && schema != nil && schema.GoLow() != nil { + hash = schema.GoLow().Hash() + if cached, ok := o.SchemaCache.Load(hash); ok && cached != nil && cached.CompiledSchema != nil { + compiledSchema = cached.CompiledSchema + referenceSchema = cached.ReferenceSchema + } } - // Attempt to compile the JSON Schema - jsch, err := helpers.NewCompiledSchema(name, jsonSchema, o) - if err != nil { - return validationErrors + // Cache miss - render and compile + if compiledSchema == nil { + var err error + jsonSchema, err = buildJsonRender(schema) + if err != nil { + return validationErrors + } + + compiledSchema, err = helpers.NewCompiledSchema(name, jsonSchema, o) + if err != nil { + return validationErrors + } + + // Store in cache for future use + if o != nil && o.SchemaCache != nil && schema != nil && schema.GoLow() != nil { + if hash == 0 { + hash = schema.GoLow().Hash() + } + renderCtx := base.NewInlineRenderContext() + renderedSchema, _ := schema.RenderInlineWithContext(renderCtx) + referenceSchema = string(renderedSchema) + o.SchemaCache.Store(hash, &cache.SchemaCacheEntry{ + Schema: schema, + RenderedInline: renderedSchema, + ReferenceSchema: referenceSchema, + RenderedJSON: jsonSchema, + CompiledSchema: compiledSchema, + }) + } } // Validate the object and report any errors. - scErrs := jsch.Validate(rawObject) + scErrs := compiledSchema.Validate(rawObject) var werras *jsonschema.ValidationError if stdError.As(scErrs, &werras) { - validationErrors = formatJsonSchemaValidationError(schema, werras, entity, reasonEntity, name, validationType, subValType) + validationErrors = formatJsonSchemaValidationError(schema, werras, entity, reasonEntity, name, validationType, subValType, referenceSchema) } return validationErrors } @@ -92,11 +126,28 @@ func ValidateParameterSchema( validationOptions *config.ValidationOptions, ) []*errors.ValidationError { var validationErrors []*errors.ValidationError + var jsonSchema []byte + var compiledSchema *jsonschema.Schema + var referenceSchema string + var hash uint64 + + // Check cache first + if validationOptions != nil && validationOptions.SchemaCache != nil && schema != nil && schema.GoLow() != nil { + hash = schema.GoLow().Hash() + if cached, ok := validationOptions.SchemaCache.Load(hash); ok && cached != nil && cached.CompiledSchema != nil { + jsonSchema = cached.RenderedJSON + compiledSchema = cached.CompiledSchema + referenceSchema = cached.ReferenceSchema + } + } - // 1. build a JSON render of the schema. - renderCtx := base.NewInlineRenderContext() - renderedSchema, _ := schema.RenderInlineWithContext(renderCtx) - jsonSchema, _ := utils.ConvertYAMLtoJSON(renderedSchema) + // Cache miss - render and compile + if compiledSchema == nil { + renderCtx := base.NewInlineRenderContext() + renderedSchema, _ := schema.RenderInlineWithContext(renderCtx) + jsonSchema, _ = utils.ConvertYAMLtoJSON(renderedSchema) + referenceSchema = string(renderedSchema) + } // 2. decode the object into a json blob. var decodedObj interface{} @@ -123,29 +174,48 @@ func ValidateParameterSchema( } validEncoding = true } - // 3. create a new json schema compiler and add the schema to it - jsch, err := helpers.NewCompiledSchema(name, jsonSchema, validationOptions) - if err != nil { - // schema compilation failed, return validation error instead of panicking - violation := &errors.SchemaValidationFailure{ - Reason: fmt.Sprintf("failed to compile JSON schema: %s", err.Error()), - Location: "schema compilation", - ReferenceSchema: string(jsonSchema), + // 3. create a new json schema compiler and add the schema to it (only on cache miss) + if compiledSchema == nil { + var err error + compiledSchema, err = helpers.NewCompiledSchema(name, jsonSchema, validationOptions) + if err != nil { + // schema compilation failed, return validation error instead of panicking + violation := &errors.SchemaValidationFailure{ + Reason: fmt.Sprintf("failed to compile JSON schema: %s", err.Error()), + Location: "schema compilation", + ReferenceSchema: referenceSchema, + } + validationErrors = append(validationErrors, &errors.ValidationError{ + ValidationType: validationType, + ValidationSubType: subValType, + Message: fmt.Sprintf("%s '%s' failed schema compilation", entity, name), + Reason: fmt.Sprintf("%s '%s' schema compilation failed: %s", + reasonEntity, name, err.Error()), + SpecLine: 1, + SpecCol: 0, + ParameterName: name, + SchemaValidationErrors: []*errors.SchemaValidationFailure{violation}, + HowToFix: "check the parameter schema for invalid JSON Schema syntax, complex regex patterns, or unsupported schema constructs", + Context: referenceSchema, + }) + return validationErrors + } + + // Store in cache for future use + if validationOptions != nil && validationOptions.SchemaCache != nil && schema != nil && schema.GoLow() != nil { + if hash == 0 { + hash = schema.GoLow().Hash() + } + renderCtx := base.NewInlineRenderContext() + renderedSchema, _ := schema.RenderInlineWithContext(renderCtx) + validationOptions.SchemaCache.Store(hash, &cache.SchemaCacheEntry{ + Schema: schema, + RenderedInline: renderedSchema, + ReferenceSchema: referenceSchema, + RenderedJSON: jsonSchema, + CompiledSchema: compiledSchema, + }) } - validationErrors = append(validationErrors, &errors.ValidationError{ - ValidationType: validationType, - ValidationSubType: subValType, - Message: fmt.Sprintf("%s '%s' failed schema compilation", entity, name), - Reason: fmt.Sprintf("%s '%s' schema compilation failed: %s", - reasonEntity, name, err.Error()), - SpecLine: 1, - SpecCol: 0, - ParameterName: name, - SchemaValidationErrors: []*errors.SchemaValidationFailure{violation}, - HowToFix: "check the parameter schema for invalid JSON Schema syntax, complex regex patterns, or unsupported schema constructs", - Context: string(jsonSchema), - }) - return validationErrors } // 4. validate the object against the schema @@ -183,13 +253,13 @@ func ValidateParameterSchema( } } if !skip { - scErrs = jsch.Validate(p) + scErrs = compiledSchema.Validate(p) } } } var werras *jsonschema.ValidationError if stdError.As(scErrs, &werras) { - validationErrors = formatJsonSchemaValidationError(schema, werras, entity, reasonEntity, name, validationType, subValType) + validationErrors = formatJsonSchemaValidationError(schema, werras, entity, reasonEntity, name, validationType, subValType, referenceSchema) } // if there are no validationErrors, check that the supplied value is even JSON @@ -213,7 +283,7 @@ func ValidateParameterSchema( return validationErrors } -func formatJsonSchemaValidationError(schema *base.Schema, scErrs *jsonschema.ValidationError, entity string, reasonEntity string, name string, validationType string, subValType string) (validationErrors []*errors.ValidationError) { +func formatJsonSchemaValidationError(schema *base.Schema, scErrs *jsonschema.ValidationError, entity string, reasonEntity string, name string, validationType string, subValType string, referenceSchema string) (validationErrors []*errors.ValidationError) { // flatten the validationErrors schFlatErrs := scErrs.BasicOutput().Errors var schemaValidationErrors []*errors.SchemaValidationFailure @@ -221,7 +291,7 @@ func formatJsonSchemaValidationError(schema *base.Schema, scErrs *jsonschema.Val er := schFlatErrs[q] errMsg := er.Error.Kind.LocalizedString(message.NewPrinter(language.Tag{})) - if er.KeywordLocation == "" || helpers.IgnoreRegex.MatchString(errMsg) { + if er.KeywordLocation == "" || helpers.ShouldIgnoreError(errMsg) { continue // ignore this error, it's not useful } @@ -233,7 +303,9 @@ func formatJsonSchemaValidationError(schema *base.Schema, scErrs *jsonschema.Val InstancePath: helpers.ConvertStringLocationToPathSegments(er.InstanceLocation), OriginalError: scErrs, } - if schema != nil { + if referenceSchema != "" { + fail.ReferenceSchema = referenceSchema + } else if schema != nil { renderCtx := base.NewInlineRenderContext() rendered, err := schema.RenderInlineWithContext(renderCtx) if err == nil && rendered != nil { diff --git a/parameters/validate_security.go b/parameters/validate_security.go index e5ce0989..c5b70e46 100644 --- a/parameters/validate_security.go +++ b/parameters/validate_security.go @@ -9,16 +9,17 @@ import ( "strings" "github.com/pb33f/libopenapi/datamodel/high/base" - v3 "github.com/pb33f/libopenapi/datamodel/high/v3" "github.com/pb33f/libopenapi/orderedmap" + v3 "github.com/pb33f/libopenapi/datamodel/high/v3" + "github.com/pb33f/libopenapi-validator/errors" "github.com/pb33f/libopenapi-validator/helpers" "github.com/pb33f/libopenapi-validator/paths" ) func (v *paramValidator) ValidateSecurity(request *http.Request) (bool, []*errors.ValidationError) { - pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options.RegexCache) + pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options) if len(errs) > 0 { return false, errs } diff --git a/parameters/validate_security_test.go b/parameters/validate_security_test.go index 8b90212a..7de9fe23 100644 --- a/parameters/validate_security_test.go +++ b/parameters/validate_security_test.go @@ -381,7 +381,7 @@ paths: v := NewParameterValidator(&m.Model) request, _ := http.NewRequest(http.MethodPost, "https://things.com/beef", nil) - pathItem, _, pv := paths.FindPath(request, &m.Model, &sync.Map{}) + pathItem, _, pv := paths.FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) valid, errors := v.ValidateSecurityWithPathItem(request, pathItem, pv) assert.False(t, valid) @@ -644,7 +644,7 @@ components: v := NewParameterValidator(&m.Model, config.WithoutSecurityValidation()) request, _ := http.NewRequest(http.MethodPost, "https://things.com/products", nil) - pathItem, errs, pv := paths.FindPath(request, &m.Model, &sync.Map{}) + pathItem, errs, pv := paths.FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.Nil(t, errs) valid, errors := v.ValidateSecurityWithPathItem(request, pathItem, pv) diff --git a/path_matcher.go b/path_matcher.go new file mode 100644 index 00000000..b28d9b6b --- /dev/null +++ b/path_matcher.go @@ -0,0 +1,126 @@ +// Copyright 2025 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package validator + +import ( + "strings" + + v3 "github.com/pb33f/libopenapi/datamodel/high/v3" + + "github.com/pb33f/libopenapi-validator/config" + "github.com/pb33f/libopenapi-validator/helpers" + "github.com/pb33f/libopenapi-validator/paths" + "github.com/pb33f/libopenapi-validator/radix" +) + +// resolvedRoute carries everything learned during path matching. +// This is the single source of truth for "what matched and what was extracted." +type resolvedRoute struct { + pathItem *v3.PathItem + matchedPath string // path template, e.g. "/users/{id}" + pathParams map[string]string // extracted param values, nil if not extracted +} + +// pathMatcher finds the matching path for an incoming request path. +// Implementations are composed into a chain — first match wins. +type pathMatcher interface { + Match(path string, doc *v3.Document) *resolvedRoute +} + +// matcherChain tries each matcher in order. First match wins. +type matcherChain []pathMatcher + +func (c matcherChain) Match(path string, doc *v3.Document) *resolvedRoute { + for _, m := range c { + if result := m.Match(path, doc); result != nil { + return result + } + } + return nil +} + +// radixMatcher uses the radix tree for O(k) path matching with parameter extraction. +type radixMatcher struct { + pathLookup radix.PathLookup +} + +func (m *radixMatcher) Match(path string, _ *v3.Document) *resolvedRoute { + if m.pathLookup == nil { + return nil + } + pathItem, matchedPath, params, found := m.pathLookup.LookupWithParams(path) + if !found { + return nil + } + return &resolvedRoute{ + pathItem: pathItem, + matchedPath: matchedPath, + pathParams: params, + } +} + +// regexMatcher uses regex-based matching for complex paths (matrix, label, OData, etc.). +// This is the fallback when radix matching doesn't find a match. +type regexMatcher struct { + regexCache config.RegexCache +} + +func (m *regexMatcher) Match(path string, doc *v3.Document) *resolvedRoute { + if doc == nil || doc.Paths == nil || doc.Paths.PathItems == nil { + return nil + } + pathItem, matchedPath, found := paths.FindPathRegex(path, doc, m.regexCache) + if !found { + return nil + } + return &resolvedRoute{ + pathItem: pathItem, + matchedPath: matchedPath, + pathParams: extractPathParams(matchedPath, path), + } +} + +// extractPathParams extracts path parameter values by comparing a matched template +// (e.g. "/users/{id}/posts/{postId}") with the actual request path (e.g. "/users/123/posts/456"). +// It uses BraceIndices to find parameter names in each template segment and maps them to +// the corresponding request path segment values. Returns nil if no parameters are found. +func extractPathParams(template, requestPath string) map[string]string { + templateSegs := strings.Split(template, "/") + requestSegs := strings.Split(requestPath, "/") + + // Strip leading empty segments from the split + if len(templateSegs) > 0 && templateSegs[0] == "" { + templateSegs = templateSegs[1:] + } + if len(requestSegs) > 0 && requestSegs[0] == "" { + requestSegs = requestSegs[1:] + } + + if len(templateSegs) != len(requestSegs) { + return nil + } + + var params map[string]string + for i, seg := range templateSegs { + idxs, err := helpers.BraceIndices(seg) + if err != nil || len(idxs) == 0 { + continue + } + // Extract parameter names from brace pairs in this segment. + for j := 0; j < len(idxs); j += 2 { + // Content between braces, e.g. "id" or "id:[0-9]+" + content := seg[idxs[j]+1 : idxs[j+1]-1] + // Strip optional pattern after ":" + name, _, _ := strings.Cut(content, ":") + if name == "" { + continue + } + if params == nil { + params = make(map[string]string) + } + params[name] = requestSegs[i] + } + } + return params +} diff --git a/path_matcher_test.go b/path_matcher_test.go new file mode 100644 index 00000000..d27e4f9d --- /dev/null +++ b/path_matcher_test.go @@ -0,0 +1,300 @@ +// Copyright 2025 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package validator + +import ( + "sync" + "testing" + + "github.com/pb33f/libopenapi" + "github.com/pb33f/libopenapi/orderedmap" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + v3 "github.com/pb33f/libopenapi/datamodel/high/v3" + + "github.com/pb33f/libopenapi-validator/radix" +) + +func createTestDocument(paths map[string]bool) *v3.Document { + doc := &v3.Document{ + Paths: &v3.Paths{ + PathItems: orderedmap.New[string, *v3.PathItem](), + }, + } + for path := range paths { + pathItem := &v3.PathItem{ + Get: &v3.Operation{}, + } + doc.Paths.PathItems.Set(path, pathItem) + } + return doc +} + +func TestMatcherChain_Empty(t *testing.T) { + chain := matcherChain(nil) + result := chain.Match("/users", createTestDocument(map[string]bool{"/users": true})) + assert.Nil(t, result, "empty chain should return nil") +} + +func TestMatcherChain_SingleMatcher(t *testing.T) { + doc := createTestDocument(map[string]bool{"/users/{id}": true}) + tree := radix.BuildPathTree(doc) + + chain := matcherChain{ + &radixMatcher{pathLookup: tree}, + } + + result := chain.Match("/users/123", doc) + require.NotNil(t, result, "should find match") + assert.NotNil(t, result.pathItem, "pathItem should not be nil") + assert.Equal(t, "/users/{id}", result.matchedPath) + assert.Equal(t, map[string]string{"id": "123"}, result.pathParams) +} + +func TestMatcherChain_FirstWins(t *testing.T) { + doc := createTestDocument(map[string]bool{"/users/{id}": true}) + tree := radix.BuildPathTree(doc) + + radixM := &radixMatcher{pathLookup: tree} + regexM := ®exMatcher{regexCache: &sync.Map{}} + + chain := matcherChain{radixM, regexM} + + result := chain.Match("/users/123", doc) + require.NotNil(t, result, "should find match") + assert.Equal(t, "/users/{id}", result.matchedPath) +} + +func TestMatcherChain_Fallback(t *testing.T) { + spec := `openapi: 3.1.0 +info: + title: Test API + version: 1.0.0 +paths: + /users/{id}: + get: + responses: + '200': + description: OK + /matrix;id=123: + get: + responses: + '200': + description: OK +` + doc, err := libopenapi.NewDocument([]byte(spec)) + require.NoError(t, err) + + model, errs := doc.BuildV3Model() + require.Empty(t, errs) + + tree := radix.BuildPathTree(&model.Model) + + radixM := &radixMatcher{pathLookup: tree} + regexM := ®exMatcher{regexCache: &sync.Map{}} + + chain := matcherChain{radixM, regexM} + + result := chain.Match("/matrix;id=123", &model.Model) + require.NotNil(t, result, "should find match via regex fallback") + assert.Equal(t, "/matrix;id=123", result.matchedPath) +} + +func TestRadixMatcher_NilPathLookup(t *testing.T) { + matcher := &radixMatcher{pathLookup: nil} + result := matcher.Match("/users/123", createTestDocument(map[string]bool{"/users/{id}": true})) + assert.Nil(t, result, "nil PathLookup should return nil") +} + +func TestRadixMatcher_WithMatch(t *testing.T) { + doc := createTestDocument(map[string]bool{"/users/{id}": true}) + tree := radix.BuildPathTree(doc) + + matcher := &radixMatcher{pathLookup: tree} + result := matcher.Match("/users/123", doc) + + require.NotNil(t, result, "should find match") + assert.NotNil(t, result.pathItem, "pathItem should not be nil") + assert.Equal(t, "/users/{id}", result.matchedPath) + assert.Equal(t, map[string]string{"id": "123"}, result.pathParams) +} + +func TestRadixMatcher_NoMatch(t *testing.T) { + doc := createTestDocument(map[string]bool{"/users/{id}": true}) + tree := radix.BuildPathTree(doc) + + matcher := &radixMatcher{pathLookup: tree} + result := matcher.Match("/posts/123", doc) + + assert.Nil(t, result, "should not find match") +} + +func TestRegexMatcher_WithMatch(t *testing.T) { + spec := `openapi: 3.1.0 +info: + title: Test API + version: 1.0.0 +paths: + /users/{id}: + get: + responses: + '200': + description: OK +` + doc, err := libopenapi.NewDocument([]byte(spec)) + require.NoError(t, err) + + model, errs := doc.BuildV3Model() + require.Empty(t, errs) + + matcher := ®exMatcher{regexCache: &sync.Map{}} + result := matcher.Match("/users/123", &model.Model) + + require.NotNil(t, result, "should find match") + assert.NotNil(t, result.pathItem, "pathItem should not be nil") + assert.Equal(t, "/users/{id}", result.matchedPath) + assert.Equal(t, map[string]string{"id": "123"}, result.pathParams) +} + +func TestRegexMatcher_ExtractsMultipleParams(t *testing.T) { + spec := `openapi: 3.1.0 +info: + title: Test API + version: 1.0.0 +paths: + /users/{userId}/posts/{postId}: + get: + responses: + '200': + description: OK +` + doc, err := libopenapi.NewDocument([]byte(spec)) + require.NoError(t, err) + + model, errs := doc.BuildV3Model() + require.Empty(t, errs) + + matcher := ®exMatcher{regexCache: &sync.Map{}} + result := matcher.Match("/users/abc/posts/456", &model.Model) + + require.NotNil(t, result, "should find match") + assert.Equal(t, "/users/{userId}/posts/{postId}", result.matchedPath) + assert.Equal(t, map[string]string{"userId": "abc", "postId": "456"}, result.pathParams) +} + +func TestRegexMatcher_NoParams(t *testing.T) { + spec := `openapi: 3.1.0 +info: + title: Test API + version: 1.0.0 +paths: + /health: + get: + responses: + '200': + description: OK +` + doc, err := libopenapi.NewDocument([]byte(spec)) + require.NoError(t, err) + + model, errs := doc.BuildV3Model() + require.Empty(t, errs) + + matcher := ®exMatcher{regexCache: &sync.Map{}} + result := matcher.Match("/health", &model.Model) + + require.NotNil(t, result, "should find match") + assert.Equal(t, "/health", result.matchedPath) + assert.Nil(t, result.pathParams, "literal paths should have nil params") +} + +func TestRegexMatcher_NilDoc(t *testing.T) { + matcher := ®exMatcher{regexCache: &sync.Map{}} + result := matcher.Match("/users/123", nil) + assert.Nil(t, result, "nil doc should return nil") +} + +func TestRegexMatcher_NilPaths(t *testing.T) { + doc := &v3.Document{} + matcher := ®exMatcher{regexCache: &sync.Map{}} + result := matcher.Match("/users/123", doc) + assert.Nil(t, result, "nil paths should return nil") +} + +func TestRegexMatcher_NoMatch(t *testing.T) { + spec := `openapi: 3.1.0 +info: + title: Test API + version: 1.0.0 +paths: + /users/{id}: + get: + responses: + '200': + description: OK +` + doc, err := libopenapi.NewDocument([]byte(spec)) + require.NoError(t, err) + + model, errs := doc.BuildV3Model() + require.Empty(t, errs) + + matcher := ®exMatcher{regexCache: &sync.Map{}} + result := matcher.Match("/posts/123", &model.Model) + assert.Nil(t, result, "should not find match") +} + +func TestExtractPathParams(t *testing.T) { + tests := []struct { + name string + template string + requestPath string + expected map[string]string + }{ + { + name: "single param", + template: "/users/{id}", + requestPath: "/users/123", + expected: map[string]string{"id": "123"}, + }, + { + name: "multiple params", + template: "/users/{userId}/posts/{postId}", + requestPath: "/users/abc/posts/456", + expected: map[string]string{"userId": "abc", "postId": "456"}, + }, + { + name: "no params", + template: "/health", + requestPath: "/health", + expected: nil, + }, + { + name: "param with pattern", + template: "/orders/{id:[0-9]+}", + requestPath: "/orders/42", + expected: map[string]string{"id": "42"}, + }, + { + name: "segment count mismatch returns nil", + template: "/users/{id}", + requestPath: "/users/123/extra", + expected: nil, + }, + { + name: "deep path with mixed segments", + template: "/api/v1/{resource}/items/{itemId}", + requestPath: "/api/v1/widgets/items/99", + expected: map[string]string{"resource": "widgets", "itemId": "99"}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + result := extractPathParams(tt.template, tt.requestPath) + assert.Equal(t, tt.expected, result) + }) + } +} diff --git a/paths/paths.go b/paths/paths.go index d8e3806a..7765861b 100644 --- a/paths/paths.go +++ b/paths/paths.go @@ -26,17 +26,39 @@ import ( // The third return value will be the path that was found in the document, as it pertains to the contract, so all path // parameters will not have been replaced with their values from the request - allowing model lookups. // +// This function first tries a fast O(k) radix tree lookup (where k is path depth). If the radix tree +// doesn't find a match, it falls back to regex-based matching which handles complex path patterns +// like matrix-style ({;param}), label-style ({.param}), and OData-style (entities('{Entity}')). +// // Path matching follows the OpenAPI specification: literal (concrete) paths take precedence over // parameterized paths, regardless of definition order in the specification. -func FindPath(request *http.Request, document *v3.Document, regexCache config.RegexCache) (*v3.PathItem, []*errors.ValidationError, string) { - basePaths := getBasePaths(document) +func FindPath(request *http.Request, document *v3.Document, options *config.ValidationOptions) (*v3.PathItem, []*errors.ValidationError, string) { stripped := StripRequestPath(request, document) + // Fast path: try radix tree first (O(k) where k = path depth) + // If no path lookup is provided, we will fall back to regex-based matching. + if options != nil && options.PathTree != nil { + if pathItem, matchedPath, found := options.PathTree.Lookup(stripped); found { + if pathHasMethod(pathItem, request.Method) { + return pathItem, nil, matchedPath + } + return pathItem, missingOperationError(request, matchedPath), matchedPath + } + } + + // Slow path: fall back to regex matching for complex paths (matrix, label, OData, etc.) + basePaths := getBasePaths(document) + reqPathSegments := strings.Split(stripped, "/") if reqPathSegments[0] == "" { reqPathSegments = reqPathSegments[1:] } + var regexCache config.RegexCache + if options != nil { + regexCache = options.RegexCache + } + candidates := make([]pathCandidate, 0, document.Paths.PathItems.Len()) for pair := orderedmap.First(document.Paths.PathItems); pair != nil; pair = pair.Next() { @@ -92,18 +114,61 @@ func FindPath(request *http.Request, document *v3.Document, regexCache config.Re } // path matches exist but none have the required method - validationErrors := []*errors.ValidationError{{ - ValidationType: helpers.PathValidation, - ValidationSubType: helpers.ValidationMissingOperation, - Message: fmt.Sprintf("%s Path '%s' not found", request.Method, request.URL.Path), - Reason: fmt.Sprintf("The %s method for that path does not exist in the specification", - request.Method), - SpecLine: -1, - SpecCol: -1, - HowToFix: errors.HowToFixPath, - }} - errors.PopulateValidationErrors(validationErrors, request, bestOverall.path) - return bestOverall.pathItem, validationErrors, bestOverall.path + return bestOverall.pathItem, missingOperationError(request, bestOverall.path), bestOverall.path +} + +// FindPathRegex performs regex-based path matching against the document paths. +// It tries to match the stripped request path against all path templates using regex. +// Returns the best matching PathItem, its path template, and whether a match was found. +// This does NOT check HTTP methods — the caller must do that separately. +func FindPathRegex(stripped string, doc *v3.Document, regexCache config.RegexCache) (*v3.PathItem, string, bool) { + if doc == nil || doc.Paths == nil || doc.Paths.PathItems == nil { + return nil, "", false + } + + basePaths := getBasePaths(doc) + + reqPathSegments := strings.Split(stripped, "/") + if len(reqPathSegments) > 0 && reqPathSegments[0] == "" { + reqPathSegments = reqPathSegments[1:] + } + + candidates := make([]pathCandidate, 0, doc.Paths.PathItems.Len()) + + for pair := orderedmap.First(doc.Paths.PathItems); pair != nil; pair = pair.Next() { + path := pair.Key() + pathItem := pair.Value() + + pathForMatching := normalizePathForMatching(path, stripped) + + segs := strings.Split(pathForMatching, "/") + if len(segs) > 0 && segs[0] == "" { + segs = segs[1:] + } + + ok := comparePaths(segs, reqPathSegments, basePaths, regexCache) + if !ok { + continue + } + + score := computeSpecificityScore(path) + candidates = append(candidates, pathCandidate{ + pathItem: pathItem, + path: path, + score: score, + hasMethod: true, // We don't check method here — always true for selection + }) + } + + if len(candidates) == 0 { + return nil, "", false + } + + _, best := selectMatches(candidates) + if best != nil { + return best.pathItem, best.path, true + } + return nil, "", false } // normalizePathForMatching removes the fragment from a path template unless @@ -220,3 +285,19 @@ func comparePaths(mapped, requested, basePaths []string, regexCache config.Regex r := filepath.Join(requested...) return checkPathAgainstBase(l, r, basePaths) } + +// missingOperationError returns a validation error for when a path was found but the HTTP method doesn't exist. +func missingOperationError(request *http.Request, matchedPath string) []*errors.ValidationError { + validationErrors := []*errors.ValidationError{{ + ValidationType: helpers.PathValidation, + ValidationSubType: helpers.ValidationMissingOperation, + Message: fmt.Sprintf("%s Path '%s' not found", request.Method, request.URL.Path), + Reason: fmt.Sprintf("The %s method for that path does not exist in the specification", + request.Method), + SpecLine: -1, + SpecCol: -1, + HowToFix: errors.HowToFixPath, + }} + errors.PopulateValidationErrors(validationErrors, request, matchedPath) + return validationErrors +} diff --git a/paths/paths_test.go b/paths/paths_test.go index 32f5f754..f13ad3c1 100644 --- a/paths/paths_test.go +++ b/paths/paths_test.go @@ -13,6 +13,8 @@ import ( "github.com/pb33f/libopenapi" "github.com/stretchr/testify/assert" + + "github.com/pb33f/libopenapi-validator/config" ) func TestNewValidator_BadParam(t *testing.T) { @@ -83,7 +85,7 @@ paths: request, _ := http.NewRequest(http.MethodPatch, "https://things.com/burgers/bish=bosh,wish=wash/locate", nil) - pathItem, _, _ := FindPath(request, &m.Model, &sync.Map{}) + pathItem, _, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.NotNil(t, pathItem) assert.Equal(t, "locateBurger", pathItem.Patch.OperationId) } @@ -127,7 +129,7 @@ func TestNewValidator_FindPathDelete(t *testing.T) { m, _ := doc.BuildV3Model() request, _ := http.NewRequest(http.MethodDelete, "https://things.com/pet/12334", nil) - pathItem, _, _ := FindPath(request, &m.Model, &sync.Map{}) + pathItem, _, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.NotNil(t, pathItem) } @@ -144,7 +146,7 @@ paths: request, _ := http.NewRequest(http.MethodPatch, "https://things.com/burgers/12345", nil) - pathItem, _, _ := FindPath(request, &m.Model, &sync.Map{}) + pathItem, _, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.NotNil(t, pathItem) assert.Equal(t, "locateBurger", pathItem.Patch.OperationId) } @@ -180,7 +182,7 @@ paths: request, _ := http.NewRequest(http.MethodTrace, "https://things.com/burgers/12345", nil) - pathItem, _, _ := FindPath(request, &m.Model, &sync.Map{}) + pathItem, _, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.NotNil(t, pathItem) assert.Equal(t, "locateBurger", pathItem.Trace.OperationId) } @@ -199,7 +201,7 @@ paths: request, _ := http.NewRequest(http.MethodPut, "https://things.com/burgers/12345", nil) - pathItem, _, _ := FindPath(request, &m.Model, &sync.Map{}) + pathItem, _, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.NotNil(t, pathItem) assert.Equal(t, "locateBurger", pathItem.Put.OperationId) } @@ -239,13 +241,13 @@ paths: // check against base1 request, _ := http.NewRequest(http.MethodPost, "https://things.com/base1/user", nil) - pathItem, _, _ := FindPath(request, &m.Model, &sync.Map{}) + pathItem, _, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.NotNil(t, pathItem) assert.Equal(t, "addUser", pathItem.Post.OperationId) // check against base2 request, _ = http.NewRequest(http.MethodPost, "https://things.com/base2/user", nil) - pathItem, _, _ = FindPath(request, &m.Model, &sync.Map{}) + pathItem, _, _ = FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.NotNil(t, pathItem) assert.Equal(t, "addUser", pathItem.Post.OperationId) @@ -271,7 +273,7 @@ paths: // check against a deeper base request, _ := http.NewRequest(http.MethodPost, "https://things.com/base3/base4/base5/base6/user/1234/thing/abcd", nil) - pathItem, _, _ := FindPath(request, &m.Model, &sync.Map{}) + pathItem, _, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.NotNil(t, pathItem) assert.Equal(t, "addUser", pathItem.Post.OperationId) } @@ -357,7 +359,7 @@ paths: request, _ := http.NewRequest(http.MethodPut, "https://things.com/pizza/burger", nil) - _, errs, _ := FindPath(request, &m.Model, &sync.Map{}) + _, errs, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.Len(t, errs, 0) } @@ -380,7 +382,7 @@ paths: request, _ := http.NewRequest(http.MethodPost, "https://things.com/pizza/1234", nil) - _, errs, _ := FindPath(request, &m.Model, &sync.Map{}) + _, errs, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.Len(t, errs, 1) assert.Equal(t, "POST Path '/pizza/1234' not found", errs[0].Message) @@ -404,7 +406,7 @@ paths: request, _ := http.NewRequest(http.MethodPost, "https://things.com/pizza/1234", nil) - _, errs, _ := FindPath(request, &m.Model, &sync.Map{}) + _, errs, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.Len(t, errs, 1) assert.Equal(t, "POST Path '/pizza/1234' not found", errs[0].Message) @@ -422,7 +424,7 @@ paths: request, _ := http.NewRequest(http.MethodPatch, "https://things.com/pizza/burger", nil) - _, errs, _ := FindPath(request, &m.Model, &sync.Map{}) + _, errs, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.Len(t, errs, 0) } @@ -480,7 +482,7 @@ paths: request, _ := http.NewRequest(http.MethodOptions, "https://things.com/pizza/burger", nil) - _, errs, _ := FindPath(request, &m.Model, &sync.Map{}) + _, errs, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.Len(t, errs, 0) } @@ -514,7 +516,7 @@ paths: request, _ := http.NewRequest(http.MethodTrace, "https://things.com/pizza/burger", nil) - _, errs, _ := FindPath(request, &m.Model, &sync.Map{}) + _, errs, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.Len(t, errs, 0) } @@ -585,7 +587,7 @@ paths: request, _ := http.NewRequest(http.MethodPut, "https://things.com/pizza/1234", nil) - _, errs, _ := FindPath(request, &m.Model, &sync.Map{}) + _, errs, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.Len(t, errs, 1) assert.Equal(t, "PUT Path '/pizza/1234' not found", errs[0].Message) @@ -607,13 +609,13 @@ paths: request, _ := http.NewRequest(http.MethodPost, "https://things.com/hashy#one", nil) - pathItem, errs, _ := FindPath(request, &m.Model, &sync.Map{}) + pathItem, errs, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.Len(t, errs, 0) assert.NotNil(t, pathItem) assert.Equal(t, "one", pathItem.Post.OperationId) request, _ = http.NewRequest(http.MethodPost, "https://things.com/hashy#two", nil) - pathItem, errs, _ = FindPath(request, &m.Model, &sync.Map{}) + pathItem, errs, _ = FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.Len(t, errs, 0) assert.NotNil(t, pathItem) assert.Equal(t, "two", pathItem.Post.OperationId) @@ -784,21 +786,21 @@ paths: request, _ := http.NewRequest(http.MethodGet, "https://things.com/entities('1')", nil) - regexCache := &sync.Map{} + opts := &config.ValidationOptions{RegexCache: &sync.Map{}} - pathItem, _, _ := FindPath(request, &m.Model, regexCache) + pathItem, _, _ := FindPath(request, &m.Model, opts) assert.NotNil(t, pathItem) assert.Equal(t, "one", pathItem.Get.OperationId) request, _ = http.NewRequest(http.MethodGet, "https://things.com/orders(RelationshipNumber='1234',ValidityEndDate=datetime'1492041600000')", nil) - pathItem, _, _ = FindPath(request, &m.Model, regexCache) + pathItem, _, _ = FindPath(request, &m.Model, opts) assert.NotNil(t, pathItem) assert.Equal(t, "one", pathItem.Get.OperationId) request, _ = http.NewRequest(http.MethodGet, "https://things.com/orders(RelationshipNumber='dummy',ValidityEndDate=datetime'1492041600000')", nil) - pathItem, _, _ = FindPath(request, &m.Model, regexCache) + pathItem, _, _ = FindPath(request, &m.Model, opts) assert.NotNil(t, pathItem) assert.Equal(t, "one", pathItem.Get.OperationId) } @@ -822,25 +824,28 @@ paths: request, _ := http.NewRequest(http.MethodGet, "https://things.com/entities('1')", nil) - _, errs, _ := FindPath(request, &m.Model, &sync.Map{}) + _, errs, _ := FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.NotEmpty(t, errs) } -func TestNewValidator_FindPathWithRegexpCache(t *testing.T) { +func TestNewValidator_FindPathWithRegexpCache_ODataPath(t *testing.T) { + // OData-style paths have embedded parameters that the radix tree can't handle, + // so they fall back to regex matching which DOES populate the cache. spec := `openapi: 3.1.0 paths: - /pizza/{sauce}/{fill}/hamburger/pizza: + /entities('{Entity}')/items: head: - operationId: locateBurger` + operationId: getEntityItems` doc, _ := libopenapi.NewDocument([]byte(spec)) m, _ := doc.BuildV3Model() - request, _ := http.NewRequest(http.MethodHead, "https://things.com/pizza/tomato/pepperoni/hamburger/pizza", nil) + request, _ := http.NewRequest(http.MethodHead, "https://things.com/entities('123')/items", nil) syncMap := sync.Map{} + opts := &config.ValidationOptions{RegexCache: &syncMap} - _, errs, _ := FindPath(request, &m.Model, &syncMap) + _, errs, _ := FindPath(request, &m.Model, opts) keys := []string{} addresses := make(map[string]bool) @@ -851,13 +856,14 @@ paths: return true }) - cached, found := syncMap.Load("pizza") + // The OData segment should be cached + cached, found := syncMap.Load("entities('{Entity}')") - assert.True(t, found) - assert.True(t, cached.(*regexp.Regexp).MatchString("pizza")) + assert.True(t, found, "OData path segment should be in regex cache") + assert.NotNil(t, cached, "Cached regex should not be nil") + assert.True(t, cached.(*regexp.Regexp).MatchString("entities('123')"), "Cached regex should match") assert.Len(t, errs, 0) - assert.Len(t, keys, 4) - assert.Len(t, addresses, 3) + assert.Len(t, keys, 2, "Should have 2 path segments cached") } // Test cases for path precedence - Issue #181 @@ -1023,38 +1029,6 @@ paths: } } -func TestFindPath_TieBreaker_DefinitionOrder(t *testing.T) { - // When two paths have equal specificity (same number of literals/params), - // the first defined path should win - spec := `openapi: 3.1.0 -info: - title: Path Precedence Test - version: 1.0.0 -paths: - /pets/{petId}: - get: - operationId: getPetById - responses: - '200': - description: OK - /pets/{petName}: - get: - operationId: getPetByName - responses: - '200': - description: OK -` - doc, _ := libopenapi.NewDocument([]byte(spec)) - m, _ := doc.BuildV3Model() - - request, _ := http.NewRequest(http.MethodGet, "https://api.com/pets/fluffy", nil) - pathItem, _, foundPath := FindPath(request, &m.Model, nil) - - // First defined path wins when scores are equal - assert.Equal(t, "getPetById", pathItem.Get.OperationId) - assert.Equal(t, "/pets/{petId}", foundPath) -} - func TestFindPath_PetsMinePrecedence(t *testing.T) { // Classic example from OpenAPI spec: /pets/mine vs /pets/{petId} spec := `openapi: 3.1.0 @@ -1250,11 +1224,11 @@ paths: doc, _ := libopenapi.NewDocument([]byte(spec)) m, _ := doc.BuildV3Model() - regexCache := &sync.Map{} + opts := &config.ValidationOptions{RegexCache: &sync.Map{}} // First request - populates cache request, _ := http.NewRequest(http.MethodGet, "https://api.com/Messages/Operations", nil) - pathItem, errs, foundPath := FindPath(request, &m.Model, regexCache) + pathItem, errs, foundPath := FindPath(request, &m.Model, opts) assert.Nil(t, errs) assert.Equal(t, "getOperations", pathItem.Get.OperationId) @@ -1262,7 +1236,7 @@ paths: // Second request - uses cache request, _ = http.NewRequest(http.MethodGet, "https://api.com/Messages/12345", nil) - pathItem, errs, foundPath = FindPath(request, &m.Model, regexCache) + pathItem, errs, foundPath = FindPath(request, &m.Model, opts) assert.Nil(t, errs) assert.Equal(t, "getMessage", pathItem.Get.OperationId) @@ -1270,7 +1244,7 @@ paths: // Third request - still works correctly request, _ = http.NewRequest(http.MethodGet, "https://api.com/Messages/Operations", nil) - pathItem, errs, foundPath = FindPath(request, &m.Model, regexCache) + pathItem, errs, foundPath = FindPath(request, &m.Model, opts) assert.Nil(t, errs) assert.Equal(t, "getOperations", pathItem.Get.OperationId) @@ -1361,3 +1335,178 @@ paths: assert.Equal(t, "postHashy", pathItem.Post.OperationId) assert.Equal(t, "/hashy#section", foundPath) } + +func TestFindPath_NilDocument(t *testing.T) { + // Passing a nil document is a programming error and will panic. + // This test verifies that behavior (callers should not pass nil). + request, _ := http.NewRequest(http.MethodGet, "https://api.com/test", nil) + + assert.Panics(t, func() { + FindPath(request, nil, nil) + }, "FindPath should panic when document is nil") +} + +func TestFindPath_NilPaths(t *testing.T) { + // A spec without paths will have nil Paths - this is a programming error + spec := `openapi: 3.1.0 +info: + title: No Paths Test + version: 1.0.0 +` + doc, _ := libopenapi.NewDocument([]byte(spec)) + m, _ := doc.BuildV3Model() + + request, _ := http.NewRequest(http.MethodGet, "https://api.com/test", nil) + + // This panics because the original code doesn't handle nil Paths either + assert.Panics(t, func() { + FindPath(request, &m.Model, nil) + }, "FindPath should panic when document has no paths") +} + +func TestFindPath_RequestWithFragment(t *testing.T) { + // Test when request URL contains a fragment - normalizePathForMatching should NOT strip template fragment + spec := `openapi: 3.1.0 +info: + title: Fragment Test + version: 1.0.0 +paths: + /docs#section: + get: + operationId: getDocs + responses: + '200': + description: OK +` + doc, _ := libopenapi.NewDocument([]byte(spec)) + m, _ := doc.BuildV3Model() + + // Request WITH fragment should match path WITH same fragment + request, _ := http.NewRequest(http.MethodGet, "https://api.com/docs#section", nil) + pathItem, errs, foundPath := FindPath(request, &m.Model, nil) + + assert.Nil(t, errs) + assert.NotNil(t, pathItem) + assert.Equal(t, "getDocs", pathItem.Get.OperationId) + assert.Equal(t, "/docs#section", foundPath) +} + +func TestFindPath_RadixTree_MethodMismatch(t *testing.T) { + // Test that radix tree path match with wrong method returns proper error + // This covers lines 72-83 in FindPath (missingOperation from radix tree) + spec := `openapi: 3.1.0 +info: + title: Method Mismatch Test + version: 1.0.0 +paths: + /users/{id}: + get: + operationId: getUser + responses: + '200': + description: OK +` + doc, _ := libopenapi.NewDocument([]byte(spec)) + m, _ := doc.BuildV3Model() + + // POST to a simple path that only has GET - radix tree handles this + request, _ := http.NewRequest(http.MethodPost, "https://api.com/users/123", nil) + pathItem, errs, foundPath := FindPath(request, &m.Model, nil) + + assert.NotNil(t, pathItem) + assert.NotNil(t, errs) + assert.Len(t, errs, 1) + assert.Equal(t, "missingOperation", errs[0].ValidationSubType) + assert.Equal(t, "/users/{id}", foundPath) +} + +func TestFindPath_RequestWithFragment_MatchesPathWithFragment(t *testing.T) { + // Test normalizePathForMatching when REQUEST has fragment + // This covers lines 167-168: if strings.Contains(requestPath, "#") { return path } + // Using OData-style path to force regex fallback (radix tree can't handle embedded params) + spec := `openapi: 3.1.0 +info: + title: Fragment Test + version: 1.0.0 +paths: + /entities('{id}')#section1: + get: + operationId: getSection1 + /entities('{id}')#section2: + get: + operationId: getSection2 +` + doc, _ := libopenapi.NewDocument([]byte(spec)) + m, _ := doc.BuildV3Model() + + // Request with fragment should match exact path with fragment + // The OData path forces regex fallback, which calls normalizePathForMatching + request, _ := http.NewRequest(http.MethodGet, "https://api.com/entities('123')#section1", nil) + pathItem, errs, foundPath := FindPath(request, &m.Model, nil) + + assert.Nil(t, errs) + assert.NotNil(t, pathItem) + assert.Equal(t, "getSection1", pathItem.Get.OperationId) + assert.Equal(t, "/entities('{id}')#section1", foundPath) + + // Different fragment should match different path + request, _ = http.NewRequest(http.MethodGet, "https://api.com/entities('456')#section2", nil) + pathItem, errs, foundPath = FindPath(request, &m.Model, nil) + + assert.Nil(t, errs) + assert.NotNil(t, pathItem) + assert.Equal(t, "getSection2", pathItem.Get.OperationId) + assert.Equal(t, "/entities('{id}')#section2", foundPath) +} + +func TestCheckPathAgainstBase_MergedPath(t *testing.T) { + // Test checkPathAgainstBase when docPath == merged (basePath + urlPath) + // This covers line 225-227 + + // Direct equality + result := checkPathAgainstBase("/users", "/users", nil) + assert.True(t, result) + + // With base path merge + basePaths := []string{"/api/v1"} + result = checkPathAgainstBase("/api/v1/users", "/users", basePaths) + assert.True(t, result) + + // With trailing slash on base path + basePaths = []string{"/api/v1/"} + result = checkPathAgainstBase("/api/v1/users", "/users", basePaths) + assert.True(t, result) + + // No match + result = checkPathAgainstBase("/other/path", "/users", basePaths) + assert.False(t, result) +} + +func TestFindPath_RegexFallback_MethodMismatch(t *testing.T) { + // Test missingOperation error from regex fallback path (lines 150-161) + // Using OData-style path to force regex fallback, with wrong method + spec := `openapi: 3.1.0 +info: + title: Method Mismatch Test + version: 1.0.0 +paths: + /entities('{id}'): + get: + operationId: getEntity + responses: + '200': + description: OK +` + doc, _ := libopenapi.NewDocument([]byte(spec)) + m, _ := doc.BuildV3Model() + + // POST to OData path that only has GET - regex fallback handles this + request, _ := http.NewRequest(http.MethodPost, "https://api.com/entities('123')", nil) + pathItem, errs, foundPath := FindPath(request, &m.Model, nil) + + assert.NotNil(t, pathItem) + assert.NotNil(t, errs) + assert.Len(t, errs, 1) + assert.Equal(t, "missingOperation", errs[0].ValidationSubType) + assert.Equal(t, "/entities('{id}')", foundPath) +} diff --git a/paths/specificity.go b/paths/specificity.go index ddf83880..a77de63d 100644 --- a/paths/specificity.go +++ b/paths/specificity.go @@ -4,10 +4,11 @@ package paths import ( - "net/http" "strings" v3 "github.com/pb33f/libopenapi/datamodel/high/v3" + + "github.com/pb33f/libopenapi-validator/helpers" ) // pathCandidate represents a potential path match with metadata for selection. @@ -53,25 +54,7 @@ func isParameterSegment(seg string) bool { // pathHasMethod checks if the PathItem has an operation for the given HTTP method. func pathHasMethod(pathItem *v3.PathItem, method string) bool { - switch method { - case http.MethodGet: - return pathItem.Get != nil - case http.MethodPost: - return pathItem.Post != nil - case http.MethodPut: - return pathItem.Put != nil - case http.MethodDelete: - return pathItem.Delete != nil - case http.MethodOptions: - return pathItem.Options != nil - case http.MethodHead: - return pathItem.Head != nil - case http.MethodPatch: - return pathItem.Patch != nil - case http.MethodTrace: - return pathItem.Trace != nil - } - return false + return helpers.OperationForMethod(method, pathItem) != nil } // selectMatches finds the best matching candidates in a single pass. diff --git a/paths/specificity_test.go b/paths/specificity_test.go index 76b88e49..e1d5dfe0 100644 --- a/paths/specificity_test.go +++ b/paths/specificity_test.go @@ -6,8 +6,9 @@ package paths import ( "testing" - v3 "github.com/pb33f/libopenapi/datamodel/high/v3" "github.com/stretchr/testify/assert" + + v3 "github.com/pb33f/libopenapi/datamodel/high/v3" ) func TestComputeSpecificityScore(t *testing.T) { diff --git a/radix/path_tree.go b/radix/path_tree.go new file mode 100644 index 00000000..e47292fe --- /dev/null +++ b/radix/path_tree.go @@ -0,0 +1,90 @@ +// Copyright 2025 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package radix + +import ( + v3 "github.com/pb33f/libopenapi/datamodel/high/v3" +) + +// PathLookup defines the interface for radix tree path matching implementations. +// The default implementation provides O(k) lookup where k is the path segment count. +// +// Note: This interface handles URL path matching only. HTTP method validation +// is performed separately after the PathItem is retrieved, since a single path +// (e.g., "/users/{id}") can support multiple HTTP methods (GET, POST, PUT, DELETE). +type PathLookup interface { + // Lookup finds the PathItem for a given URL path. + // Returns the matched PathItem, the path template (e.g., "/users/{id}"), and whether found. + Lookup(urlPath string) (pathItem *v3.PathItem, matchedPath string, found bool) + // LookupWithParams finds the PathItem for a given URL path and extracts path parameter values. + // Returns the matched PathItem, path template, extracted parameter map, and whether found. + // The params map is nil if the matched path has no parameters. + LookupWithParams(urlPath string) (pathItem *v3.PathItem, matchedPath string, params map[string]string, found bool) +} + +// PathTree is a radix tree optimized for OpenAPI path matching. +// It provides O(k) lookup where k is the number of path segments (typically 3-5), +// with minimal allocations during lookup. +// +// This is a thin wrapper around the generic Tree, specialized for +// OpenAPI PathItem values. It implements the PathLookup interface. +type PathTree struct { + tree *Tree[*v3.PathItem] +} + +// Ensure PathTree implements PathLookup at compile time. +var _ PathLookup = (*PathTree)(nil) + +// NewPathTree creates a new empty radix tree for path matching. +func NewPathTree() *PathTree { + return &PathTree{ + tree: New[*v3.PathItem](), + } +} + +// Insert adds a path and its PathItem to the tree. +// Path should be in OpenAPI format, e.g., "/users/{id}/posts" +func (t *PathTree) Insert(path string, pathItem *v3.PathItem) { + t.tree.Insert(path, pathItem) +} + +// Lookup finds the PathItem for a given request path. +// Returns the PathItem, the matched path template, and whether a match was found. +func (t *PathTree) Lookup(urlPath string) (*v3.PathItem, string, bool) { + return t.tree.Lookup(urlPath) +} + +// LookupWithParams finds the PathItem for a given request path and extracts path parameter values. +// Returns the PathItem, matched path template, extracted parameter map, and whether a match was found. +func (t *PathTree) LookupWithParams(urlPath string) (*v3.PathItem, string, map[string]string, bool) { + return t.tree.LookupWithParams(urlPath) +} + +// Size returns the number of paths stored in the tree. +func (t *PathTree) Size() int { + return t.tree.Size() +} + +// Walk calls the given function for each path in the tree. +func (t *PathTree) Walk(fn func(path string, pathItem *v3.PathItem) bool) { + t.tree.Walk(fn) +} + +// BuildPathTree creates a PathTree from an OpenAPI document. +// This should be called once during validator initialization. +func BuildPathTree(doc *v3.Document) *PathTree { + tree := NewPathTree() + + if doc == nil || doc.Paths == nil || doc.Paths.PathItems == nil { + return tree + } + + for pair := doc.Paths.PathItems.First(); pair != nil; pair = pair.Next() { + path := pair.Key() + pathItem := pair.Value() + tree.Insert(path, pathItem) + } + + return tree +} diff --git a/radix/path_tree_test.go b/radix/path_tree_test.go new file mode 100644 index 00000000..5c5656e8 --- /dev/null +++ b/radix/path_tree_test.go @@ -0,0 +1,338 @@ +// Copyright 2025 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package radix + +import ( + "testing" + + "github.com/pb33f/libopenapi" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + v3 "github.com/pb33f/libopenapi/datamodel/high/v3" +) + +func TestNewPathTree(t *testing.T) { + tree := NewPathTree() + require.NotNil(t, tree) + assert.Equal(t, 0, tree.Size()) +} + +func TestPathTree_ImplementsPathLookup(t *testing.T) { + // Compile-time check that PathTree implements PathLookup + var _ PathLookup = (*PathTree)(nil) +} + +func TestPathTree_Insert_Lookup(t *testing.T) { + spec := `openapi: 3.1.0 +info: + title: Test API + version: 1.0.0 +paths: + /users: + get: + responses: + '200': + description: OK +` + doc, err := libopenapi.NewDocument([]byte(spec)) + require.NoError(t, err) + + model, errs := doc.BuildV3Model() + require.Empty(t, errs) + + pair := model.Model.Paths.PathItems.First() + require.NotNil(t, pair) + + tree := NewPathTree() + tree.Insert("/users", pair.Value()) + + pathItem, path, found := tree.Lookup("/users") + assert.True(t, found) + assert.Equal(t, "/users", path) + assert.NotNil(t, pathItem) + assert.NotNil(t, pathItem.Get) +} + +func TestPathTree_Walk(t *testing.T) { + spec := `openapi: 3.1.0 +info: + title: Test API + version: 1.0.0 +paths: + /users: + get: + responses: + '200': + description: OK + /posts: + get: + responses: + '200': + description: OK +` + doc, err := libopenapi.NewDocument([]byte(spec)) + require.NoError(t, err) + + model, errs := doc.BuildV3Model() + require.Empty(t, errs) + + tree := BuildPathTree(&model.Model) + assert.Equal(t, 2, tree.Size()) + + var paths []string + tree.Walk(func(path string, pathItem *v3.PathItem) bool { + paths = append(paths, path) + assert.NotNil(t, pathItem) + return true + }) + assert.Len(t, paths, 2) +} + +func TestBuildPathTree(t *testing.T) { + spec := `openapi: 3.1.0 +info: + title: Test API + version: 1.0.0 +paths: + /users: + get: + responses: + '200': + description: OK + /users/{id}: + get: + responses: + '200': + description: OK + /posts: + post: + responses: + '201': + description: Created +` + doc, err := libopenapi.NewDocument([]byte(spec)) + require.NoError(t, err) + + model, errs := doc.BuildV3Model() + require.Empty(t, errs) + + tree := BuildPathTree(&model.Model) + + assert.Equal(t, 3, tree.Size()) + + // Test lookups + pathItem, path, found := tree.Lookup("/users") + assert.True(t, found) + assert.Equal(t, "/users", path) + assert.NotNil(t, pathItem.Get) + + pathItem, path, found = tree.Lookup("/users/123") + assert.True(t, found) + assert.Equal(t, "/users/{id}", path) + assert.NotNil(t, pathItem.Get) + + pathItem, path, found = tree.Lookup("/posts") + assert.True(t, found) + assert.Equal(t, "/posts", path) + assert.NotNil(t, pathItem.Post) +} + +func TestBuildPathTree_NilDocument(t *testing.T) { + tree := BuildPathTree(nil) + require.NotNil(t, tree) + assert.Equal(t, 0, tree.Size()) +} + +func TestBuildPathTree_NilPaths(t *testing.T) { + doc := &v3.Document{} + tree := BuildPathTree(doc) + require.NotNil(t, tree) + assert.Equal(t, 0, tree.Size()) +} + +func TestPathTree_LiteralOverParam(t *testing.T) { + spec := `openapi: 3.1.0 +info: + title: Test API + version: 1.0.0 +paths: + /users/{id}: + get: + operationId: getUserById + responses: + '200': + description: OK + /users/admin: + get: + operationId: getAdmin + responses: + '200': + description: OK +` + doc, err := libopenapi.NewDocument([]byte(spec)) + require.NoError(t, err) + + model, errs := doc.BuildV3Model() + require.Empty(t, errs) + + tree := BuildPathTree(&model.Model) + + // Literal should win + pathItem, path, found := tree.Lookup("/users/admin") + assert.True(t, found) + assert.Equal(t, "/users/admin", path) + assert.Equal(t, "getAdmin", pathItem.Get.OperationId) + + // Param should match other values + pathItem, path, found = tree.Lookup("/users/123") + assert.True(t, found) + assert.Equal(t, "/users/{id}", path) + assert.Equal(t, "getUserById", pathItem.Get.OperationId) +} + +func TestPathTree_LookupWithParams(t *testing.T) { + spec := `openapi: 3.1.0 +info: + title: Test API + version: 1.0.0 +paths: + /users: + get: + responses: + '200': + description: OK + /users/{id}: + get: + responses: + '200': + description: OK + /users/{userId}/posts/{postId}: + get: + responses: + '200': + description: OK +` + doc, err := libopenapi.NewDocument([]byte(spec)) + require.NoError(t, err) + + model, errs := doc.BuildV3Model() + require.Empty(t, errs) + + tree := BuildPathTree(&model.Model) + + tests := []struct { + name string + lookupPath string + expectedPath string + expectedParams map[string]string + expectedFound bool + }{ + { + name: "Literal path - no params", + lookupPath: "/users", + expectedPath: "/users", + expectedParams: nil, + expectedFound: true, + }, + { + name: "Single param", + lookupPath: "/users/123", + expectedPath: "/users/{id}", + expectedParams: map[string]string{"id": "123"}, + expectedFound: true, + }, + { + name: "Multiple params", + lookupPath: "/users/abc/posts/xyz", + expectedPath: "/users/{userId}/posts/{postId}", + expectedParams: map[string]string{"id": "abc", "postId": "xyz"}, + expectedFound: true, + }, + { + name: "Single param matches when multiple paths exist", + lookupPath: "/users/123", + expectedPath: "/users/{id}", + expectedParams: map[string]string{"id": "123"}, + expectedFound: true, + }, + { + name: "Not found", + lookupPath: "/posts/123", + expectedPath: "", + expectedParams: nil, + expectedFound: false, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + pathItem, path, params, found := tree.LookupWithParams(tt.lookupPath) + + assert.Equal(t, tt.expectedFound, found, "found mismatch") + if tt.expectedFound { + assert.NotNil(t, pathItem, "pathItem should not be nil") + assert.Equal(t, tt.expectedPath, path, "path mismatch") + if tt.expectedParams == nil { + assert.Nil(t, params, "params should be nil") + } else { + assert.Equal(t, tt.expectedParams, params, "params mismatch") + } + } else { + assert.Nil(t, pathItem, "pathItem should be nil") + assert.Empty(t, path, "path should be empty") + assert.Nil(t, params, "params should be nil") + } + }) + } +} + +// Benchmark + +func BenchmarkPathTree_Lookup(b *testing.B) { + spec := `openapi: 3.1.0 +info: + title: Test API + version: 1.0.0 +paths: + /api/v3/ad_accounts: + get: + responses: + '200': + description: OK + /api/v3/ad_accounts/{id}: + get: + responses: + '200': + description: OK + /api/v3/ad_accounts/{id}/campaigns: + get: + responses: + '200': + description: OK + /api/v3/ad_accounts/{id}/campaigns/{campaign_id}: + get: + responses: + '200': + description: OK +` + doc, err := libopenapi.NewDocument([]byte(spec)) + if err != nil { + b.Fatal(err) + } + + model, modelErr := doc.BuildV3Model() + if modelErr != nil { + b.Fatal(modelErr) + } + + tree := BuildPathTree(&model.Model) + + b.ResetTimer() + b.ReportAllocs() + + for i := 0; i < b.N; i++ { + tree.Lookup("/api/v3/ad_accounts/acc123/campaigns/camp456") + } +} diff --git a/radix/tree.go b/radix/tree.go new file mode 100644 index 00000000..eab7d385 --- /dev/null +++ b/radix/tree.go @@ -0,0 +1,285 @@ +// Copyright 2025 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +// Package radix provides a radix tree (prefix tree) implementation optimized for +// URL path matching with support for parameterized segments. +// +// The tree provides O(k) lookup complexity where k is the number of path segments +// (typically 3-5 for REST APIs), making it ideal for routing and path matching. +// +// Example usage: +// +// tree := radix.New[*MyHandler]() +// tree.Insert("/users/{id}", handler1) +// tree.Insert("/users/{id}/posts", handler2) +// +// handler, path, found := tree.Lookup("/users/123/posts") +// // handler = handler2, path = "/users/{id}/posts", found = true +package radix + +import "strings" + +// Tree is a radix tree optimized for URL path matching. +// It supports both literal path segments and parameterized segments like {id}. +// T is the type of value stored at leaf nodes. +type Tree[T any] struct { + root *node[T] + size int +} + +// node represents a node in the radix tree. +type node[T any] struct { + // children maps literal path segments to child nodes + children map[string]*node[T] + + // paramChild handles parameterized segments like {id} + // Only one param child is allowed per node + paramChild *node[T] + + // paramName stores the parameter name without braces (e.g., "id" from "{id}") + paramName string + + // leaf contains the stored value and path template for endpoints + leaf *leafData[T] +} + +// leafData stores the value and original path template for a leaf node. +type leafData[T any] struct { + value T + path string +} + +// New creates a new empty radix tree. +func New[T any]() *Tree[T] { + return &Tree[T]{ + root: &node[T]{ + children: make(map[string]*node[T]), + }, + } +} + +// Insert adds a path and its associated value to the tree. +// The path should use {param} syntax for parameterized segments. +// Examples: "/users", "/users/{id}", "/users/{userId}/posts/{postId}" +// +// Returns true if a new path was inserted, false if an existing path was updated. +func (t *Tree[T]) Insert(path string, value T) bool { + if t.root == nil { + t.root = &node[T]{children: make(map[string]*node[T])} + } + + segments := splitPath(path) + n := t.root + isNew := true + + for _, seg := range segments { + if isParam(seg) { + // Parameter segment + if n.paramChild == nil { + n.paramChild = &node[T]{ + children: make(map[string]*node[T]), + paramName: extractParamName(seg), + } + } + n = n.paramChild + } else { + // Literal segment + child, exists := n.children[seg] + if !exists { + child = &node[T]{children: make(map[string]*node[T])} + n.children[seg] = child + } + n = child + } + } + + // Check if this is a new path or an update + if n.leaf != nil { + isNew = false + } else { + t.size++ + } + + // Set the leaf data + n.leaf = &leafData[T]{ + value: value, + path: path, + } + + return isNew +} + +// Lookup finds the value for a given URL path. +// Returns the value, the matched path template, and whether a match was found. +// +// Literal matches take precedence over parameter matches per OpenAPI specification. +// For example, "/users/admin" will match "/users/admin" before "/users/{id}". +func (t *Tree[T]) Lookup(urlPath string) (value T, matchedPath string, found bool) { + var zero T + if t.root == nil { + return zero, "", false + } + + segments := splitPath(urlPath) + leaf := t.lookupRecursive(t.root, segments, 0) + + if leaf != nil { + return leaf.value, leaf.path, true + } + return zero, "", false +} + +// LookupWithParams finds the value for a given URL path and extracts path parameter values. +// Returns the value, matched path template, extracted parameter map, and whether a match was found. +// The params map is nil if the matched path has no parameters. +func (t *Tree[T]) LookupWithParams(urlPath string) (value T, matchedPath string, params map[string]string, found bool) { + var zero T + if t.root == nil { + return zero, "", nil, false + } + + segments := splitPath(urlPath) + leaf, params := t.lookupWithParamsRecursive(t.root, segments, 0, nil) + + if leaf != nil { + return leaf.value, leaf.path, params, true + } + return zero, "", nil, false +} + +// lookupRecursive performs the tree traversal. +// It prioritizes literal matches over parameter matches. +func (t *Tree[T]) lookupRecursive(n *node[T], segments []string, depth int) *leafData[T] { + // Base case: consumed all segments + if depth == len(segments) { + return n.leaf + } + + seg := segments[depth] + + // Try literal match first (higher specificity) + if child, exists := n.children[seg]; exists { + if result := t.lookupRecursive(child, segments, depth+1); result != nil { + return result + } + } + + // Fall back to parameter match + if n.paramChild != nil { + if result := t.lookupRecursive(n.paramChild, segments, depth+1); result != nil { + return result + } + } + + return nil +} + +// lookupWithParamsRecursive performs the tree traversal, extracting path parameters. +// The params map is lazily allocated on first parameter match. +func (t *Tree[T]) lookupWithParamsRecursive(n *node[T], segments []string, depth int, params map[string]string) (*leafData[T], map[string]string) { + if depth == len(segments) { + return n.leaf, params + } + + seg := segments[depth] + + // Try literal match first (higher specificity) + if child, exists := n.children[seg]; exists { + if result, p := t.lookupWithParamsRecursive(child, segments, depth+1, params); result != nil { + return result, p + } + } + + // Fall back to parameter match + if n.paramChild != nil { + // Lazily allocate params map on first param encounter + if params == nil { + params = make(map[string]string) + } + params[n.paramChild.paramName] = seg + if result, p := t.lookupWithParamsRecursive(n.paramChild, segments, depth+1, params); result != nil { + return result, p + } + // Backtrack: remove param if this branch didn't match + delete(params, n.paramChild.paramName) + } + + return nil, params +} + +// Size returns the number of paths stored in the tree. +func (t *Tree[T]) Size() int { + return t.size +} + +// Clear removes all entries from the tree. +func (t *Tree[T]) Clear() { + t.root = &node[T]{children: make(map[string]*node[T])} + t.size = 0 +} + +// Walk calls the given function for each path in the tree. +// The function receives the path template and its associated value. +// If the function returns false, iteration stops. +func (t *Tree[T]) Walk(fn func(path string, value T) bool) { + if t.root == nil { + return + } + t.walkRecursive(t.root, fn) +} + +func (t *Tree[T]) walkRecursive(n *node[T], fn func(path string, value T) bool) bool { + if n.leaf != nil { + if !fn(n.leaf.path, n.leaf.value) { + return false + } + } + + for _, child := range n.children { + if !t.walkRecursive(child, fn) { + return false + } + } + + if n.paramChild != nil { + if !t.walkRecursive(n.paramChild, fn) { + return false + } + } + + return true +} + +// splitPath splits a path into segments, removing empty segments. +// "/users/{id}/posts" -> ["users", "{id}", "posts"] +func splitPath(path string) []string { + path = strings.Trim(path, "/") + if path == "" { + return nil + } + + parts := strings.Split(path, "/") + + // Filter out empty segments (from double slashes, etc.) + result := make([]string, 0, len(parts)) + for _, p := range parts { + if p != "" { + result = append(result, p) + } + } + return result +} + +// isParam checks if a segment is a parameter (e.g., "{id}") +func isParam(seg string) bool { + return len(seg) > 2 && seg[0] == '{' && seg[len(seg)-1] == '}' +} + +// extractParamName extracts the parameter name from a segment. +// "{id}" -> "id", "{userId}" -> "userId" +func extractParamName(seg string) string { + if len(seg) > 2 && seg[0] == '{' && seg[len(seg)-1] == '}' { + return seg[1 : len(seg)-1] + } + return seg +} diff --git a/radix/tree_test.go b/radix/tree_test.go new file mode 100644 index 00000000..fe08f2b2 --- /dev/null +++ b/radix/tree_test.go @@ -0,0 +1,940 @@ +// Copyright 2025 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package radix + +import ( + "fmt" + "sort" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestNew(t *testing.T) { + tree := New[string]() + require.NotNil(t, tree) + assert.NotNil(t, tree.root) + assert.Equal(t, 0, tree.Size()) +} + +func TestTree_Insert_LiteralPaths(t *testing.T) { + tree := New[string]() + + // Insert literal paths + assert.True(t, tree.Insert("/users", "users handler")) + assert.True(t, tree.Insert("/users/admin", "admin handler")) + assert.True(t, tree.Insert("/posts", "posts handler")) + assert.True(t, tree.Insert("/posts/trending", "trending handler")) + + assert.Equal(t, 4, tree.Size()) + + // Verify lookups + val, path, found := tree.Lookup("/users") + assert.True(t, found) + assert.Equal(t, "users handler", val) + assert.Equal(t, "/users", path) + + val, path, found = tree.Lookup("/users/admin") + assert.True(t, found) + assert.Equal(t, "admin handler", val) + assert.Equal(t, "/users/admin", path) +} + +func TestTree_Insert_ParameterizedPaths(t *testing.T) { + tree := New[string]() + + tree.Insert("/users/{id}", "user by id") + tree.Insert("/users/{id}/posts", "user posts") + tree.Insert("/users/{id}/posts/{postId}", "single post") + + assert.Equal(t, 3, tree.Size()) + + // Verify parameter matching + val, path, found := tree.Lookup("/users/123") + assert.True(t, found) + assert.Equal(t, "user by id", val) + assert.Equal(t, "/users/{id}", path) + + val, path, found = tree.Lookup("/users/abc") + assert.True(t, found) + assert.Equal(t, "user by id", val) + assert.Equal(t, "/users/{id}", path) + + val, path, found = tree.Lookup("/users/123/posts") + assert.True(t, found) + assert.Equal(t, "user posts", val) + assert.Equal(t, "/users/{id}/posts", path) + + val, path, found = tree.Lookup("/users/123/posts/456") + assert.True(t, found) + assert.Equal(t, "single post", val) + assert.Equal(t, "/users/{id}/posts/{postId}", path) +} + +func TestTree_Specificity_LiteralOverParam(t *testing.T) { + tree := New[string]() + + // Insert both literal and parameterized for same depth + tree.Insert("/users/{id}", "user by id") + tree.Insert("/users/admin", "admin user") + tree.Insert("/users/me", "current user") + + // Literal matches should take precedence + val, path, found := tree.Lookup("/users/admin") + assert.True(t, found) + assert.Equal(t, "admin user", val) + assert.Equal(t, "/users/admin", path) + + val, path, found = tree.Lookup("/users/me") + assert.True(t, found) + assert.Equal(t, "current user", val) + assert.Equal(t, "/users/me", path) + + // Non-literal should fall back to param + val, path, found = tree.Lookup("/users/123") + assert.True(t, found) + assert.Equal(t, "user by id", val) + assert.Equal(t, "/users/{id}", path) +} + +func TestTree_Specificity_DeepPaths(t *testing.T) { + tree := New[string]() + + // Deeper literal path should match over param + tree.Insert("/api/{version}/users", "versioned users") + tree.Insert("/api/v1/users", "v1 users") + tree.Insert("/api/v2/users", "v2 users") + tree.Insert("/api/v1/users/{id}", "v1 user by id") + + val, path, found := tree.Lookup("/api/v1/users") + assert.True(t, found) + assert.Equal(t, "v1 users", val) + assert.Equal(t, "/api/v1/users", path) + + val, path, found = tree.Lookup("/api/v2/users") + assert.True(t, found) + assert.Equal(t, "v2 users", val) + assert.Equal(t, "/api/v2/users", path) + + val, path, found = tree.Lookup("/api/v3/users") + assert.True(t, found) + assert.Equal(t, "versioned users", val) + assert.Equal(t, "/api/{version}/users", path) + + val, path, found = tree.Lookup("/api/v1/users/123") + assert.True(t, found) + assert.Equal(t, "v1 user by id", val) + assert.Equal(t, "/api/v1/users/{id}", path) +} + +func TestTree_Lookup_NoMatch(t *testing.T) { + tree := New[string]() + + tree.Insert("/users", "users") + tree.Insert("/users/{id}", "user by id") + + // Path doesn't exist + _, _, found := tree.Lookup("/posts") + assert.False(t, found) + + // Path too deep + _, _, found = tree.Lookup("/users/123/posts/456/comments") + assert.False(t, found) + + // Empty tree lookup + emptyTree := New[string]() + _, _, found = emptyTree.Lookup("/anything") + assert.False(t, found) +} + +func TestTree_Lookup_EdgeCases(t *testing.T) { + tree := New[string]() + + tree.Insert("/", "root") + tree.Insert("/users", "users") + + // Root path + val, path, found := tree.Lookup("/") + assert.True(t, found) + assert.Equal(t, "root", val) + assert.Equal(t, "/", path) + + // Empty path treated as root + val, path, found = tree.Lookup("") + assert.True(t, found) + assert.Equal(t, "root", val) + assert.Equal(t, "/", path) + + // Trailing slash normalization + val, path, found = tree.Lookup("/users/") + assert.True(t, found) + assert.Equal(t, "users", val) + assert.Equal(t, "/users", path) + + // Double slashes + val, path, found = tree.Lookup("//users//") + assert.True(t, found) + assert.Equal(t, "users", val) + assert.Equal(t, "/users", path) +} + +func TestTree_Insert_Update(t *testing.T) { + tree := New[string]() + + // First insert + isNew := tree.Insert("/users", "v1") + assert.True(t, isNew) + assert.Equal(t, 1, tree.Size()) + + // Update existing path + isNew = tree.Insert("/users", "v2") + assert.False(t, isNew) + assert.Equal(t, 1, tree.Size()) + + // Verify updated value + val, _, _ := tree.Lookup("/users") + assert.Equal(t, "v2", val) +} + +func TestTree_MultipleParameters(t *testing.T) { + tree := New[string]() + + tree.Insert("/orgs/{orgId}/teams/{teamId}/members/{memberId}", "org team member") + tree.Insert("/accounts/{accountId}/ads/{adId}/metrics/{metricId}/breakdown/{breakdownId}", "deep nested") + + val, path, found := tree.Lookup("/orgs/org1/teams/team2/members/member3") + assert.True(t, found) + assert.Equal(t, "org team member", val) + assert.Equal(t, "/orgs/{orgId}/teams/{teamId}/members/{memberId}", path) + + val, path, found = tree.Lookup("/accounts/acc1/ads/ad2/metrics/met3/breakdown/bd4") + assert.True(t, found) + assert.Equal(t, "deep nested", val) + assert.Equal(t, "/accounts/{accountId}/ads/{adId}/metrics/{metricId}/breakdown/{breakdownId}", path) +} + +func TestTree_Clear(t *testing.T) { + tree := New[string]() + + tree.Insert("/users", "users") + tree.Insert("/posts", "posts") + assert.Equal(t, 2, tree.Size()) + + tree.Clear() + assert.Equal(t, 0, tree.Size()) + + _, _, found := tree.Lookup("/users") + assert.False(t, found) +} + +func TestTree_Walk(t *testing.T) { + tree := New[string]() + + tree.Insert("/users", "users") + tree.Insert("/users/{id}", "user by id") + tree.Insert("/posts", "posts") + + var paths []string + tree.Walk(func(path string, value string) bool { + paths = append(paths, path) + return true + }) + + assert.Len(t, paths, 3) + sort.Strings(paths) + assert.Contains(t, paths, "/posts") + assert.Contains(t, paths, "/users") + assert.Contains(t, paths, "/users/{id}") +} + +func TestTree_Walk_EarlyStop(t *testing.T) { + tree := New[string]() + + for i := 0; i < 10; i++ { + tree.Insert(fmt.Sprintf("/path%d", i), fmt.Sprintf("handler%d", i)) + } + + count := 0 + tree.Walk(func(path string, value string) bool { + count++ + return count < 3 // Stop after 3 + }) + + assert.Equal(t, 3, count) +} + +func TestTree_Size(t *testing.T) { + tree := New[string]() + + assert.Equal(t, 0, tree.Size()) + + tree.Insert("/a", "a") + assert.Equal(t, 1, tree.Size()) + + tree.Insert("/b", "b") + assert.Equal(t, 2, tree.Size()) + + // Update shouldn't increase size + tree.Insert("/a", "a2") + assert.Equal(t, 2, tree.Size()) + + tree.Clear() + assert.Equal(t, 0, tree.Size()) +} + +// OpenAPI-specific test cases + +func TestTree_OpenAPIStylePaths(t *testing.T) { + tree := New[string]() + + // Common OpenAPI-style paths + paths := []string{ + "/api/v3/ad_accounts", + "/api/v3/ad_accounts/{ad_account_id}", + "/api/v3/ad_accounts/{ad_account_id}/ads", + "/api/v3/ad_accounts/{ad_account_id}/ads/{ad_id}", + "/api/v3/ad_accounts/{ad_account_id}/campaigns", + "/api/v3/ad_accounts/{ad_account_id}/campaigns/{campaign_id}", + "/api/v3/ad_accounts/{ad_account_id}/bulk_actions", + "/api/v3/ad_accounts/{ad_account_id}/bulk_actions/{bulk_action_id}", + } + + for _, p := range paths { + tree.Insert(p, "handler:"+p) + } + + assert.Equal(t, len(paths), tree.Size()) + + // Test various lookups + tests := []struct { + input string + expected string + }{ + {"/api/v3/ad_accounts", "/api/v3/ad_accounts"}, + {"/api/v3/ad_accounts/123", "/api/v3/ad_accounts/{ad_account_id}"}, + {"/api/v3/ad_accounts/abc-def-ghi", "/api/v3/ad_accounts/{ad_account_id}"}, + {"/api/v3/ad_accounts/123/ads", "/api/v3/ad_accounts/{ad_account_id}/ads"}, + {"/api/v3/ad_accounts/123/ads/456", "/api/v3/ad_accounts/{ad_account_id}/ads/{ad_id}"}, + {"/api/v3/ad_accounts/acc1/campaigns/camp1", "/api/v3/ad_accounts/{ad_account_id}/campaigns/{campaign_id}"}, + {"/api/v3/ad_accounts/acc1/bulk_actions", "/api/v3/ad_accounts/{ad_account_id}/bulk_actions"}, + {"/api/v3/ad_accounts/acc1/bulk_actions/ba1", "/api/v3/ad_accounts/{ad_account_id}/bulk_actions/{bulk_action_id}"}, + } + + for _, tc := range tests { + t.Run(tc.input, func(t *testing.T) { + val, path, found := tree.Lookup(tc.input) + require.True(t, found, "path should be found: %s", tc.input) + assert.Equal(t, tc.expected, path) + assert.Equal(t, "handler:"+tc.expected, val) + }) + } +} + +func TestTree_ConsistentWithVaryingIDs(t *testing.T) { + // This test verifies that the radix tree performs consistently + // regardless of the specific parameter values used + tree := New[string]() + + tree.Insert("/api/v3/ad_accounts/{ad_account_id}/bulk_actions", "bulk_actions") + + // All of these should match the same path template + testCases := []string{ + "/api/v3/ad_accounts/1/bulk_actions", + "/api/v3/ad_accounts/999999/bulk_actions", + "/api/v3/ad_accounts/uuid-here/bulk_actions", + "/api/v3/ad_accounts/acc_123abc/bulk_actions", + } + + for _, tc := range testCases { + val, path, found := tree.Lookup(tc) + require.True(t, found, "should find path for %s", tc) + assert.Equal(t, "/api/v3/ad_accounts/{ad_account_id}/bulk_actions", path) + assert.Equal(t, "bulk_actions", val) + } +} + +func TestTree_NilRoot(t *testing.T) { + // Test that a tree with nil root handles gracefully + tree := &Tree[string]{root: nil} + + _, _, found := tree.Lookup("/anything") + assert.False(t, found) + + // Insert should work even with nil root + tree.Insert("/users", "users") + val, _, found := tree.Lookup("/users") + assert.True(t, found) + assert.Equal(t, "users", val) +} + +func TestTree_ComplexParamNames(t *testing.T) { + tree := New[string]() + + // Various parameter naming styles + tree.Insert("/users/{user_id}", "underscore") + tree.Insert("/posts/{postId}", "camelCase") + tree.Insert("/items/{item-id}", "kebab-case") + tree.Insert("/things/{THING_ID}", "screaming") + + tests := []struct { + input string + expected string + }{ + {"/users/123", "/users/{user_id}"}, + {"/posts/abc", "/posts/{postId}"}, + {"/items/xyz", "/items/{item-id}"}, + {"/things/T1", "/things/{THING_ID}"}, + } + + for _, tc := range tests { + _, path, found := tree.Lookup(tc.input) + assert.True(t, found) + assert.Equal(t, tc.expected, path) + } +} + +// Additional edge case tests for full coverage + +func TestTree_Walk_NilRoot(t *testing.T) { + // Verify Walk handles nil root gracefully + tree := &Tree[string]{root: nil} + + count := 0 + tree.Walk(func(path string, value string) bool { + count++ + return true + }) + + assert.Equal(t, 0, count, "Walk on nil root should not call callback") +} + +func TestTree_Walk_EarlyStopOnParamChild(t *testing.T) { + // Test that Walk respects early stop when iterating paramChild + tree := New[string]() + + // Create a structure where we have literal children AND a param child + tree.Insert("/users/admin", "admin") + tree.Insert("/users/{id}", "user by id") + tree.Insert("/users/{id}/posts", "posts") + + // Stop immediately + count := 0 + tree.Walk(func(path string, value string) bool { + count++ + return false // Stop after first + }) + + assert.Equal(t, 1, count, "Walk should stop after first callback returns false") +} + +func TestTree_Walk_StopInParamChildBranch(t *testing.T) { + // Specifically test stopping while in the paramChild branch + tree := New[string]() + + tree.Insert("/a", "a") + tree.Insert("/b/{id}", "b-id") + tree.Insert("/b/{id}/c", "b-id-c") + + paths := []string{} + tree.Walk(func(path string, value string) bool { + paths = append(paths, path) + // Stop when we hit the param child's nested path + return path != "/b/{id}/c" + }) + + // Should have stopped at or after /b/{id}/c + assert.LessOrEqual(t, len(paths), 3) +} + +func TestExtractParamName_NonParam(t *testing.T) { + // Test extractParamName with non-parameter segments (fallback case) + // This tests the "return seg" branch + + // These are NOT valid params, should return as-is + testCases := []struct { + input string + expected string + }{ + {"users", "users"}, // normal segment + {"{}", "{}"}, // empty param - not valid (len <= 2) + {"{a", "{a"}, // missing closing brace + {"a}", "a}"}, // missing opening brace + {"{", "{"}, // single char + {"}", "}"}, // single char + {"", ""}, // empty string + {"ab", "ab"}, // two chars, not a param + {"{x}", "x"}, // Valid param - extracts "x" + {"{ab}", "ab"}, // Valid param - extracts "ab" + } + + for _, tc := range testCases { + result := extractParamName(tc.input) + assert.Equal(t, tc.expected, result, "extractParamName(%q)", tc.input) + } +} + +func TestIsParam(t *testing.T) { + testCases := []struct { + input string + expected bool + }{ + {"{id}", true}, + {"{userId}", true}, + {"{a}", true}, + {"{}", false}, // empty param name + {"{a", false}, // missing close + {"a}", false}, // missing open + {"id", false}, // no braces + {"{", false}, // single char + {"}", false}, // single char + {"", false}, // empty + {"ab", false}, // two chars + {"{ab", false}, // three chars, missing close + {"ab}", false}, // three chars, missing open + } + + for _, tc := range testCases { + result := isParam(tc.input) + assert.Equal(t, tc.expected, result, "isParam(%q)", tc.input) + } +} + +func TestSplitPath(t *testing.T) { + testCases := []struct { + input string + expected []string + }{ + {"/users/{id}/posts", []string{"users", "{id}", "posts"}}, + {"/users", []string{"users"}}, + {"/", nil}, + {"", nil}, + {"users", []string{"users"}}, + {"/a/b/c", []string{"a", "b", "c"}}, + {"//a//b//", []string{"a", "b"}}, // double slashes filtered + {"/a/", []string{"a"}}, + {"///", nil}, // all slashes + } + + for _, tc := range testCases { + result := splitPath(tc.input) + assert.Equal(t, tc.expected, result, "splitPath(%q)", tc.input) + } +} + +func TestTree_SpecialCharacters(t *testing.T) { + tree := New[string]() + + // Paths with special characters (URL-safe ones) + tree.Insert("/api/v1/users", "users") + tree.Insert("/api/v1/users/{id}", "user") + tree.Insert("/api/v1/items-list", "items-list") + tree.Insert("/api/v1/snake_case", "snake") + tree.Insert("/api/v1/CamelCase", "camel") + + tests := []struct { + lookup string + expected string + found bool + }{ + {"/api/v1/users", "/api/v1/users", true}, + {"/api/v1/users/user-123", "/api/v1/users/{id}", true}, + {"/api/v1/users/user_456", "/api/v1/users/{id}", true}, + {"/api/v1/items-list", "/api/v1/items-list", true}, + {"/api/v1/snake_case", "/api/v1/snake_case", true}, + {"/api/v1/CamelCase", "/api/v1/CamelCase", true}, + } + + for _, tc := range tests { + _, path, found := tree.Lookup(tc.lookup) + assert.Equal(t, tc.found, found, "lookup %q", tc.lookup) + if tc.found { + assert.Equal(t, tc.expected, path, "lookup %q", tc.lookup) + } + } +} + +func TestTree_SingleCharSegments(t *testing.T) { + tree := New[string]() + + tree.Insert("/a", "a") + tree.Insert("/a/b", "ab") + tree.Insert("/a/{x}", "ax") + tree.Insert("/a/b/c", "abc") + + _, path, found := tree.Lookup("/a") + assert.True(t, found) + assert.Equal(t, "/a", path) + + _, path, found = tree.Lookup("/a/b") + assert.True(t, found) + assert.Equal(t, "/a/b", path) + + _, path, found = tree.Lookup("/a/z") + assert.True(t, found) + assert.Equal(t, "/a/{x}", path) +} + +func TestTree_URLEncodedSegments(t *testing.T) { + // URL-encoded values should be matched as literals + tree := New[string]() + + tree.Insert("/users/{id}", "user") + + // These are all different IDs that should match the param + testIDs := []string{ + "123", + "abc", + "user%40example.com", // @ encoded + "hello%20world", // space encoded + "100%25", // % encoded + } + + for _, id := range testIDs { + _, path, found := tree.Lookup("/users/" + id) + assert.True(t, found, "should find path for /users/%s", id) + assert.Equal(t, "/users/{id}", path) + } +} + +func TestTree_NumericSegments(t *testing.T) { + tree := New[string]() + + tree.Insert("/v1/resource", "v1") + tree.Insert("/v2/resource", "v2") + tree.Insert("/{version}/resource", "versioned") + + _, path, found := tree.Lookup("/v1/resource") + assert.True(t, found) + assert.Equal(t, "/v1/resource", path) + + _, path, found = tree.Lookup("/v2/resource") + assert.True(t, found) + assert.Equal(t, "/v2/resource", path) + + _, path, found = tree.Lookup("/v999/resource") + assert.True(t, found) + assert.Equal(t, "/{version}/resource", path) +} + +func TestTree_DeepNesting(t *testing.T) { + tree := New[string]() + + // Very deep path + deepPath := "/a/{b}/c/{d}/e/{f}/g/{h}/i/{j}/k" + tree.Insert(deepPath, "deep") + + _, path, found := tree.Lookup("/a/1/c/2/e/3/g/4/i/5/k") + assert.True(t, found) + assert.Equal(t, deepPath, path) +} + +func TestTree_LookupPartialMatch(t *testing.T) { + tree := New[string]() + + tree.Insert("/users/{id}/posts/{postId}", "post") + + // Partial path should not match + _, _, found := tree.Lookup("/users/123/posts") + assert.False(t, found, "partial path should not match") + + _, _, found = tree.Lookup("/users/123") + assert.False(t, found, "partial path should not match") +} + +func TestTree_OverlappingPaths(t *testing.T) { + tree := New[string]() + + // Insert paths that could conflict + tree.Insert("/api/users", "users list") + tree.Insert("/api/users/search", "users search") + tree.Insert("/api/users/{id}", "user by id") + tree.Insert("/api/users/{id}/profile", "user profile") + tree.Insert("/api/users/{userId}/posts/{postId}", "user post") + + tests := []struct { + lookup string + expected string + }{ + {"/api/users", "/api/users"}, + {"/api/users/search", "/api/users/search"}, + {"/api/users/123", "/api/users/{id}"}, + {"/api/users/123/profile", "/api/users/{id}/profile"}, + {"/api/users/u1/posts/p1", "/api/users/{userId}/posts/{postId}"}, + } + + for _, tc := range tests { + _, path, found := tree.Lookup(tc.lookup) + require.True(t, found, "should find %s", tc.lookup) + assert.Equal(t, tc.expected, path, "lookup %s", tc.lookup) + } +} + +func TestTree_ConcurrentAccess(t *testing.T) { + // Test concurrent reads (tree is read-only after construction) + tree := New[string]() + + paths := []string{ + "/api/v1/users", + "/api/v1/users/{id}", + "/api/v1/posts", + "/api/v1/posts/{id}", + } + + for _, p := range paths { + tree.Insert(p, "handler:"+p) + } + + // Concurrent lookups + done := make(chan bool) + for i := 0; i < 100; i++ { + go func(n int) { + for j := 0; j < 100; j++ { + path := paths[n%len(paths)] + testPath := path + if n%2 == 0 { + // Replace params with values + testPath = "/api/v1/users/123" + } + _, _, _ = tree.Lookup(testPath) + } + done <- true + }(i) + } + + // Wait for all goroutines + for i := 0; i < 100; i++ { + <-done + } +} + +func TestTree_EmptyValue(t *testing.T) { + // Test that empty values are stored correctly + tree := New[string]() + + tree.Insert("/empty", "") + + val, path, found := tree.Lookup("/empty") + assert.True(t, found) + assert.Equal(t, "/empty", path) + assert.Equal(t, "", val) // Empty string is a valid value +} + +func TestTree_PointerValues(t *testing.T) { + // Test with pointer values to ensure nil handling + type Handler struct { + Name string + } + + tree := New[*Handler]() + + h1 := &Handler{Name: "h1"} + tree.Insert("/a", h1) + tree.Insert("/b", nil) // nil pointer value + + val, _, found := tree.Lookup("/a") + assert.True(t, found) + assert.Equal(t, "h1", val.Name) + + val, _, found = tree.Lookup("/b") + assert.True(t, found) + assert.Nil(t, val) // nil is a valid value + + _, _, found = tree.Lookup("/c") + assert.False(t, found) +} + +func TestTree_LookupWithParams(t *testing.T) { + tests := []struct { + name string + insertPaths []string + lookupPath string + expectedValue string + expectedPath string + expectedParams map[string]string + expectedFound bool + }{ + { + name: "No params - literal path", + insertPaths: []string{"/users"}, + lookupPath: "/users", + expectedValue: "users handler", + expectedPath: "/users", + expectedParams: nil, + expectedFound: true, + }, + { + name: "Single param", + insertPaths: []string{"/users/{id}"}, + lookupPath: "/users/123", + expectedValue: "user by id", + expectedPath: "/users/{id}", + expectedParams: map[string]string{"id": "123"}, + expectedFound: true, + }, + { + name: "Multiple params", + insertPaths: []string{"/users/{userId}/posts/{postId}"}, + lookupPath: "/users/abc/posts/xyz", + expectedValue: "user post", + expectedPath: "/users/{userId}/posts/{postId}", + expectedParams: map[string]string{"userId": "abc", "postId": "xyz"}, + expectedFound: true, + }, + { + name: "Literal over param precedence", + insertPaths: []string{"/users/{id}", "/users/admin"}, + lookupPath: "/users/admin", + expectedValue: "admin user", + expectedPath: "/users/admin", + expectedParams: nil, + expectedFound: true, + }, + { + name: "Param match when literal doesn't match", + insertPaths: []string{"/a/{x}/d"}, + lookupPath: "/a/b/d", + expectedValue: "a-x-d", + expectedPath: "/a/{x}/d", + expectedParams: map[string]string{"x": "b"}, + expectedFound: true, + }, + { + name: "Not found", + insertPaths: []string{"/users/{id}"}, + lookupPath: "/posts/123", + expectedValue: "", + expectedPath: "", + expectedParams: nil, + expectedFound: false, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + tree := New[string]() + for i, path := range tt.insertPaths { + var value string + switch i { + case 0: + if path == "/users" { + value = "users handler" + } else if path == "/users/{id}" { + value = "user by id" + } else if path == "/users/{userId}/posts/{postId}" { + value = "user post" + } else if path == "/a/b/c" { + value = "a-b-c" + } else if path == "/a/{x}/d" { + value = "a-x-d" + } + case 1: + if path == "/users/admin" { + value = "admin user" + } + } + tree.Insert(path, value) + } + + val, path, params, found := tree.LookupWithParams(tt.lookupPath) + + assert.Equal(t, tt.expectedFound, found, "found mismatch") + if tt.expectedFound { + assert.Equal(t, tt.expectedValue, val, "value mismatch") + assert.Equal(t, tt.expectedPath, path, "path mismatch") + if tt.expectedParams == nil { + assert.Nil(t, params, "params should be nil") + } else { + assert.Equal(t, tt.expectedParams, params, "params mismatch") + } + } else { + assert.Empty(t, val, "value should be empty") + assert.Empty(t, path, "path should be empty") + assert.Nil(t, params, "params should be nil") + } + }) + } +} + +// Benchmark tests + +func BenchmarkTree_Insert(b *testing.B) { + paths := []string{ + "/api/v3/ad_accounts", + "/api/v3/ad_accounts/{ad_account_id}", + "/api/v3/ad_accounts/{ad_account_id}/ads", + "/api/v3/ad_accounts/{ad_account_id}/ads/{ad_id}", + "/api/v3/ad_accounts/{ad_account_id}/campaigns", + "/api/v3/ad_accounts/{ad_account_id}/campaigns/{campaign_id}", + } + + b.ResetTimer() + for i := 0; i < b.N; i++ { + tree := New[string]() + for _, p := range paths { + tree.Insert(p, p) + } + } +} + +func BenchmarkTree_Lookup_Literal(b *testing.B) { + tree := New[string]() + tree.Insert("/api/v3/ad_accounts", "accounts") + + b.ResetTimer() + for i := 0; i < b.N; i++ { + tree.Lookup("/api/v3/ad_accounts") + } +} + +func BenchmarkTree_Lookup_SingleParam(b *testing.B) { + tree := New[string]() + tree.Insert("/api/v3/ad_accounts/{ad_account_id}", "account") + + b.ResetTimer() + for i := 0; i < b.N; i++ { + tree.Lookup("/api/v3/ad_accounts/123456") + } +} + +func BenchmarkTree_Lookup_MultipleParams(b *testing.B) { + tree := New[string]() + tree.Insert("/api/v3/ad_accounts/{ad_account_id}/campaigns/{campaign_id}/ads/{ad_id}", "ad") + + b.ResetTimer() + for i := 0; i < b.N; i++ { + tree.Lookup("/api/v3/ad_accounts/acc1/campaigns/camp1/ads/ad1") + } +} + +func BenchmarkTree_Lookup_ManyPaths(b *testing.B) { + tree := New[string]() + + // Simulate a realistic API with many paths + for i := 0; i < 100; i++ { + tree.Insert(fmt.Sprintf("/api/v3/resource%d", i), fmt.Sprintf("handler%d", i)) + tree.Insert(fmt.Sprintf("/api/v3/resource%d/{id}", i), fmt.Sprintf("handler%d-id", i)) + } + + b.ResetTimer() + for i := 0; i < b.N; i++ { + tree.Lookup("/api/v3/resource50/abc123") + } +} + +func BenchmarkTree_Lookup_VaryingIDs(b *testing.B) { + tree := New[string]() + tree.Insert("/api/v3/ad_accounts/{ad_account_id}/bulk_actions", "bulk") + + // Pre-generate test paths + testPaths := make([]string, 1000) + for i := 0; i < 1000; i++ { + testPaths[i] = fmt.Sprintf("/api/v3/ad_accounts/account_%d/bulk_actions", i) + } + + b.ResetTimer() + for i := 0; i < b.N; i++ { + tree.Lookup(testPaths[i%1000]) + } +} diff --git a/request_context.go b/request_context.go new file mode 100644 index 00000000..2350d16b --- /dev/null +++ b/request_context.go @@ -0,0 +1,99 @@ +// Copyright 2025 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package validator + +import ( + "fmt" + "net/http" + "strings" + + "github.com/pb33f/libopenapi/datamodel/high/base" + + v3 "github.com/pb33f/libopenapi/datamodel/high/v3" + + "github.com/pb33f/libopenapi-validator/errors" + "github.com/pb33f/libopenapi-validator/helpers" + "github.com/pb33f/libopenapi-validator/paths" +) + +// requestContext is per-request shared state that flows through the entire +// validation pipeline. Created once per request, shared by all validators. +type requestContext struct { + request *http.Request + route *resolvedRoute + operation *v3.Operation + parameters []*v3.Parameter // path + operation params, extracted once + security []*base.SecurityRequirement + stripped string // request path with base path removed + segments []string // pre-split path segments + version float32 // cached OAS version (3.0 or 3.1) +} + +// buildRequestContext creates a requestContext from an incoming request. +// It strips the path, matches it against the spec, resolves the operation, +// and extracts parameters and security requirements — all exactly once. +// +// Returns (*requestContext, nil) on success, or (nil, errors) on failure +// (path not found, method not found). +func (v *validator) buildRequestContext(request *http.Request) (*requestContext, []*errors.ValidationError) { + stripped := paths.StripRequestPath(request, v.v3Model) + + // Split path into segments for future use (filter leading empty string) + segments := strings.Split(stripped, "/") + if len(segments) > 0 && segments[0] == "" { + segments = segments[1:] + } + + // Match path using the matcher chain + route := v.matchers.Match(stripped, v.v3Model) + if route == nil { + validationErrors := []*errors.ValidationError{ + { + ValidationType: helpers.PathValidation, + ValidationSubType: helpers.ValidationMissing, + Message: fmt.Sprintf("%s Path '%s' not found", request.Method, request.URL.Path), + Reason: fmt.Sprintf("The %s request contains a path of '%s' "+ + "however that path, or the %s method for that path does not exist in the specification", + request.Method, request.URL.Path, request.Method), + SpecLine: -1, + SpecCol: -1, + HowToFix: errors.HowToFixPath, + }, + } + errors.PopulateValidationErrors(validationErrors, request, "") + return nil, validationErrors + } + + // Resolve operation for the HTTP method + operation := helpers.OperationForMethod(request.Method, route.pathItem) + if operation == nil { + validationErrors := []*errors.ValidationError{{ + ValidationType: helpers.PathValidation, + ValidationSubType: helpers.ValidationMissingOperation, + Message: fmt.Sprintf("%s Path '%s' not found", request.Method, request.URL.Path), + Reason: fmt.Sprintf("The %s method for that path does not exist in the specification", + request.Method), + SpecLine: -1, + SpecCol: -1, + HowToFix: errors.HowToFixPath, + }} + errors.PopulateValidationErrors(validationErrors, request, route.matchedPath) + return nil, validationErrors + } + + // Extract parameters and security once + params := helpers.ExtractParamsForOperation(request, route.pathItem) + security := helpers.ExtractSecurityForOperation(request, route.pathItem) + + return &requestContext{ + request: request, + route: route, + operation: operation, + parameters: params, + security: security, + stripped: stripped, + segments: segments, + version: v.version, + }, nil +} diff --git a/request_context_test.go b/request_context_test.go new file mode 100644 index 00000000..d3fb594a --- /dev/null +++ b/request_context_test.go @@ -0,0 +1,196 @@ +// Copyright 2025 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package validator + +import ( + "net/http" + "testing" + + "github.com/pb33f/libopenapi" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestBuildRequestContext(t *testing.T) { + spec := `openapi: "3.1.0" +info: + title: Test + version: "0.1.0" +paths: + /users: + get: + operationId: listUsers + parameters: + - name: limit + in: query + schema: + type: integer + responses: + "200": + description: OK + /users/{id}: + parameters: + - name: id + in: path + required: true + schema: + type: string + get: + operationId: getUser + security: + - bearerAuth: + - read + responses: + "200": + description: OK + post: + operationId: createUser + requestBody: + content: + application/json: + schema: + type: object + responses: + "201": + description: Created + /health: + get: + operationId: healthCheck + responses: + "200": + description: OK +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer +` + + doc, err := libopenapi.NewDocument([]byte(spec)) + require.NoError(t, err) + + m, errs := doc.BuildV3Model() + require.Nil(t, errs) + + v := NewValidatorFromV3Model(&m.Model).(*validator) + + tests := []struct { + name string + method string + url string + expectErr bool + expectPath string + expectSegments []string + expectVersion float32 + expectParamLen int // expected number of parameters (-1 to skip check) + expectSecurity bool // expect non-nil security + }{ + { + name: "success - simple path", + method: http.MethodGet, + url: "/health", + expectErr: false, + expectPath: "/health", + expectSegments: []string{"health"}, + expectVersion: 3.1, + expectParamLen: 0, + expectSecurity: false, + }, + { + name: "success - path with parameters", + method: http.MethodGet, + url: "/users/abc123", + expectErr: false, + expectPath: "/users/{id}", + expectSegments: []string{"users", "abc123"}, + expectVersion: 3.1, + expectParamLen: 1, // path-level "id" param + expectSecurity: true, + }, + { + name: "success - path with query params", + method: http.MethodGet, + url: "/users", + expectErr: false, + expectPath: "/users", + expectSegments: []string{"users"}, + expectVersion: 3.1, + expectParamLen: 1, // operation-level "limit" param + expectSecurity: false, + }, + { + name: "path not found", + method: http.MethodGet, + url: "/nonexistent", + expectErr: true, + }, + { + name: "method not found", + method: http.MethodDelete, + url: "/health", + expectErr: true, + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + req, _ := http.NewRequest(tc.method, tc.url, nil) + ctx, validationErrs := v.buildRequestContext(req) + + if tc.expectErr { + assert.Nil(t, ctx) + assert.NotEmpty(t, validationErrs) + return + } + + require.NotNil(t, ctx) + assert.Empty(t, validationErrs) + assert.Equal(t, tc.expectPath, ctx.route.matchedPath) + assert.Equal(t, tc.expectSegments, ctx.segments) + assert.Equal(t, tc.expectVersion, ctx.version) + assert.NotNil(t, ctx.operation) + assert.Equal(t, req, ctx.request) + + if tc.expectParamLen >= 0 { + assert.Len(t, ctx.parameters, tc.expectParamLen) + } + + if tc.expectSecurity { + assert.NotNil(t, ctx.security) + assert.NotEmpty(t, ctx.security) + } else { + assert.Nil(t, ctx.security) + } + }) + } +} + +func TestBuildRequestContext_Version30(t *testing.T) { + spec := `openapi: "3.0.3" +info: + title: Test + version: "0.1.0" +paths: + /ping: + get: + operationId: ping + responses: + "200": + description: OK +` + doc, err := libopenapi.NewDocument([]byte(spec)) + require.NoError(t, err) + + m, errs := doc.BuildV3Model() + require.Nil(t, errs) + + v := NewValidatorFromV3Model(&m.Model).(*validator) + + req, _ := http.NewRequest(http.MethodGet, "/ping", nil) + ctx, validationErrs := v.buildRequestContext(req) + + require.NotNil(t, ctx) + assert.Empty(t, validationErrs) + assert.Equal(t, float32(3.0), ctx.version) +} diff --git a/requests/request_body.go b/requests/request_body.go index 16468908..857d3b86 100644 --- a/requests/request_body.go +++ b/requests/request_body.go @@ -10,6 +10,7 @@ import ( "github.com/pb33f/libopenapi-validator/config" "github.com/pb33f/libopenapi-validator/errors" + "github.com/pb33f/libopenapi-validator/helpers" ) // RequestBodyValidator is an interface that defines the methods for validating request bodies for Operations. @@ -31,11 +32,15 @@ type RequestBodyValidator interface { // NewRequestBodyValidator will create a new RequestBodyValidator from an OpenAPI 3+ document func NewRequestBodyValidator(document *v3.Document, opts ...config.Option) RequestBodyValidator { options := config.NewValidationOptions(opts...) - - return &requestBodyValidator{options: options, document: document} + return &requestBodyValidator{ + options: options, + document: document, + version: helpers.VersionToFloat(document.Version), + } } type requestBodyValidator struct { options *config.ValidationOptions document *v3.Document + version float32 } diff --git a/requests/validate_body.go b/requests/validate_body.go index e9aad701..100b22db 100644 --- a/requests/validate_body.go +++ b/requests/validate_body.go @@ -10,14 +10,13 @@ import ( v3 "github.com/pb33f/libopenapi/datamodel/high/v3" - "github.com/pb33f/libopenapi-validator/config" "github.com/pb33f/libopenapi-validator/errors" "github.com/pb33f/libopenapi-validator/helpers" "github.com/pb33f/libopenapi-validator/paths" ) func (v *requestBodyValidator) ValidateRequestBody(request *http.Request) (bool, []*errors.ValidationError) { - pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options.RegexCache) + pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options) if len(errs) > 0 { return false, errs } @@ -83,8 +82,8 @@ func (v *requestBodyValidator) ValidateRequestBodyWithPathItem(request *http.Req validationSucceeded, validationErrors := ValidateRequestSchema(&ValidateRequestSchemaInput{ Request: request, Schema: schema, - Version: helpers.VersionToFloat(v.document.Version), - Options: []config.Option{config.WithExistingOpts(v.options)}, + Version: v.version, + Options: v.options, }) errors.PopulateValidationErrors(validationErrors, request, pathValue) diff --git a/requests/validate_body_test.go b/requests/validate_body_test.go index bc96085a..f8f7f116 100644 --- a/requests/validate_body_test.go +++ b/requests/validate_body_test.go @@ -496,7 +496,7 @@ paths: request, _ := http.NewRequest(http.MethodPost, "https://things.com/burgers/createBurger", bytes.NewBuffer(bodyBytes)) - pathItem, validationErrors, pathValue := paths.FindPath(request, &m.Model, &sync.Map{}) + pathItem, validationErrors, pathValue := paths.FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) assert.Len(t, validationErrors, 0) valid, errors := v.ValidateRequestBodyWithPathItem(request, pathItem, pathValue) diff --git a/requests/validate_request.go b/requests/validate_request.go index f1ce93c0..5967ea35 100644 --- a/requests/validate_request.go +++ b/requests/validate_request.go @@ -32,17 +32,20 @@ var instanceLocationRegex = regexp.MustCompile(`^/(\d+)`) // ValidateRequestSchemaInput contains parameters for request schema validation. type ValidateRequestSchemaInput struct { - Request *http.Request // Required: The HTTP request to validate - Schema *base.Schema // Required: The OpenAPI schema to validate against - Version float32 // Required: OpenAPI version (3.0 or 3.1) - Options []config.Option // Optional: Functional options (defaults applied if empty/nil) + Request *http.Request // Required: The HTTP request to validate + Schema *base.Schema // Required: The OpenAPI schema to validate against + Version float32 // Required: OpenAPI version (3.0 or 3.1) + Options *config.ValidationOptions // Optional: Validation options (defaults applied if nil) } // ValidateRequestSchema will validate a http.Request pointer against a schema. // If validation fails, it will return a list of validation errors as the second return value. // The schema will be stored and reused from cache if available, otherwise it will be compiled on each call. func ValidateRequestSchema(input *ValidateRequestSchemaInput) (bool, []*errors.ValidationError) { - validationOptions := config.NewValidationOptions(input.Options...) + validationOptions := input.Options + if validationOptions == nil { + validationOptions = config.NewValidationOptions() + } var validationErrors []*errors.ValidationError var renderedSchema, jsonSchema []byte var referenceSchema string @@ -65,8 +68,8 @@ func ValidateRequestSchema(input *ValidateRequestSchemaInput) (bool, []*errors.V }} } + hash := input.Schema.GoLow().Hash() if validationOptions.SchemaCache != nil { - hash := input.Schema.GoLow().Hash() if cached, ok := validationOptions.SchemaCache.Load(hash); ok && cached != nil && cached.CompiledSchema != nil { renderedSchema = cached.RenderedInline referenceSchema = cached.ReferenceSchema @@ -109,7 +112,7 @@ func ValidateRequestSchema(input *ValidateRequestSchemaInput) (bool, []*errors.V jsonSchema, _ = utils.ConvertYAMLtoJSON(renderedSchema) var err error - schemaName := fmt.Sprintf("%x", input.Schema.GoLow().Hash()) + schemaName := fmt.Sprintf("%x", hash) compiledSchema, err = helpers.NewCompiledSchemaWithVersion( schemaName, jsonSchema, @@ -138,7 +141,6 @@ func ValidateRequestSchema(input *ValidateRequestSchemaInput) (bool, []*errors.V } if validationOptions.SchemaCache != nil { - hash := input.Schema.GoLow().Hash() validationOptions.SchemaCache.Store(hash, &cache.SchemaCacheEntry{ Schema: input.Schema, RenderedInline: renderedSchema, @@ -242,7 +244,7 @@ func ValidateRequestSchema(input *ValidateRequestSchemaInput) (bool, []*errors.V errMsg := er.Error.Kind.LocalizedString(message.NewPrinter(language.Tag{})) - if er.KeywordLocation == "" || helpers.IgnoreRegex.MatchString(errMsg) { + if er.KeywordLocation == "" || helpers.ShouldIgnoreError(errMsg) { continue // ignore this error, it's useless tbh, utter noise. } if er.Error != nil { @@ -253,30 +255,35 @@ func ValidateRequestSchema(input *ValidateRequestSchemaInput) (bool, []*errors.V // extract the element specified by the instance val := instanceLocationRegex.FindStringSubmatch(er.InstanceLocation) var referenceObject string - - if len(val) > 0 { - referenceIndex, _ := strconv.Atoi(val[1]) - if reflect.ValueOf(decodedObj).Type().Kind() == reflect.Slice { - found := decodedObj.([]any)[referenceIndex] - recoded, _ := json.MarshalIndent(found, "", " ") - referenceObject = string(recoded) + if !validationOptions.LazyErrors { + if len(val) > 0 { + referenceIndex, _ := strconv.Atoi(val[1]) + if reflect.ValueOf(decodedObj).Type().Kind() == reflect.Slice { + found := decodedObj.([]any)[referenceIndex] + recoded, _ := json.Marshal(found) + referenceObject = string(recoded) + } + } + if referenceObject == "" { + referenceObject = string(requestBody) } } - if referenceObject == "" { - referenceObject = string(requestBody) - } - - errMsg := er.Error.Kind.LocalizedString(message.NewPrinter(language.Tag{})) violation := &errors.SchemaValidationFailure{ - Reason: errMsg, - Location: er.KeywordLocation, - FieldName: helpers.ExtractFieldNameFromStringLocation(er.InstanceLocation), - FieldPath: helpers.ExtractJSONPathFromStringLocation(er.InstanceLocation), - InstancePath: helpers.ConvertStringLocationToPathSegments(er.InstanceLocation), - ReferenceSchema: referenceSchema, - ReferenceObject: referenceObject, - OriginalError: jk, + Reason: errMsg, + Location: er.KeywordLocation, + FieldName: helpers.ExtractFieldNameFromStringLocation(er.InstanceLocation), + FieldPath: helpers.ExtractJSONPathFromStringLocation(er.InstanceLocation), + InstancePath: helpers.ConvertStringLocationToPathSegments(er.InstanceLocation), + OriginalError: jk, + } + if validationOptions.LazyErrors { + violation.SetLazySource(renderedSchema, decodedObj, requestBody, er.InstanceLocation) + } else { + //nolint:staticcheck // Backward compatibility: set deprecated fields directly in eager mode + violation.ReferenceSchema = referenceSchema + //nolint:staticcheck // Backward compatibility: set deprecated fields directly in eager mode + violation.ReferenceObject = referenceObject } // if we have a location within the schema, add it to the error if located != nil { diff --git a/requests/validate_request_test.go b/requests/validate_request_test.go index c47f120e..df2ae937 100644 --- a/requests/validate_request_test.go +++ b/requests/validate_request_test.go @@ -146,7 +146,7 @@ properties: Request: postRequestWithBody(`{"name": "test"}`), Schema: schema, Version: openAPIVersion, - Options: []config.Option{config.WithExistingOpts(opts)}, + Options: opts, }) assert.True(t, valid) diff --git a/responses/response_body.go b/responses/response_body.go index 62bac3f6..7eeedf0b 100644 --- a/responses/response_body.go +++ b/responses/response_body.go @@ -10,6 +10,7 @@ import ( "github.com/pb33f/libopenapi-validator/config" "github.com/pb33f/libopenapi-validator/errors" + "github.com/pb33f/libopenapi-validator/helpers" ) // ResponseBodyValidator is an interface that defines the methods for validating response bodies for Operations. @@ -31,11 +32,15 @@ type ResponseBodyValidator interface { // NewResponseBodyValidator will create a new ResponseBodyValidator from an OpenAPI 3+ document func NewResponseBodyValidator(document *v3.Document, opts ...config.Option) ResponseBodyValidator { options := config.NewValidationOptions(opts...) - - return &responseBodyValidator{options: options, document: document} + return &responseBodyValidator{ + options: options, + document: document, + version: helpers.VersionToFloat(document.Version), + } } type responseBodyValidator struct { options *config.ValidationOptions document *v3.Document + version float32 } diff --git a/responses/validate_body.go b/responses/validate_body.go index ae09b307..e0f9f4ae 100644 --- a/responses/validate_body.go +++ b/responses/validate_body.go @@ -23,7 +23,7 @@ func (v *responseBodyValidator) ValidateResponseBody( request *http.Request, response *http.Response, ) (bool, []*errors.ValidationError) { - pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options.RegexCache) + pathItem, errs, foundPath := paths.FindPath(request, v.document, v.options) if len(errs) > 0 { return false, errs } @@ -144,8 +144,8 @@ func (v *responseBodyValidator) checkResponseSchema( Request: request, Response: response, Schema: schema, - Version: helpers.VersionToFloat(v.document.Version), - Options: []config.Option{config.WithExistingOpts(v.options)}, + Version: v.version, + Options: v.options, }) if !valid { validationErrors = append(validationErrors, vErrs...) diff --git a/responses/validate_body_test.go b/responses/validate_body_test.go index a40bdd10..22668bb4 100644 --- a/responses/validate_body_test.go +++ b/responses/validate_body_test.go @@ -244,7 +244,7 @@ paths: request.Header.Set(helpers.ContentTypeHeader, helpers.JSONContentType) // preset the path - path, _, pv := paths.FindPath(request, &m.Model, &sync.Map{}) + path, _, pv := paths.FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) // simulate a request/response res := httptest.NewRecorder() @@ -648,7 +648,7 @@ paths: response := res.Result() // preset the path - path, _, pv := paths.FindPath(request, &m.Model, &sync.Map{}) + path, _, pv := paths.FindPath(request, &m.Model, &config.ValidationOptions{RegexCache: &sync.Map{}}) // validate! valid, errors := v.ValidateResponseBodyWithPathItem(request, response, path, pv) diff --git a/responses/validate_response.go b/responses/validate_response.go index f63a6a35..3bc21fdc 100644 --- a/responses/validate_response.go +++ b/responses/validate_response.go @@ -32,11 +32,11 @@ var instanceLocationRegex = regexp.MustCompile(`^/(\d+)`) // ValidateResponseSchemaInput contains parameters for response schema validation. type ValidateResponseSchemaInput struct { - Request *http.Request // Required: The HTTP request (for context) - Response *http.Response // Required: The HTTP response to validate - Schema *base.Schema // Required: The OpenAPI schema to validate against - Version float32 // Required: OpenAPI version (3.0 or 3.1) - Options []config.Option // Optional: Functional options (defaults applied if empty/nil) + Request *http.Request // Required: The HTTP request (for context) + Response *http.Response // Required: The HTTP response to validate + Schema *base.Schema // Required: The OpenAPI schema to validate against + Version float32 // Required: OpenAPI version (3.0 or 3.1) + Options *config.ValidationOptions // Optional: Validation options (defaults applied if nil) } // ValidateResponseSchema will validate the response body for a http.Response pointer. The request is used to @@ -46,7 +46,10 @@ type ValidateResponseSchemaInput struct { // This function is used by the ValidateResponseBody function, but can be used independently. // The schema will be compiled from cache if available, otherwise it will be compiled and cached. func ValidateResponseSchema(input *ValidateResponseSchemaInput) (bool, []*errors.ValidationError) { - validationOptions := config.NewValidationOptions(input.Options...) + validationOptions := input.Options + if validationOptions == nil { + validationOptions = config.NewValidationOptions() + } var validationErrors []*errors.ValidationError var renderedSchema, jsonSchema []byte var referenceSchema string @@ -69,8 +72,8 @@ func ValidateResponseSchema(input *ValidateResponseSchemaInput) (bool, []*errors }} } + hash := input.Schema.GoLow().Hash() if validationOptions.SchemaCache != nil { - hash := input.Schema.GoLow().Hash() if cached, ok := validationOptions.SchemaCache.Load(hash); ok && cached != nil && cached.CompiledSchema != nil { renderedSchema = cached.RenderedInline referenceSchema = cached.ReferenceSchema @@ -112,7 +115,7 @@ func ValidateResponseSchema(input *ValidateResponseSchemaInput) (bool, []*errors jsonSchema, _ = utils.ConvertYAMLtoJSON(renderedSchema) var err error - schemaName := fmt.Sprintf("%x", input.Schema.GoLow().Hash()) + schemaName := fmt.Sprintf("%x", hash) compiledSchema, err = helpers.NewCompiledSchemaWithVersion( schemaName, jsonSchema, @@ -142,7 +145,6 @@ func ValidateResponseSchema(input *ValidateResponseSchemaInput) (bool, []*errors } if validationOptions.SchemaCache != nil { - hash := input.Schema.GoLow().Hash() validationOptions.SchemaCache.Store(hash, &cache.SchemaCacheEntry{ Schema: input.Schema, RenderedInline: renderedSchema, @@ -259,7 +261,7 @@ func ValidateResponseSchema(input *ValidateResponseSchemaInput) (bool, []*errors er := schFlatErrs[q] errMsg := er.Error.Kind.LocalizedString(message.NewPrinter(language.Tag{})) - if er.KeywordLocation == "" || helpers.IgnoreRegex.MatchString(errMsg) { + if er.KeywordLocation == "" || helpers.ShouldIgnoreError(errMsg) { continue // ignore this error, it's useless tbh, utter noise. } if er.Error != nil { @@ -270,27 +272,35 @@ func ValidateResponseSchema(input *ValidateResponseSchemaInput) (bool, []*errors val := instanceLocationRegex.FindStringSubmatch(er.InstanceLocation) var referenceObject string - if len(val) > 0 { - referenceIndex, _ := strconv.Atoi(val[1]) - if reflect.ValueOf(decodedObj).Type().Kind() == reflect.Slice { - found := decodedObj.([]any)[referenceIndex] - recoded, _ := json.MarshalIndent(found, "", " ") - referenceObject = string(recoded) + if !validationOptions.LazyErrors { + if len(val) > 0 { + referenceIndex, _ := strconv.Atoi(val[1]) + if reflect.ValueOf(decodedObj).Type().Kind() == reflect.Slice { + found := decodedObj.([]any)[referenceIndex] + recoded, _ := json.Marshal(found) + referenceObject = string(recoded) + } + } + if referenceObject == "" { + referenceObject = string(responseBody) } - } - if referenceObject == "" { - referenceObject = string(responseBody) } violation := &errors.SchemaValidationFailure{ - Reason: errMsg, - Location: er.KeywordLocation, - FieldName: helpers.ExtractFieldNameFromStringLocation(er.InstanceLocation), - FieldPath: helpers.ExtractJSONPathFromStringLocation(er.InstanceLocation), - InstancePath: helpers.ConvertStringLocationToPathSegments(er.InstanceLocation), - ReferenceSchema: referenceSchema, - ReferenceObject: referenceObject, - OriginalError: jk, + Reason: errMsg, + Location: er.KeywordLocation, + FieldName: helpers.ExtractFieldNameFromStringLocation(er.InstanceLocation), + FieldPath: helpers.ExtractJSONPathFromStringLocation(er.InstanceLocation), + InstancePath: helpers.ConvertStringLocationToPathSegments(er.InstanceLocation), + OriginalError: jk, + } + if validationOptions.LazyErrors { + violation.SetLazySource(renderedSchema, decodedObj, responseBody, er.InstanceLocation) + } else { + //nolint:staticcheck // Backward compatibility: set deprecated fields directly in eager mode + violation.ReferenceSchema = referenceSchema + //nolint:staticcheck // Backward compatibility: set deprecated fields directly in eager mode + violation.ReferenceObject = referenceObject } // if we have a location within the schema, add it to the error if located != nil { diff --git a/responses/validate_response_test.go b/responses/validate_response_test.go index 241e1ac3..50bc212c 100644 --- a/responses/validate_response_test.go +++ b/responses/validate_response_test.go @@ -154,7 +154,7 @@ properties: Response: responseWithBody(`{"name": "test"}`), Schema: schema, Version: 3.1, - Options: []config.Option{config.WithExistingOpts(opts)}, + Options: opts, }) assert.True(t, valid) diff --git a/schema_validation/locate_schema_property.go b/schema_validation/locate_schema_property.go index 4ade2f46..4dde96c3 100644 --- a/schema_validation/locate_schema_property.go +++ b/schema_validation/locate_schema_property.go @@ -11,32 +11,16 @@ import ( // LocateSchemaPropertyNodeByJSONPath will locate a schema property node by a JSONPath. It converts something like // #/components/schemas/MySchema/properties/MyProperty to something like $.components.schemas.MySchema.properties.MyProperty -func LocateSchemaPropertyNodeByJSONPath(doc *yaml.Node, JSONPath string) *yaml.Node { - var locatedNode *yaml.Node - doneChan := make(chan bool) - locatedNodeChan := make(chan *yaml.Node) - go func() { - defer func() { - if err := recover(); err != nil { - // can't search path, too crazy. - doneChan <- true - } - }() - _, path := utils.ConvertComponentIdIntoFriendlyPathSearch(JSONPath) - if path == "" { - doneChan <- true - } - jsonPath, _ := jsonpath.NewPath(path) - locatedNodes := jsonPath.Query(doc) - if len(locatedNodes) > 0 { - locatedNode = locatedNodes[0] - } - locatedNodeChan <- locatedNode - }() - select { - case locatedNode = <-locatedNodeChan: - return locatedNode - case <-doneChan: +func LocateSchemaPropertyNodeByJSONPath(doc *yaml.Node, JSONPath string) (result *yaml.Node) { + defer func() { _ = recover() }() + _, path := utils.ConvertComponentIdIntoFriendlyPathSearch(JSONPath) + if path == "" { return nil } + jp, _ := jsonpath.NewPath(path) + nodes := jp.Query(doc) + if len(nodes) > 0 { + return nodes[0] + } + return nil } diff --git a/schema_validation/validate_document.go b/schema_validation/validate_document.go index bc4f30f7..9b2bc66b 100644 --- a/schema_validation/validate_document.go +++ b/schema_validation/validate_document.go @@ -101,7 +101,7 @@ func ValidateOpenAPIDocument(doc libopenapi.Document, opts ...config.Option) (bo er := schFlatErrs[q] errMsg := er.Error.Kind.LocalizedString(message.NewPrinter(language.Tag{})) - if er.KeywordLocation == "" || helpers.IgnorePolyRegex.MatchString(errMsg) { + if er.KeywordLocation == "" || helpers.ShouldIgnorePolyError(errMsg) { continue // ignore this error, it's useless tbh, utter noise. } if errMsg != "" { diff --git a/schema_validation/validate_schema.go b/schema_validation/validate_schema.go index 5740f1e1..23603e01 100644 --- a/schema_validation/validate_schema.go +++ b/schema_validation/validate_schema.go @@ -277,7 +277,7 @@ func extractBasicErrors(schFlatErrs []jsonschema.OutputUnit, er := schFlatErrs[q] errMsg := er.Error.Kind.LocalizedString(message.NewPrinter(language.Tag{})) - if helpers.IgnoreRegex.MatchString(errMsg) { + if helpers.ShouldIgnoreError(errMsg) { continue // ignore this error, it's useless tbh, utter noise. } if er.Error != nil { diff --git a/strict/validator.go b/strict/validator.go index 1917eff9..025e8053 100644 --- a/strict/validator.go +++ b/strict/validator.go @@ -8,6 +8,7 @@ import ( "strings" "github.com/pb33f/libopenapi/datamodel/high/base" + v3 "github.com/pb33f/libopenapi/datamodel/high/v3" "github.com/pb33f/libopenapi-validator/config" diff --git a/strict/validator_test.go b/strict/validator_test.go index c4abfaba..249808d2 100644 --- a/strict/validator_test.go +++ b/strict/validator_test.go @@ -11,10 +11,11 @@ import ( "github.com/pb33f/libopenapi" "github.com/pb33f/libopenapi/datamodel/high/base" - v3 "github.com/pb33f/libopenapi/datamodel/high/v3" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + v3 "github.com/pb33f/libopenapi/datamodel/high/v3" + libcache "github.com/pb33f/libopenapi-validator/cache" "github.com/pb33f/libopenapi-validator/config" "github.com/pb33f/libopenapi-validator/helpers" diff --git a/test_specs/ads_api_bulk_actions.yaml b/test_specs/ads_api_bulk_actions.yaml new file mode 100644 index 00000000..7698f081 --- /dev/null +++ b/test_specs/ads_api_bulk_actions.yaml @@ -0,0 +1,1323 @@ +openapi: "3.0.2" +info: + title: Reddit Ads API - BulkActions (Benchmark Spec) + description: | + Realistic OpenAPI spec modeled after the Reddit Ads API v3 BulkActions endpoints. + Used for benchmarking libopenapi-validator performance with production-like schemas. + version: "3.0.0" +servers: + - url: /api/v3 + +paths: + /ad_accounts: + get: + operationId: listAdAccounts + summary: List ad accounts + parameters: + - $ref: "#/components/parameters/PageSize" + - $ref: "#/components/parameters/PageToken" + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/AdAccount" + pagination: + $ref: "#/components/schemas/Pagination" + + /ad_accounts/{ad_account_id}: + get: + operationId: getAdAccount + summary: Get a specific ad account + parameters: + - $ref: "#/components/parameters/AdAccountId" + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + $ref: "#/components/schemas/AdAccount" + "404": + $ref: "#/components/responses/NotFound" + + /ad_accounts/{ad_account_id}/campaigns: + get: + operationId: listCampaigns + summary: List campaigns for an ad account + parameters: + - $ref: "#/components/parameters/AdAccountId" + - $ref: "#/components/parameters/PageSize" + - $ref: "#/components/parameters/PageToken" + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/Campaign" + pagination: + $ref: "#/components/schemas/Pagination" + post: + operationId: createCampaign + summary: Create a campaign + parameters: + - $ref: "#/components/parameters/AdAccountId" + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: "#/components/schemas/CampaignInput" + responses: + "201": + description: Campaign created + content: + application/json: + schema: + type: object + properties: + data: + $ref: "#/components/schemas/Campaign" + + /ad_accounts/{ad_account_id}/campaigns/{campaign_id}: + get: + operationId: getCampaign + summary: Get a specific campaign + parameters: + - $ref: "#/components/parameters/AdAccountId" + - $ref: "#/components/parameters/CampaignId" + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + $ref: "#/components/schemas/Campaign" + put: + operationId: updateCampaign + summary: Update a campaign + parameters: + - $ref: "#/components/parameters/AdAccountId" + - $ref: "#/components/parameters/CampaignId" + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: "#/components/schemas/CampaignInput" + responses: + "200": + description: Campaign updated + content: + application/json: + schema: + type: object + properties: + data: + $ref: "#/components/schemas/Campaign" + + /ad_accounts/{ad_account_id}/ad_groups: + get: + operationId: listAdGroups + summary: List ad groups + parameters: + - $ref: "#/components/parameters/AdAccountId" + - $ref: "#/components/parameters/PageSize" + - $ref: "#/components/parameters/PageToken" + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/AdGroup" + pagination: + $ref: "#/components/schemas/Pagination" + post: + operationId: createAdGroup + summary: Create an ad group + parameters: + - $ref: "#/components/parameters/AdAccountId" + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: "#/components/schemas/AdGroupInput" + responses: + "201": + description: Ad group created + content: + application/json: + schema: + type: object + properties: + data: + $ref: "#/components/schemas/AdGroup" + + /ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}: + get: + operationId: getAdGroup + summary: Get a specific ad group + parameters: + - $ref: "#/components/parameters/AdAccountId" + - $ref: "#/components/parameters/AdGroupId" + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + $ref: "#/components/schemas/AdGroup" + put: + operationId: updateAdGroup + summary: Update an ad group + parameters: + - $ref: "#/components/parameters/AdAccountId" + - $ref: "#/components/parameters/AdGroupId" + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: "#/components/schemas/AdGroupInput" + responses: + "200": + description: Ad group updated + + /ad_accounts/{ad_account_id}/ads: + get: + operationId: listAds + summary: List ads + parameters: + - $ref: "#/components/parameters/AdAccountId" + - $ref: "#/components/parameters/PageSize" + - $ref: "#/components/parameters/PageToken" + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/Ad" + pagination: + $ref: "#/components/schemas/Pagination" + post: + operationId: createAd + summary: Create an ad + parameters: + - $ref: "#/components/parameters/AdAccountId" + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: "#/components/schemas/AdInput" + responses: + "201": + description: Ad created + content: + application/json: + schema: + type: object + properties: + data: + $ref: "#/components/schemas/Ad" + + /ad_accounts/{ad_account_id}/ads/{ad_id}: + get: + operationId: getAd + summary: Get a specific ad + parameters: + - $ref: "#/components/parameters/AdAccountId" + - $ref: "#/components/parameters/AdId" + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + $ref: "#/components/schemas/Ad" + put: + operationId: updateAd + summary: Update an ad + parameters: + - $ref: "#/components/parameters/AdAccountId" + - $ref: "#/components/parameters/AdId" + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: "#/components/schemas/AdInput" + responses: + "200": + description: Ad updated + + /ad_accounts/{ad_account_id}/bulk_actions: + post: + operationId: createBulkActions + summary: Create bulk actions + description: | + Submit a batch of campaign management actions (campaign, ad group, ad, post creation/edits) + to be processed as a single job. Returns a job ID for status polling. + parameters: + - $ref: "#/components/parameters/AdAccountId" + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + minItems: 1 + maxItems: 50 + items: + $ref: "#/components/schemas/BulkAction" + validate_only: + type: boolean + default: false + description: If true, validate the actions without executing them + responses: + "201": + description: Bulk action job created + content: + application/json: + schema: + type: object + properties: + data: + $ref: "#/components/schemas/BulkActionsResponse" + validate_only: + type: boolean + "400": + $ref: "#/components/responses/BadRequest" + + /ad_accounts/{ad_account_id}/bulk_actions/{job_id}: + get: + operationId: getBulkActions + summary: Get bulk action job status + parameters: + - $ref: "#/components/parameters/AdAccountId" + - name: job_id + in: path + required: true + schema: + type: string + responses: + "200": + description: Bulk action job status + content: + application/json: + schema: + type: object + properties: + data: + $ref: "#/components/schemas/BulkActionsResponse" + "404": + $ref: "#/components/responses/NotFound" + + /ad_accounts/{ad_account_id}/posts: + get: + operationId: listPosts + summary: List posts for an ad account + parameters: + - $ref: "#/components/parameters/AdAccountId" + - $ref: "#/components/parameters/PageSize" + - $ref: "#/components/parameters/PageToken" + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/Post" + + /ad_accounts/{ad_account_id}/posts/{post_id}: + get: + operationId: getPost + summary: Get a specific post + parameters: + - $ref: "#/components/parameters/AdAccountId" + - name: post_id + in: path + required: true + schema: + type: string + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + $ref: "#/components/schemas/Post" + + /ad_accounts/{ad_account_id}/pixels: + get: + operationId: listPixels + summary: List pixels + parameters: + - $ref: "#/components/parameters/AdAccountId" + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/Pixel" + + /ad_accounts/{ad_account_id}/funding_instruments: + get: + operationId: listFundingInstruments + summary: List funding instruments + parameters: + - $ref: "#/components/parameters/AdAccountId" + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/FundingInstrument" + + /ad_accounts/{ad_account_id}/reporting: + post: + operationId: getReporting + summary: Get reporting data + parameters: + - $ref: "#/components/parameters/AdAccountId" + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ReportingRequest" + responses: + "200": + description: Reporting data + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/ReportingRow" + + /ad_accounts/{ad_account_id}/custom_audiences: + get: + operationId: listCustomAudiences + summary: List custom audiences + parameters: + - $ref: "#/components/parameters/AdAccountId" + - $ref: "#/components/parameters/PageSize" + - $ref: "#/components/parameters/PageToken" + responses: + "200": + description: Successful response + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/CustomAudience" + + /ad_accounts/{ad_account_id}/custom_audiences/{audience_id}: + get: + operationId: getCustomAudience + summary: Get a custom audience + parameters: + - $ref: "#/components/parameters/AdAccountId" + - name: audience_id + in: path + required: true + schema: + type: string + responses: + "200": + description: Successful response + + /ad_accounts/{ad_account_id}/saved_audiences: + get: + operationId: listSavedAudiences + summary: List saved audiences + parameters: + - $ref: "#/components/parameters/AdAccountId" + responses: + "200": + description: Successful response + + /businesses: + get: + operationId: listBusinesses + summary: List businesses + responses: + "200": + description: Successful response + + /businesses/{business_id}: + get: + operationId: getBusiness + summary: Get a business + parameters: + - name: business_id + in: path + required: true + schema: + type: string + responses: + "200": + description: Successful response + + /me: + get: + operationId: getMe + summary: Get authenticated user + responses: + "200": + description: Successful response + + /interests: + get: + operationId: listInterests + summary: List interests + responses: + "200": + description: Successful response + + /industries: + get: + operationId: listIndustries + summary: List industries + responses: + "200": + description: Successful response + +components: + parameters: + AdAccountId: + name: ad_account_id + in: path + required: true + schema: + type: string + pattern: "^t2_[a-z0-9]+$" + CampaignId: + name: campaign_id + in: path + required: true + schema: + type: string + AdGroupId: + name: ad_group_id + in: path + required: true + schema: + type: string + AdId: + name: ad_id + in: path + required: true + schema: + type: string + PageSize: + name: page_size + in: query + schema: + type: integer + minimum: 1 + maximum: 100 + default: 25 + PageToken: + name: page_token + in: query + schema: + type: string + + responses: + BadRequest: + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + NotFound: + description: Resource not found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + + schemas: + ErrorResponse: + type: object + properties: + error: + type: object + properties: + code: + type: string + message: + type: string + details: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + + Pagination: + type: object + properties: + next_url: + type: string + nullable: true + previous_url: + type: string + nullable: true + + AdAccount: + type: object + properties: + id: + type: string + name: + type: string + status: + type: string + enum: [ACTIVE, PAUSED, SUSPENDED, CLOSED] + currency: + type: string + enum: [USD, GBP, EUR, CAD, AUD] + time_zone: + type: string + business_id: + type: string + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time + + Campaign: + type: object + properties: + id: + type: string + name: + type: string + status: + type: string + enum: [ACTIVE, PAUSED, COMPLETED, DRAFT] + objective: + type: string + enum: [AWARENESS, CONSIDERATION, CONVERSIONS, TRAFFIC, VIDEO_VIEWS, APP_INSTALLS, CATALOG_SALES, LEADS] + daily_budget_micro: + type: integer + format: int64 + lifetime_budget_micro: + type: integer + format: int64 + start_time: + type: string + format: date-time + end_time: + type: string + format: date-time + funding_instrument_id: + type: string + is_paid: + type: boolean + configured_status: + type: string + enum: [ACTIVE, PAUSED] + effective_status: + type: string + enum: [ACTIVE, PAUSED, COMPLETED, BUDGET_EXHAUSTED, ENDED] + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time + + CampaignInput: + type: object + required: + - name + - objective + - daily_budget_micro + - start_time + - funding_instrument_id + properties: + name: + type: string + minLength: 1 + maxLength: 400 + objective: + type: string + enum: [AWARENESS, CONSIDERATION, CONVERSIONS, TRAFFIC, VIDEO_VIEWS, APP_INSTALLS, CATALOG_SALES, LEADS] + daily_budget_micro: + type: integer + format: int64 + minimum: 500000 + lifetime_budget_micro: + type: integer + format: int64 + minimum: 500000 + start_time: + type: string + format: date-time + end_time: + type: string + format: date-time + funding_instrument_id: + type: string + configured_status: + type: string + enum: [ACTIVE, PAUSED] + default: PAUSED + + AdGroup: + type: object + properties: + id: + type: string + name: + type: string + campaign_id: + type: string + status: + type: string + enum: [ACTIVE, PAUSED, COMPLETED, DRAFT] + bid_strategy: + type: string + enum: [AUTO, MANUAL_CPC, MANUAL_CPM, MANUAL_CPV] + bid_micro: + type: integer + format: int64 + goal_type: + type: string + enum: [CLICKS, IMPRESSIONS, VIDEO_VIEWS, CONVERSIONS, APP_INSTALLS] + goal_value_micro: + type: integer + format: int64 + start_time: + type: string + format: date-time + end_time: + type: string + format: date-time + targeting: + $ref: "#/components/schemas/Targeting" + expansion: + type: object + properties: + enabled: + type: boolean + targeting_mode: + type: string + enum: [BALANCED, AGGRESSIVE, CONSERVATIVE] + optimization_strategy: + type: string + enum: [BALANCED, SPEND, CONVERSIONS] + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time + + AdGroupInput: + type: object + required: + - name + - campaign_id + - bid_strategy + - goal_type + - start_time + properties: + name: + type: string + minLength: 1 + maxLength: 400 + campaign_id: + type: string + bid_strategy: + type: string + enum: [AUTO, MANUAL_CPC, MANUAL_CPM, MANUAL_CPV] + bid_micro: + type: integer + format: int64 + minimum: 10000 + goal_type: + type: string + enum: [CLICKS, IMPRESSIONS, VIDEO_VIEWS, CONVERSIONS, APP_INSTALLS] + goal_value_micro: + type: integer + format: int64 + start_time: + type: string + format: date-time + end_time: + type: string + format: date-time + targeting: + $ref: "#/components/schemas/Targeting" + configured_status: + type: string + enum: [ACTIVE, PAUSED] + default: PAUSED + + Targeting: + type: object + properties: + geos: + type: object + properties: + included: + type: array + items: + type: object + properties: + country: + type: string + region: + type: string + city: + type: string + dma: + type: string + excluded: + type: array + items: + type: object + properties: + country: + type: string + region: + type: string + interests: + type: array + items: + type: object + properties: + id: + type: string + name: + type: string + communities: + type: array + items: + type: object + properties: + id: + type: string + name: + type: string + devices: + type: array + items: + type: string + enum: [DESKTOP, MOBILE, TABLET] + os: + type: array + items: + type: string + enum: [IOS, ANDROID, WINDOWS, MACOS, LINUX] + placements: + type: array + items: + type: string + enum: [FEED, CONVERSATION, SIDEBAR] + age_range: + type: object + properties: + min: + type: integer + minimum: 18 + maximum: 65 + max: + type: integer + minimum: 18 + maximum: 65 + gender: + type: string + enum: [ALL, MALE, FEMALE, OTHER] + custom_audience_ids: + type: array + items: + type: string + excluded_custom_audience_ids: + type: array + items: + type: string + + Ad: + type: object + properties: + id: + type: string + name: + type: string + ad_group_id: + type: string + post_id: + type: string + status: + type: string + enum: [ACTIVE, PAUSED, REJECTED, PENDING_REVIEW, APPROVED] + click_url: + type: string + format: uri + third_party_trackers: + type: array + items: + type: object + properties: + event_type: + type: string + enum: [IMPRESSION, CLICK, VIDEO_VIEWED] + url: + type: string + format: uri + is_dynamic_creative: + type: boolean + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time + + AdInput: + type: object + required: + - name + - ad_group_id + - post_id + properties: + name: + type: string + minLength: 1 + maxLength: 400 + ad_group_id: + type: string + post_id: + type: string + click_url: + type: string + format: uri + third_party_trackers: + type: array + items: + type: object + properties: + event_type: + type: string + enum: [IMPRESSION, CLICK, VIDEO_VIEWED] + url: + type: string + format: uri + configured_status: + type: string + enum: [ACTIVE, PAUSED] + default: PAUSED + + Post: + type: object + properties: + id: + type: string + headline: + type: string + body: + type: string + post_type: + type: string + enum: [IMAGE, VIDEO, TEXT, GALLERY, CAROUSEL, LINK] + content: + type: array + items: + type: object + properties: + type: + type: string + enum: [IMAGE, VIDEO, TEXT, LINK] + url: + type: string + format: uri + thumbnail_url: + type: string + format: uri + destination_url: + type: string + format: uri + width: + type: integer + height: + type: integer + call_to_action: + type: string + enum: [LEARN_MORE, SIGN_UP, SHOP_NOW, INSTALL, DOWNLOAD, GET_QUOTE, CONTACT_US, APPLY_NOW] + cta_text: + type: string + preview_url: + type: string + format: uri + created_at: + type: string + format: date-time + + BulkAction: + type: object + required: + - type + - action + - reference_id + - entity_data + properties: + type: + type: string + enum: [CAMPAIGN, AD_GROUP, AD, POST, ASSET] + action: + type: string + enum: [CREATE, EDIT] + reference_id: + type: string + minLength: 1 + maxLength: 100 + description: Client-provided reference ID for correlating results + entity_data: + type: object + description: | + The entity data varies by type: + - CAMPAIGN: CampaignInput fields + - AD_GROUP: AdGroupInput fields + - AD: AdInput fields + - POST: PostInput fields + properties: + # Campaign fields + name: + type: string + maxLength: 400 + objective: + type: string + enum: [AWARENESS, CONSIDERATION, CONVERSIONS, TRAFFIC, VIDEO_VIEWS, APP_INSTALLS, CATALOG_SALES, LEADS] + daily_budget_micro: + type: integer + format: int64 + lifetime_budget_micro: + type: integer + format: int64 + start_time: + type: string + format: date-time + end_time: + type: string + format: date-time + funding_instrument_id: + type: string + configured_status: + type: string + enum: [ACTIVE, PAUSED] + # Ad Group fields + campaign_id: + type: string + bid_strategy: + type: string + enum: [AUTO, MANUAL_CPC, MANUAL_CPM, MANUAL_CPV] + bid_micro: + type: integer + format: int64 + goal_type: + type: string + enum: [CLICKS, IMPRESSIONS, VIDEO_VIEWS, CONVERSIONS, APP_INSTALLS] + targeting: + $ref: "#/components/schemas/Targeting" + # Ad fields + ad_group_id: + type: string + post_id: + type: string + click_url: + type: string + format: uri + # Post fields + headline: + type: string + maxLength: 300 + body: + type: string + maxLength: 40000 + post_type: + type: string + enum: [IMAGE, VIDEO, TEXT, GALLERY, CAROUSEL, LINK] + content: + type: array + items: + type: object + properties: + type: + type: string + url: + type: string + destination_url: + type: string + call_to_action: + type: string + destination_url: + type: string + format: uri + + BulkActionsResponse: + type: object + properties: + id: + type: string + nullable: true + status: + type: string + enum: [PENDING, RUNNING, SUCCESS, FAILED, UNVALIDATED] + input: + type: array + items: + $ref: "#/components/schemas/BulkAction" + results: + type: array + items: + $ref: "#/components/schemas/BulkActionResult" + + BulkActionResult: + type: object + properties: + reference_id: + type: string + type: + type: string + enum: [CAMPAIGN, AD_GROUP, AD, POST, ASSET] + status: + type: string + enum: [SUCCESS, FAILED, PENDING] + id: + type: string + nullable: true + errors: + type: array + items: + type: object + properties: + code: + type: string + field: + type: string + message: + type: string + suggestions: + type: array + items: + type: object + properties: + code: + type: string + field: + type: string + message: + type: string + + Pixel: + type: object + properties: + id: + type: string + name: + type: string + status: + type: string + enum: [ACTIVE, INACTIVE] + last_fired_at: + type: string + format: date-time + + FundingInstrument: + type: object + properties: + id: + type: string + type: + type: string + enum: [CREDIT_CARD, INVOICE, PREPAID] + status: + type: string + enum: [ACTIVE, INACTIVE, EXPIRED] + currency: + type: string + created_at: + type: string + format: date-time + + ReportingRequest: + type: object + required: + - start_date + - end_date + - level + properties: + start_date: + type: string + format: date + end_date: + type: string + format: date + level: + type: string + enum: [ACCOUNT, CAMPAIGN, AD_GROUP, AD] + metrics: + type: array + items: + type: string + enum: [IMPRESSIONS, CLICKS, SPEND, CTR, CPC, CPM, CONVERSIONS, ROAS, VIDEO_VIEWS, VIDEO_COMPLETION_RATE] + dimensions: + type: array + items: + type: string + enum: [DATE, CAMPAIGN_ID, AD_GROUP_ID, AD_ID, COUNTRY, DEVICE, OS, PLACEMENT, AGE, GENDER] + filters: + type: array + items: + type: object + properties: + field: + type: string + operator: + type: string + enum: [EQ, NEQ, GT, GTE, LT, LTE, IN, NOT_IN, CONTAINS] + values: + type: array + items: + type: string + + ReportingRow: + type: object + properties: + dimensions: + type: object + additionalProperties: + type: string + metrics: + type: object + additionalProperties: + type: number + + CustomAudience: + type: object + properties: + id: + type: string + name: + type: string + type: + type: string + enum: [CUSTOMER_LIST, WEBSITE, APP, ENGAGEMENT, LOOKALIKE] + status: + type: string + enum: [ACTIVE, PROCESSING, ERROR, EXPIRED] + size: + type: integer + created_at: + type: string + format: date-time diff --git a/test_specs/discriminator_ifthen.yaml b/test_specs/discriminator_ifthen.yaml new file mode 100644 index 00000000..3bfc52a4 --- /dev/null +++ b/test_specs/discriminator_ifthen.yaml @@ -0,0 +1,407 @@ +openapi: "3.1.0" +info: + title: Discriminator Benchmark - if/then (optimized) + description: | + Replaces oneOf+discriminator with allOf of if/then blocks. The jsonschema + library only validates the matching schema (the one where the if condition + passes), skipping all others with a cheap boolean const check. + version: "1.0.0" +servers: + - url: /api/v3 + +paths: + /ad_accounts/{ad_account_id}/bulk_actions: + post: + operationId: createBulkActions + parameters: + - name: ad_account_id + in: path + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + minItems: 1 + maxItems: 50 + items: + $ref: "#/components/schemas/BulkAction" + responses: + "201": + description: Created + +components: + schemas: + BulkAction: + type: object + required: + - type + - action + - reference_id + - entity_data + properties: + type: + type: string + enum: [CAMPAIGN, AD_GROUP, AD, POST, ASSET] + action: + type: string + enum: [CREATE, EDIT] + reference_id: + type: string + minLength: 1 + maxLength: 100 + entity_data: + # Instead of oneOf + discriminator, use allOf with if/then. + # Only the matching if/then branch runs full validation. + # Non-matching branches just do a cheap const check and skip. + type: object + allOf: + - if: + required: [entity_type] + properties: + entity_type: + const: CAMPAIGN + then: + $ref: "#/components/schemas/CampaignInput" + - if: + required: [entity_type] + properties: + entity_type: + const: AD_GROUP + then: + $ref: "#/components/schemas/AdGroupInput" + - if: + required: [entity_type] + properties: + entity_type: + const: AD + then: + $ref: "#/components/schemas/AdInput" + - if: + required: [entity_type] + properties: + entity_type: + const: POST + then: + $ref: "#/components/schemas/PostInput" + - if: + required: [entity_type] + properties: + entity_type: + const: ASSET + then: + $ref: "#/components/schemas/AssetInput" + # Ensure discriminator value is valid + - properties: + entity_type: + type: string + enum: [CAMPAIGN, AD_GROUP, AD, POST, ASSET] + required: [entity_type] + + CampaignInput: + type: object + required: + - entity_type + - name + - objective + - daily_budget_micro + - start_time + - funding_instrument_id + properties: + entity_type: + type: string + const: CAMPAIGN + name: + type: string + minLength: 1 + maxLength: 400 + objective: + type: string + enum: [AWARENESS, CONSIDERATION, CONVERSIONS, TRAFFIC, VIDEO_VIEWS, APP_INSTALLS] + daily_budget_micro: + type: integer + minimum: 500000 + lifetime_budget_micro: + type: integer + minimum: 500000 + start_time: + type: string + format: date-time + end_time: + type: string + format: date-time + funding_instrument_id: + type: string + configured_status: + type: string + enum: [ACTIVE, PAUSED] + default: PAUSED + + AdGroupInput: + type: object + required: + - entity_type + - name + - campaign_id + - bid_strategy + - goal_type + - start_time + properties: + entity_type: + type: string + const: AD_GROUP + name: + type: string + minLength: 1 + maxLength: 400 + campaign_id: + type: string + bid_strategy: + type: string + enum: [AUTO, MANUAL_CPC, MANUAL_CPM, MANUAL_CPV] + bid_micro: + type: integer + minimum: 10000 + goal_type: + type: string + enum: [CLICKS, IMPRESSIONS, VIDEO_VIEWS, CONVERSIONS, APP_INSTALLS] + start_time: + type: string + format: date-time + end_time: + type: string + format: date-time + targeting: + $ref: "#/components/schemas/Targeting" + configured_status: + type: string + enum: [ACTIVE, PAUSED] + default: PAUSED + + AdInput: + type: object + required: + - entity_type + - name + - ad_group_id + - post_id + properties: + entity_type: + type: string + const: AD + name: + type: string + minLength: 1 + maxLength: 400 + ad_group_id: + type: string + post_id: + type: string + click_url: + type: string + format: uri + configured_status: + type: string + enum: [ACTIVE, PAUSED] + default: PAUSED + + PostInput: + type: object + required: + - entity_type + - headline + - post_type + - content + properties: + entity_type: + type: string + const: POST + headline: + type: string + maxLength: 300 + body: + type: string + maxLength: 40000 + post_type: + type: string + enum: [IMAGE, VIDEO, TEXT, GALLERY, CAROUSEL, LINK] + content: + type: array + minItems: 1 + items: + # Nested discriminator also uses if/then pattern + type: object + allOf: + - if: + required: [content_type] + properties: + content_type: + const: IMAGE + then: + $ref: "#/components/schemas/ImageContent" + - if: + required: [content_type] + properties: + content_type: + const: VIDEO + then: + $ref: "#/components/schemas/VideoContent" + - if: + required: [content_type] + properties: + content_type: + const: TEXT + then: + $ref: "#/components/schemas/TextContent" + - properties: + content_type: + type: string + enum: [IMAGE, VIDEO, TEXT] + required: [content_type] + destination_url: + type: string + format: uri + + AssetInput: + type: object + required: + - entity_type + - asset_type + - url + properties: + entity_type: + type: string + const: ASSET + asset_type: + type: string + enum: [IMAGE, VIDEO, LOGO] + url: + type: string + format: uri + width: + type: integer + height: + type: integer + + ImageContent: + type: object + required: + - content_type + - url + properties: + content_type: + type: string + const: IMAGE + url: + type: string + format: uri + thumbnail_url: + type: string + format: uri + destination_url: + type: string + format: uri + width: + type: integer + height: + type: integer + call_to_action: + type: string + enum: [LEARN_MORE, SIGN_UP, SHOP_NOW, INSTALL, DOWNLOAD] + + VideoContent: + type: object + required: + - content_type + - url + properties: + content_type: + type: string + const: VIDEO + url: + type: string + format: uri + thumbnail_url: + type: string + format: uri + destination_url: + type: string + format: uri + duration_seconds: + type: integer + minimum: 1 + maximum: 180 + call_to_action: + type: string + enum: [LEARN_MORE, SIGN_UP, SHOP_NOW, INSTALL, DOWNLOAD, WATCH_MORE] + + TextContent: + type: object + required: + - content_type + - body + properties: + content_type: + type: string + const: TEXT + body: + type: string + maxLength: 40000 + destination_url: + type: string + format: uri + call_to_action: + type: string + enum: [LEARN_MORE, SIGN_UP, SHOP_NOW] + + Targeting: + type: object + properties: + geos: + type: object + properties: + included: + type: array + items: + type: object + properties: + country: + type: string + region: + type: string + interests: + type: array + items: + type: object + properties: + id: + type: string + name: + type: string + devices: + type: array + items: + type: string + enum: [DESKTOP, MOBILE, TABLET] + age_range: + type: object + properties: + min: + type: integer + minimum: 18 + maximum: 65 + max: + type: integer + minimum: 18 + maximum: 65 + gender: + type: string + enum: [ALL, MALE, FEMALE, OTHER] diff --git a/test_specs/discriminator_oneof.yaml b/test_specs/discriminator_oneof.yaml new file mode 100644 index 00000000..d7fd2f8a --- /dev/null +++ b/test_specs/discriminator_oneof.yaml @@ -0,0 +1,355 @@ +openapi: "3.1.0" +info: + title: Discriminator Benchmark - oneOf (baseline) + description: | + Uses standard oneOf + discriminator pattern. The jsonschema library will + brute-force validate against ALL schemas in the oneOf to find the match. + version: "1.0.0" +servers: + - url: /api/v3 + +paths: + /ad_accounts/{ad_account_id}/bulk_actions: + post: + operationId: createBulkActions + parameters: + - name: ad_account_id + in: path + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + minItems: 1 + maxItems: 50 + items: + $ref: "#/components/schemas/BulkAction" + responses: + "201": + description: Created + +components: + schemas: + BulkAction: + type: object + required: + - type + - action + - reference_id + - entity_data + properties: + type: + type: string + enum: [CAMPAIGN, AD_GROUP, AD, POST, ASSET] + action: + type: string + enum: [CREATE, EDIT] + reference_id: + type: string + minLength: 1 + maxLength: 100 + entity_data: + oneOf: + - $ref: "#/components/schemas/CampaignInput" + - $ref: "#/components/schemas/AdGroupInput" + - $ref: "#/components/schemas/AdInput" + - $ref: "#/components/schemas/PostInput" + - $ref: "#/components/schemas/AssetInput" + discriminator: + propertyName: entity_type + mapping: + CAMPAIGN: "#/components/schemas/CampaignInput" + AD_GROUP: "#/components/schemas/AdGroupInput" + AD: "#/components/schemas/AdInput" + POST: "#/components/schemas/PostInput" + ASSET: "#/components/schemas/AssetInput" + + CampaignInput: + type: object + required: + - entity_type + - name + - objective + - daily_budget_micro + - start_time + - funding_instrument_id + properties: + entity_type: + type: string + const: CAMPAIGN + name: + type: string + minLength: 1 + maxLength: 400 + objective: + type: string + enum: [AWARENESS, CONSIDERATION, CONVERSIONS, TRAFFIC, VIDEO_VIEWS, APP_INSTALLS] + daily_budget_micro: + type: integer + minimum: 500000 + lifetime_budget_micro: + type: integer + minimum: 500000 + start_time: + type: string + format: date-time + end_time: + type: string + format: date-time + funding_instrument_id: + type: string + configured_status: + type: string + enum: [ACTIVE, PAUSED] + default: PAUSED + + AdGroupInput: + type: object + required: + - entity_type + - name + - campaign_id + - bid_strategy + - goal_type + - start_time + properties: + entity_type: + type: string + const: AD_GROUP + name: + type: string + minLength: 1 + maxLength: 400 + campaign_id: + type: string + bid_strategy: + type: string + enum: [AUTO, MANUAL_CPC, MANUAL_CPM, MANUAL_CPV] + bid_micro: + type: integer + minimum: 10000 + goal_type: + type: string + enum: [CLICKS, IMPRESSIONS, VIDEO_VIEWS, CONVERSIONS, APP_INSTALLS] + start_time: + type: string + format: date-time + end_time: + type: string + format: date-time + targeting: + $ref: "#/components/schemas/Targeting" + configured_status: + type: string + enum: [ACTIVE, PAUSED] + default: PAUSED + + AdInput: + type: object + required: + - entity_type + - name + - ad_group_id + - post_id + properties: + entity_type: + type: string + const: AD + name: + type: string + minLength: 1 + maxLength: 400 + ad_group_id: + type: string + post_id: + type: string + click_url: + type: string + format: uri + configured_status: + type: string + enum: [ACTIVE, PAUSED] + default: PAUSED + + PostInput: + type: object + required: + - entity_type + - headline + - post_type + - content + properties: + entity_type: + type: string + const: POST + headline: + type: string + maxLength: 300 + body: + type: string + maxLength: 40000 + post_type: + type: string + enum: [IMAGE, VIDEO, TEXT, GALLERY, CAROUSEL, LINK] + content: + type: array + minItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ImageContent" + - $ref: "#/components/schemas/VideoContent" + - $ref: "#/components/schemas/TextContent" + discriminator: + propertyName: content_type + mapping: + IMAGE: "#/components/schemas/ImageContent" + VIDEO: "#/components/schemas/VideoContent" + TEXT: "#/components/schemas/TextContent" + destination_url: + type: string + format: uri + + AssetInput: + type: object + required: + - entity_type + - asset_type + - url + properties: + entity_type: + type: string + const: ASSET + asset_type: + type: string + enum: [IMAGE, VIDEO, LOGO] + url: + type: string + format: uri + width: + type: integer + height: + type: integer + + ImageContent: + type: object + required: + - content_type + - url + properties: + content_type: + type: string + const: IMAGE + url: + type: string + format: uri + thumbnail_url: + type: string + format: uri + destination_url: + type: string + format: uri + width: + type: integer + height: + type: integer + call_to_action: + type: string + enum: [LEARN_MORE, SIGN_UP, SHOP_NOW, INSTALL, DOWNLOAD] + + VideoContent: + type: object + required: + - content_type + - url + properties: + content_type: + type: string + const: VIDEO + url: + type: string + format: uri + thumbnail_url: + type: string + format: uri + destination_url: + type: string + format: uri + duration_seconds: + type: integer + minimum: 1 + maximum: 180 + call_to_action: + type: string + enum: [LEARN_MORE, SIGN_UP, SHOP_NOW, INSTALL, DOWNLOAD, WATCH_MORE] + + TextContent: + type: object + required: + - content_type + - body + properties: + content_type: + type: string + const: TEXT + body: + type: string + maxLength: 40000 + destination_url: + type: string + format: uri + call_to_action: + type: string + enum: [LEARN_MORE, SIGN_UP, SHOP_NOW] + + Targeting: + type: object + properties: + geos: + type: object + properties: + included: + type: array + items: + type: object + properties: + country: + type: string + region: + type: string + interests: + type: array + items: + type: object + properties: + id: + type: string + name: + type: string + devices: + type: array + items: + type: string + enum: [DESKTOP, MOBILE, TABLET] + age_range: + type: object + properties: + min: + type: integer + minimum: 18 + maximum: 65 + max: + type: integer + minimum: 18 + maximum: 65 + gender: + type: string + enum: [ALL, MALE, FEMALE, OTHER] diff --git a/validator.go b/validator.go index bc6e39cf..96c9b16d 100644 --- a/validator.go +++ b/validator.go @@ -7,6 +7,7 @@ import ( "fmt" "net/http" "sort" + "strings" "sync" "github.com/pb33f/libopenapi" @@ -21,7 +22,7 @@ import ( "github.com/pb33f/libopenapi-validator/errors" "github.com/pb33f/libopenapi-validator/helpers" "github.com/pb33f/libopenapi-validator/parameters" - "github.com/pb33f/libopenapi-validator/paths" + "github.com/pb33f/libopenapi-validator/radix" "github.com/pb33f/libopenapi-validator/requests" "github.com/pb33f/libopenapi-validator/responses" "github.com/pb33f/libopenapi-validator/schema_validation" @@ -88,7 +89,32 @@ func NewValidator(document libopenapi.Document, opts ...config.Option) (Validato func NewValidatorFromV3Model(m *v3.Document, opts ...config.Option) Validator { options := config.NewValidationOptions(opts...) - v := &validator{options: options, v3Model: m} + // Build radix tree for O(k) path lookup (where k = path depth) + // Skip if explicitly set via WithPathTree (including nil to disable) + if options.PathTree == nil && !options.IsPathTreeSet() { + options.PathTree = radix.BuildPathTree(m) + } + + // warm the schema caches by pre-compiling all schemas in the document + // (warmSchemaCaches checks for nil cache and skips if disabled) + warmSchemaCaches(m, options) + + // warm the regex cache by pre-compiling all path parameter regexes + warmRegexCache(m, options) + + // Build the matcher chain: radix first (fast), regex fallback (handles complex patterns) + var matchers matcherChain + if options.PathTree != nil { + matchers = append(matchers, &radixMatcher{pathLookup: options.PathTree}) + } + matchers = append(matchers, ®exMatcher{regexCache: options.RegexCache}) + + v := &validator{ + options: options, + v3Model: m, + matchers: matchers, + version: helpers.VersionToFloat(m.Version), + } // create a new parameter validator v.paramValidator = parameters.NewParameterValidator(m, config.WithExistingOpts(options)) @@ -99,10 +125,6 @@ func NewValidatorFromV3Model(m *v3.Document, opts ...config.Option) Validator { // create a response body validator v.responseValidator = responses.NewResponseBodyValidator(m, config.WithExistingOpts(options)) - // warm the schema caches by pre-compiling all schemas in the document - // (warmSchemaCaches checks for nil cache and skips if disabled) - warmSchemaCaches(m, options) - return v } @@ -145,20 +167,12 @@ func (v *validator) ValidateHttpResponse( request *http.Request, response *http.Response, ) (bool, []*errors.ValidationError) { - var pathItem *v3.PathItem - var pathValue string - var errs []*errors.ValidationError - - pathItem, errs, pathValue = paths.FindPath(request, v.v3Model, v.options.RegexCache) - if pathItem == nil || errs != nil { + ctx, errs := v.buildRequestContext(request) + if errs != nil { return false, errs } - - responseBodyValidator := v.responseValidator - - // validate response - _, responseErrors := responseBodyValidator.ValidateResponseBodyWithPathItem(request, response, pathItem, pathValue) - + _, responseErrors := v.responseValidator.ValidateResponseBodyWithPathItem( + request, response, ctx.route.pathItem, ctx.route.matchedPath) if len(responseErrors) > 0 { return false, responseErrors } @@ -169,21 +183,13 @@ func (v *validator) ValidateHttpRequestResponse( request *http.Request, response *http.Response, ) (bool, []*errors.ValidationError) { - var pathItem *v3.PathItem - var pathValue string - var errs []*errors.ValidationError - - pathItem, errs, pathValue = paths.FindPath(request, v.v3Model, v.options.RegexCache) - if pathItem == nil || errs != nil { + ctx, errs := v.buildRequestContext(request) + if errs != nil { return false, errs } - - responseBodyValidator := v.responseValidator - - // validate request and response - _, requestErrors := v.ValidateHttpRequestWithPathItem(request, pathItem, pathValue) - _, responseErrors := responseBodyValidator.ValidateResponseBodyWithPathItem(request, response, pathItem, pathValue) - + _, requestErrors := v.ValidateHttpRequestWithPathItem(request, ctx.route.pathItem, ctx.route.matchedPath) + _, responseErrors := v.responseValidator.ValidateResponseBodyWithPathItem( + request, response, ctx.route.pathItem, ctx.route.matchedPath) if len(requestErrors) > 0 || len(responseErrors) > 0 { return false, append(requestErrors, responseErrors...) } @@ -191,154 +197,125 @@ func (v *validator) ValidateHttpRequestResponse( } func (v *validator) ValidateHttpRequest(request *http.Request) (bool, []*errors.ValidationError) { - pathItem, errs, foundPath := paths.FindPath(request, v.v3Model, v.options.RegexCache) - if len(errs) > 0 { + // Fast path: use synchronous validation for requests without a body + // to avoid unnecessary goroutine overhead. + if request.Body == nil || request.ContentLength == 0 { + return v.ValidateHttpRequestSync(request) + } + + ctx, errs := v.buildRequestContext(request) + if errs != nil { return false, errs } - return v.ValidateHttpRequestWithPathItem(request, pathItem, foundPath) + return v.validateWithContext(ctx) } func (v *validator) ValidateHttpRequestWithPathItem(request *http.Request, pathItem *v3.PathItem, pathValue string) (bool, []*errors.ValidationError) { - // create a new parameter validator - paramValidator := v.paramValidator - - // create a new request body validator - reqBodyValidator := v.requestValidator - - // create some channels to handle async validation - doneChan := make(chan struct{}) - errChan := make(chan []*errors.ValidationError) - controlChan := make(chan struct{}) - - // async param validation function. - parameterValidationFunc := func(control chan struct{}, errorChan chan []*errors.ValidationError) { - paramErrs := make(chan []*errors.ValidationError) - paramControlChan := make(chan struct{}) - paramFunctionControlChan := make(chan struct{}) - var paramValidationErrors []*errors.ValidationError - - validations := []validationFunction{ - paramValidator.ValidatePathParamsWithPathItem, - paramValidator.ValidateCookieParamsWithPathItem, - paramValidator.ValidateHeaderParamsWithPathItem, - paramValidator.ValidateQueryParamsWithPathItem, - paramValidator.ValidateSecurityWithPathItem, - } + ctx := &requestContext{ + request: request, + route: &resolvedRoute{ + pathItem: pathItem, + matchedPath: pathValue, + }, + operation: helpers.OperationForMethod(request.Method, pathItem), + version: v.version, + } + return v.validateWithContext(ctx) +} - // listen for validation errors on parameters. everything will run async. - paramListener := func(control chan struct{}, errorChan chan []*errors.ValidationError) { - completedValidations := 0 - for { - select { - case vErrs := <-errorChan: - paramValidationErrors = append(paramValidationErrors, vErrs...) - case <-control: - completedValidations++ - if completedValidations == len(validations) { - paramFunctionControlChan <- struct{}{} - return - } - } - } - } +func (v *validator) validatePathParamsCtx(ctx *requestContext) (bool, []*errors.ValidationError) { + return v.paramValidator.ValidatePathParamsWithPathItem(ctx.request, ctx.route.pathItem, ctx.route.matchedPath) +} - validateParamFunction := func( - control chan struct{}, - errorChan chan []*errors.ValidationError, - validatorFunc validationFunction, - ) { - valid, pErrs := validatorFunc(request, pathItem, pathValue) - if !valid { - errorChan <- pErrs - } - control <- struct{}{} - } - go paramListener(paramControlChan, paramErrs) - for i := range validations { - go validateParamFunction(paramControlChan, paramErrs, validations[i]) - } +func (v *validator) validateQueryParamsCtx(ctx *requestContext) (bool, []*errors.ValidationError) { + return v.paramValidator.ValidateQueryParamsWithPathItem(ctx.request, ctx.route.pathItem, ctx.route.matchedPath) +} - // wait for all the validations to complete - <-paramFunctionControlChan - if len(paramValidationErrors) > 0 { - errorChan <- paramValidationErrors - } +func (v *validator) validateHeaderParamsCtx(ctx *requestContext) (bool, []*errors.ValidationError) { + return v.paramValidator.ValidateHeaderParamsWithPathItem(ctx.request, ctx.route.pathItem, ctx.route.matchedPath) +} - // let runValidation know we are done with this part. - controlChan <- struct{}{} - } +func (v *validator) validateCookieParamsCtx(ctx *requestContext) (bool, []*errors.ValidationError) { + return v.paramValidator.ValidateCookieParamsWithPathItem(ctx.request, ctx.route.pathItem, ctx.route.matchedPath) +} - requestBodyValidationFunc := func(control chan struct{}, errorChan chan []*errors.ValidationError) { - valid, pErrs := reqBodyValidator.ValidateRequestBodyWithPathItem(request, pathItem, pathValue) - if !valid { - errorChan <- pErrs - } - control <- struct{}{} - } +func (v *validator) validateSecurityCtx(ctx *requestContext) (bool, []*errors.ValidationError) { + return v.paramValidator.ValidateSecurityWithPathItem(ctx.request, ctx.route.pathItem, ctx.route.matchedPath) +} - // build async functions - asyncFunctions := []validationFunctionAsync{ - parameterValidationFunc, - requestBodyValidationFunc, - } +func (v *validator) validateRequestBodyCtx(ctx *requestContext) (bool, []*errors.ValidationError) { + return v.requestValidator.ValidateRequestBodyWithPathItem(ctx.request, ctx.route.pathItem, ctx.route.matchedPath) +} +// validateRequestSync runs all validation functions sequentially using the request context. +func (v *validator) validateRequestSync(ctx *requestContext) (bool, []*errors.ValidationError) { var validationErrors []*errors.ValidationError - - // sit and wait for everything to report back. - go runValidation(controlChan, doneChan, errChan, &validationErrors, len(asyncFunctions)) - - // run async functions - for i := range asyncFunctions { - go asyncFunctions[i](controlChan, errChan) + for _, validateFunc := range []validationFunction{ + v.validatePathParamsCtx, + v.validateCookieParamsCtx, + v.validateHeaderParamsCtx, + v.validateQueryParamsCtx, + v.validateSecurityCtx, + v.validateRequestBodyCtx, + } { + if valid, pErrs := validateFunc(ctx); !valid { + validationErrors = append(validationErrors, pErrs...) + } } + return len(validationErrors) == 0, validationErrors +} - // wait for all the validations to complete - <-doneChan - - // sort errors for deterministic ordering (async validation can return errors in any order) - sortValidationErrors(validationErrors) +// validateWithContext runs all validation functions concurrently using a WaitGroup. +// This replaces the previous 9-goroutine/5-channel choreography with a simpler pattern. +func (v *validator) validateWithContext(ctx *requestContext) (bool, []*errors.ValidationError) { + var mu sync.Mutex + var wg sync.WaitGroup + var allErrors []*errors.ValidationError + + validators := []validationFunction{ + v.validatePathParamsCtx, + v.validateCookieParamsCtx, + v.validateHeaderParamsCtx, + v.validateQueryParamsCtx, + v.validateSecurityCtx, + v.validateRequestBodyCtx, + } - return len(validationErrors) == 0, validationErrors + wg.Add(len(validators)) + for _, fn := range validators { + go func(validate validationFunction) { + defer wg.Done() + if valid, errs := validate(ctx); !valid { + mu.Lock() + allErrors = append(allErrors, errs...) + mu.Unlock() + } + }(fn) + } + wg.Wait() + sortValidationErrors(allErrors) + return len(allErrors) == 0, allErrors } func (v *validator) ValidateHttpRequestSync(request *http.Request) (bool, []*errors.ValidationError) { - pathItem, errs, foundPath := paths.FindPath(request, v.v3Model, v.options.RegexCache) - if len(errs) > 0 { + ctx, errs := v.buildRequestContext(request) + if errs != nil { return false, errs } - return v.ValidateHttpRequestSyncWithPathItem(request, pathItem, foundPath) + return v.validateRequestSync(ctx) } func (v *validator) ValidateHttpRequestSyncWithPathItem(request *http.Request, pathItem *v3.PathItem, pathValue string) (bool, []*errors.ValidationError) { - // create a new parameter validator - paramValidator := v.paramValidator - - // create a new request body validator - reqBodyValidator := v.requestValidator - - validationErrors := make([]*errors.ValidationError, 0) - - paramValidationErrors := make([]*errors.ValidationError, 0) - for _, validateFunc := range []validationFunction{ - paramValidator.ValidatePathParamsWithPathItem, - paramValidator.ValidateCookieParamsWithPathItem, - paramValidator.ValidateHeaderParamsWithPathItem, - paramValidator.ValidateQueryParamsWithPathItem, - paramValidator.ValidateSecurityWithPathItem, - } { - valid, pErrs := validateFunc(request, pathItem, pathValue) - if !valid { - paramValidationErrors = append(paramValidationErrors, pErrs...) - } - } - - valid, pErrs := reqBodyValidator.ValidateRequestBodyWithPathItem(request, pathItem, pathValue) - if !valid { - paramValidationErrors = append(paramValidationErrors, pErrs...) + ctx := &requestContext{ + request: request, + route: &resolvedRoute{ + pathItem: pathItem, + matchedPath: pathValue, + }, + operation: helpers.OperationForMethod(request.Method, pathItem), + version: v.version, } - - validationErrors = append(validationErrors, paramValidationErrors...) - return len(validationErrors) == 0, validationErrors + return v.validateRequestSync(ctx) } type validator struct { @@ -348,35 +325,11 @@ type validator struct { paramValidator parameters.ParameterValidator requestValidator requests.RequestBodyValidator responseValidator responses.ResponseBodyValidator + matchers matcherChain + version float32 // cached OAS version (3.0 or 3.1) } -func runValidation(control, doneChan chan struct{}, - errorChan chan []*errors.ValidationError, - validationErrors *[]*errors.ValidationError, - total int, -) { - var validationLock sync.Mutex - completedValidations := 0 - for { - select { - case vErrs := <-errorChan: - validationLock.Lock() - *validationErrors = append(*validationErrors, vErrs...) - validationLock.Unlock() - case <-control: - completedValidations++ - if completedValidations == total { - doneChan <- struct{}{} - return - } - } - } -} - -type ( - validationFunction func(request *http.Request, pathItem *v3.PathItem, pathValue string) (bool, []*errors.ValidationError) - validationFunctionAsync func(control chan struct{}, errorChan chan []*errors.ValidationError) -) +type validationFunction func(ctx *requestContext) (bool, []*errors.ValidationError) // sortValidationErrors sorts validation errors for deterministic ordering. // Errors are sorted by validation type first, then by message. @@ -563,3 +516,31 @@ func warmParameterSchema(param *v3.Parameter, schemaCache cache.SchemaCache, opt } } } + +// warmRegexCache pre-compiles all path parameter regexes in the OpenAPI document and stores them in the regex cache. +// This frontloads the compilation cost so that runtime validation doesn't need to compile regexes for path segments. +func warmRegexCache(doc *v3.Document, options *config.ValidationOptions) { + if doc == nil || doc.Paths == nil || doc.Paths.PathItems == nil || options.RegexCache == nil { + return + } + + for pathPair := doc.Paths.PathItems.First(); pathPair != nil; pathPair = pathPair.Next() { + pathKey := pathPair.Key() + segments := strings.Split(pathKey, "/") + for _, segment := range segments { + if segment == "" { + continue + } + // Only compile segments that contain path parameters (have braces) + if !strings.Contains(segment, "{") { + continue + } + if _, found := options.RegexCache.Load(segment); !found { + r, err := helpers.GetRegexForPath(segment) + if err == nil { + options.RegexCache.Store(segment, r) + } + } + } + } +}