Merge branch 'develop' into fix-api-docs-parser

Author: Michael Brewer

Diff for: aws_lambda_powertools/event_handler/api_gateway.py

@@ -525,10 +525,10 @@ def _resolve(self) -> ResponseBuilder:
         for route in self._routes:
             if method != route.method:
                 continue
-            match: Optional[re.Match] = route.rule.match(path)
-            if match:
+            match_results: Optional[re.Match] = route.rule.match(path)
+            if match_results:
                 logger.debug("Found a registered route. Calling function")
-                return self._call_route(route, match.groupdict())  # pass fn args
+                return self._call_route(route, match_results.groupdict())  # pass fn args
 
         logger.debug(f"No match found for path {path} and method {method}")
         return self._not_found(method)

Diff for: aws_lambda_powertools/exceptions/__init__.py

@@ -0,0 +1,5 @@
+"""Shared exceptions that don't belong to a single utility"""
+
+
+class InvalidEnvelopeExpressionError(Exception):
+    """When JMESPath fails to parse expression"""

Diff for: aws_lambda_powertools/logging/correlation_paths.py

@@ -2,6 +2,7 @@
 
 API_GATEWAY_REST = "requestContext.requestId"
 API_GATEWAY_HTTP = API_GATEWAY_REST
+APPSYNC_AUTHORIZER = "requestContext.requestId"
 APPSYNC_RESOLVER = 'request.headers."x-amzn-trace-id"'
 APPLICATION_LOAD_BALANCER = 'headers."x-amzn-trace-id"'
 EVENT_BRIDGE = "id"

Diff for: aws_lambda_powertools/shared/jmespath_utils.py

@@ -1,13 +1,15 @@
 import base64
 import gzip
 import json
+import logging
 from typing import Any, Dict, Optional, Union
 
 import jmespath
 from jmespath.exceptions import LexerError
 
-from aws_lambda_powertools.utilities.validation import InvalidEnvelopeExpressionError
-from aws_lambda_powertools.utilities.validation.base import logger
+from aws_lambda_powertools.exceptions import InvalidEnvelopeExpressionError
+
+logger = logging.getLogger(__name__)
 
 
 class PowertoolsFunctions(jmespath.functions.Functions):
@@ -27,7 +29,7 @@ def _func_powertools_base64_gzip(self, value):
         return uncompressed.decode()
 
 
