Skip to content

fix(event_handler): match exact routes before catch-all regex routes - #8881

Open
annastudios wants to merge 2 commits into
aws-powertools:developfrom
annastudios:fix/event-handler-exact-route-priority
Open

annastudios wants to merge 2 commits into
aws-powertools:developfrom
annastudios:fix/event-handler-exact-route-priority

Conversation

@annastudios

Copy link
Copy Markdown

Issue number:

closes #8879

Summary

Changes

A regex rule without named groups, such as /proxy/.+, has rule.groups == 0, so route() stored it in _static_routes next to exact rules, and _resolve matched them in registration order. A catch-all registered before /proxy/health took its requests.

route() now inserts exact static rules (no regex metacharacters) before regex static rules, so the order no longer depends on registration. This happens at registration; matching at request time is unchanged, and dynamic routes keep coming after static ones. Routes included from a Router go through route() too, so they are covered.

Thanks @bardrop for the detailed report and repro.

User experience

Before: with @app.get("/proxy/.+") registered before @app.get("/proxy/health"), GET /proxy/health returns {"route":"catch-all"}.

After: it returns {"route":"health"}, as the "Route Matching Priority" box in the Catch-all routes docs says. GET /proxy/other still goes to the catch-all.

Verification

  • New functional tests in tests/functional/event_handler/required_dependencies/test_api_gateway.py, through the public API: both registration orders, and an exact route included later from a prefixed Router. Two of the three fail on develop (the "exact registered first" case already worked) and all pass with the fix.
  • pytest tests/unit/event_handler tests/functional/event_handler: 1288 passed, 1 skipped. Two failures, test_load_resolver_file_not_found and test_openapi_encode_purepath, also fail on develop: they are Windows path-separator issues on my machine, unrelated to this change.
  • ruff format --check, ruff check and mypy clean on the changed files.
  • The issue's repro script now prints {"route":"health"} for /proxy/health and {"route":"catch-all"} for /proxy/other.

AI-assisted; I reproduced the bug, reviewed the change and ran the checks above myself.


By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

A regex rule without named groups, such as /proxy/.+, was stored with
the exact rules and matched in registration order, so it took requests
for /proxy/health when registered first. The "Catch-all routes" docs
say exact matches take precedence over regex patterns.

Exact static rules are now placed before regex static rules when the
route is registered, so matching order no longer depends on
registration order. Request-time matching is unchanged.

closes aws-powertools#8879
@annastudios
annastudios requested a review from a team as a code owner November 21, 2026 07:38
@boring-cyborg

boring-cyborg Bot commented Nov 21, 2026

Copy link
Copy Markdown

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

@powertools-for-aws-oss-automation powertools-for-aws-oss-automation Bot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Nov 21, 2026
_NAMED_GROUP_BOUNDARY_PATTERN = rf"(?P\1[{_SAFE_URI}{_UNSAFE_URI}\\w]+)"
_ROUTE_REGEX = "^{}$"
# A static rule with any of these is a regex (/proxy/.+), not an exact path (/proxy/health)
_REGEX_METACHARACTERS = frozenset(".^$*+?{}[]\\|()")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Exact paths that contain a dot still lose to a catch-all registered first, because . is in this set, so they go to the regex bucket and are appended after it:

app.get("/.well-known/.+")(lambda: {"route": "catch"})
app.get("/.well-known/jwks.json")(lambda: {"route": "jwks"})
# GET /.well-known/jwks.json -> {"route": "catch"}

Same for /files/.+ + /files/readme.txt and /v1.0/.+ + /v1.0/health. File names and versioned prefixes are common in exact routes.

Leaving . out fixes these: a rule whose only metacharacter is . still matches one fixed-length path shape, so it can safely go before rules with quantifiers or groups.

Suggested change
_REGEX_METACHARACTERS = frozenset(".^$*+?{}[]\\|()")
_REGEX_METACHARACTERS = frozenset("^$*+?{}[]\\|()")

With that change all three cases above pick the exact route, /proxy/health still works, and tests/functional/event_handler gives the same results as on this branch.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, thanks! Applied your suggestion in e4de9f8 and added a parametrized test covering /.well-known/jwks.json, /files/readme.txt and /v1.0/health (each fails without the change). tests/unit/event_handler + tests/functional/event_handler: 1291 passed; ruff and mypy clean.

A rule whose only metacharacter is "." (/.well-known/jwks.json, /files/readme.txt, /v1.0/health) matches one fixed-length path shape, so it now goes before catch-all regex rules too. Suggested in review.
@sonarqubecloud

Copy link
Copy Markdown

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

event_handlers size/M Denotes a PR that changes 30-99 lines, ignoring generated files. tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bug: exact route loses to a catch-all regex route registered before it

2 participants