modmex-lambda 0.1.0__py3-none-any.whl

modmex_lambda/__init__.py

@@ -0,0 +1,62 @@
+"""Public API for modmex-lambda."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .event_handler import (
+        ApiGatewayHttpResolver,
+        ApiGatewayRestResolver,
+        Response,
+    )
+    from .event_handler.request import Request
+    from .event_sources import event_source
+    from .event_handler.dependencies.depends import Depends
+    from .logging import Logger
+    from .parser import event_parser, parse
+    from .validation import ModmexValidator, ValidationError
+
+_EXPORTS = {
+    "ApiGatewayHttpResolver": ("modmex_lambda.event_handler", "ApiGatewayHttpResolver"),
+    "ApiGatewayRestResolver": ("modmex_lambda.event_handler", "ApiGatewayRestResolver"),
+    "Request": ("modmex_lambda.event_handler.request", "Request"),
+    "Response": ("modmex_lambda.event_handler", "Response"),
+    "parse": ("modmex_lambda.parser", "parse"),
+    "event_parser": ("modmex_lambda.parser", "event_parser"),
+    "event_source": ("modmex_lambda.event_sources", "event_source"),
+    "Depends": ("modmex_lambda.event_handler.dependencies.depends", "Depends"),
+    "Logger": ("modmex_lambda.logging", "Logger"),
+    "ModmexValidator": ("modmex_lambda.validation", "ModmexValidator"),
+    "ValidationError": ("modmex_lambda.validation", "ValidationError"),
+}
+
+__all__ = [
+    "ApiGatewayHttpResolver",
+    "ApiGatewayRestResolver",
+    "Request",
+    "Response",
+    "parse",
+    "event_parser",
+    "event_source",
+    "Depends",
+    "Logger",
+    "ModmexValidator",
+    "ValidationError",
+]
+
+
+def __getattr__(name: str) -> Any:
+    target = _EXPORTS.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module_name, attr = target
+    value = getattr(import_module(module_name), attr)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted([*globals().keys(), *__all__])

modmex_lambda/data_classes/__init__.py

@@ -0,0 +1,49 @@
+from modmex_lambda.data_classes.api_gateway_proxy_event import (
+    APIGatewayProxyEvent,
+    APIGatewayProxyEventV2,
+)
+from modmex_lambda.data_classes.api_gateway_authorizer_event import APIGatewayAuthorizerEvent
+from modmex_lambda.data_classes.api_gateway_websocket_event import APIGatewayWebSocketEvent
+from modmex_lambda.data_classes.common import DictWrapper
+from modmex_lambda.data_classes.cognito_user_pool_event import (
+    CognitoUserPoolEvent,
+    CreateAuthChallengeTriggerEvent,
+    CustomEmailSenderTriggerEvent,
+    CustomMessageTriggerEvent,
+    CustomSMSSenderTriggerEvent,
+    DefineAuthChallengeTriggerEvent,
+    PostAuthenticationTriggerEvent,
+    PostConfirmationTriggerEvent,
+    PreAuthenticationTriggerEvent,
+    PreSignUpTriggerEvent,
+    PreTokenGenerationTriggerEvent,
+    PreTokenGenerationV2TriggerEvent,
+    PreTokenGenerationV3TriggerEvent,
+    UserMigrationTriggerEvent,
+    VerifyAuthChallengeResponseTriggerEvent,
+)
+
+__all__ = [
+    "DictWrapper",
+    "APIGatewayProxyEvent",
+    "APIGatewayProxyEventV2",
+    "APIGatewayRestEvent",
+    "APIGatewayHttpEvent",
+    "APIGatewayAuthorizerEvent",
+    "APIGatewayWebSocketEvent",
+    "CognitoUserPoolEvent",
+    "PreSignUpTriggerEvent",
+    "PostConfirmationTriggerEvent",
+    "UserMigrationTriggerEvent",
+    "CustomMessageTriggerEvent",
+    "PreAuthenticationTriggerEvent",
+    "PostAuthenticationTriggerEvent",
+    "PreTokenGenerationTriggerEvent",
+    "PreTokenGenerationV2TriggerEvent",
+    "PreTokenGenerationV3TriggerEvent",
+    "DefineAuthChallengeTriggerEvent",
+    "CreateAuthChallengeTriggerEvent",
+    "VerifyAuthChallengeResponseTriggerEvent",
+    "CustomEmailSenderTriggerEvent",
+    "CustomSMSSenderTriggerEvent",
+]

modmex_lambda/data_classes/api_gateway_authorizer_event.py

@@ -0,0 +1,38 @@
+"""API Gateway Lambda authorizer event data class."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from modmex_lambda.data_classes.common import DictWrapper
+
+
+class APIGatewayAuthorizerEvent(DictWrapper):
+    @property
+    def type(self) -> str:
+        return str(self.get("type") or "")
+
+    @property
+    def method_arn(self) -> str:
+        return str(self.get("methodArn") or "")
+
+    @property
+    def authorization_token(self) -> str | None:
+        value = self.get("authorizationToken")
+        return None if value is None else str(value)
+
+    @property
+    def headers(self) -> dict[str, Any]:
+        return dict(self.get("headers") or {})
+
+    @property
+    def query_string_parameters(self) -> dict[str, Any]:
+        return dict(self.get("queryStringParameters") or {})
+
+    @property
+    def path_parameters(self) -> dict[str, Any]:
+        return dict(self.get("pathParameters") or {})
+
+    @property
+    def request_context(self) -> dict[str, Any]:
+        return dict(self.get("requestContext") or {})