-def unwrap_event_from_envelope(data: Union[Dict, str], envelope: str, jmespath_options: Optional[Dict]) -> Any:
+def extract_data_from_envelope(data: Union[Dict, str], envelope: str, jmespath_options: Optional[Dict]) -> Any:
     """Searches data using JMESPath expression
 
     Parameters

Diff for: aws_lambda_powertools/utilities/data_classes/appsync_authorizer_event.py

@@ -0,0 +1,116 @@
+from typing import Any, Dict, List, Optional
+
+from aws_lambda_powertools.utilities.data_classes.common import DictWrapper
+
+
+class AppSyncAuthorizerEventRequestContext(DictWrapper):
+    """Request context"""
+
+    @property
+    def api_id(self) -> str:
+        """AppSync API ID"""
+        return self["requestContext"]["apiId"]
+
+    @property
+    def account_id(self) -> str:
+        """AWS Account ID"""
+        return self["requestContext"]["accountId"]
+
+    @property
+    def request_id(self) -> str:
+        """Requestt ID"""
+        return self["requestContext"]["requestId"]
+
+    @property
+    def query_string(self) -> str:
+        """GraphQL query string"""
+        return self["requestContext"]["queryString"]
+
+    @property
+    def operation_name(self) -> Optional[str]:
+        """GraphQL operation name, optional"""
+        return self["requestContext"].get("operationName")
+
+    @property
+    def variables(self) -> Dict:
+        """GraphQL variables"""
+        return self["requestContext"]["variables"]
+
+
+class AppSyncAuthorizerEvent(DictWrapper):
+    """AppSync lambda authorizer event
+
+    Documentation:
+    -------------
+    - https://aws.amazon.com/blogs/mobile/appsync-lambda-auth/
+    - https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html#aws-lambda-authorization
+    - https://docs.amplify.aws/lib/graphqlapi/authz/q/platform/js#aws-lambda
+    """
+
+    @property
+    def authorization_token(self) -> str:
+        """Authorization token"""
+        return self["authorizationToken"]
+
+    @property
+    def request_context(self) -> AppSyncAuthorizerEventRequestContext:
+        """Request context"""
+        return AppSyncAuthorizerEventRequestContext(self._data)
+
+
+class AppSyncAuthorizerResponse:
+    """AppSync Lambda authorizer response helper
+
+    Parameters
+    ----------
+    authorize: bool
+        authorize is a boolean value indicating if the value in authorizationToken
+        is authorized to make calls to the GraphQL API. If this value is
+        true, execution of the GraphQL API continues. If this value is false,
+        an UnauthorizedException is raised
+    max_age: int, optional
+        Set the ttlOverride. The number of seconds that the response should be
+        cached for. If no value is returned, the value from the API (if configured)
+        or the default of 300 seconds (five minutes) is used. If this is 0, the response
+        is not cached.
+    resolver_context: Dict[str, Any], optional
+        A JSON object visible as `$ctx.identity.resolverContext` in resolver templates
+
+        The resolverContext object only supports key-value pairs. Nested keys are not supported.
+
+        Warning: The total size of this JSON object must not exceed 5MB.
+    deny_fields: List[str], optional
+        A list of fields that will be set to `null` regardless of the resolver's return.
+
+        A field is either `TypeName.FieldName`, or an ARN such as
+        `arn:aws:appsync:us-east-1:111122223333:apis/GraphQLApiId/types/TypeName/fields/FieldName`
+
+        Use the full ARN for correctness when sharing a Lambda function authorizer between APIs.
+    """
+
+    def __init__(
+        self,
+        authorize: bool = False,
+        max_age: Optional[int] = None,
+        resolver_context: Optional[Dict[str, Any]] = None,
+        deny_fields: Optional[List[str]] = None,
+    ):
+        self.authorize = authorize
+        self.max_age = max_age
+        self.deny_fields = deny_fields
+        self.resolver_context = resolver_context
+
+    def asdict(self) -> dict:
+        """Return the response as a dict"""
+        response: Dict = {"isAuthorized": self.authorize}
+
+        if self.max_age is not None:
+            response["ttlOverride"] = self.max_age
+
+        if self.deny_fields:
+            response["deniedFields"] = self.deny_fields
+
+        if self.resolver_context:
+            response["resolverContext"] = self.resolver_context
+
+        return response

Diff for: aws_lambda_powertools/utilities/feature_flags/appconfig.py

@@ -80,7 +80,7 @@ def get_configuration(self) -> Dict[str, Any]:
             )
 
             if self.envelope:
-                config = jmespath_utils.unwrap_event_from_envelope(
+                config = jmespath_utils.extract_data_from_envelope(
                     data=config, envelope=self.envelope, jmespath_options=self.jmespath_options
                 )
 

Diff for: aws_lambda_powertools/utilities/validation/exceptions.py

@@ -1,3 +1,6 @@
+from ...exceptions import InvalidEnvelopeExpressionError
+
+
 class SchemaValidationError(Exception):
     """When serialization fail schema validation"""
 
@@ -6,5 +9,4 @@ class InvalidSchemaFormatError(Exception):
     """When JSON Schema is in invalid format"""
 
 
-class InvalidEnvelopeExpressionError(Exception):
-    """When JMESPath fails to parse expression"""
+__all__ = ["SchemaValidationError", "InvalidSchemaFormatError", "InvalidEnvelopeExpressionError"]

Diff for: aws_lambda_powertools/utilities/validation/validator.py

@@ -117,7 +117,7 @@ def handler(event, context):
         When JMESPath expression to unwrap event is invalid
     """
     if envelope:
-        event = jmespath_utils.unwrap_event_from_envelope(
+        event = jmespath_utils.extract_data_from_envelope(
             data=event, envelope=envelope, jmespath_options=jmespath_options
         )
 
@@ -219,7 +219,7 @@ def handler(event, context):
         When JMESPath expression to unwrap event is invalid
     """
     if envelope:
-        event = jmespath_utils.unwrap_event_from_envelope(
+        event = jmespath_utils.extract_data_from_envelope(
             data=event, envelope=envelope, jmespath_options=jmespath_options
         )
 

Diff for: docs/utilities/data_classes.md

@@ -63,6 +63,7 @@ Event Source | Data_class
 [API Gateway Proxy V2](#api-gateway-proxy-v2) | `APIGatewayProxyEventV2`
 [Application Load Balancer](#application-load-balancer) | `ALBEvent`
 [AppSync Resolver](#appsync-resolver) | `AppSyncResolverEvent`
+[AppSync Authorizer](#appsync-authorizer) | `AppSyncAuthorizerEvent`
 [CloudWatch Logs](#cloudwatch-logs) | `CloudWatchLogsEvent`
 [CodePipeline Job Event](#codepipeline-job) | `CodePipelineJobEvent`
 [Cognito User Pool](#cognito-user-pool) | Multiple available under `cognito_user_pool_event`
@@ -128,6 +129,53 @@ Is it used for Application load balancer event.
             do_something_with(event.json_body, event.query_string_parameters)
     ```
 
+## AppSync Authorizer
+
+> New in 1.20.0
+
+Used when building an [AWS_LAMBDA Authorization](https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html#aws-lambda-authorization){target="_blank"} with AppSync.
+See blog post [Introducing Lambda authorization for AWS AppSync GraphQL APIs](https://aws.amazon.com/blogs/mobile/appsync-lambda-auth/){target="_blank"}
+or read the Amplify documentation on using [AWS Lambda for authorization](https://docs.amplify.aws/lib/graphqlapi/authz/q/platform/js#aws-lambda){target="_blank"} with AppSync.
+
+In this example extract the `requestId` as the `correlation_id` for logging, used `@event_source` decorator and builds the AppSync authorizer using the `AppSyncAuthorizerResponse` helper.
+
+=== "app.py"
+
+    ```python
+    from typing import Dict
+
+    from aws_lambda_powertools.logging import correlation_paths
+    from aws_lambda_powertools.logging.logger import Logger
+    from aws_lambda_powertools.utilities.data_classes.appsync_authorizer_event import (
+        AppSyncAuthorizerEvent,
+        AppSyncAuthorizerResponse,
+    )
+    from aws_lambda_powertools.utilities.data_classes.event_source import event_source
+
+    logger = Logger()
+
+
+    def get_user_by_token(token: str):
+        """Look a user by token"""
+
+
+    @logger.inject_lambda_context(correlation_id_path=correlation_paths.APPSYNC_AUTHORIZER)
+    @event_source(data_class=AppSyncAuthorizerEvent)
+    def lambda_handler(event: AppSyncAuthorizerEvent, context) -> Dict:
+        user = get_user_by_token(event.authorization_token)
+
+        if not user:
+            # No user found, return not authorized
+            return AppSyncAuthorizerResponse().to_dict()
+
+        return AppSyncAuthorizerResponse(
+            authorize=True,
+            resolver_context={"id": user.id},
+            # Only allow admins to delete events
+            deny_fields=None if user.is_admin else ["Mutation.deleteEvent"],
+        ).asdict()
+    ```
+
 ### AppSync Resolver
 
 > New in 1.12.0

Diff for: poetry.lock

@@ -34,7 +34,7 @@ black = "^20.8b1"
 flake8 = "^3.9.0"
 flake8-black = "^0.2.3"
 flake8-builtins = "^1.5.3"
-flake8-comprehensions = "^3.6.0"
+flake8-comprehensions = "^3.6.1"
 flake8-debugger = "^4.0.0"
 flake8-fixme = "^1.1.1"
 flake8-isort = "^4.0.0"
@@ -60,7 +60,7 @@ pydantic = ["pydantic", "email-validator"]
 
 [tool.coverage.run]
 source = ["aws_lambda_powertools"]
-omit = ["tests/*"]
+omit = ["tests/*", "aws_lambda_powertools/exceptions/*"]
 branch = true
 
 [tool.coverage.html]

Diff for: pyproject.toml

@@ -0,0 +1,13 @@
+{
+    "authorizationToken": "BE9DC5E3-D410-4733-AF76-70178092E681",
+    "requestContext": {
+        "apiId": "giy7kumfmvcqvbedntjwjvagii",
+        "accountId": "254688921111",
+        "requestId": "b80ed838-14c6-4500-b4c3-b694c7bef086",
+        "queryString": "mutation MyNewTask($desc: String!) {\n  createTask(description: $desc, owner: \"ccc\", taskStatus: \"cc\", title: \"ccc\") {\n    id\n  }\n}\n",
+        "operationName": "MyNewTask",
+        "variables": {
+            "desc": "Foo"
+        }
+    }
+}

Diff for: tests/events/appSyncAuthorizerEvent.json

@@ -0,0 +1,9 @@
+{
+    "isAuthorized": true,
+    "resolverContext": {
+        "name": "Foo Man",
+        "balance": 100
+    },
+    "deniedFields": ["Mutation.createEvent"],
+    "ttlOverride": 15
+}