Find an operation without walking the document

[rasuvaeff]

Class C of the full-cycle review (docs/reviews/review-openapi-contract-2026-09-06-full-cycle.md), findings C-1 and C-2.

C-1. Matching scanned every operation and every one of its servers per request — 0.83 ms on a thousand-operation document, identical for a hit and for a miss, since nothing stopped early.

              before      after
   50 ops:   0.053 ms   0.014 ms
  250 ops:   0.210 ms   0.009 ms
 1000 ops:   0.829 ms   0.006 ms

Routes are bucketed by method, segment count and first literal segment. Each key is a property matchPath() checks before anything else — equal segment counts, a literal equal to the decoded request segment — so a bucket miss skips work that would have been discarded anyway. Templated first segments sit in an always-scanned bucket.

Selection is unchanged by construction, not by hope: candidates are sorted by a comparator ending on the unique operation key, so the outcome never depended on collection order. The first attempt bucketed by method and segment count only and came out slower — a document where every path has the same shape lands in one bucket and pays the index for nothing. That measurement is what led to the first-segment key.

A benchmark pins the property against the lookup a consumer would write by hand over operations(): 1.63 µs versus 225 µs on the same document. A new test pins the bucketing edges — templated first segment, percent-encoded literal, a server base that prefixes the route.

C-2. examples/ had one script for thirteen public types. Two more: gate-a-request.php (validate in, hand on, validate out — the shape a PSR-15 middleware takes, over a multi-file fromFile() document) and budgets.php (Limits, and why *.body.too_large is a refusal to read).

Verification: composer build, composer rector, bin/package-audit green; corpus current (290 cases); mutation 2222 killed / 160 escaped, MSI 93% against a gate of 92 — the two new escapes widen bucketing, which cannot change a verdict, and are classified in AGENTS.md.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 9c8d9543-8aff-462e-a099-62353771babc

Warning

Your free Security trial is over. An organization admin can upgrade to Advanced for continuous pull request security review or dismiss this notice.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}