fix: backport #7974 — [TT-16890] validate middleware collapsed path fix

[buger]

Summary

Backport of #7974 to release-5.8. Follow-up fix for collapsed parameterized path disambiguation in validate-request and mock-response OAS middleware.

This branch includes two commits:

1. Backport of [TT-16890] critical regression validate request middleware d #7972 (prerequisite) -- static path shields and path priority sorting
2. Backport of [TT-16890] Validate middleware speicifc fix #7974 -- collapsed parameterized path disambiguation

Conflict resolution (vs master):

• Replaced pkg/schema.RestoreUnicodeEscapesInError with lib.RestoreUnicodeEscapesInError (pkg/schema doesn't exist on release-5.8)
• Removed internal/mcp import and MCP-related functions (not present on release-5.8)
• Added internal/oasutil import with exported PathLess and PathParamRegex

Test plan

• Unit Tests & Linting passes
• go build ./gateway/... passes (verified locally)

🤖 Generated with Claude Code

[github-actions]

Failed to generate code suggestions for PR

[github-actions]

API Changes

--- prev.txt	2026-04-17 07:19:03.011817282 +0000
+++ current.txt	2026-04-17 07:18:58.274695244 +0000
@@ -10461,6 +10461,14 @@
 
 func (m *MockReadCloser) Read(p []byte) (n int, err error)
 
+type MockResponseCandidate struct {
+	OASMockResponseMeta *oas.MockResponse
+	OASMethod           string
+	OASPath             string
+}
+    MockResponseCandidate represents one OAS endpoint that maps to the same
+    compiled regex pattern for mock response disambiguation.
+
 type Monitor struct {
 	Gw *Gateway `json:"-"`
 }
@@ -11825,6 +11833,16 @@
 	OASValidateRequestMeta    *oas.ValidateRequest
 	OASMockResponseMeta       *oas.MockResponse
 
+	// OASValidateRequestCandidates holds multiple OAS endpoints that compile to the
+	// same regex pattern. When non-empty, the validate request middleware must
+	// disambiguate by checking path parameter schemas against each candidate.
+	OASValidateRequestCandidates []ValidateRequestCandidate
+
+	// OASMockResponseCandidates holds multiple OAS endpoints that compile to the
+	// same regex pattern. When non-empty, the mock response middleware must
+	// disambiguate by checking path parameter schemas against each candidate.
+	OASMockResponseCandidates []MockResponseCandidate
+
 	IgnoreCase bool
 	// OASMethod stores the HTTP method for OAS-specific middleware
 	// This is needed because OAS operations are method-specific
@@ -11927,6 +11945,16 @@
     ProcessRequest will run any checks on the request on the way through the
     system, return an error to have the chain fail
 
+type ValidateRequestCandidate struct {
+	OASValidateRequestMeta *oas.ValidateRequest
+	OASMethod              string
+	OASPath                string
+}
+    ValidateRequestCandidate represents one OAS endpoint that maps to the
+    same compiled regex pattern. Used for disambiguation when multiple
+    parameterized paths collapse to the same regex (e.g., /employees/{prct} and
+    /employees/{zd}).
+
 type ValueExtractor struct {
 	BaseExtractor
 }

[github-actions]

🚨 Jira Linter Failed

Commit: 7bacd82
Failed at: 2026-04-17 07:18:37 UTC

The Jira linter failed to validate your PR. Please check the error details below:

🔍 Click to view error details

failed to validate branch and PR title rules: branch name 'backport/7974-to-5.8' must contain a valid Jira ticket ID (e.g., ABC-123)

Next Steps

• Ensure your branch name contains a valid Jira ticket ID (e.g., ABC-123)
• Verify your PR title matches the branch's Jira ticket ID
• Check that the Jira ticket exists and is accessible

---

This comment will be automatically deleted once the linter passes.