aws-lambda-powertools 3.10.1a10__py3-none-any.whl → 3.11.0__py3-none-any.whl

aws_lambda_powertools/event_handler/events_appsync/base.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Callable
+
+DEFAULT_ROUTE = "/default/*"
+
+
+class BaseRouter(ABC):
+    """Abstract base class for Router (resolvers)"""
+
+    @abstractmethod
+    def on_publish(
+        self,
+        path: str = DEFAULT_ROUTE,
+        aggregate: bool = True,
+    ) -> Callable:
+        raise NotImplementedError
+
+    @abstractmethod
+    def async_on_publish(
+        self,
+        path: str = DEFAULT_ROUTE,
+        aggregate: bool = True,
+    ) -> Callable:
+        raise NotImplementedError
+
+    @abstractmethod
+    def on_subscribe(
+        self,
+        path: str = DEFAULT_ROUTE,
+    ) -> Callable:
+        raise NotImplementedError
+
+    def append_context(self, **additional_context) -> None:
+        """
+        Appends context information available under any route.
+
+        Parameters
+        -----------
+        **additional_context: dict
+            Additional context key-value pairs to append.
+        """
+        raise NotImplementedError

aws_lambda_powertools/event_handler/events_appsync/exceptions.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+
+class UnauthorizedException(Exception):
+    """
+    Error to be thrown to communicate the subscription is unauthorized.
+
+    When this error is raised, the client will receive a 40x error code
+    and the subscription will be closed.
+
+    Attributes:
+        message (str): The error message describing the unauthorized access.
+    """
+
+    def __init__(self, message: str | None = None, *args, **kwargs):
+        """
+        Initialize the UnauthorizedException.
+
+        Args:
+            message (str): A descriptive error message.
+            *args: Variable positional arguments.
+            **kwargs: Variable keyword arguments.
+        """
+        super().__init__(message, *args, **kwargs)
+        self.name = "UnauthorizedException"

aws_lambda_powertools/event_handler/events_appsync/functions.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from typing import Any
+
+PATH_REGEX = re.compile(r"^\/([^\/\*]+)(\/[^\/\*]+)*(\/\*)?$")
+
+
+def is_valid_path(path: str) -> bool:
+    """
+    Checks if a given path is valid based on specific rules.
+
+    Parameters
+    ----------
+    path: str
+        The path to validate
+
+    Returns:
+    --------
+    bool:
+        True if the path is valid, False otherwise
+
+    Examples:
+        >>> is_valid_path('/*')
+        True
+        >>> is_valid_path('/users')
+        True
+        >>> is_valid_path('/users/profile')
+        True
+        >>> is_valid_path('/users/*/details')
+        False
+        >>> is_valid_path('/users/*')
+        True
+        >>> is_valid_path('users')
+        False
+    """
+    return True if path == "/*" else bool(PATH_REGEX.fullmatch(path))
+
+
+def find_best_route(routes: dict[str, Any], path: str):
+    """
+    Find the most specific matching route for a given path.
+
+    Examples of matches:
+        Route: /default/v1/*         Path: /default/v1/users      -> MATCH
+        Route: /default/v1/*         Path: /default/v1/users/students  -> MATCH
+        Route: /default/v1/users/*   Path: /default/v1/users/123  -> MATCH (this wins over /default/v1/*)
+        Route: /*                    Path: /anything/here      -> MATCH (lowest priority)
+
+    Parameters
+    ----------
+    routes: dict[str, Any]
+        Dictionary containing routes and their handlers
+            Format: {
+                'resolvers': {
+                    '/path/*': {'func': callable, 'aggregate': bool},
+                    '/path/specific/*': {'func': callable, 'aggregate': bool}
+                }
+            }
+    path: str
+        Actual path to match (e.g., '/default/v1/users')
+
+    Returns
+    -------
+        str: Most specific matching route or None if no match
+    """
+
+    @lru_cache(maxsize=1024)
+    def pattern_to_regex(route):
+        """
+        Convert a route pattern to a regex pattern with caching.
+        Examples:
+            /default/v1/*         -> ^/default/v1/[^/]+$
+            /default/v1/users/*   -> ^/default/v1/users/.*$
+
+        Parameters
+        ----------
+        route: str
+            Route pattern with wildcards
+
+        Returns
+        -------
+        Pattern:
+            Compiled regex pattern
+        """
+        # Escape special regex chars but convert * to regex pattern
+        pattern = re.escape(route).replace("\\*", "[^/]+")
+
+        # If pattern ends with [^/]+, replace with .* for multi-segment match
+        if pattern.endswith("[^/]+"):
+            pattern = pattern[:-6] + ".*"
+
+        # Compile and return the regex pattern
+        return re.compile(f"^{pattern}$")
+
+    # Find all matching routes
+    matches = [route for route in routes.keys() if pattern_to_regex(route).match(path)]
+
+    # Return the most specific route (longest length minus wildcards)
+    # Examples of specificity:
+    # - '/default/v1/users'     -> score: 14 (len=14, wildcards=0)
+    # - '/default/v1/users/*'   -> score: 14 (len=15, wildcards=1)
+    # - '/default/v1/*'        -> score: 8  (len=9, wildcards=1)
+    # - '/*'               -> score: 0  (len=2, wildcards=1)
+    return max(matches, key=lambda x: len(x) - x.count("*"), default=None)

