fastapi-aws 0.0.7__py3-none-any.whl

fastapi_aws/integrations.py

@@ -0,0 +1,306 @@
+from typing import Any, Dict, List
+import json
+
+
+from .route import register_integration
+
+
+@register_integration("mock")
+def mock_integration(
+    uri: str, iam_arn: str, path_parameters: List[str], **kwargs
+) -> Dict[str, Any]:
+    """returns a mock integration which has a fixed response value
+    NB: this function should take parameters for the fixed responses.
+    NB: this can currently be used for a 'not implemented' response.
+    """
+    return dict(
+        uri="",
+        integration_type="mock",
+        request_template={"statusCode": 200},
+        responses={
+            "default": {
+                "statusCode": 501,
+                "responseTemplates": {
+                    "application/json": json.dumps({"status": "not implemented"})
+                },
+            }
+        },
+    )
+
+
+@register_integration("aws_lambda_uri")
+def lambda_integration(
+    uri: str,
+    iam_arn: str,
+    integration_type="aws_proxy",
+    path_parameters: List[str] = None,
+    request_template: str = None,
+    **kwargs,
+) -> Dict[str, Any]:
+    """returns an aws integration description for calling lambdas from apigw.
+
+    NB: this return value includes strings relating to resource arns in terraform,
+        so the apigw deployment must load this function output and replace these placeholders.
+
+    The return value should look like:
+        "x-amazon-apigateway-integration": {
+            "uri": "${lambda_function_arn}",
+            "httpMethod": "POST",
+            "type": "aws",
+            "credentials": "${lambda_function_iam_arn}",
+            "requestTemplates": {
+                "application/json": json.dumps({
+                    "body": "$input.json('$')",
+                    "httpMethod": "POST",
+                    "resource": "/",
+                    "path": "/"
+                })
+            }
+        }
+      There is also a "responses" key which we should set to reformat the output, but do not yet.
+      The optional "path_parameters" parameter is a list of variable path elements
+      which are added to the requestTemplate:
+        "application/json": json.dumps({
+            "body": "$input.json('$')",
+            "httpMethod": "POST",
+            "resource": "/",
+            "path": "/"
+            "pathParameters": {...}
+        })
+
+      MB: the format of this pathParameters string is important, see the code for details
+
+      NB: use "type": "aws" to pass request.body directory, or "aws_proxy" to get request context
+    """
+    if path_parameters:
+        if not isinstance(path_parameters, list):
+            raise ValueError("path_parameters must be a list of strings")
+
+        request_parameters = {
+            "integration.request.path.%s" % k: "method.request.path.%s" % k
+            for k in path_parameters
+        }
+    else:
+        request_parameters = None
+
+    if request_template:
+        request_template = {"application/json": request_template}
+
+    responses = {"default": {"statusCode": "200"}}
+
+    return dict(
+        uri=uri,
+        integration_type=integration_type,
+        http_method="POST",
+        credentials=iam_arn,
+        request_template=request_template,
+        request_parameters=request_parameters,
+        responses=responses,
+    )
+
+
+def step_function_integration_base(
+    uri: str,
+    sfn_arn: str,
+    iam_arn: str,
+    mapping_template: Dict[str, str],
+) -> Dict[str, Any]:
+    """returns an aws integration for sync invocation of a step function from apigw.
+
+    NB: the input to the step function is always the json serialized body object.
+        we not **not** pass through any path parameters at the moment.
+
+    NB: this return value includes strings relating to resource arns in terraform,
+        so the apigw deployment must load this function output and replace these placeholders.
+
+    The return value should look like:
+        "x-amazon-apigateway-integration": {
+            "uri": "arn:aws:apigateway:${region}:states:action/StartSyncExecution",
+            "httpMethod": "POST",
+            "type": "aws",
+            "credentials": "${sfn_invoke_iam_role_arn}",
+            "requestTemplates": {
+                "application/json": json.dumps({
+                    "input": "$util.escapeJavaScript($input.json(\'$\'))",
+                    "stateMachineArn": "${step_function_arn}",
+                    "region": "${region}"
+                })
+            },
+            "responses": {
+                "default": {
+                    "statusCode": "200",
+                    "responseTemplates": {
+                        "application/json": "#set($output = $util.parseJson($input.path('$.output')))\n$output.body"
+                    },
+                }
+            },
+        }
+    },
+    NB: the format of this pathParameters string is important, see the code for details
+    """
+    if mapping_template is None:
+        mapping_template = "$input.json('$')"
+    elif isinstance(mapping_template, dict):
+        mapping_template = json.dumps(mapping_template)
+
+    request_template = {
+        "application/json": json.dumps(
+            {
+                "input": mapping_template,
+                "stateMachineArn": sfn_arn,
+                "region": "${region}",
+            }
+        )
+    }
+
+    # FIXME: take response templates as parameters so we can handle errors nicely.
+    responses = {
+        "default": {
+            "statusCode": "200",
+            "responseTemplates": {
+                "application/json": "#set($output = $util.parseJson($input.path('$.output')))\n$output.body"
+            },
+        }
+    }
+
+    return dict(
+        uri=uri,
+        integration_type="aws",
+        http_method="POST",
+        credentials=iam_arn,
+        request_template=request_template,
+        responses=responses,
+    )
+
+
+@register_integration("aws_sfn_sync_arn")
+def step_function_sync_integration(
+    sfn_arn: str,
+    iam_arn: str,
+    path_parameters: List[str] = None,
+    mapping_template: dict = None,
+    **kwargs,
+) -> Dict[str, Any]:
+    """returns an aws integration for sync invocation of a step function from apigw."""
+
+    return step_function_integration_base(
+        "arn:aws:apigateway:${region}:states:action/StartSyncExecution",
+        sfn_arn,
+        iam_arn,
+        mapping_template,
+    )
+
+
+@register_integration("aws_sfn_arn")
+def step_function_integration(
+    sfn_arn: str,
+    iam_arn: str,
+    path_parameters: List[str] = None,
+    mapping_template: dict = None,
+    **kwargs,
+) -> Dict[str, Any]:
+    return step_function_integration_base(
+        "arn:aws:apigateway:${region}:states:action/StartExecution",
+        sfn_arn,
+        iam_arn,
+        mapping_template,
+    )
+
+
+@register_integration("aws_s3_bucket")
+def s3_integration(
+    bucket_name: str,
+    iam_arn: str,
+    path_parameters: List[str] = None,
+    http_method: str = "GET",
+    object_key: str = None,
+    **kwargs,
+) -> Dict[str, Any]:
+    """
+    Returns an AWS integration for S3 from API Gateway.
+
+    This allows API Gateway to interact with S3 objects via HTTP methods.
+
+    :param bucket_name: Name of the S3 bucket.
+    :param iam_arn: IAM role ARN to assume for the integration.
+    :param path_parameters: list of path parameters in the apigw request path; if `object_key` is None, the last value here is used as as the object key to lookup
+    :param http_method: HTTP method (GET, PUT, DELETE) to use for the integration.
+    :param object_key: [optional] fixed object key to return from the bucket
+
+    # TODO: path_parameters could be merged to allow multiple names
+    # TODO: object_key_prefix: allow a key prefix to be used for accessing objects by path parameter
+
+    Example OpenAPI integration:
+
+    "x-amazon-apigateway-integration": {
+        "uri": "arn:aws:apigateway:${region}:s3:path/{bucket}/{key}",
+        "httpMethod": "GET",
+        "type": "aws",
+        "credentials": "${iam_role_arn}",
+        "requestParameters": {
+            "integration.request.path.bucket": "bucket_name",
+            "integration.request.path.key": "method.request.path.key"
+        },
+        "responses": {
+            "default": {
+                "statusCode": "200",
+                "responseParameters": {
+                    "method.response.header.Content-Type": "'application/octet-stream'"
+                }
+            }
+        }
+    }
+    """
+    assert http_method in (
+        "GET",
+        "PUT",
+        "DELETE",
+    ), "Invalid HTTP method for S3 integration"
+
+    # define the S3 integration URI using API Gateway's S3 service
+    # uri = f"arn:aws:apigateway:${{region}}:s3:path/{bucket_name}/{{key}}"
+    # FIXME: add the key parameter here to specify an object; but where should the value coem from?
+    #        path_parameters? kwargs?
+    # NB: i think uri should be the bucket arn
+    uri = f"arn:aws:apigateway:${{region}}:s3:path/{bucket_name}"
+
+    if object_key:
+        uri = "/".join((uri, object_key))
+    elif path_parameters:
+        uri = "/".join([uri] + path_parameters)
+    else:
+        raise ValueError("expected one of: 'object_key', 'path_parameters'")
+
+    # apigw request parameters mapping
+    request_parameters = kwargs.get("request_parameters")
+
+    # response mapping (simple passthrough)
+    # FIXME: take the integration response content type to get the object content type
+    default_response_parameters = {
+        "default": {
+            "statusCode": "200",
+            #            "responseParameters": {
+            #                "method.response.header.Content-Type": "integration.response.header.Content-Type"
+            #            },
+        },
+        "4xx": {"statusCode": "404"},
+        "403": {"statusCode": "404"},
+        "404": {"statusCode": "404"},
+    }
+
+    responses = kwargs.get("responses") or default_response_parameters
+
+    # generate apigw integration config
+    integration = dict(
+        uri=uri,
+        http_method=http_method,
+        integration_type="aws",
+        credentials=iam_arn,
+        request_parameters=request_parameters,
+        responses=responses,
+    )
+
+    if request_parameters:
+        integration["request_parameters"] = request_parameters
+
+    return integration

