aws-lambda-powertools 3.26.0__tar.gz → 3.27.0__tar.gz

{aws_lambda_powertools-3.26.0 → aws_lambda_powertools-3.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: aws_lambda_powertools
-Version: 3.26.0
+Version: 3.27.0
 Summary: Powertools for AWS Lambda (Python) is a developer toolkit to implement Serverless best practices and increase developer velocity.
 License: MIT
 Keywords: aws_lambda_powertools,aws,tracing,logging,lambda,powertools,feature_flags,idempotency,middleware
@@ -36,7 +36,7 @@ Requires-Dist: datadog-lambda (>=8.114.0,<9.0.0) ; extra == "datadog"
 Requires-Dist: fastjsonschema (>=2.14.5,<3.0.0) ; extra == "validation" or extra == "all"
 Requires-Dist: jmespath (>=1.0.1,<2.0.0)
 Requires-Dist: jsonpath-ng (>=1.6.0,<2.0.0) ; extra == "all" or extra == "datamasking"
-Requires-Dist: protobuf (>=6.30.2,<7.0.0) ; extra == "kafka-consumer-protobuf"
+Requires-Dist: protobuf (>=6.30.2,<8.0.0) ; extra == "kafka-consumer-protobuf"
 Requires-Dist: pydantic (>=2.4.0,<3.0.0) ; extra == "parser" or extra == "all"
 Requires-Dist: pydantic-settings (>=2.6.1,<3.0.0) ; extra == "all"
 Requires-Dist: redis (>=4.4,<8.0) ; extra == "redis"

{aws_lambda_powertools-3.26.0 → aws_lambda_powertools-3.27.0}/aws_lambda_powertools/event_handler/__init__.py

@@ -21,6 +21,7 @@ from aws_lambda_powertools.event_handler.http_resolver import HttpResolverLocal
 from aws_lambda_powertools.event_handler.lambda_function_url import (
     LambdaFunctionUrlResolver,
 )
+from aws_lambda_powertools.event_handler.request import Request
 from aws_lambda_powertools.event_handler.vpc_lattice import VPCLatticeResolver, VPCLatticeV2Resolver
 
 __all__ = [
@@ -37,6 +38,7 @@ __all__ = [
     "CORSConfig",
     "HttpResolverLocal",
     "LambdaFunctionUrlResolver",
+    "Request",
     "Response",
     "VPCLatticeResolver",
     "VPCLatticeV2Resolver",

{aws_lambda_powertools-3.26.0 → aws_lambda_powertools-3.27.0}/aws_lambda_powertools/event_handler/api_gateway.py

@@ -42,6 +42,7 @@ from aws_lambda_powertools.event_handler.openapi.types import (
     validation_error_definition,
     validation_error_response_definition,
 )
+from aws_lambda_powertools.event_handler.request import Request
 from aws_lambda_powertools.event_handler.util import (
     _FrozenDict,
     _FrozenListDict,
@@ -466,6 +467,11 @@ class Route:
 
         self.custom_response_validation_http_code = custom_response_validation_http_code
 
+        # Caches the name of any Request-typed parameter in the handler.
+        # Avoids re-scanning the signature on every invocation.
+        self.request_param_name: str | None = None
+        self.request_param_name_checked: bool = False
+
     def __call__(
         self,
         router_middlewares: list[Callable],
@@ -1608,6 +1614,47 @@ class BaseRouter(ABC):
         """Resets routing context"""
         self.context.clear()
 
+    @property
+    def request(self) -> Request:
+        """Current resolved :class:`Request` object.
+
+        Available inside middleware and in route handlers that declare a parameter
+        typed as :class:`Request <aws_lambda_powertools.event_handler.request.Request>`.
+
+        Raises
+        ------
+        RuntimeError
+            When accessed before route resolution (i.e. outside of middleware / handler scope).
+
+        Examples
+        --------
+        **Middleware**
+
+        ```python
+        def my_middleware(app, next_middleware):
+            req = app.request
+            print(req.route, req.method, req.path_parameters)
+            return next_middleware(app)
+        ```
+        """
+        cached: Request | None = self.context.get("_request")
+        if cached is not None:
+            return cached
+
+        route: Route | None = self.context.get("_route")
+        if route is None:
+            raise RuntimeError(
+                "app.request is only available after route resolution. Use it inside middleware or a route handler.",
+            )
+
+        request = Request(
+            route_path=route.openapi_path,
+            path_parameters=self.context.get("_route_args", {}),
+            current_event=self.current_event,
+        )
+        self.context["_request"] = request
+        return request
+
 
 class MiddlewareFrame:
     """
@@ -1680,6 +1727,24 @@ class MiddlewareFrame:
         return self.current_middleware(app, self.next_middleware)
 
 
+def _find_request_param_name(func: Callable) -> str | None:
+    """Return the name of the first parameter annotated as ``Request``, or ``None``."""
+    from typing import get_type_hints
+
+    try:
+        # get_type_hints resolves string annotations from ``from __future__ import annotations``
+        # using the function's own module globals.
+        hints = get_type_hints(func)
+    except Exception:
+        hints = {}
+
+    for param_name, annotation in hints.items():
+        if annotation is Request:
+            return param_name
+
+    return None
+
+
 def _registered_api_adapter(
     app: ApiGatewayResolver,
     next_middleware: Callable[..., Any],
@@ -1708,6 +1773,17 @@ def _registered_api_adapter(
     """
     route_args: dict = app.context.get("_route_args", {})
     logger.debug(f"Calling API Route Handler: {route_args}")
+
+    # Inject a Request object when the handler declares a parameter typed as Request.
+    # Lookup is cached on the Route object to avoid repeated signature inspection.
+    route: Route | None = app.context.get("_route")
+    if route is not None:
+        if not route.request_param_name_checked:
+            route.request_param_name = _find_request_param_name(next_middleware)
+            route.request_param_name_checked = True
+        if route.request_param_name:
+            route_args = {**route_args, route.request_param_name: app.request}
+
     return app._to_response(next_middleware(**route_args))
 
 

{aws_lambda_powertools-3.26.0 → aws_lambda_powertools-3.27.0}/aws_lambda_powertools/event_handler/http_resolver.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import asyncio
 import base64
 import inspect
+import threading
 import warnings
 from typing import TYPE_CHECKING, Any, Callable
 from urllib.parse import parse_qs
@@ -324,36 +325,65 @@ class HttpResolverLocal(ApiGatewayResolver):
         return await next_handler(self)
 
     def _wrap_middleware_async(self, middleware: Callable, next_handler: Callable) -> Callable:
-        """Wrap a middleware to work in async context."""
+        """Wrap a middleware to work in async context.
+
+        For sync middlewares, we split execution into pre/post phases around the
+        call to next(). The sync middleware runs its pre-processing (e.g. request
+        validation), then we intercept the next() call, await the async handler,
+        and resume the middleware with the real response so post-processing
+        (e.g. response validation) sees the actual data.
+        """
 
         async def wrapped(app):
-            # Create a next_middleware that the sync middleware can call
-            def sync_next(app):
-                # This will be called by sync middleware
-                # We need to run the async next_handler
-                loop = asyncio.get_event_loop()
-                if loop.is_running():
-                    # We're in an async context, create a task
-                    future = asyncio.ensure_future(next_handler(app))
-                    # Store for later await
-                    app.context["_async_next_result"] = future
-                    return Response(status_code=200, body="")  # Placeholder
-                else:  # pragma: no cover
-                    return loop.run_until_complete(next_handler(app))
-
-            # Check if middleware is async
             if inspect.iscoroutinefunction(middleware):
-                result = await middleware(app, next_handler)
-            else:
-                # Sync middleware - need special handling
-                result = middleware(app, sync_next)
+                return await middleware(app, next_handler)
 
-                # Check if we stored an async result
-                if "_async_next_result" in app.context:
-                    future = app.context.pop("_async_next_result")
-                    result = await future
+            # We use an Event to coordinate: the sync middleware runs in a thread,
+            # calls sync_next which signals us to resolve the async handler,
+            # then waits for the real response.
+            middleware_called_next = asyncio.Event()
+            next_app_holder: list = []
+            real_response_holder: list = []
+            middleware_result_holder: list = []
+            middleware_error_holder: list = []
 
-            return result
+            def sync_next(app):
+                next_app_holder.append(app)
+                middleware_called_next.set()
+                # Block this thread until the real response is available
+                event = threading.Event()
+                next_app_holder.append(event)
+                event.wait()
+                return real_response_holder[0]
+
+            def run_middleware():
+                try:
+                    result = middleware(app, sync_next)
+                    middleware_result_holder.append(result)
+                except Exception as e:
+                    middleware_error_holder.append(e)
+
+            thread = threading.Thread(target=run_middleware, daemon=True)
+            thread.start()
+
+            # Wait for the middleware to call next()
+            await middleware_called_next.wait()
+
+            # Now resolve the async next_handler
+            real_response = await next_handler(next_app_holder[0])
+            real_response_holder.append(real_response)
+
+            # Signal the thread that the response is ready
+            threading_event = next_app_holder[1]
+            threading_event.set()
+
+            # Wait for the middleware thread to finish
+            thread.join()
+
+            if middleware_error_holder:
+                raise middleware_error_holder[0]
+
+            return middleware_result_holder[0]
 
         return wrapped
 

{aws_lambda_powertools-3.26.0 → aws_lambda_powertools-3.27.0}/aws_lambda_powertools/event_handler/middlewares/openapi_validation.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
+import base64
 import dataclasses
 import json
 import logging
-from typing import TYPE_CHECKING, Any, Callable, Mapping, MutableMapping, Sequence, cast
+import warnings
+from typing import TYPE_CHECKING, Any, Callable, Mapping, MutableMapping, Sequence, Union, cast
 from urllib.parse import parse_qs
 
 from pydantic import BaseModel
+from typing_extensions import get_args, get_origin
 
 from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler
 from aws_lambda_powertools.event_handler.openapi.compat import (
@@ -24,7 +27,8 @@ from aws_lambda_powertools.event_handler.openapi.exceptions import (
     RequestValidationError,
     ResponseValidationError,
 )
-from aws_lambda_powertools.event_handler.openapi.params import Param
+from aws_lambda_powertools.event_handler.openapi.params import Param, UploadFile
+from aws_lambda_powertools.event_handler.openapi.types import UnionType
 
 if TYPE_CHECKING:
     from pydantic.fields import FieldInfo
@@ -42,6 +46,7 @@ logger = logging.getLogger(__name__)
 CONTENT_DISPOSITION_NAME_PARAM = "name="
 APPLICATION_JSON_CONTENT_TYPE = "application/json"
 APPLICATION_FORM_CONTENT_TYPE = "application/x-www-form-urlencoded"
+MULTIPART_FORM_DATA_CONTENT_TYPE = "multipart/form-data"
 
 
 class OpenAPIRequestValidationMiddleware(BaseMiddlewareHandler):
@@ -94,10 +99,17 @@ class OpenAPIRequestValidationMiddleware(BaseMiddlewareHandler):
             headers,
         )
 
+        # Process cookie values
+        cookie_values, cookie_errors = _request_params_to_args(
+            route.dependant.cookie_params,
+            app.current_event.resolved_cookies_field,
+        )
+
         values.update(path_values)
         values.update(query_values)
         values.update(header_values)
-        errors += path_errors + query_errors + header_errors
+        values.update(cookie_values)
+        errors += path_errors + query_errors + header_errors + cookie_errors
 
         # Process the request body, if it exists
         if route.dependant.body_params:
@@ -132,14 +144,18 @@ class OpenAPIRequestValidationMiddleware(BaseMiddlewareHandler):
         elif content_type.startswith(APPLICATION_FORM_CONTENT_TYPE):
             return self._parse_form_data(app)
 
+        # Handle multipart/form-data (file uploads)
+        elif content_type.startswith(MULTIPART_FORM_DATA_CONTENT_TYPE):
+            return self._parse_multipart_data(app, content_type)
+
         else:
             raise RequestUnsupportedContentType(
-                "Only JSON body or Form() are supported",
+                "Unsupported content type",
                 errors=[
                     {
                         "type": "unsupported_content_type",
                         "loc": ("body",),
-                        "msg": "Only JSON body or Form() are supported",
+                        "msg": f"Unsupported content type: {content_type}",
                         "input": {},
                         "ctx": {},
                     },
@@ -186,6 +202,49 @@ class OpenAPIRequestValidationMiddleware(BaseMiddlewareHandler):
                 ],
             ) from e
 
+    def _parse_multipart_data(self, app: EventHandlerInstance, content_type: str) -> dict[str, Any]:
+        """Parse multipart/form-data from the request body (file uploads)."""
+        try:
+            # Extract the boundary from the content-type header
+            boundary = _extract_multipart_boundary(content_type)
+            if not boundary:
+                raise ValueError("Missing boundary in multipart/form-data content-type header")
+
+            # Get raw body bytes
+            raw_body = app.current_event.body or ""
+            if app.current_event.is_base64_encoded:
+                body_bytes = base64.b64decode(raw_body)
+            else:
+                warnings.warn(
+                    "Received multipart/form-data without base64 encoding. "
+                    "Binary file uploads may be corrupted. "
+                    "If using API Gateway REST API (v1), configure Binary Media Types "
+                    "to include 'multipart/form-data'. "
+                    "See: https://docs.aws.amazon.com/apigateway/latest/developerguide/"
+                    "api-gateway-payload-encodings.html",
+                    stacklevel=2,
+                )
+                # Use latin-1 to preserve all byte values (0-255) since the body
+                # may contain raw binary data that isn't valid UTF-8
+                body_bytes = raw_body.encode("latin-1")
+
+            return _parse_multipart_body(body_bytes, boundary)
+
+        except ValueError:
+            raise
+        except Exception as e:
+            raise RequestValidationError(
+                [
+                    {
+                        "type": "multipart_invalid",
+                        "loc": ("body",),
+                        "msg": "Multipart form data parsing error",
+                        "input": {},
+                        "ctx": {"error": str(e)},
+                    },
+                ],
+            ) from e
+
 
 class OpenAPIResponseValidationMiddleware(BaseMiddlewareHandler):
     """
@@ -389,7 +448,12 @@ def _request_body_to_args(
             continue
 
         value = _normalize_field_value(value=value, field_info=field.field_info)
-        values[field.name] = _validate_field(field=field, value=value, loc=loc, existing_errors=errors)
+
+        # UploadFile objects bypass Pydantic validation — they're already constructed
+        if isinstance(value, UploadFile):
+            values[field.name] = value
+        else:
+            values[field.name] = _validate_field(field=field, value=value, loc=loc, existing_errors=errors)
 
     return values, errors
 
@@ -431,9 +495,45 @@ def _handle_missing_field_value(
         values[field.name] = field.get_default()
 
 
+def _is_or_contains_sequence(annotation: Any) -> bool:
+    """
+    Check if annotation is a sequence or Union/RootModel containing a sequence.
+
+    This function handles complex type annotations like:
+    - List[Model] - direct sequence
+    - Union[Model, List[Model]] - checks if any Union member is a sequence
+    - Optional[List[Model]] - Union[List[Model], None]
+    - RootModel[List[Model]] - checks if the RootModel wraps a sequence
+    - Optional[RootModel[List[Model]]] - Union member that is a RootModel
+    - RootModel[Union[Model, List[Model]]] - RootModel wrapping a Union with a sequence
+    """
+    # Direct sequence check
+    if field_annotation_is_sequence(annotation):
+        return True
+
+    # Check Union members — recurse so we catch RootModel inside Union
+    origin = get_origin(annotation)
+    if origin is Union or origin is UnionType:
+        for arg in get_args(annotation):
+            if _is_or_contains_sequence(arg):
+                return True
+
+    # Check if it's a RootModel wrapping a sequence (or Union containing a sequence)
+    if lenient_issubclass(annotation, BaseModel) and getattr(annotation, "__pydantic_root_model__", False):
+        if hasattr(annotation, "model_fields") and "root" in annotation.model_fields:
+            root_annotation = annotation.model_fields["root"].annotation
+            return _is_or_contains_sequence(root_annotation)
+
+    return False
+
+
 def _normalize_field_value(value: Any, field_info: FieldInfo) -> Any:
     """Normalize field value, converting lists to single values for non-sequence fields."""
-    if field_annotation_is_sequence(field_info.annotation):
+    # When annotation is bytes but value is UploadFile, extract raw content
+    if isinstance(value, UploadFile) and field_info.annotation is bytes:
+        return value.content
+
+    if _is_or_contains_sequence(field_info.annotation):
         return value
     elif isinstance(value, list) and value:
         return value[0]
@@ -546,3 +646,106 @@ def _get_param_value(
         value = input_dict.get(field_name)
 
     return value
+
+
+def _extract_multipart_boundary(content_type: str) -> str | None:
+    """Extract the boundary string from a multipart/form-data content-type header."""
+    for segment in content_type.split(";"):
+        stripped = segment.strip()
+        if stripped.startswith("boundary="):
+            boundary = stripped[len("boundary=") :]
+            # Remove optional quotes around boundary
+            if boundary.startswith('"') and boundary.endswith('"'):
+                boundary = boundary[1:-1]
+            return boundary
+    return None
+
+
+def _parse_multipart_body(body: bytes, boundary: str) -> dict[str, Any]:
+    """
+    Parse a multipart/form-data body into a dict of field names to values.
+
+    File fields get bytes values; regular form fields get string values.
+    Multiple values for the same field name are collected into lists.
+    """
+    delimiter = f"--{boundary}".encode()
+    end_delimiter = f"--{boundary}--".encode()
+
+    result: dict[str, Any] = {}
+
+    # Split body by the boundary delimiter
+    raw_parts = body.split(delimiter)
+
+    for raw_part in raw_parts:
+        # Skip the preamble (before first boundary) and epilogue (after closing boundary)
+        if not raw_part or raw_part.strip() == b"" or raw_part.strip() == b"--":
+            continue
+
+        # Remove the end delimiter marker if present
+        chunk = raw_part
+        if chunk.endswith(end_delimiter):
+            chunk = chunk[: -len(end_delimiter)]
+
+        # Strip leading \r\n
+        if chunk.startswith(b"\r\n"):
+            chunk = chunk[2:]
+
+        # Strip trailing \r\n
+        if chunk.endswith(b"\r\n"):
+            chunk = chunk[:-2]
+
+        # Split headers from body at the double CRLF
+        header_end = chunk.find(b"\r\n\r\n")
+        if header_end == -1:
+            continue
+
+        header_section = chunk[:header_end].decode("utf-8")
+        body_section = chunk[header_end + 4 :]
+
+        # Parse Content-Disposition to get the field name and optional filename
+        field_name = None
+        filename = None
+        content_type_header = None
+
+        for header_line in header_section.split("\r\n"):
+            header_lower = header_line.lower()
+            if header_lower.startswith("content-disposition:"):
+                field_name = _extract_header_param(header_line, "name")
+                filename = _extract_header_param(header_line, "filename")
+            elif header_lower.startswith("content-type:"):
+                content_type_header = header_line.split(":", 1)[1].strip()
+
+        if field_name is None:
+            continue
+
+        # If it has a filename, it's a file upload — wrap as UploadFile
+        # Otherwise it's a regular form field — decode to string
+        if filename is not None:
+            value: Any = UploadFile(content=body_section, filename=filename, content_type=content_type_header)
+        else:
+            value = body_section.decode("utf-8")
+
+        # Collect multiple values for same field name into a list
+        if field_name in result:
+            existing = result[field_name]
+            if isinstance(existing, list):
+                existing.append(value)
+            else:
+                result[field_name] = [existing, value]
+        else:
+            result[field_name] = value
+
+    return result
+
+
+def _extract_header_param(header_line: str, param_name: str) -> str | None:
+    """Extract a parameter value from a header line (e.g., name="file" from Content-Disposition)."""
+    search = f'{param_name}="'
+    idx = header_line.find(search)
+    if idx == -1:
+        return None
+    start = idx + len(search)
+    end = header_line.find('"', start)
+    if end == -1:
+        return None
+    return header_line[start:end]

{aws_lambda_powertools-3.26.0 → aws_lambda_powertools-3.27.0}/aws_lambda_powertools/event_handler/openapi/dependant.py

@@ -13,15 +13,16 @@ from aws_lambda_powertools.event_handler.openapi.compat import (
 from aws_lambda_powertools.event_handler.openapi.params import (
     Body,
     Dependant,
+    File,
     Form,
     Param,
     ParamTypes,
-    _File,
     analyze_param,
     create_response_field,
     get_flat_dependant,
 )
 from aws_lambda_powertools.event_handler.openapi.types import OpenAPIResponse, OpenAPIResponseContentModel
+from aws_lambda_powertools.event_handler.request import Request
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -187,6 +188,11 @@ def get_dependant(
 
     # Add each parameter to the dependant model
     for param_name, param in signature_params.items():
+        # Request-typed parameters are injected by the resolver at call time;
+        # they carry no OpenAPI meaning and must be excluded from schema generation.
+        if param.annotation is Request:
+            continue
+
         # If the parameter is a path parameter, we need to set the in_ field to "path".
         is_path_param = param_name in path_param_names
 
@@ -364,9 +370,9 @@ def get_body_field_info(
     if not required:
         body_field_info_kwargs["default"] = None
 
-    if any(isinstance(f.field_info, _File) for f in flat_dependant.body_params):
-        # MAINTENANCE: body_field_info: type[Body] = _File
-        raise NotImplementedError("_File fields are not supported in request bodies")
+    if any(isinstance(f.field_info, File) for f in flat_dependant.body_params):
+        body_field_info = Body
+        body_field_info_kwargs["media_type"] = "multipart/form-data"
     elif any(isinstance(f.field_info, Form) for f in flat_dependant.body_params):
         body_field_info = Body
         body_field_info_kwargs["media_type"] = "application/x-www-form-urlencoded"

{aws_lambda_powertools-3.26.0 → aws_lambda_powertools-3.27.0}/aws_lambda_powertools/event_handler/openapi/merge.py

@@ -67,11 +67,18 @@ def _file_has_resolver(file_path: Path, resolver_name: str) -> bool:
         return False
 
     for node in ast.walk(tree):
+        targets: list[ast.expr] = []
+        value: ast.expr | None = None
         if isinstance(node, ast.Assign):
-            for target in node.targets:
-                if isinstance(target, ast.Name) and target.id == resolver_name:
-                    if _is_resolver_call(node.value):
-                        return True
+            targets = node.targets
+            value = node.value
+        elif isinstance(node, ast.AnnAssign):
+            targets = [node.target]
+            value = node.value
+        for target in targets:
+            if isinstance(target, ast.Name) and target.id == resolver_name:
+                if value is not None and _is_resolver_call(value):
+                    return True
     return False