aws_lambda_powertools/event_handler/events_appsync/router.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from aws_lambda_powertools.event_handler.events_appsync._registry import ResolverEventsRegistry
+from aws_lambda_powertools.event_handler.events_appsync.base import DEFAULT_ROUTE, BaseRouter
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from aws_lambda_powertools.utilities.data_classes.appsync_resolver_events_event import AppSyncResolverEventsEvent
+    from aws_lambda_powertools.utilities.typing.lambda_context import LambdaContext
+
+
+class Router(BaseRouter):
+    """
+    Router for AppSync real-time API event handling.
+
+    This class provides decorators to register resolver functions for publish and subscribe
+    operations in AppSync real-time APIs.
+
+    Parameters
+    ----------
+    context : dict
+        Dictionary to store context information accessible across resolvers
+    current_event : AppSyncResolverEventsEvent
+        Current event being processed
+    lambda_context : LambdaContext
+        Lambda context from the AWS Lambda function
+
+    Examples
+    --------
+    Create a router and define resolvers:
+
+    >>> chat_router = Router()
+    >>>
+    >>> # Register a resolver for publish operations
+    >>> @chat_router.on_publish(path="/chat/message")
+    >>> def handle_message(payload):
+    >>>     # Process message
+    >>>     return {"success": True, "messageId": payload.get("id")}
+    >>>
+    >>> # Register an async resolver for publish operations
+    >>> @chat_router.async_on_publish(path="/chat/typing")
+    >>> async def handle_typing(event):
+    >>>     # Process typing indicator
+    >>>     await some_async_operation()
+    >>>     return {"processed": True}
+    >>>
+    >>> # Register a resolver for subscribe operations
+    >>> @chat_router.on_subscribe(path="/chat/room/*")
+    >>> def handle_subscribe(event):
+    >>>     # Handle subscription setup
+    >>>     return {"allowed": True}
+    """
+
+    context: dict
+    current_event: AppSyncResolverEventsEvent
+    lambda_context: LambdaContext
+
+    def __init__(self):
+        """
+        Initialize a new Router instance.
+
+        Sets up empty context and registry containers for different types of resolvers.
+        """
+        self.context = {}  # early init as customers might add context before event resolution
+        self._publish_registry = ResolverEventsRegistry(kind_resolver="on_publish")
+        self._async_publish_registry = ResolverEventsRegistry(kind_resolver="async_on_publish")
+        self._subscribe_registry = ResolverEventsRegistry(kind_resolver="on_subscribe")
+
+    def on_publish(
+        self,
+        path: str = DEFAULT_ROUTE,
+        aggregate: bool = False,
+    ) -> Callable:
+        """
+        Register a resolver function for publish operations.
+
+        Parameters
+        ----------
+        path : str, optional
+            The channel path pattern to match for this resolver, by default "/default/*"
+        aggregate : bool, optional
+            Whether to process events in aggregate (batch) mode, by default False
+
+        Returns
+        -------
+        Callable
+            Decorator function that registers the resolver
+
+        Examples
+        --------
+        >>> router = Router()
+        >>>
+        >>> # Basic usage
+        >>> @router.on_publish(path="/notifications/new")
+        >>> def handle_notification(payload):
+        >>>     # Process a single notification
+        >>>     return {"processed": True, "notificationId": payload.get("id")}
+        >>>
+        >>> # Aggregate mode for batch processing
+        >>> @router.on_publish(path="/notifications/batch", aggregate=True)
+        >>> def handle_batch_notifications(payload):
+        >>>     # Process multiple notifications at once
+        >>>     results = []
+        >>>     for item in payload:
+        >>>         # Process each item
+        >>>         results.append({"processed": True, "id": item.get("id")})
+        >>>     return results
+        """
+        return self._publish_registry.register(path=path, aggregate=aggregate)
+
+    def async_on_publish(
+        self,
+        path: str = DEFAULT_ROUTE,
+        aggregate: bool = False,
+    ) -> Callable:
+        """
+        Register an asynchronous resolver function for publish operations.
+
+        Parameters
+        ----------
+        path : str, optional
+            The channel path pattern to match for this resolver, by default "/default/*"
+        aggregate : bool, optional
+            Whether to process events in aggregate (batch) mode, by default False
+
+        Returns
+        -------
+        Callable
+            Decorator function that registers the async resolver
+
+        Examples
+        --------
+        >>> router = Router()
+        >>>
+        >>> # Basic async usage
+        >>> @router.async_on_publish(path="/messages/send")
+        >>> async def handle_message(event):
+        >>>     # Perform async operations
+        >>>     result = await database.save_message(event)
+        >>>     return {"saved": True, "messageId": result.id}
+        >>>
+        >>> # Aggregate mode for batch processing
+        >>> @router.async_on_publish(path="/messages/batch", aggregate=True)
+        >>> async def handle_batch_messages(events):
+        >>>     # Process multiple messages asynchronously
+        >>>     tasks = [database.save_message(e) for e in events]
+        >>>     results = await asyncio.gather(*tasks)
+        >>>     return [{"saved": True, "id": r.id} for r in results]
+        """
+        return self._async_publish_registry.register(path=path, aggregate=aggregate)
+
+    def on_subscribe(
+        self,
+        path: str = DEFAULT_ROUTE,
+    ) -> Callable:
+        """
+        Register a resolver function for subscribe operations.
+
+        Parameters
+        ----------
+        path : str, optional
+            The channel path pattern to match for this resolver, by default "/default/*"
+
+        Returns
+        -------
+        Callable
+            Decorator function that registers the resolver
+
+        Examples
+        --------
+        >>> router = Router()
+        >>>
+        >>> # Handle subscription request
+        >>> @router.on_subscribe(path="/chat/room/*")
+        >>> def authorize_subscription(event):
+        >>>     # Verify if the client can subscribe to this room
+        >>>     room_id = event.info.channel_path.split('/')[-1]
+        >>>     user_id = event.identity.username
+        >>>
+        >>>     # Check if user is allowed in this room
+        >>>     is_allowed = check_permission(user_id, room_id)
+        >>>
+        >>>     return {
+        >>>         "allowed": is_allowed,
+        >>>         "roomId": room_id
+        >>>     }
+        """
+        return self._subscribe_registry.register(path=path)
+
+    def append_context(self, **additional_context):
+        """Append key=value data as routing context"""
+        self.context.update(**additional_context)
+
+    def clear_context(self):
+        """Resets routing context"""
+        self.context.clear()