fastapi_aws/models.py

@@ -0,0 +1,57 @@
+"""Pydantic models for the AWS API integration validation
+"""
+class IntegrationType(str, Enum):
+    AWS_PROXY = "aws_proxy"
+    AWS = "aws"
+    MOCK = "mock"
+
+
+class Integration(BaseModel):
+    """Baseclass for defining integrations
+    TODO: build the integrations with classes and then export to dict.
+    """
+
+    type: IntegrationType
+    requestTemplates: Dict[str, Any]
+    responses: Dict[str, Any]
+
+    def model_dump(self) -> Dict[str, Any]:
+        return {"x-amazon-apigateway-integration": super().model_dump()}
+
+
+class LambdaJSONRequestTemplate(BaseModel):
+    body: str
+    httpMethod: str = "POST"
+    resource: str = "/"
+    path: str = "/"
+    pathParameters: Optional[Dict[str, str]] = None
+
+
+class MockIntegration(Integration):
+    type: IntegrationType = IntegrationType.MOCK
+
+
+class ServiceIntegration(Integration):
+    uri: str = Field(..., description="arn of the called resource")
+    credentials: str = Field(..., description="arn of the IAM used to invoke the resource")
+    httpMethod: str = "POST"
+
+
+class LambdaIntegration(ServiceIntegration):
+    type: IntegrationType = IntegrationType.AWS_PROXY
+    # uri must be lambda arn
+
+
+class StepFunctionIntegration(ServiceIntegration):
+    type: IntegrationType = IntegrationType.AWS
+    # uri: "arn:aws:apigateway:${region}:states:action/StartSyncExecution"
+
+
+class NotImplementedIntegration(MockIntegration):
+    requestTemplates: Dict[str, Any] = {"application/json": {"statusCode": 200}}
+    responses: Dict[str, Any] = {
+        "default": {
+            "statusCode": "200",
+            "responseTemplates": {"application/json": '{"status": "not implemented"}'},
+        }
+    }