modmex_lambda/data_classes/api_gateway_proxy_event.py

@@ -0,0 +1,328 @@
+"""API Gateway event source data classes."""
+
+from __future__ import annotations
+
+
+from typing import Any
+from functools import cached_property
+from modmex_lambda.data_classes.common import (
+    DictWrapper,
+    BaseProxyEvent,
+    CaseInsensitiveDict,
+    BaseRequestContext,
+    BaseRequestContextV2,
+)
+from modmex_lambda.shared.headers_serializer import HttpApiHeadersSerializer, MultiValueHeadersSerializer, BaseHeadersSerializer
+
+
+class APIGatewayEventAuthorizer(DictWrapper):
+    @property
+    def claims(self) -> dict[str, Any]:
+        return self.get("claims") or {}  # key might exist but can be `null`
+
+    @property
+    def scopes(self) -> list[str]:
+        return self.get("scopes") or []  # key might exist but can be `null`
+
+    @property
+    def principal_id(self) -> str:
+        """The principal user identification associated with the token sent by the client and returned from an
+        API Gateway Lambda authorizer (formerly known as a custom authorizer)"""
+        return self.get("principalId") or ""  # key might exist but can be `null`
+
+    @property
+    def integration_latency(self) -> int | None:
+        """The authorizer latency in ms."""
+        return self.get("integrationLatency")
+
+    def get_context(self) -> dict[str, Any]:
+        """Retrieve the authorization context details injected by a Lambda Authorizer.
+
+        Example
+        --------
+
+        ```python
+        ctx: dict = request_context.authorizer.get_context()
+
+        tenant_id = ctx.get("tenant_id")
+        ```
+
+        Returns:
+        --------
+        dict[str, Any]
+            A dictionary containing Lambda authorization context details.
+        """
+        return self._data
+
+
+class APIGatewayEventRequestContext(BaseRequestContext):
+    @property
+    def connected_at(self) -> int | None:
+        """The Epoch-formatted connection time. (WebSocket API)"""
+        return self.get("connectedAt")
+
+    @property
+    def connection_id(self) -> str | None:
+        """A unique ID for the connection that can be used to make a callback to the client. (WebSocket API)"""
+        return self.get("connectionId")
+
+    @property
+    def event_type(self) -> str | None:
+        """The event type: `CONNECT`, `MESSAGE`, or `DISCONNECT`. (WebSocket API)"""
+        return self.get("eventType")
+
+    @property
+    def message_direction(self) -> str | None:
+        """Message direction (WebSocket API)"""
+        return self.get("messageDirection")
+
+    @property
+    def message_id(self) -> str | None:
+        """A unique server-side ID for a message. Available only when the `eventType` is `MESSAGE`."""
+        return self.get("messageId")
+
+    @property
+    def operation_name(self) -> str | None:
+        """The name of the operation being performed"""
+        return self.get("operationName")
+
+    @property
+    def route_key(self) -> str | None:
+        """The selected route key."""
+        return self.get("routeKey")
+
+    @property
+    def authorizer(self) -> APIGatewayEventAuthorizer:
+        return APIGatewayEventAuthorizer(self.get("authorizer") or {})
+
+
+
+
+class APIGatewayProxyEvent(BaseProxyEvent):
+    
+    @property
+    def version(self) -> str:
+        return self.get("version") or "1.0"
+
+    @property
+    def resource(self) -> str:
+        return self["resource"]
+
+    @property
+    def multi_value_headers(self) -> dict[str, list[str]]:
+        return CaseInsensitiveDict(self.get("multiValueHeaders"))
+
+    @property
+    def resolved_query_string_parameters(self) -> dict[str, list[str]]:
+        multi_value = self.multi_value_query_string_parameters
+        single_value = super().resolved_query_string_parameters
+
+        if not multi_value:
+            return single_value
+
+        if not single_value:
+            return multi_value
+
+        # Merge both: multi_value takes precedence, single_value fills missing keys
+        return {**single_value, **multi_value}
+
+    @property
+    def resolved_headers_field(self) -> dict[str, Any]:
+        return self.multi_value_headers or self.headers
+
+    @property
+    def request_context(self) -> APIGatewayEventRequestContext:
+        return APIGatewayEventRequestContext(self["requestContext"])
+
+    @property
+    def path_parameters(self) -> dict[str, str]:
+        return self.get("pathParameters") or {}
+
+    @property
+    def stage_variables(self) -> dict[str, str]:
+        return self.get("stageVariables") or {}
+
+    def header_serializer(self) -> BaseHeadersSerializer:
+        return MultiValueHeadersSerializer()
+
+
+
+class RequestContextV2AuthorizerIam(DictWrapper):
+    @property
+    def access_key(self) -> str:
+        """The IAM user access key associated with the request."""
+        return self.get("accessKey") or ""  # key might exist but can be `null`
+
+    @property
+    def account_id(self) -> str:
+        """The AWS account ID associated with the request."""
+        return self.get("accountId") or ""  # key might exist but can be `null`
+
+    @property
+    def caller_id(self) -> str:
+        """The principal identifier of the caller making the request."""
+        return self.get("callerId") or ""  # key might exist but can be `null`
+
+    def _cognito_identity(self) -> dict:
+        return self.get("cognitoIdentity") or {}  # not available in FunctionURL; key might exist but can be `null`
+
+    @property
+    def cognito_amr(self) -> list[str]:
+        """This represents how the user was authenticated.
+        AMR stands for  Authentication Methods References as per the openid spec"""
+        return self._cognito_identity().get("amr", [])
+
+    @property
+    def cognito_identity_id(self) -> str:
+        """The Amazon Cognito identity ID of the caller making the request.
+        Available only if the request was signed with Amazon Cognito credentials."""
+        return self._cognito_identity().get("identityId", "")
+
+    @property
+    def cognito_identity_pool_id(self) -> str:
+        """The Amazon Cognito identity pool ID of the caller making the request.
+        Available only if the request was signed with Amazon Cognito credentials."""
+        return self._cognito_identity().get("identityPoolId") or ""  # key might exist but can be `null`
+
+    @property
+    def principal_org_id(self) -> str:
+        """The AWS organization ID."""
+        return self.get("principalOrgId") or ""  # key might exist but can be `null`
+
+    @property
+    def user_arn(self) -> str:
+        """The Amazon Resource Name (ARN) of the effective user identified after authentication."""
+        return self.get("userArn") or ""  # key might exist but can be `null`
+
+    @property
+    def user_id(self) -> str:
+        """The IAM user ID of the effective user identified after authentication."""
+        return self.get("userId") or ""  # key might exist but can be `null`
+
+
+class RequestContextV2Authorizer(DictWrapper):
+    @property
+    def jwt_claim(self) -> dict[str, Any]:
+        jwt = self.get("jwt") or {}  # not available in FunctionURL; key might exist but can be `null`
+        return jwt.get("claims") or {}  # key might exist but can be `null`
+
+    @property
+    def jwt_scopes(self) -> list[str]:
+        jwt = self.get("jwt") or {}  # not available in FunctionURL; key might exist but can be `null`
+        return jwt.get("scopes", [])
+
+    @property
+    def get_lambda(self) -> dict[str, Any]:
+        """Lambda authorization context details"""
+        return self.get("lambda") or {}  # key might exist but can be `null`
+
+    def get_context(self) -> dict[str, Any]:
+        """Retrieve the authorization context details injected by a Lambda Authorizer.
+
+        Example
+        --------
+
+        ```python
+        ctx: dict = request_context.authorizer.get_context()
+
+        tenant_id = ctx.get("tenant_id")
+        ```
+
+        Returns:
+        --------
+        dict[str, Any]
+            A dictionary containing Lambda authorization context details.
+        """
+        return self.get_lambda
+
+    @property
+    def iam(self) -> RequestContextV2AuthorizerIam:
+        """IAM authorization details used for making the request."""
+        iam = self.get("iam") or {}  # key might exist but can be `null`
+        return RequestContextV2AuthorizerIam(iam)
+
+
+class RequestContextV2(BaseRequestContextV2):
+    @property
+    def authorizer(self) -> RequestContextV2Authorizer:
+        return RequestContextV2Authorizer(self.get("authorizer") or {})
+
+
+class APIGatewayProxyEventV2(BaseProxyEvent):
+    """AWS Lambda proxy V2 event
+
+    Notes:
+    -----
+    Format 2.0 doesn't have multiValueHeaders or multiValueQueryStringParameters fields. Duplicate headers
+    are combined with commas and included in the headers field. Duplicate query strings are combined with
+    commas and included in the queryStringParameters field.
+
+    Format 2.0 includes a new cookies field. All cookie headers in the request are combined with commas and
+    added to the cookies field. In the response to the client, each cookie becomes a set-cookie header.
+
+    Documentation:
+    --------------
+    - https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html
+    """
+
+    @property
+    def version(self) -> str:
+        return self["version"]
+
+    @property
+    def route_key(self) -> str:
+        return self["routeKey"]
+
+    @property
+    def raw_path(self) -> str:
+        return self["rawPath"]
+
+    @property
+    def raw_query_string(self) -> str:
+        return self["rawQueryString"]
+
+    @property
+    def cookies(self) -> list[str]:
+        return self.get("cookies") or []
+
+    @property
+    def resolved_cookies_field(self) -> dict[str, str]:
+        """
+        Parse cookies from the dedicated ``cookies`` field in API Gateway HTTP API v2 format.
+
+        The ``cookies`` field contains a list of strings like ``["session=abc", "theme=dark"]``.
+        """
+        from modmex_lambda.data_classes.common import _parse_cookie_string
+
+        return _parse_cookie_string("; ".join(self.cookies))
+
+    @property
+    def request_context(self) -> RequestContextV2:
+        return RequestContextV2(self["requestContext"])
+
+    @property
+    def path_parameters(self) -> dict[str, str]:
+        return self.get("pathParameters") or {}
+
+    @property
+    def stage_variables(self) -> dict[str, str]:
+        return self.get("stageVariables") or {}
+
+    @property
+    def path(self) -> str:
+        stage = self.request_context.stage
+        if stage != "$default":
+            return self.raw_path[len("/" + stage) :]
+        return self.raw_path
+
+    @property
+    def http_method(self) -> str:
+        """The HTTP method used. Valid values include: DELETE, GET, HEAD, OPTIONS, PATCH, POST, and PUT."""
+        return self.request_context.http.method
+
+    def header_serializer(self):
+        return HttpApiHeadersSerializer()
+
+    @cached_property
+    def resolved_headers_field(self) -> dict[str, Any]:
+        return CaseInsensitiveDict((k, v.split(",") if "," in v else v) for k, v in self.headers.items())

modmex_lambda/data_classes/api_gateway_websocket_event.py

@@ -0,0 +1,40 @@
+"""API Gateway WebSocket event data class."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from modmex_lambda.data_classes.common import DictWrapper
+
+
+class APIGatewayWebSocketEvent(DictWrapper):
+    @property
+    def request_context(self) -> dict[str, Any]:
+        return dict(self.get("requestContext") or {})
+
+    @property
+    def route_key(self) -> str:
+        return str((self.request_context or {}).get("routeKey") or "")
+
+    @property
+    def event_type(self) -> str:
+        return str((self.request_context or {}).get("eventType") or "")
+
+    @property
+    def connection_id(self) -> str:
+        return str((self.request_context or {}).get("connectionId") or "")
+
+    @property
+    def body(self) -> Any:
+        return self.get("body")
+
+    @property
+    def json_body(self) -> Any:
+        body = self.body
+        if isinstance(body, str):
+            try:
+                return json.loads(body)
+            except json.JSONDecodeError:
+                return body
+        return body