lambda-api-decorators-cdk 0.2.3__py3-none-any.whl

lambda_api_decorators_cdk/__init__.py

@@ -0,0 +1,5 @@
+from .api_type import ApiType
+from .lambda_api import LambdaApi
+from .lambda_api_config import LambdaApiConfig
+from .resource_builder import ResourceBuilder
+from .source_layout import SourceLayout

lambda_api_decorators_cdk/api_type.py

@@ -0,0 +1,8 @@
+from enum import Enum
+
+
+class ApiType(Enum):
+    """The API Gateway family managed by :class:`LambdaApi`."""
+
+    REST = "rest"
+    HTTP = "http"

lambda_api_decorators_cdk/ast_helper.py

@@ -0,0 +1,361 @@
+import ast
+import os
+from dataclasses import dataclass
+from typing import Any, Tuple
+
+
+@dataclass(frozen=True)
+class DecoratorInvocation:
+    """A single decorator call captured without interpreting its purpose."""
+
+    name: str
+    args: Tuple[Any, ...]
+    kwargs: Tuple[Tuple[str, Any], ...]
+
+class Method:
+    ALLOWED_METHODS = {'PUT', 'POST', 'GET', 'DELETE', 'ANY'}
+
+    def __init__(self, path_to_file:str, file: str, handler: str, method: str, decorators):
+        '''One http method is always associated with a file:handler entrypoint in a one-to-one relationship and each handler has decorators in a one-to-many relationship'''
+        if method not in self.ALLOWED_METHODS:
+            raise ValueError(f"Invalid method: {method}. Allowed methods are {', '.join(self.ALLOWED_METHODS)}")
+        self.method = method
+        self.file = file.replace(os.sep, '/')
+        self.path_to_file = path_to_file.replace(os.sep, '/')
+        self.handler = handler
+        if isinstance(decorators, dict):
+            decorators = tuple(
+                DecoratorInvocation(name, (value,), ())
+                for name, value in decorators.items()
+            )
+        self._decorator_invocations = tuple(decorators)
+
+    def __str__(self):
+        return (self.get_method(), self.get_file(), self.get_handler())
+
+    def get_method(self):
+        return self.method
+    
+    def get_logical_id(self):
+        return self.get_file().replace('.','dot').replace('/','-') + '-' + self.get_handler()
+    
+    def get_file(self):
+        return self.file
+
+    def get_handler(self):
+        return self.handler       
+
+    def get_path_to_file(self):
+        return self.path_to_file
+    
+    def get_method(self):
+        return self.method    
+    
+    def get_decorator_invocations(self):
+        return self._decorator_invocations
+    
+    def __eq__(self, other):
+        try:
+            check = self.get_method() == other.get_method and self.get_handler() == other.get_handler()
+            if check:
+                raise ValueError(f'{self.file()} and {other.get_file()} define the same method and handler, implementation may vary')
+            return isinstance(other, Method) and check
+        except TypeError:
+            raise TypeError
+
+
+class Resource:
+    def __init__(self, path = '/'):
+        self.path = path
+        self.methods = []
+        self.connections = []
+
+    def get_path(self) -> str:
+        return self.path
+    
+    def get_methods(self) -> list[Method]:
+        return self.methods
+    
+    def get_connections(self) -> list['Resource']:
+        return self.connections
+
+    def __eq__(self, other):
+        return isinstance(other, Resource) and self.get_path() == other.get_path()
+
+    def __str__(self):
+        methods_str = ' '
+        for method in self.get_methods():
+            methods_str = '(' + str(method.__str__()) + ') '
+            #methods_str = methods_str + '(' + method.get_method() + ' at ' + method.get_logical_id() + ') '
+        return self.get_path() + methods_str 
+    
+    def add_method(self, method: Method) -> bool:
+        '''Aggregate Method to present Resource's endpoint'''
+        if method not in self.methods:
+            self.methods.append(method)
+            return True
+        else:
+            return False
+        
+    def add_methods(self, method: list[Method]) -> bool:
+        '''Aggregate Methods to present Resource's endpoint'''
+        for method in self.methods:
+            if method not in self.methods:
+                self.methods.append(method)
+            return True
+
+    def includes_path(self, sub_path) -> bool:
+        '''Will indicate if another's Resource path is a ramification of the present Resource'''
+        return self.path == '/' or sub_path == self.path or sub_path.startswith(self.path.rstrip('/') + '/')
+
+    def connect(self, resource: 'Resource') -> bool:
+        if self.includes_path(resource.get_path()) and resource not in self.get_connections():
+            self.connections.append(resource)
+            return True
+        return False
+
+    def get_matching_prefix_index(self, ext_path: str) -> int:
+        current_path = self.get_path()
+        matching_prefix_index = ext_path.index(current_path) + len(current_path) if current_path in ext_path else -1
+        return matching_prefix_index
+        #We should always have a longest prefix match index at 1 because '/'
+    
+    def clone(self) -> 'Resource':
+        clone = Resource(self.get_path())
+        clone.connections = self.get_connections()
+        clone.methods = self.get_methods()
+        return clone
+    
+    def switch_nodes(self, resource:'Resource'):
+        aux = self.clone()
+        self.methods = resource.get_methods()
+        self.connections = resource.get_connections()
+        self.path = resource.get_path()
+        resource.connect(aux)
+        return True
+    
+    def insert_node(self, resource: 'Resource') -> bool:
+        resource_path = resource.get_path()
+
+        #Edge cases: Resource refers to same endpoint / Resource comes before  / Resource goes deeper or next to current node as bifurcation
+        if resource_path == self.get_path(): #They have the same path, new resource comes from a different function/file so we merge
+            for method in resource.get_methods():
+                self.add_method(method)
+            for connection in resource.get_connections():
+                self.connect(connection)
+            return True
+        
+        if len(resource_path) < len(self.get_path()) and resource.includes_path(self.get_path()): #Given resource comes before current, so we have to switch them
+            # aux = self.clone()
+            # self.methods = resource.get_methods()
+            # self.connections = resource.get_connections()
+            # self.path = resource.get_path()
+            # resource.connect(aux)
+            # return True
+            return self.switch_nodes(resource)
+        
+        if len(resource_path) >= len(self.get_path()) and self.includes_path(resource_path): #Resource goes deeper or bifurcation
+            if len(self.get_connections()) < 1:
+                self.connect(resource)
+                return True
+            else:
+                matching_node = self
+                matching_prefix_index = self.get_matching_prefix_index(resource_path)
+                for node in self.get_connections(): # Check if it goes deeper or may come in between two nodes
+                    if node.includes_path(resource_path): #deeper candidate
+                        node_matching_index = node.get_matching_prefix_index(resource_path)
+                        if node_matching_index > matching_prefix_index:
+                            matching_prefix_index = node_matching_index
+                            matching_node = node
+                    elif resource.includes_path(node.get_path()): #It comes in between, so we have to switch them or guess if it goes deeper
+                        return node.insert_node(resource)
+                if matching_node.includes_path(resource_path) and matching_node.get_path() != self.get_path(): #Goes deeper/recursion
+                    return matching_node.insert_node(resource)
+                else: #Bifurcation
+                    self.connect(resource)
+                    return True
+        else: #We should never get to this case because the root path would be '/' so we always have a startswith match in 3rd case for bifurcation
+            self.connect(resource)
+            return True
+
+def parse_file(file_path):
+    with open(file_path, 'r') as file:
+        source_code = file.read()
+        return ast.parse(source_code, filename=file_path)
+
+
+def _literal_value(node, decorator_name):
+    try:
+        return ast.literal_eval(node)
+    except (ValueError, TypeError) as error:
+        raise ValueError(
+            f"{decorator_name} only supports literal decorator values"
+        ) from error
+
+
+def _require_non_empty_string(value, decorator_name, field):
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{decorator_name} {field} must be a non-empty string")
+
+
+def _validate_grant(invocation, physical_field):
+    name = invocation.name
+    kwargs = dict(invocation.kwargs)
+    allowed_fields = {"resource_key", physical_field, "access"}
+    unexpected = next((key for key in kwargs if key not in allowed_fields), None)
+    if unexpected is not None:
+        raise ValueError(f"{name} received unexpected field {unexpected}")
+
+    if invocation.args:
+        if invocation.kwargs or len(invocation.args) != 2:
+            raise ValueError(
+                f"{name} positional form requires resource_key and access"
+            )
+        resource_key, access = invocation.args
+        _require_non_empty_string(resource_key, name, "resource_key")
+    else:
+        has_resource_key = "resource_key" in kwargs
+        has_physical_name = physical_field in kwargs
+        if has_resource_key == has_physical_name:
+            raise ValueError(
+                f"{name} requires exactly one of resource_key or {physical_field}"
+            )
+        address_field = "resource_key" if has_resource_key else physical_field
+        _require_non_empty_string(kwargs[address_field], name, address_field)
+        if "access" not in kwargs:
+            raise ValueError(f"{name} requires access")
+        access = kwargs["access"]
+
+    if access not in ("read", "write"):
+        raise ValueError(f"{name} access must be read or write, not {access!r}")
+
+
+def _validate_permission(invocation):
+    if invocation.args:
+        raise ValueError("permission only accepts keyword arguments")
+    kwargs = dict(invocation.kwargs)
+    for key in kwargs:
+        if key not in ("actions", "resources"):
+            raise ValueError(f"permission received unexpected field {key}")
+    for field in ("actions", "resources"):
+        if field not in kwargs:
+            raise ValueError(f"permission requires {field}")
+        values = kwargs[field]
+        if not isinstance(values, (list, tuple)) or not values:
+            raise ValueError(f"permission {field} must be a non-empty sequence")
+        if any(not isinstance(value, str) or not value.strip() for value in values):
+            raise ValueError(
+                f"permission {field} must contain only non-empty strings"
+            )
+
+    normalized = tuple(
+        (key, tuple(value) if key in ("actions", "resources") else value)
+        for key, value in invocation.kwargs
+    )
+    return DecoratorInvocation(invocation.name, invocation.args, normalized)
+
+
+def _parse_invocation(decorator):
+    if not isinstance(decorator, ast.Call) or not isinstance(decorator.func, ast.Name):
+        return None
+    name = decorator.func.id
+    if any(keyword.arg is None for keyword in decorator.keywords):
+        raise ValueError(f"{name} does not support expanded keyword arguments")
+    invocation = DecoratorInvocation(
+        name=name,
+        args=tuple(_literal_value(arg, name) for arg in decorator.args),
+        kwargs=tuple(
+            (keyword.arg, _literal_value(keyword.value, name))
+            for keyword in decorator.keywords
+        ),
+    )
+    if name == "grant_dynamodb":
+        _validate_grant(invocation, "table_name")
+    elif name == "grant_s3":
+        _validate_grant(invocation, "bucket_name")
+    elif name == "permission":
+        invocation = _validate_permission(invocation)
+    return invocation
+
+
+def get_file_nodes(parsed_tree, id, directory):
+    node_list = []
+    for node in parsed_tree.body:
+        if isinstance(node, ast.FunctionDef):
+            is_lambda_http = False
+            decorator_invocations = []
+            func_name = node.name
+            paths = [] #A handler could have multiple paths with multiple HTTP methods
+            for decorator in node.decorator_list:
+                invocation = _parse_invocation(decorator)
+                if invocation is None:
+                    continue
+                decorator_invocations.append(invocation)
+                if invocation.name in Method.ALLOWED_METHODS:
+                    if len(invocation.args) != 1 or invocation.kwargs:
+                        raise ValueError(
+                            f"{invocation.name} requires one positional path"
+                        )
+                    path = invocation.args[0]
+                    _require_non_empty_string(path, invocation.name, "path")
+                    is_lambda_http = True
+                    paths.append((path, invocation.name))
+
+            #ast.FunctionDef ends. If the Function had an HTTP Decorator it means it's a lambda function
+            if is_lambda_http: 
+                for key,value in paths:
+                    #If id (file) is at the root of directory, no change needed. Else we need to only get the file
+                    filepath = id[id.rindex(os.sep)+1:] if id.count(os.sep) > 0 else id 
+                    #Concatenate directory to id (file) for lambda entry point /  separate "index" file from path
+                    full_path = os.path.join(directory,id)
+                    
+                    method = Method(path_to_file=full_path[:full_path.rindex(os.sep)], file= filepath, handler=func_name, method=value, decorators=decorator_invocations)
+                    node_exists = False
+                    if len(node_list) > 0:
+                        for node in node_list:
+                            if node.get_path() == key:
+                                node.add_method(method)
+                                node_exists = True
+                    if not node_exists:
+                        new_resource = Resource(path=key)
+                        new_resource.add_method(method)
+                        node_list.append(new_resource)
+
+    return node_list
+
+def dump_tree(node, level=0):
+    if node is None:
+        return
+
+    # Print current node with indentation
+    print("   " * level, node)
+
+    # Recursively print connections
+    for child in node.get_connections():
+        dump_tree(child, level + 1)
+
+def has_decorators(parsed_tree):
+    for node in ast.walk(parsed_tree):
+        if isinstance(node, ast.FunctionDef) and node.decorator_list: #Es necesario fijarme si tiene si o si un decorador de tipo http? o con que tenga alcanza
+            return True
+    return False
+
+
+def get_lambda_graph(directory):
+    python_files = []
+    graph = Resource('/')
+    for root, dirs, files in os.walk(directory):
+        for file in files:
+            if file.endswith(".py"):
+                python_files.append(os.path.join(root, file))
+    
+    for file in python_files:
+        parsed_tree = parse_file(file)
+        file_id = file[len(directory)+len(os.sep):]
+        if has_decorators(parsed_tree):
+            new_nodes = get_file_nodes(parsed_tree, file_id, directory)
+            for node in new_nodes:
+                graph.insert_node(node)
+        else:
+            print("Skipped " + file + ' due to it not having decorators')
+    return graph

