modmex-lambda 0.1.0__py3-none-any.whl

modmex_lambda/event_handler/api_gateway.py

@@ -0,0 +1,331 @@
+"""API Gateway event handler public API."""
+
+from __future__ import annotations
+
+import re
+import json
+from typing import Any, Callable, Pattern
+from functools import partial
+from enum import Enum
+from http import HTTPStatus
+
+from modmex_lambda.event_handler import content_types
+from modmex_lambda.event_handler.exceptions import (
+    ForbiddenError,
+    MethodNotAllowedError,
+    NotFoundError,
+    RequestValidationError,
+    UnauthorizedError,
+)
+from modmex_lambda.event_handler.gateway_response import GatewayResponseBuilder
+from modmex_lambda.event_handler.request import Request
+from modmex_lambda.event_handler.response import Response
+from modmex_lambda.event_handler.routing import HasRoutes, Route, Router
+from modmex_lambda.event_handler.routing_fallbacks import RoutingFallbackHandler
+from modmex_lambda.data_classes.common import BaseProxyEvent
+from modmex_lambda.data_classes.api_gateway_proxy_event import APIGatewayProxyEvent, APIGatewayProxyEventV2
+from modmex_lambda.shared.types import AnyCallableT
+from modmex_lambda.event_handler.types import IApiGatewayResolver
+from modmex_lambda.event_handler.dependencies.dependency_middleware import DependencyMiddleware
+from modmex_lambda.event_handler.middlewares import NextMiddleware
+from modmex_lambda.event_handler.cors import CORSConfig
+from modmex_lambda.shared.json_encoder import JSONEncoder
+from modmex_lambda.event_handler.constants import DEFAULT_STATUS_CODE
+
+# NextMiddleware = Callable[["ApiGatewayResolver"], Response]
+Middleware = Callable[["ApiGatewayResolver", NextMiddleware], Response]
+
+
+JSON_DUMP_CALL = partial(json.dumps, separators=(",", ":"), cls=JSONEncoder)
+
+
+class ProxyEventType(Enum):
+    """An enumerations of the supported proxy event types."""
+
+    APIGatewayProxyEvent = "APIGatewayProxyEvent"
+    APIGatewayProxyEventV2 = "APIGatewayProxyEventV2"
+    LambdaFunctionUrlEvent = "LambdaFunctionUrlEvent"
+
+
+_PROXY_EVENT_MAP: dict[Enum, type[BaseProxyEvent]] = {
+    ProxyEventType.APIGatewayProxyEvent: APIGatewayProxyEvent,
+    ProxyEventType.APIGatewayProxyEventV2: APIGatewayProxyEventV2,
+    ProxyEventType.LambdaFunctionUrlEvent: APIGatewayProxyEventV2,
+}
+
+
+class BaseRouter(HasRoutes):
+    current_event: BaseProxyEvent
+    lambda_context: object
+    context: dict[str, Any]
+    _router_middlewares: list[Callable] = []
+    processed_stack_frames: list[str] = []
+    
+    def use(self, middlewares: list[Middleware]) -> None:
+        self._router_middlewares = self._router_middlewares + middlewares
+
+    def append_context(self, **kwargs: Any) -> None:
+        self.context.update(kwargs)
+
+    def clear_context(self) -> None:
+        """Resets routing context"""
+        self.context.clear()
+
+    @property
+    def request(self) -> Request:
+        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.path,
+            path_parameters=self.context.get("_path_params", {}),
+            current_event=self.current_event,
+            context=self.context,
+        )
+        self.context["_request"] = request
+        return request
+
+
+class ApiGatewayResolver(BaseRouter, IApiGatewayResolver):
+    _event_type: ProxyEventType
+
+    def __init__(
+        self,
+        *,
+        cors: CORSConfig | None = None,
+        serializer: Callable[[dict], str] | None = None,
+        strip_prefixes: list[str | Pattern] | None = None,
+        json_body_deserializer: Callable[[str], dict] | None = None,
+        logger: Any | None = None,
+    ) -> None:
+        self._cors = cors
+        self._cors_enabled = cors is not None
+        
+        self._router = Router()
+        self._routing_fallbacks = RoutingFallbackHandler(self)
+        self._response_builder_class = GatewayResponseBuilder
+        
+        self._serializer = serializer or JSON_DUMP_CALL
+        self._json_body_deserializer = json_body_deserializer
+        
+        self._router_middlewares: list[Middleware] = []
+
+        self._logger = logger
+        self.dependency_overrides: dict[Callable[..., Any], Callable[..., Any]] = {}
+        self.current_event = None
+        self.current_context = None
+        self._strip_prefixes = strip_prefixes
+        self.context: dict[str, Any] = {}
+        self._dependency_middleware = DependencyMiddleware()
+
+
+    @property
+    def handler(self) -> Callable[[dict[str, Any], object], dict[str, Any]]:
+        return self.resolve
+
+    def middleware(self, func: Middleware | None = None) -> Any:
+        if func is None:
+            def decorator(mw: Middleware) -> Middleware:
+                self._router_middlewares.append(mw)
+                return mw
+
+            return decorator
+
+        self._router_middlewares.append(func)
+        return func
+
+    def route(
+        self,
+        rule: str,
+        method: str | list[str] | tuple[str],
+        description: str | None = None,
+        status_code: int | None = DEFAULT_STATUS_CODE,
+        middlewares: list[Middleware] | None = None,
+        cors: bool | None = None,
+        compress: bool = False,
+        cache_control: str | None = None,
+        **_: Any,
+    ) -> Callable[[AnyCallableT], AnyCallableT]:
+        cors_enabled = self._cors_enabled if cors is None else cors
+        return self._router.route(
+            rule=rule,
+            method=method,
+            description=description,
+            status_code=status_code,
+            middlewares=middlewares,
+            cors=cors_enabled,
+            compress=compress,
+            cache_control=cache_control,
+        )
+
+    def include_router(self, router: Router) -> None:
+        self._router.include_router(router)
+
+    def resolve(self, event: dict[str, Any], context: object) -> dict[str, Any]:
+        self.current_event = self._to_proxy_event(event)
+        self.current_context = context
+        self.context = {}
+        response = self._resolve().serialize(self.current_event, self._cors)
+        self.clear_context()
+        return response
+
+    def _resolve(self) -> GatewayResponseBuilder:
+        path = self._remove_prefix(self.current_event.path)
+        method = self.current_event.http_method.upper()
+        route, path_params, allowed_methods = self._router.match(method, path)
+    
+        if route:
+            self.append_context(
+                _route=route,
+                _route_args=path_params,
+                _path_params=path_params,
+                _path=path,
+            )
+            
+            response = self._call_route(route, route_arguments=path_params)
+        elif allowed_methods:
+            response = self._routing_fallbacks.method_not_allowed(
+                method=method,
+                path=path,
+                allowed_methods=allowed_methods,
+            )
+        else:
+            response = self._routing_fallbacks.not_found(method=method, path=path)
+            
+        return self._response_builder_class(
+            response=response,
+            route=route,
+            json_serializer=self._serializer,
+        )
+
+    def _call_route(self, route: Route, route_arguments: dict | None = None) -> Response:
+        try:
+            response = route.invoke(
+                router_middlewares=self._router_middlewares,
+                app=self,
+                route_arguments=route_arguments or {},
+            )
+            return response
+        except Exception as e:
+            response = self._call_exception_handler(e)
+            if response:
+                return response
+            
+            raise
+
+    def _remove_prefix(self, path: str) -> str:
+        """Remove the configured prefix from the path"""
+        if not isinstance(self._strip_prefixes, list):
+            return path
+
+        for prefix in self._strip_prefixes:
+            if isinstance(prefix, str):
+                if path == prefix:
+                    return "/"
+
+                if self._path_starts_with(path, prefix):
+                    return path[len(prefix) :]
+
+            if isinstance(prefix, Pattern):
+                path = re.sub(prefix, "", path)
+
+                if not path:
+                    return "/"
+
+        return path
+
+    def _to_proxy_event(self, event: dict) -> BaseProxyEvent:
+        event_type = getattr(self, "_event_type", None)
+        if event_type is None:
+            raise TypeError(
+                "ApiGatewayResolver is a base resolver. Use ApiGatewayRestResolver for API Gateway REST API "
+                "payload v1 or ApiGatewayHttpResolver for API Gateway HTTP API payload v2.",
+            )
+
+        event_class = _PROXY_EVENT_MAP.get(event_type)
+        if event_class is None:
+            raise TypeError(f"Unsupported API Gateway event type: {event_type!r}")
+
+        return event_class(event, self._json_body_deserializer)
+
+    def _to_response(self, result: dict | tuple | Response) -> Response:
+        if isinstance(result, Response):
+            return result
+        if isinstance(result, tuple) and len(result) == 2:
+            result, status_code = result
+        else:
+            route: Route | None = self.context.get("_route")
+            status_code = route.status_code if route else HTTPStatus.OK.value
+        return Response(body=result, status_code=status_code, content_type=content_types.APPLICATION_JSON)
+
+    def exception_handler(
+        self,
+        exc_class: type[Exception] | list[type[Exception]],
+    ):
+        return self._router.exception_handler(exc_class)
+    
+    def _call_exception_handler(self, exp: Exception) -> Response | None:
+        handler = self._router.exception_handler_manager.lookup_exception_handler(type(exp))
+        if handler:
+            try:
+                return handler(exp)
+            except Exception as exc:
+                exp = exc
+
+        return self._default_error_response(exp)
+
+    def _default_error_response(self, exc: Exception) -> Response | None:
+        if isinstance(exc, RequestValidationError):
+            errors = [{"loc": e["loc"], "type": e["type"]} for e in exc.errors()]
+            return Response(
+                body={
+                    "message": "Validation Error",
+                    "detail": errors,
+                },
+                status_code=HTTPStatus.BAD_REQUEST.value,
+                content_type=content_types.APPLICATION_JSON,
+            )
+        if isinstance(exc, MethodNotAllowedError):
+            return Response(body={"message": "Method Not Allowed"}, status_code=405)
+        if isinstance(exc, NotFoundError):
+            return Response(body={"message": "Not Found"}, status_code=404)
+        if isinstance(exc, UnauthorizedError):
+            return Response(body={"message": "Unauthorized"}, status_code=401)
+        if isinstance(exc, ForbiddenError):
+            return Response(body={"message": "Forbidden"}, status_code=403)
+        return None
+
+    @staticmethod
+    def _path_starts_with(path: str, prefix: str) -> bool:
+        """Returns true if the `path` starts with a prefix plus a `/`"""
+        if not isinstance(prefix, str) or prefix == "":
+            return False
+
+        return path.startswith(f"{prefix}/")
+
+class ApiGatewayRestResolver(ApiGatewayResolver):
+    """Resolver for API Gateway REST API payload v1."""
+
+    _event_type = ProxyEventType.APIGatewayProxyEvent
+
+
+class ApiGatewayHttpResolver(ApiGatewayResolver):
+    """Resolver for API Gateway HTTP API payload v2."""
+
+    _event_type = ProxyEventType.APIGatewayProxyEventV2
+
+
+__all__ = [
+    "ApiGatewayHttpResolver",
+    "ApiGatewayRestResolver",
+    "Request",
+    "Response",
+    "Route",
+]