fastapi_aws/route.py

@@ -0,0 +1,191 @@
+from fastapi.routing import APIRoute
+from typing import Any, Callable, List
+from string import Formatter
+
+
+def register_integration(service_name: str):
+    """Decorator to register integration methods dynamically in AWSAPIRoute"""
+
+    def decorator(func):
+        if not hasattr(AWSAPIRoute, "_integration_registry"):
+            AWSAPIRoute._integration_registry = {}
+        AWSAPIRoute._integration_registry[service_name] = func
+        return func
+
+    return decorator
+
+
+class AWSAPIRoute(APIRoute):
+    """fastapi.apiroute derived class adapted for aws service integrations
+    This will provide an openapi json description of an aws service integration
+    for a route, allowing the openapi spec to be uploaded as an aws apigw rest
+    service automativicly.
+    """
+
+    _integration_registry = {}  # registered service integrations
+
+    def __init__(self, path: str, endpoint: Callable[..., Any], **kwargs: Any):
+        """overload the APIRoute constructor
+
+        This has to happen because we cannot just pass kwargs around fastapi.
+        Probably for code highlighting or smth but the internal fastapi include_router
+        functions copy objects by explicity listing all the fields of the objects, so
+        our derived class cannot have custom fields and use the app or router functions.
+
+        Futhermore, the super-constructor removes or resets fields when it is called.
+
+        very frustrating, up yours fastapi
+        """
+        # validate the route args contain an aws service entry for which we have an integration
+        # and an entry for 'aws_iam_arn' for permission to call that service.
+        selected_services = set(self._integration_registry).intersection(set(kwargs))
+
+        if not selected_services:
+            # no aws integration in this route, so just call super
+            return super().__init__(path, endpoint, **kwargs)
+
+        if len(selected_services) > 1:
+            raise ValueError(
+                f"Exactly one of {self._integration_registry.keys()} is required, but found {selected_services} in {kwargs.keys()}"
+            )
+
+        # pop the params from the kwargs to stop fastapi spazzing out
+        aws_service_name = selected_services.pop()
+        aws_service_value = kwargs.pop(aws_service_name)
+        aws_object_key = kwargs.pop("aws_object_key", None)
+
+        aws_iam_arn = kwargs.pop("aws_iam_arn", None)
+        if not aws_iam_arn:
+            raise ValueError("'aws_iam_arn' is required for AWS integrations.")
+
+        # extract the path parmaeters
+        if hasattr(self, "path_format"):
+            path_parameters = self._extract_path_parameters(self.path_format)
+        else:
+            path_parameters = []
+
+        # extract the mapping templates if present
+        aws_request_template = kwargs.pop("request_template", None)
+        aws_request_parameters = kwargs.pop("request_parameters", None)
+        aws_mapping_template = kwargs.pop("aws_mapping_template", None)
+        aws_response_template = kwargs.pop("response_template", None)
+
+        # this is hack because fastapi does explict member copies resulting in duplicate
+        # objects rather than copy-by-reference (which i expect).
+        self.openapi_extra = kwargs.pop("openapi_extra", {})
+
+        # APIRoute clears openapi_extra here if it is set, so preseve it before calling the super constructor
+        if "x-amazon-apigateway-integration" in self.openapi_extra:
+            integration = self.openapi_extra
+        else:
+            integration = None
+
+        super().__init__(path, endpoint, **kwargs)
+
+        # if we already have the x-int, it has been copied over the super constructor
+        # so do not build a new integration
+        if not integration:
+            # find the integration which matches one of our kwargs
+            integration_fn = self._integration_registry[aws_service_name]
+
+            integration_params = integration_fn(
+                aws_service_value,
+                iam_arn=aws_iam_arn,
+                path_parameters=path_parameters,
+                mapping_template=aws_mapping_template,
+                request_template=aws_request_template,
+                request_parameters=aws_request_parameters,
+                response_template=aws_response_template,
+                object_key=aws_object_key,  # NB: s3 only
+                http_method="GET" if "GET" in self.methods else next(iter(self.methods)),
+            )
+
+            integration = self._create_integration(**integration_params)
+
+        if self.openapi_extra is None:
+            self.openapi_extra = {}
+
+        self.openapi_extra.update(integration)
+
+    @staticmethod
+    def _extract_path_parameters(path: str) -> List[str]:
+        formatter = Formatter()
+        return [fname for _, fname, _, _ in formatter.parse(path) if fname]
+
+    def _create_integration(
+        self,
+        uri: str,
+        integration_type: str,
+        credentials: str,
+        responses: dict = None,
+        request_template: dict = None,
+        request_parameters: dict = None,
+        http_method: str = "POST",
+    ):
+        """create the x-amazon-apigateway-integration block for the openapi spec
+
+        This block defines how a request is made to the backend function so is always a POST request
+
+        NB: uri is not required for mock integrations, so it should be optional
+
+        request_template must be a dict of mimetype->string
+        request_parameters map request (HTTP) to integration parameter
+        responses is a dict of integration response patterns (key) to output transform
+
+        see:
+        + general: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html
+        + request_templates: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration-requestTemplates.html
+        + request_parameters: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration-requestParameters.html
+        + responses: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration-response.html
+        """
+        assert integration_type in ("aws", "aws_proxy")
+
+        assert isinstance(responses, dict), "responses must be a dict [%s]" % str(
+            type(responses)
+        )
+        assert (
+            "default" in responses
+        ), "expected 'default' in responses (recieved: '%s')" % str(
+            list(responses.keys())
+        )
+
+        integration = {
+            "uri": uri,
+            "httpMethod": http_method,
+            "type": integration_type,
+            "credentials": credentials,
+            "responses": responses,
+        }
+
+        if request_template is not None:
+            # request templates must be a dict of mimetypes to strings
+            # https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration-requestTemplates.html
+            assert isinstance(
+                request_template, dict
+            ), "request_template must be dict [%s]" % (str(type(request_template)))
+
+            request_template_mimetypes = ("application/json", "application/xml")
+            assert all(
+                x_ in request_template_mimetypes for x_ in request_template
+            ), "only mimetypes are expected in request_templates (found: '%s')" % str(
+                list(request_template.keys())
+            )
+            assert all(
+                isinstance(x_, str) for x_ in request_template
+            ), "all request templates must be strings (found: '%s')" % (
+                str([str(type(x)) for x in request_template.values()])
+            )
+
+            integration["requestTemplates"] = request_template
+
+        if request_parameters is not None:
+            # TODO: validate against: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration-requestParameters.html
+            assert isinstance(
+                request_parameters, dict
+            ), "request_parameters must be dict [%s]" % str(type(request_parameters))
+            integration["requestParameters"] = request_parameters
+
+        return {"x-amazon-apigateway-integration": integration}
+
+
+from .integrations import *