lambda_api_decorators_cdk/lambda_api.py

@@ -0,0 +1,85 @@
+from typing import Optional, Union
+
+from aws_cdk import aws_apigateway as apigateway
+from aws_cdk import aws_apigatewayv2 as apigatewayv2
+from constructs import Construct
+
+from .api_type import ApiType
+from .lambda_api_config import LambdaApiConfig
+from .source_layout import SourceLayout
+
+
+class LambdaApi(Construct):
+    """Build decorated Lambda handlers behind an API Gateway."""
+
+    def __init__(
+        self,
+        scope: Construct,
+        construct_id: str,
+        *,
+        lambda_path: str,
+        source_layout: SourceLayout = SourceLayout.ROOT,
+        layers_path: Optional[str] = None,
+        api: Optional[
+            Union[apigateway.IRestApi, apigatewayv2.HttpApi]
+        ] = None,
+        api_type: Optional[ApiType] = None,
+        config: Optional[LambdaApiConfig] = None,
+    ) -> None:
+        super().__init__(scope, construct_id)
+
+        if not isinstance(source_layout, SourceLayout):
+            raise TypeError("source_layout must be a SourceLayout")
+        if config is not None and not isinstance(config, LambdaApiConfig):
+            raise TypeError("config must be a LambdaApiConfig or None")
+        if api_type is not None and not isinstance(api_type, ApiType):
+            raise TypeError("api_type must be an ApiType or None")
+
+        inferred_type = self._infer_api_type(api) if api is not None else None
+        if api_type is not None and inferred_type is not None and api_type is not inferred_type:
+            raise ValueError(
+                f"api_type {api_type!r} conflicts with supplied {inferred_type.value} API"
+            )
+
+        resolved_type = inferred_type or api_type or ApiType.REST
+        resolved_config = config if config is not None else LambdaApiConfig()
+
+        if api is None:
+            if resolved_type is ApiType.REST:
+                api = apigateway.RestApi(self, "RestApi")
+            else:
+                api = apigatewayv2.HttpApi(self, "HttpApi")
+
+        self._api = api
+        self._api_type = resolved_type
+        resource_builder = resolved_config._create_resource_builder()
+
+        if resolved_type is ApiType.REST:
+            resource_builder.build(
+                self, api.root, lambda_path, source_layout=source_layout,
+                layers_path=layers_path)
+        else:
+            resource_builder.build_http(
+                self, api, lambda_path, source_layout=source_layout,
+                layers_path=layers_path)
+
+    @staticmethod
+    def _infer_api_type(api: object) -> ApiType:
+        # IRestApi is a non-runtime-checkable Protocol in CDK Python. Both
+        # created and imported REST APIs derive from its concrete RestApiBase.
+        if isinstance(api, apigateway.RestApiBase):
+            return ApiType.REST
+        if isinstance(api, apigatewayv2.HttpApi):
+            return ApiType.HTTP
+        raise TypeError(
+            "api must be an apigateway IRestApi implementation or "
+            "apigatewayv2.HttpApi"
+        )
+
+    @property
+    def api(self) -> Union[apigateway.IRestApi, apigatewayv2.HttpApi]:
+        return self._api
+
+    @property
+    def api_type(self) -> ApiType:
+        return self._api_type