modmex_lambda/event_handler/constants.py

@@ -0,0 +1,3 @@
+
+
+DEFAULT_STATUS_CODE = 200

modmex_lambda/event_handler/content_types.py

@@ -0,0 +1,13 @@
+"""Common HTTP content types."""
+
+APPLICATION_JSON = "application/json"
+TEXT_PLAIN = "text/plain"
+TEXT_HTML = "text/html"
+APPLICATION_OCTET_STREAM = "application/octet-stream"
+
+__all__ = [
+    "APPLICATION_JSON",
+    "TEXT_PLAIN",
+    "TEXT_HTML",
+    "APPLICATION_OCTET_STREAM",
+]

modmex_lambda/event_handler/cors.py

@@ -0,0 +1,97 @@
+
+
+
+
+class CORSConfig:
+
+    _REQUIRED_HEADERS = ["Authorization", "Content-Type", "X-Amz-Date", "X-Api-Key", "X-Amz-Security-Token"]
+
+    def __init__(
+        self,
+        allow_origin: str = "*",
+        extra_origins: list[str] | None = None,
+        allow_headers: list[str] | None = None,
+        expose_headers: list[str] | None = None,
+        max_age: int | None = None,
+        allow_credentials: bool = False,
+    ):
+        """
+        Parameters
+        ----------
+        allow_origin: str
+            The value of the `Access-Control-Allow-Origin` to send in the response. Defaults to "*", but should
+            only be used during development.
+        extra_origins: list[str] | None
+            The list of additional allowed origins.
+        allow_headers: list[str] | None
+            The list of additional allowed headers. This list is added to list of
+            built-in allowed headers: `Authorization`, `Content-Type`, `X-Amz-Date`,
+            `X-Api-Key`, `X-Amz-Security-Token`.
+        expose_headers: list[str] | None
+            A list of values to return for the Access-Control-Expose-Headers
+        max_age: int | None
+            The value for the `Access-Control-Max-Age`
+        allow_credentials: bool
+            A boolean value that sets the value of `Access-Control-Allow-Credentials`
+        """
+
+        self._allowed_origins = [allow_origin]
+
+        if extra_origins:
+            self._allowed_origins.extend(extra_origins)
+
+        self.allow_headers = set(self._REQUIRED_HEADERS + (allow_headers or []))
+        self.expose_headers = expose_headers or []
+        self.max_age = max_age
+        self.allow_credentials = allow_credentials
+
+    def to_dict(self, origin: str | None) -> dict[str, str]:
+        """Builds the configured Access-Control http headers"""
+
+        # If there's no Origin, don't add any CORS headers
+        if not origin:
+            return {}
+
+        # If the origin doesn't match any of the allowed origins, and we don't allow all origins ("*"),
+        # don't add any CORS headers
+        if origin not in self._allowed_origins and "*" not in self._allowed_origins:
+            return {}
+
+        # The origin matched an allowed origin, so return the CORS headers
+        headers = {
+            "Access-Control-Allow-Origin": origin,
+            "Access-Control-Allow-Headers": CORSConfig.build_allow_methods(self.allow_headers),
+        }
+
+        if self.expose_headers:
+            headers["Access-Control-Expose-Headers"] = ",".join(self.expose_headers)
+        if self.max_age is not None:
+            headers["Access-Control-Max-Age"] = str(self.max_age)
+        if origin != "*" and self.allow_credentials is True:
+            headers["Access-Control-Allow-Credentials"] = "true"
+        return headers
+
+    def allowed_origin(self, extracted_origin: str) -> str | None:
+        if extracted_origin in self._allowed_origins:
+            return extracted_origin
+        if extracted_origin is not None and "*" in self._allowed_origins:
+            return "*"
+
+        return None
+
+    @staticmethod
+    def build_allow_methods(methods: set[str]) -> str:
+        """Build sorted comma delimited methods for Access-Control-Allow-Methods header
+
+        Parameters
+        ----------
+        methods : set[str]
+            Set of HTTP Methods
+
+        Returns
+        -------
+        set[str]
+            Formatted string with all HTTP Methods allowed for CORS e.g., `GET, OPTIONS`
+
+        """
+        return ",".join(sorted(methods))

