fix(event_handler): split OpenAPI validation to respect middleware returns

[leandrodamascena]

Issue number: #5228
Discussion: #4656

Summary

Fixes middleware validation issues by splitting OpenAPI validation into separate request and response validation middlewares.

Changes

New Middleware Architecture

Split the OpenAPIValidationMiddleware into two separate middlewares:

1. OpenAPIRequestValidationMiddleware - Validates incoming requests only
2. OpenAPIResponseValidationMiddleware - Validates outgoing responses only

Execution Order

┌─────────────────────────────────────────────────────────────────┐
│                    Request Flow                                 │
├─────────────────────────────────────────────────────────────────┤
│ 1. Request Validation Middleware                                │
│    ├─ Validates path params, query params, headers, body       │
│    ├─ If invalid → Returns 422, stops execution               │
│    └─ If valid → Continues to next middleware                  │
│                                                                 │
│ 2. User Middlewares (in order of registration)                 │
│    ├─ Auth middleware                                          │
│    ├─ Rate limiting middleware                                 │
│    ├─ Logging middleware                                       │
│    ├─ etc...                                                   │
│    └─ Can return early responses (401, 403, 429, etc.)        │
│                                                                 │
│ 3. Response Validation Middleware                              │
│    ├─ Only executes if reached (no early returns)             │
│    └─ Validates response against OpenAPI schema               │
│                                                                 │
│ 4. Route Handler                                               │
│    └─ The actual endpoint function                             │
└─────────────────────────────────────────────────────────────────┘

User experience

Breaking change consideration

⚠️ Potential Impact: This fix may affect customers who were working around the previous incorrect behavior by catching RequestValidationError exceptions from middleware responses. However, this was unintended behavior that needed to be corrected.

Why this change is necessary:

• The previous behavior was a bug - middleware responses should not be validated against OpenAPI schemas
• Middleware responses (401, 403, 429) are control flow responses, not data responses
• The fix aligns with expected middleware behavior patterns
• Continuing the incorrect behavior would prevent proper middleware functionality

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

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.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.33%. Comparing base (c614d5b) to head (a6bbdcc).
⚠️ Report is 2 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #7050      +/-   ##
===========================================
+ Coverage    96.26%   96.33%   +0.07%     
===========================================
  Files          275      275              
  Lines        12917    12921       +4     
  Branches       955      953       -2     
===========================================
+ Hits         12435    12448      +13     
+ Misses         376      367       -9     
  Partials       106      106              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[leandrodamascena]

Hey @m-walmsley! I'd love to have your review and opinion here.

[walmsles]

Hey @m-walmsley! I'd love to have your review and opinion here.

Sure - but that's not the real me (need to remove that one - it was for internal Accenture projects)

[leandrodamascena]

Hey @m-walmsley! I'd love to have your review and opinion here.

Sure - but that's not the real me (need to remove that one - it was for internal Accenture projects)

Yes, sorry for that! It was the autocomplete.

Thanks.

[leandrodamascena]

@walmsles and I met today to discuss this change and the impact it may have on customers who already use Middleware and Data Validation. I'd like to highlight a few points for clarity:

1/ Customers who use Middleware but do not use Data Validation will not be impacted.

2/ Customers who use Data Validation but do not use Middleware will not be impacted.

3/ Customers who use Middleware + Data Validation but do not use early return with Middleware will not be impacted.

4/ Customers who use Middleware + Data Validation + Early Return and use the exception handler to intercept RequestValidationError or ResponseValidationError may be impacted, as it will no longer raise these exceptions and will respect the Middleware's return. The Powertools team does not consider this a breaking change, as this is incorrect behavior and we want to provide the best customer experience. However, if there are many customers complaining about this fix, we may revert the PR. We will monitor this.

We're also looking to the future, and it makes sense for customers to have full control over the execution of the middleware stack. So, I'll open an issue to expose OpenAPIRequestValidationMiddleware and OpenAPIResponseValidationMiddleware to customers, so they can build their middleware stack however they want. We may also consider adding a new field to add priority in the order that Middleware can be executed.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[leandrodamascena]

e2e tests are green: https://github.com/aws-powertools/powertools-lambda-python/actions/runs/16622167125/job/47029007096