lambda_api_decorators_cdk/lambda_api_config.py

@@ -0,0 +1,151 @@
+from typing import Mapping, Optional, Sequence
+
+from aws_cdk import Duration
+from aws_cdk import aws_ec2 as ec2
+from aws_cdk import aws_dynamodb as dynamodb
+from aws_cdk import aws_iam as iam
+from aws_cdk import aws_lambda as lambda_
+from aws_cdk import aws_s3 as s3
+
+from .resource_builder import ResourceBuilder
+
+
+class LambdaApiConfig:
+    """Reusable defaults and named resources for a :class:`LambdaApi` build."""
+
+    def __init__(
+        self,
+        *,
+        runtime: Optional[lambda_.Runtime] = None,
+        timeout: Optional[Duration] = None,
+        memory_size: Optional[int] = None,
+        vpc: Optional[ec2.IVpc] = None,
+        vpc_subnets: Optional[ec2.SubnetSelection] = None,
+        role: Optional[iam.IRole] = None,
+        layers: Optional[Sequence[lambda_.ILayerVersion]] = None,
+        security_groups: Optional[Sequence[ec2.ISecurityGroup]] = None,
+        environment: Optional[Mapping[str, str]] = None,
+        dynamodb_tables: Optional[Mapping[str, dynamodb.ITable]] = None,
+        s3_buckets: Optional[Mapping[str, s3.IBucket]] = None,
+    ) -> None:
+        self._default_runtime = runtime
+        self._default_timeout = timeout
+        self._default_memory_size = memory_size
+        self._default_vpc = (vpc, vpc_subnets) if vpc is not None else None
+        self._default_role = role
+
+        self._common_layers = list(layers) if layers is not None else []
+        self._common_security_groups = (
+            list(security_groups) if security_groups is not None else []
+        )
+        self._common_environments = dict(environment) if environment is not None else {}
+
+        self._custom_runtimes = {}
+        self._custom_roles = {}
+        self._custom_layers = {}
+        self._custom_environments = {}
+        self._custom_security_groups = {}
+        self._custom_vpcs = {}
+
+        self._dynamodb_tables = {}
+        self._s3_buckets = {}
+        for key, table in (dynamodb_tables or {}).items():
+            self.add_dynamodb_table(key, table)
+        for key, bucket in (s3_buckets or {}).items():
+            self.add_s3_bucket(key, bucket)
+
+    def set_default_runtime(self, runtime: Optional[lambda_.Runtime]) -> None:
+        self._default_runtime = runtime
+
+    def set_default_timeout(self, timeout: Optional[Duration]) -> None:
+        self._default_timeout = timeout
+
+    def set_default_memory_size(self, memory_size: Optional[int]) -> None:
+        self._default_memory_size = memory_size
+
+    def set_default_vpc(
+        self,
+        vpc: Optional[ec2.IVpc],
+        vpc_subnets: Optional[ec2.SubnetSelection] = None,
+    ) -> None:
+        self._default_vpc = (vpc, vpc_subnets) if vpc is not None else None
+
+    def set_default_role(self, role: Optional[iam.IRole]) -> None:
+        self._default_role = role
+
+    def add_common_layer(self, layer: lambda_.ILayerVersion) -> None:
+        if layer not in self._common_layers:
+            self._common_layers.append(layer)
+
+    def add_common_security_group(
+        self, security_group: ec2.ISecurityGroup
+    ) -> None:
+        if security_group not in self._common_security_groups:
+            self._common_security_groups.append(security_group)
+
+    def add_common_environment(self, key: str, value: str) -> None:
+        self._common_environments[key] = value
+
+    def add_custom_runtime(self, key: str, runtime: lambda_.Runtime) -> None:
+        self._custom_runtimes[key] = runtime
+
+    def add_custom_role(self, key: str, role: iam.IRole) -> None:
+        self._custom_roles[key] = role
+
+    def add_custom_layer(self, key: str, layer: lambda_.ILayerVersion) -> None:
+        self._custom_layers[key] = layer
+
+    def add_custom_environment(self, key: str, value: str) -> None:
+        self._custom_environments[key] = value
+
+    def add_custom_security_group(
+        self, key: str, security_group: ec2.ISecurityGroup
+    ) -> None:
+        self._custom_security_groups[key] = security_group
+
+    def add_custom_vpc(
+        self,
+        key: str,
+        vpc: ec2.IVpc,
+        vpc_subnets: Optional[ec2.SubnetSelection] = None,
+    ) -> None:
+        self._custom_vpcs[key] = (vpc, vpc_subnets)
+
+    def add_dynamodb_table(self, key: str, table: dynamodb.ITable) -> None:
+        self._add_resource(key, table, self._dynamodb_tables, "DynamoDB table")
+
+    def add_s3_bucket(self, key: str, bucket: s3.IBucket) -> None:
+        self._add_resource(key, bucket, self._s3_buckets, "S3 bucket")
+
+    @staticmethod
+    def _add_resource(key: str, resource, registry: dict, resource_type: str) -> None:
+        if not isinstance(key, str):
+            raise TypeError("Resource registry keys must be strings")
+        if not key.strip():
+            raise ValueError("Resource registry keys must not be empty or whitespace")
+        if resource is None or isinstance(resource, (str, int)):
+            raise TypeError(f"{resource_type} must be a CDK resource object")
+        if key in registry:
+            raise ValueError(f"Resource key {key!r} is already registered")
+        registry[key] = resource
+
+    def _create_resource_builder(self) -> ResourceBuilder:
+        """Create an isolated builder snapshot without copying CDK resources."""
+        return ResourceBuilder(
+            default_runtime=self._default_runtime,
+            default_timeout=self._default_timeout,
+            default_memory_size=self._default_memory_size,
+            default_vpc=self._default_vpc,
+            default_role=self._default_role,
+            common_layers=list(self._common_layers),
+            common_security_groups=list(self._common_security_groups),
+            common_environments=dict(self._common_environments),
+            custom_runtimes=dict(self._custom_runtimes),
+            custom_roles=dict(self._custom_roles),
+            custom_layers=dict(self._custom_layers),
+            custom_environments=dict(self._custom_environments),
+            custom_security_groups=dict(self._custom_security_groups),
+            custom_vpcs=dict(self._custom_vpcs),
+            dynamodb_tables=dict(self._dynamodb_tables),
+            s3_buckets=dict(self._s3_buckets),
+        )