fix(openapi): improve OpenAPI path matching with rou3 v1

[dinwwwh]

Upgrade to rou3 v1.0.0 and improve OpenAPI path matching to handle edge cases with catch-all parameters, non-identifier parameter names, special characters, and percent-encoding.

Summary

This PR upgrades the rou3 dependency to v1.0.0 and refactors the OpenAPI path matching logic to properly handle:

• Catch-all parameters ({+path}) that may be empty or followed by additional segments
• Parameter names that aren't valid JavaScript identifiers (e.g., {user-id}, {0})
• Repeated parameter names in the same path
• Special characters in literal path segments (:, *, ?, +, (), {}, ., etc.)
• Non-ASCII characters in paths (matched against percent-encoded request paths)
• Percent-encoding normalization for user requests

Key Changes

• Route pattern generation: Replaced simple parameter substitution with a more robust toRou3Route() function that:

  • Escapes rou3 syntax characters in literal path segments
  • Maps parameter names to internal rou3 keys (p0, p1, etc.) to support non-identifier names
  • Detects and validates that paths have at most one catch-all parameter
  • Tracks catch-all parameter keys for later validation

• Match resolution: Added findMatch() method that:

  • Filters out matches where catch-all parameters captured empty values (invalid)
  • Falls back to less specific routes when catch-all parameters are empty
  • Uses findAllRoutes() to find the most specific valid match

• Parameter decoding: Updated decodeParams() to map from internal rou3 keys back to original parameter names and decode URI components

• Prefix matching: Enhanced toRou3PrefixMatcher() to handle prefixes with catch-all parameters

• Lazy router handling: Improved to resolve lazy routers with prefixes ending in / or containing catch-all parameters, and to properly handle errors during lazy loading

• Test coverage: Added comprehensive tests for edge cases including special characters, non-ASCII paths, catch-all parameter validation, and lazy router resolution

Implementation Details

• Parameter names are now stored as [rou3Key, originalName] tuples in tree entries to support non-identifier names
• Literal path segments are escaped using a regex that covers rou3 syntax plus the first dot of . and .. segments
• Empty catch-all matches are detected and skipped to find the next most specific route
• Percent-encoding normalization is only retried for paths containing % to keep misses efficient

https://claude.ai/code/session_01YRJj66odKexHiFFZ1qyVcU

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	orpc	ef3096b	Commit Preview URL Branch Preview URL	Oct 04 2026, 04:09 AM

[pkg-pr-new]

More templates

• @orpc/bun-playground
• @orpc/cloudflare-playground
• @orpc/nest-playground
• @orpc/next-playground

@orpc/ai-sdk

npm i https://pkg.pr.new/@orpc/ai-sdk@2173

@orpc/arktype

npm i https://pkg.pr.new/@orpc/arktype@2173

@orpc/bun

npm i https://pkg.pr.new/@orpc/bun@2173

@orpc/client

npm i https://pkg.pr.new/@orpc/client@2173

@orpc/cloudflare

npm i https://pkg.pr.new/@orpc/cloudflare@2173

@orpc/contract

npm i https://pkg.pr.new/@orpc/contract@2173

@orpc/experimental-effect

npm i https://pkg.pr.new/@orpc/experimental-effect@2173

@orpc/evlog

npm i https://pkg.pr.new/@orpc/evlog@2173

@orpc/hibernation

npm i https://pkg.pr.new/@orpc/hibernation@2173

@orpc/json-schema

npm i https://pkg.pr.new/@orpc/json-schema@2173

@orpc/experimental-lock

npm i https://pkg.pr.new/@orpc/experimental-lock@2173

@orpc/experimental-msw

npm i https://pkg.pr.new/@orpc/experimental-msw@2173

@orpc/nest

npm i https://pkg.pr.new/@orpc/nest@2173

@orpc/next

npm i https://pkg.pr.new/@orpc/next@2173

@orpc/node

npm i https://pkg.pr.new/@orpc/node@2173

@orpc/openapi

npm i https://pkg.pr.new/@orpc/openapi@2173

@orpc/opentelemetry

npm i https://pkg.pr.new/@orpc/opentelemetry@2173

@orpc/pinia-colada

npm i https://pkg.pr.new/@orpc/pinia-colada@2173

@orpc/pino

npm i https://pkg.pr.new/@orpc/pino@2173

@orpc/publisher

npm i https://pkg.pr.new/@orpc/publisher@2173

@orpc/ratelimit

npm i https://pkg.pr.new/@orpc/ratelimit@2173

@orpc/server

npm i https://pkg.pr.new/@orpc/server@2173

@orpc/shared

npm i https://pkg.pr.new/@orpc/shared@2173

@orpc/swr

npm i https://pkg.pr.new/@orpc/swr@2173

@orpc/tanstack-query

npm i https://pkg.pr.new/@orpc/tanstack-query@2173

@orpc/trpc

npm i https://pkg.pr.new/@orpc/trpc@2173

@orpc/valibot

npm i https://pkg.pr.new/@orpc/valibot@2173

@orpc/zod

npm i https://pkg.pr.new/@orpc/zod@2173

commit: ef3096b

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will not alter performance

✅ 30 untouched benchmarks

---

_{Comparing claude/hopeful-darwin-k7ip6f (ef3096b) with main (cf36774)¹}

Footnotes

1. No successful run was found on main (cb7715a) during the generation of this report, so cf36774 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[pullfrog]

ℹ️ No critical issues — one informational note on the dependency bump.

Reviewed changes

• rou3 0.9.1 → 1.0.0 — packages/openapi/package.json, the lockfile, and the pnpm-workspace.yaml release-age allowlist.
• Route pattern generation (toRou3Route) — escapes rou3 syntax in literal segments, remaps non-identifier and repeated param names to internal p0… keys, rejects more than one catch-all, and records the catch-all key on the entry.
• Match resolution (findMatch) — when the best match's catch-all captured an empty value, falls back to the most specific valid route via findAllRoutes; empty catch-alls are no longer valid matches.
• Param decoding (decodeParams) — maps internal keys back to the original names and decodes values, using setOwn so a __proto__ param stays an own property.
• Prefix and lazy indexing (toRou3PrefixMatcher, index) — prefix matchers now handle trailing slashes and catch-all prefixes, and routes are collected before being committed so a single invalid path in a lazy router indexes nothing.
• Tests and docs — extensive edge-case coverage (non-identifier names, repeated names, special characters, non-ASCII, catch-all suffix and empty fallback, lazy resolution) plus a docs sentence about {+name}.

Behavior looks correct and thoroughly covered. I ran the full @orpc/openapi suite (481 passed), the package typecheck, and eslint on both changed files — all clean. I also confirmed against rou3 v1 that findAllRoutes orders least→most specific, so .reverse().find(...) genuinely yields the most specific valid route, and probed __proto__/special-character params.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}