aws_lambda_powertools/event_handler/events_appsync/types.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypedDict
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class ResolverTypeDef(TypedDict):
+    """
+    Type definition for resolver dictionary
+    Parameters
+    ----------
+    func: Callable[..., Any]
+        Resolver function
+    aggregate: bool
+        Aggregation flag or method
+    """
+
+    func: Callable[..., Any]
+    aggregate: bool

aws_lambda_powertools/event_handler/exception_handling.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Mapping
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class ExceptionHandlerManager:
+    """
+    A class to manage exception handlers for different exception types.
+    This class allows registering handler functions for specific exception types
+    and looking up the appropriate handler when an exception occurs.
+    Example usage:
+    -------------
+    handler_manager = ExceptionHandlerManager()
+    @handler_manager.exception_handler(ValueError)
+    def handle_value_error(e):
+        print(f"Handling ValueError: {e}")
+        return "Error handled"
+    # To handle multiple exception types with the same handler:
+    @handler_manager.exception_handler([KeyError, TypeError])
+    def handle_multiple_errors(e):
+        print(f"Handling {type(e).__name__}: {e}")
+        return "Multiple error types handled"
+    # To find and execute a handler:
+    try:
+        # some code that might raise an exception
+        raise ValueError("Invalid value")
+    except Exception as e:
+        handler = handler_manager.lookup_exception_handler(type(e))
+        if handler:
+            result = handler(e)
+    """
+
+    def __init__(self):
+        """Initialize an empty dictionary to store exception handlers."""
+        self._exception_handlers: dict[type[Exception], Callable] = {}
+
+    def exception_handler(self, exc_class: type[Exception] | list[type[Exception]]):
+        """
+        A decorator function that registers a handler for one or more exception types.
+        Parameters
+        ----------
+        exc_class : type[Exception] | list[type[Exception]]
+            A single exception type or a list of exception types.
+        Returns
+        -------
+        Callable
+            A decorator function that registers the exception handler.
+        """
+
+        def register_exception_handler(func: Callable):
+            if isinstance(exc_class, list):
+                for exp in exc_class:
+                    self._exception_handlers[exp] = func
+            else:
+                self._exception_handlers[exc_class] = func
+            return func
+
+        return register_exception_handler
+
+    def lookup_exception_handler(self, exp_type: type) -> Callable | None:
+        """
+        Looks up the registered exception handler for the given exception type or its base classes.
+        Parameters
+        ----------
+        exp_type : type
+            The exception type to look up the handler for.
+        Returns
+        -------
+        Callable | None
+            The registered exception handler function if found, otherwise None.
+        """
+        for cls in exp_type.__mro__:
+            if cls in self._exception_handlers:
+                return self._exception_handlers[cls]
+        return None
+
+    def update_exception_handlers(self, handlers: Mapping[type[Exception], Callable]) -> None:
+        """
+        Updates the exception handlers dictionary with new handler mappings.
+        This method allows bulk updates of exception handlers by providing a dictionary
+        mapping exception types to handler functions.
+        Parameters
+        ----------
+        handlers : Mapping[Type[Exception], Callable]
+            A dictionary mapping exception types to handler functions.
+        Example
+        -------
+        >>> def handle_value_error(e):
+        ...     print(f"Value error: {e}")
+        ...
+        >>> def handle_key_error(e):
+        ...     print(f"Key error: {e}")
+        ...
+        >>> handler_manager.update_exception_handlers({
+        ...     ValueError: handle_value_error,
+        ...     KeyError: handle_key_error
+        ... })
+        """
+        self._exception_handlers.update(handlers)
+
+    def get_registered_handlers(self) -> dict[type[Exception], Callable]:
+        """
+        Returns all registered exception handlers.
+        Returns
+        -------
+        Dict[Type[Exception], Callable]
+            A dictionary mapping exception types to their handler functions.
+        """
+        return self._exception_handlers.copy()
+
+    def clear_handlers(self) -> None:
+        """
+        Clears all registered exception handlers.
+        """
+        self._exception_handlers.clear()