modmex_lambda/event_handler/dependencies/compat.py

@@ -0,0 +1,231 @@
+# mypy: ignore-errors
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Mapping, Sequence
+from copy import copy
+from dataclasses import dataclass, is_dataclass
+from typing import Any, Deque, FrozenSet, List, Set, Tuple, Union, Literal, Annotated, get_args, get_origin
+
+
+from modmex import BaseModel, ValidationError, create_model
+from modmex_lambda.validation import ModmexValidator
+
+from modmex_lambda.event_handler.dependencies.types import IncEx, UnionType
+    
+from modmex import Field as FieldInfo, Undefined
+from modmex.fields import UndefinedType
+
+
+Required = Undefined
+
+
+
+sequence_annotation_to_type = {
+    Sequence: list,
+    List: list,
+    list: list,
+    Tuple: tuple,
+    tuple: tuple,
+    Set: set,
+    set: set,
+    FrozenSet: frozenset,
+    frozenset: frozenset,
+    Deque: deque,
+    deque: deque,
+}
+
+sequence_types = tuple(sequence_annotation_to_type.keys())
+
+
+
+class ErrorWrapper(Exception):
+    pass
+
+
+@dataclass
+class ModelField:
+    field_info: FieldInfo
+    name: str
+    mode: Literal["validation", "serialization"] = "validation"
+
+    @property
+    def alias(self) -> str:
+        value = self.field_info.alias
+        return value if value is not None else self.name
+
+    @property
+    def required(self) -> bool:
+        return self.field_info.is_required()
+
+    @property
+    def default(self) -> Any:
+        return self.get_default()
+
+    @property
+    def type_(self) -> Any:
+        return self.field_info.annotation
+
+    # def __post_init__(self) -> None:
+    #     # If the field_info.annotation is already an Annotated type with discriminator metadata,
+    #     # use it directly instead of wrapping it again
+    #     annotation = self.field_info.annotation
+    #     if (
+    #         get_origin(annotation) is Annotated
+    #         and hasattr(self.field_info, "discriminator")
+    #         and self.field_info.discriminator is not None
+    #     ):
+    #         self._type_adapter: TypeAdapter[Any] = TypeAdapter(annotation)
+    #     else:
+    #         self._type_adapter: TypeAdapter[Any] = TypeAdapter(
+    #             Annotated[annotation, self.field_info],
+    #         )
+
+    def get_default(self) -> Any:
+        if self.field_info.is_required():
+            return None
+        return self.field_info.get_default(call_default_factory=True)
+
+    def serialize(
+        self,
+        value: Any,
+        *,
+        mode: Literal["json", "python"] = "json",
+        include: IncEx | None = None,
+        exclude: IncEx | None = None,
+        by_alias: bool = True,
+        exclude_unset: bool = False,
+        exclude_defaults: bool = False,
+        exclude_none: bool = False,
+    ) -> Any:
+        return ModmexValidator().serialize(value)
+
+    def validate(
+        self,
+        value: Any,
+        *,
+        loc: tuple[int | str, ...] = (),
+    ) -> tuple[Any, list[dict[str, Any]] | None]:
+        try:
+            return (ModmexValidator().validate(value, self.field_info.annotation, list(loc)), None)
+        except ValidationError as exc:
+            return None, _regenerate_error_with_loc(errors=exc.errors, loc_prefix=())
+
+    def __hash__(self) -> int:
+        # Each ModelField is unique for our purposes
+        return id(self)
+
+
+def _normalize_errors(errors: Sequence[Any]) -> list[dict[str, Any]]:
+    return errors  # type: ignore[r
+
+
+def create_body_model(*, fields: Sequence[ModelField], model_name: str) -> type[BaseModel]:
+    field_params = {f.name: (f.field_info.annotation, f.field_info) for f in fields}
+    model: type[BaseModel] = create_model(model_name, **field_params)
+    return model
+
+
+def is_scalar_field(field: ModelField) -> bool:
+    from modmex_lambda.event_handler.dependencies.params import Body
+
+    return field_annotation_is_scalar(field.field_info.annotation) and not isinstance(field.field_info, Body)
+
+
+def field_annotation_is_complex(annotation: type[Any] | None) -> bool:
+    origin = get_origin(annotation)
+    if origin is Union or origin is UnionType:
+        return any(field_annotation_is_complex(arg) for arg in get_args(annotation))
+
+    return (
+        _annotation_is_complex(annotation)
+        or _annotation_is_complex(origin)
+        # or hasattr(origin, "__pydantic_core_schema__")
+        # or hasattr(origin, "__get_pydantic_core_schema__")
+    )
+
+
+def field_annotation_is_scalar(annotation: Any) -> bool:
+    return annotation is Ellipsis or not field_annotation_is_complex(annotation)
+
+
+def field_annotation_is_sequence(annotation: type[Any] | None) -> bool:
+    return _annotation_is_sequence(annotation) or _annotation_is_sequence(get_origin(annotation))
+
+
+def _annotation_is_complex(annotation: type[Any] | None) -> bool:
+    return (
+        lenient_issubclass(annotation, (BaseModel, Mapping))  # Keep it to UploadFile
+        or _annotation_is_sequence(annotation)
+        or is_dataclass(annotation)
+    )
+
+def get_annotation_from_field_info(annotation: Any, field_info: FieldInfo, field_name: str) -> Any:
+    return annotation
+
+
+def copy_field_info(*, field_info: FieldInfo, annotation: Any) -> FieldInfo:
+    # Create a shallow copy of the field_info to preserve its type and all attributes
+    new_field = copy(field_info)
+
+    # Recursively extract all metadata from nested Annotated types
+    def extract_metadata(ann: Any) -> tuple[Any, list[Any]]:
+        """Extract base type and all non-FieldInfo metadata from potentially nested Annotated types."""
+        if get_origin(ann) is not Annotated:
+            return ann, []
+
+        args = get_args(ann)
+        base_type = args[0]
+        metadata = list(args[1:])
+
+        # If base type is also Annotated, recursively extract its metadata
+        if get_origin(base_type) is Annotated:
+            inner_base, inner_metadata = extract_metadata(base_type)
+            all_metadata = [m for m in inner_metadata + metadata if not isinstance(m, FieldInfo)]
+            return inner_base, all_metadata
+        else:
+            constraint_metadata = [m for m in metadata if not isinstance(m, FieldInfo)]
+            return base_type, constraint_metadata
+
+    # Extract base type and constraints
+    base_type, constraints = extract_metadata(annotation)
+
+    # Set the annotation with base type and all constraint metadata
+    # Use tuple unpacking for Python 3.10+ compatibility
+    if constraints:
+        new_field.annotation = Annotated[(base_type, *constraints)]
+    else:
+        new_field.annotation = base_type
+
+    return new_field
+
+
+def get_missing_field_error(loc: tuple[str, ...]) -> dict[str, Any]:
+    if hasattr(ValidationError, "from_exception_data"):
+        error = ValidationError.from_exception_data(
+            "Field required",
+            [{"type": "missing", "loc": loc, "input": {}}],
+        ).errors()[0]
+        error["input"] = None
+        return error
+    return {"type": "missing", "loc": loc, "msg": "Field required", "input": None}
+
+
+def _annotation_is_sequence(annotation: type[Any] | None) -> bool:
+    if lenient_issubclass(annotation, (str, bytes)):
+        return False
+    return lenient_issubclass(annotation, sequence_types)
+
+def _regenerate_error_with_loc(*, errors: Sequence[Any], loc_prefix: tuple[str | int, ...]) -> list[dict[str, Any]]:
+    updated_loc_errors: list[Any] = [
+        {**err, "loc": loc_prefix + tuple(err.get("loc", ()))} for err in _normalize_errors(errors)
+    ]
+
+    return updated_loc_errors
+
+
+def lenient_issubclass(cls: Any, class_or_tuple: Any) -> bool:  # pragma: no cover
+    try:
+        return isinstance(cls, type) and issubclass(cls, class_or_tuple)
+    except TypeError:
+        return False