fastapi_aws/router.py

@@ -0,0 +1,45 @@
+"""AWSAPIRouter
+
+inherited from APIRouter so we can pass kwargs to get, post, put, delete decorators
+"""
+from fastapi import APIRouter
+from fastapi.types import DecoratedCallable
+from typing import Any, Callable, Optional, Type
+
+
+from .route import AWSAPIRoute
+
+
+class AWSAPIRouter(APIRouter):
+    def __init__(self, *args, route_class: Type[AWSAPIRoute] = AWSAPIRoute, **kwargs):
+        super().__init__(*args, route_class=route_class, **kwargs)
+
+    def add_api_route(
+        self,
+        path: str,
+        endpoint: Callable[..., Any],
+        **kwargs: Any
+    ) -> None:
+        route_class = kwargs.pop("route_class_override", None) or self.route_class
+        route = route_class(path, endpoint, **kwargs)
+        self.routes.append(route)
+
+    def api_route(self, path: str, **kwargs: Any) -> Callable[[DecoratedCallable], DecoratedCallable]:
+        def decorator(func: DecoratedCallable) -> DecoratedCallable:
+            self.add_api_route(path, func, **kwargs)
+            return func
+
+        return decorator
+
+    # Override the HTTP method decorators to accept aws_lambda_uri
+    def get(self, path: str, **kwargs: Any):
+        return self.api_route(path, methods=["GET"], **kwargs)
+
+    def post(self, path: str, **kwargs: Any):
+        return self.api_route(path, methods=["POST"], **kwargs)
+
+    def put(self, path: str, **kwargs: Any):
+        return self.api_route(path, methods=["PUT"], **kwargs)
+
+    def delete(self, path: str, **kwargs: Any):
+        return self.api_route(path, methods=["DELETE"], **kwargs)