aws_lambda_powertools/shared/version.py

@@ -1,3 +1,3 @@
 """Exposes version constant to avoid circular dependencies."""
 
-VERSION = "3.10.1a10"
+VERSION = "3.11.0"

aws_lambda_powertools/utilities/data_classes/__init__.py

@@ -6,6 +6,7 @@ from .alb_event import ALBEvent
 from .api_gateway_proxy_event import APIGatewayProxyEvent, APIGatewayProxyEventV2
 from .api_gateway_websocket_event import APIGatewayWebSocketEvent
 from .appsync_resolver_event import AppSyncResolverEvent
+from .appsync_resolver_events_event import AppSyncResolverEventsEvent
 from .aws_config_rule_event import AWSConfigRuleEvent
 from .bedrock_agent_event import BedrockAgentEvent
 from .cloud_watch_alarm_event import (
@@ -55,6 +56,7 @@ __all__ = [
     "APIGatewayWebSocketEvent",
     "SecretsManagerEvent",
     "AppSyncResolverEvent",
+    "AppSyncResolverEventsEvent",
     "ALBEvent",
     "BedrockAgentEvent",
     "CloudWatchAlarmData",

aws_lambda_powertools/utilities/data_classes/appsync_resolver_event.py

@@ -26,6 +26,46 @@ def get_identity_object(identity: dict | None) -> Any:
     return AppSyncIdentityIAM(identity)
 
 
+class AppSyncEventBase(DictWrapper):
+    """AppSync resolver event base to work with AppSync GraphQL + Events"""
+
+    @property
+    def request_headers(self) -> dict[str, str]:
+        """Request headers"""
+        return CaseInsensitiveDict(self["request"]["headers"])
+
+    @property
+    def domain_name(self) -> str | None:
+        """The domain name when using custom domain"""
+        return self["request"].get("domainName")
+
+    @property
+    def prev_result(self) -> dict[str, Any] | None:
+        """It represents the result of whatever previous operation was executed in a pipeline resolver."""
+        prev = self.get("prev")
+        return prev.get("result") if prev else None
+
+    @property
+    def stash(self) -> dict:
+        """The stash is a map that is made available inside each resolver and function mapping template.
+        The same stash instance lives through a single resolver execution. This means that you can use the
+        stash to pass arbitrary data across request and response mapping templates, and across functions in
+        a pipeline resolver."""
+        return self.get("stash") or {}
+
+    @property
+    def identity(self) -> AppSyncIdentityIAM | AppSyncIdentityCognito | None:
+        """An object that contains information about the caller.
+        Depending on the type of identify found:
+        - API_KEY authorization - returns None
+        - AWS_IAM authorization - returns AppSyncIdentityIAM
+        - AMAZON_COGNITO_USER_POOLS authorization - returns AppSyncIdentityCognito
+        - AWS_LAMBDA authorization - returns None - NEED TO TEST
+        - OPENID_CONNECT authorization - returns None - NEED TO TEST
+        """
+        return get_identity_object(self.get("identity"))
+
+
 class AppSyncIdentityIAM(DictWrapper):
     """AWS_IAM authorization"""
 
@@ -141,7 +181,7 @@ class AppSyncResolverEventInfo(DictWrapper):
         return self.get("selectionSetGraphQL")
 
 
-class AppSyncResolverEvent(DictWrapper):
+class AppSyncResolverEvent(AppSyncEventBase):
     """AppSync resolver event
 
     **NOTE:** AppSync Resolver Events can come in various shapes this data class
@@ -178,49 +218,16 @@ class AppSyncResolverEvent(DictWrapper):
         """A map that contains all GraphQL arguments for this field."""
         return self["arguments"]
 
-    @property
-    def identity(self) -> AppSyncIdentityIAM | AppSyncIdentityCognito | None:
-        """An object that contains information about the caller.
-
-        Depending on the type of identify found:
-
-        - API_KEY authorization - returns None
-        - AWS_IAM authorization - returns AppSyncIdentityIAM
-        - AMAZON_COGNITO_USER_POOLS authorization - returns AppSyncIdentityCognito
-        """
-        return get_identity_object(self.get("identity"))
-
     @property
     def source(self) -> dict[str, Any]:
         """A map that contains the resolution of the parent field."""
         return self.get("source") or {}
 
-    @property
-    def request_headers(self) -> dict[str, str]:
-        """Request headers"""
-        return CaseInsensitiveDict(self["request"]["headers"])
-
-    @property
-    def prev_result(self) -> dict[str, Any] | None:
-        """It represents the result of whatever previous operation was executed in a pipeline resolver."""
-        prev = self.get("prev")
-        if not prev:
-            return None
-        return prev.get("result")
-
     @property
     def info(self) -> AppSyncResolverEventInfo:
         """The info section contains information about the GraphQL request."""
         return self._info
 
-    @property
-    def stash(self) -> dict:
-        """The stash is a map that is made available inside each resolver and function mapping template.
-        The same stash instance lives through a single resolver execution. This means that you can use the
-        stash to pass arbitrary data across request and response mapping templates, and across functions in
-        a pipeline resolver."""
-        return self.get("stash") or {}
-
     @overload
     def get_header_value(
         self,