feat(event_handler): add custom response validation in OpenAPI utility #6189

amin-farjadi · 2025-02-28T14:37:13Z

Issue number: #5888

Summary

Add the option to distinguish between payload validation and response validation.

Changes

Optional has_response_validation_error argument has been added to OpenAPIValidationMiddleware.
Optional response_validation_error_http_status argument has been added to the ApiGatewayResolver and its subclasses.
ResponseValidationError exception class has been added to OpenAPI exceptions
Tests have been added for APIGatewayRestResolver response validation.
Add Validating responses section in the docs

User experience

Nothing will change. The user will have the option to set a custom response validation http status for Amazon API Gateway REST and HTTP APIs, Application Load Balancer (ALB), Lambda Function URLs, and VPC Lattice.

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.

…xception.

… error status code.

boring-cyborg · 2025-02-28T14:37:17Z

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

leandrodamascena · 2025-02-28T14:50:03Z

Hey hey @amin-farjadi! Thanks a lot for this PR! I'm working on fixing something else and will review it by Monday, ok?

amin-farjadi · 2025-02-28T14:56:23Z

Hey hey @amin-farjadi! Thanks a lot for this PR! I'm working on fixing something else and will review it by Monday, ok?

Hi @leandrodamascena 👋 Absolutely fine, thanks

leandrodamascena · 2025-02-28T15:01:17Z

Hey hey @amin-farjadi! Thanks a lot for this PR! I'm working on fixing something else and will review it by Monday, ok?

Hi @leandrodamascena 👋 Absolutely fine, thanks

I see that our CI is failing with some importing or type annotation. Can you take a look please?

amin-farjadi · 2025-02-28T15:03:46Z

Why are the tests checked against python 3.9 when the codebase is not compatible with it? Union operator for typing is used extensively in the codebase (which fails the python 3.9 test).

If I turn int | None to Optional[int], formatter will be unhappy. But, happy to do so if needs be

leandrodamascena · 2025-02-28T15:07:52Z

tests/unit/event_handler/test_response_validation.py

+
+class Todo(BaseModel):
+    userId: int
+    id_: int | None = Field(alias="id", default=None)


Suggested change

id_: int | None = Field(alias="id", default=None)

id_: Optional[int] = Field(alias="id", default=None)

leandrodamascena · 2025-02-28T15:09:17Z

Why are the tests checked against python 3.9 when the codebase is not compatible with it? Union operator for typing is used extensively in the codebase (which fails the python 3.9 test).

If I turn int | None to Optional[int], formatter will be unhappy. But, happy to do so if needs be

There are some inconsistencies when using Pydantic models and Union operations.. Try to make this Optional and remove future annotations. I think this can solve the problem for now. If not, I can take a look during the review.

amin-farjadi · 2025-02-28T15:09:55Z

I see!

amin-farjadi · 2025-02-28T16:06:58Z

@leandrodamascena added ruff rule FA102 to be ignored for linting as this project uses python >=3.9 . This resolved the issue I was having in precommit, forcing me to import annotations in the test.

codecov · 2025-02-28T16:19:38Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.26%. Comparing base (bf64061) to head (218c666).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #6189   +/-   ##
========================================
  Coverage    96.25%   96.26%           
========================================
  Files          236      236           
  Lines        11407    11429   +22     
  Branches       830      834    +4     
========================================
+ Hits         10980    11002   +22     
  Misses         337      337           
  Partials        90       90

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

…s and add more detailed error messages.

leandrodamascena · 2025-03-04T21:40:58Z

I'm starting my review of this PR.

leandrodamascena

Hey @amin-farjadi! This is an excellent PR, and I really appreciate your work on this. I've left some comments that I believe we should address before moving to the next round of review.

I'm also curious about potentially enabling this response validation code for individual routes as well. We could have it at both the global level and per route. This isn't a mandatory change, but I'd like to hear your thoughts on this idea.

Let me know what you think, and thanks again for your valuable contribution!

leandrodamascena · 2025-03-04T22:11:28Z

aws_lambda_powertools/event_handler/api_gateway.py

+        response_validation_error_http_status
+            Enables response validation and sets returned status code if response is not validated.


Suggested change

response_validation_error_http_status

Enables response validation and sets returned status code if response is not validated.

response_validation_error_http_status

HTTP status code returned when response validation fails.

Response validation is already enabled, we are modifying the customer to inform a specific http status code.

leandrodamascena · 2025-03-04T22:11:57Z

aws_lambda_powertools/event_handler/api_gateway.py

@@ -1496,6 +1500,7 @@ def __init__(
        serializer: Callable[[dict], str] | None = None,
        strip_prefixes: list[str | Pattern] | None = None,
        enable_validation: bool = False,
+        response_validation_error_http_status=None,


Suggested change

response_validation_error_http_status=None,

response_validation_error_http_code=None,

What do you think about this?

leandrodamascena · 2025-03-04T22:17:36Z

aws_lambda_powertools/event_handler/api_gateway.py

+        if response_validation_error_http_status and not enable_validation:
+            msg = "'response_validation_error_http_status' cannot be set when enable_validation is False."
+            raise ValueError(msg)
+
+        if (
+            not isinstance(response_validation_error_http_status, HTTPStatus)
+            and response_validation_error_http_status is not None
+        ):
+
+            try:
+                response_validation_error_http_status = HTTPStatus(response_validation_error_http_status)
+            except ValueError:
+                msg = f"'{response_validation_error_http_status}' must be an integer representing an HTTP status code."
+                raise ValueError(msg) from None
+
+        self._response_validation_error_http_status = (
+            response_validation_error_http_status
+            if response_validation_error_http_status
+            else HTTPStatus.UNPROCESSABLE_ENTITY
+        )


Suggested change

if response_validation_error_http_status and not enable_validation:

msg = "'response_validation_error_http_status' cannot be set when enable_validation is False."

raise ValueError(msg)

if (

not isinstance(response_validation_error_http_status, HTTPStatus)

and response_validation_error_http_status is not None

):

try:

response_validation_error_http_status = HTTPStatus(response_validation_error_http_status)

except ValueError:

msg = f"'{response_validation_error_http_status}' must be an integer representing an HTTP status code."

raise ValueError(msg) from None

self._response_validation_error_http_status = (

response_validation_error_http_status

if response_validation_error_http_status

else HTTPStatus.UNPROCESSABLE_ENTITY

)

self._response_validation_error_http_status = self._validate_response_validation_error_status(

response_validation_error_http_status,

enable_validation

)

And then we can simplify the logic and move the code for a specific function:

def _validate_response_validation_error_status(self, response_validation_error_http_status, enable_validation): if response_validation_error_http_status and not enable_validation: raise ValueError("'response_validation_error_http_status' cannot be set when enable_validation is False.") if response_validation_error_http_status is None: return HTTPStatus.UNPROCESSABLE_ENTITY if isinstance(response_validation_error_http_status, HTTPStatus): return response_validation_error_http_status try: return HTTPStatus(response_validation_error_http_status) except ValueError: raise ValueError(f"'{response_validation_error_http_status}' must be an integer representing an HTTP status code.")

leandrodamascena · 2025-03-04T22:20:10Z

aws_lambda_powertools/event_handler/api_gateway.py

+            http_status = (
+                self._response_validation_error_http_status
+                if self._response_validation_error_http_status
+                else HTTPStatus.UNPROCESSABLE_ENTITY
+            )


Suggested change

http_status = (

self._response_validation_error_http_status

if self._response_validation_error_http_status

else HTTPStatus.UNPROCESSABLE_ENTITY

)

http_status = self._response_validation_error_http_status

Am I wrong or aren't we testing this condition before setting the HTTP code? Do we need it again here?

Absolutely right

leandrodamascena · 2025-03-04T22:22:09Z

aws_lambda_powertools/event_handler/middlewares/openapi_validation.py

+        custom_serialize_response_error: ValidationException, optional
+            Optional error type to raise when response to be returned by the endpoint is not
+            serialisable according to field type.
+            Raises RequestValidationError by default.


I'm not sure I fully understand this. Could you please explain it to me?

I have no idea where this came from :D. Will remove it and add _has_response_validation_error param to docstring.

leandrodamascena · 2025-03-04T22:26:20Z

tests/unit/event_handler/test_response_validation.py

This shouldn't be a unit test; it's more suited as a functional test. I'd like it moved to https://github.com/aws-powertools/powertools-lambda-python/tree/develop/tests/functional/event_handler/_pydantic.

Also, please avoid adding tests inside classes. Please move the tests to plain functions, and utilizes fixtures when needed.

leandrodamascena · 2025-03-04T22:27:21Z

ruff.toml

@@ -38,7 +38,8 @@ lint.ignore = [
    "B904",    # raise-without-from-inside-except - disabled temporarily
    "PLC1901", # Compare-to-empty-string - disabled temporarily
    "PYI024",
-    "A005"
+    "A005",
+    "FA102" # project must require python >= 3.9 making this error obsolete


I'll review this once all other reviews are complete.

amin-farjadi · 2025-03-05T07:08:53Z

Hi @leandrodamascena, thanks for the review. Will implement suggested changes by the end of the week. Regarding custom http status code on a route-level, I will familiarise myself with the Route implementation and has a crack at it in this PR.

leandrodamascena · 2025-03-05T08:07:05Z

Hi @leandrodamascena, thanks for the review. Will implement suggested changes by the end of the week. Regarding custom http status code on a route-level, I will familiarise myself with the Route implementation and has a crack at it in this PR.

Thanks @amin-farjadi! It's great that you understand the Route implementation. However, after further consideration, let's keep this PR as is and create a new issue to discuss the implementation of the route-specific functionality. We can then work on that in a separate PR.

…lidation_error_http_code

…error_http_code param.

…r_http_code param.

…r_http_code param being None.

…param.

…est file

amin-farjadi · 2025-03-10T08:47:43Z

Hi @leandrodamascena, I believe all your points have been addressed in the recent commits. I have drafted an implemented for route-specific custom response validation http status code which I can add in a subsequent PR

sonarqubecloud · 2025-03-10T09:38:36Z

Quality Gate passed

Issues
5 New issues
1 Accepted issue

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

See analysis details on SonarQube Cloud

leandrodamascena · 2025-03-10T09:40:21Z

Hi @leandrodamascena, I believe all your points have been addressed in the recent commits. I have drafted an implemented for route-specific custom response validation http status code which I can add in a subsequent PR

Hi @amin-farjadi! Thanks a lot for addressing all the points! I'll review it again today and I'll probably have some very small changes to make, especially in the documentation part, but nothing critical and I can push a commit before approving it, ok?

I'm very happy to have this new feature, it will give customers more flexibility when working with data validation.

Regarding to the validation code per route, please open an issue with a pseudo code showing the experience, this will be super nice!

amin-farjadi · 2025-03-10T10:00:55Z

Hi @leandrodamascena, I believe all your points have been addressed in the recent commits. I have drafted an implemented for route-specific custom response validation http status code which I can add in a subsequent PR

Hi @amin-farjadi! Thanks a lot for addressing all the points! I'll review it again today and I'll probably have some very small changes to make, especially in the documentation part, but nothing critical and I can push a commit before approving it, ok?

I'm very happy to have this new feature, it will give customers more flexibility when working with data validation.

Regarding to the validation code per route, please open an issue with a pseudo code showing the experience, this will be super nice!

I'm happy to try and close this PR today. Absolutely fine by me, please do feel free.

I drafted this issue for route-specific custom response validation http status code (that's a mouthful!) #6245

leandrodamascena · 2025-03-10T11:11:28Z

Hi @amin-farjadi! Just a quick explanation. A while ago you opened this issue and we fixed it in this PR. But this created a regression and I had to revert it while I find the right solution.

So because of this, some tests in the test_openapi_validation_middleware.py file are failing, but this is not caused by you. Can you please disable the those tests? Don't remove, just add the decorator @pytest.mark.skipif(reason="Test temporarily disabled until falsy return is fixed")?

test_validation_error_none_returned_non_optional_type
test_none_returned_for_falsy_return
test_custom_response_validation_error_http_code_invalid_response_none

Amin Farjadi added 7 commits February 28, 2025 13:26

feat(openapi-validation): Add response validation flag and distinct e…

cc27ba7

…xception.

feat(api-gateway-resolver): Add option for custom response validation…

bc69d18

… error status code.

feat(docs): Added doc for custom response validation error responses.

6ddfdc0

refactor(docs): Make exception handler function name better.

a9be196

feat(unit-test): Add tests for custom response validation error.

276d7cd

fix: Formatting.

fb49e9b

fix(docs): Fix grammar in response validation docs

df105dc

amin-farjadi requested a review from a team as a code owner February 28, 2025 14:37

amin-farjadi requested a review from leandrodamascena February 28, 2025 14:37

boring-cyborg bot added documentation Improvements or additions to documentation event_handlers tests labels Feb 28, 2025

pull-request-size bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Feb 28, 2025

leandrodamascena changed the title ~~feat: add custom response validation~~ feat(openapi): add custom response validation Feb 28, 2025

github-actions bot added feature New feature or functionality and removed documentation Improvements or additions to documentation labels Feb 28, 2025

leandrodamascena linked an issue Feb 28, 2025 that may be closed by this pull request

Feature request: HTTP response of an unsuccessful response validation must be a server-side error #5888

Open

leandrodamascena assigned amin-farjadi Feb 28, 2025

leandrodamascena reviewed Feb 28, 2025

View reviewed changes

Amin Farjadi added 2 commits February 28, 2025 15:54

fix(unit-test): fix failed CI.

63fd201

bugfix(lint): Ignore lint error FA102, irrelevant for python >=3.9

1c33611

boring-cyborg bot added the documentation Improvements or additions to documentation label Feb 28, 2025

github-actions bot removed the documentation Improvements or additions to documentation label Feb 28, 2025

Amin Farjadi added 2 commits February 28, 2025 17:49

refactor: make response_validation_error_http_status accept more type…

f8ead84

…s and add more detailed error messages.

feat(unit-test): add tests for incorrect types and invalid configs

eb2430b

boring-cyborg bot added the documentation Improvements or additions to documentation label Feb 28, 2025

leandrodamascena changed the title ~~feat(openapi): add custom response validation~~ feat(event_handler): add custom response validation in OpenAPI utility Mar 1, 2025

Merge branch 'develop' into feature/response-validation

d6b7638

github-actions bot removed the documentation Improvements or additions to documentation label Mar 1, 2025

Merge branch 'develop' into feature/response-validation

0090692

boring-cyborg bot added the documentation Improvements or additions to documentation label Mar 3, 2025

leandrodamascena added 2 commits March 4, 2025 21:41

Merge branch 'develop' into feature/response-validation

13b7380

Merge branch 'develop' into feature/response-validation

218c666

leandrodamascena requested changes Mar 4, 2025

View reviewed changes

leandrodamascena and others added 7 commits March 9, 2025 20:47

Merge branch 'develop' into feature/response-validation

82918c7

refactor: rename response_validation_error_http_status to response_va…

2a4d57f

…lidation_error_http_code

refactor(api_gateway): add method for validating response_validation_…

fece0e8

…error_http_code param.

fix(api_gateway): fix type and docstring for response_validation_erro…

f85c749

…r_http_code param.

fix(api_gateway): remove unncessary check of response_validation_erro…

c4f0819

…r_http_code param being None.

fix(openapi-validation): docstring for has_response_validation_error …

8fe4edc

…param.

refactor(tests): move unit tests into openapi_validation functional t…

f89b598

…est file

amin-farjadi requested a review from leandrodamascena March 10, 2025 09:01

Merge branch 'develop' into feature/response-validation

f60b812

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(event_handler): add custom response validation in OpenAPI utility #6189

feat(event_handler): add custom response validation in OpenAPI utility #6189

amin-farjadi commented Feb 28, 2025

boring-cyborg bot commented Feb 28, 2025

leandrodamascena commented Feb 28, 2025

amin-farjadi commented Feb 28, 2025

leandrodamascena commented Feb 28, 2025

amin-farjadi commented Feb 28, 2025 •

edited

Loading

leandrodamascena Feb 28, 2025

leandrodamascena commented Feb 28, 2025

amin-farjadi commented Feb 28, 2025

amin-farjadi commented Feb 28, 2025 •

edited

Loading

codecov bot commented Feb 28, 2025 •

edited

Loading

leandrodamascena commented Mar 4, 2025

leandrodamascena left a comment

leandrodamascena Mar 4, 2025

leandrodamascena Mar 4, 2025

amin-farjadi Mar 5, 2025

leandrodamascena Mar 4, 2025

amin-farjadi Mar 5, 2025

leandrodamascena Mar 4, 2025

amin-farjadi Mar 5, 2025

leandrodamascena Mar 4, 2025

amin-farjadi Mar 5, 2025

leandrodamascena Mar 4, 2025

leandrodamascena Mar 4, 2025

amin-farjadi commented Mar 5, 2025

leandrodamascena commented Mar 5, 2025

amin-farjadi commented Mar 10, 2025

sonarqubecloud bot commented Mar 10, 2025

leandrodamascena commented Mar 10, 2025

amin-farjadi commented Mar 10, 2025

leandrodamascena commented Mar 10, 2025

	id_: int \| None = Field(alias="id", default=None)
	id_: Optional[int] = Field(alias="id", default=None)

		response_validation_error_http_status
		Enables response validation and sets returned status code if response is not validated.

	response_validation_error_http_status=None,
	response_validation_error_http_code=None,

feat(event_handler): add custom response validation in OpenAPI utility #6189

Are you sure you want to change the base?

feat(event_handler): add custom response validation in OpenAPI utility #6189

Conversation

amin-farjadi commented Feb 28, 2025

Summary

Changes

User experience

Checklist

Acknowledgment

boring-cyborg bot commented Feb 28, 2025

leandrodamascena commented Feb 28, 2025

amin-farjadi commented Feb 28, 2025

leandrodamascena commented Feb 28, 2025

amin-farjadi commented Feb 28, 2025 • edited Loading

Choose a reason for hiding this comment

leandrodamascena commented Feb 28, 2025

amin-farjadi commented Feb 28, 2025

amin-farjadi commented Feb 28, 2025 • edited Loading

codecov bot commented Feb 28, 2025 • edited Loading

Codecov Report

leandrodamascena commented Mar 4, 2025

leandrodamascena left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amin-farjadi commented Mar 5, 2025

leandrodamascena commented Mar 5, 2025

amin-farjadi commented Mar 10, 2025

sonarqubecloud bot commented Mar 10, 2025

Quality Gate passed

leandrodamascena commented Mar 10, 2025

amin-farjadi commented Mar 10, 2025

leandrodamascena commented Mar 10, 2025

amin-farjadi commented Feb 28, 2025 •

edited

Loading

amin-farjadi commented Feb 28, 2025 •

edited

Loading

codecov bot commented Feb 28, 2025 •

edited

Loading