Merge pull request #1320 from awslabs/start-api/cfn

feat(start-api): Support for RestApi and Stage of CloudFormation resources

Author: jfuss

samcli/commands/local/lib/api_collector.py

@@ -0,0 +1,181 @@
+"""
+Class to store the API configurations in the SAM Template. This class helps store both implicit and explicit
+routes in a standardized format
+"""
+
+import logging
+from collections import defaultdict
+
+from six import string_types
+
+from samcli.local.apigw.local_apigw_service import Route
+from samcli.commands.local.lib.provider import Api
+
+LOG = logging.getLogger(__name__)
+
+
+class ApiCollector(object):
+
+    def __init__(self):
+        # Route properties stored per resource.
+        self._route_per_resource = defaultdict(list)
+
+        # processed values to be set before creating the api
+        self._routes = []
+        self.binary_media_types_set = set()
+        self.stage_name = None
+        self.stage_variables = None
+
+    def __iter__(self):
+        """
+        Iterator to iterate through all the routes stored in the collector. In each iteration, this yields the
+        LogicalId of the route resource and a list of routes available in this resource.
+        Yields
+        -------
+        str
+            LogicalID of the AWS::Serverless::Api or AWS::ApiGateway::RestApi resource
+        list samcli.commands.local.lib.provider.Api
+            List of the API available in this resource along with additional configuration like binary media types.
+        """
+
+        for logical_id, _ in self._route_per_resource.items():
+            yield logical_id, self._get_routes(logical_id)
+
+    def add_routes(self, logical_id, routes):
+        """
+        Stores the given routes tagged under the given logicalId
+        Parameters
+        ----------
+        logical_id : str
+            LogicalId of the AWS::Serverless::Api or AWS::ApiGateway::RestApi resource
+        routes : list of samcli.commands.local.agiw.local_apigw_service.Route
+            List of routes available in this resource
+        """
+        self._get_routes(logical_id).extend(routes)
+
+    def _get_routes(self, logical_id):
+        """
+        Returns the properties of resource with given logical ID. If a resource is not found, then it returns an
+        empty data.
+        Parameters
+        ----------
+        logical_id : str
+            Logical ID of the resource
+        Returns
+        -------
+        samcli.commands.local.lib.Routes
+            Properties object for this resource.
+        """
+
+        return self._route_per_resource[logical_id]
+
+    @property
+    def routes(self):
+        return self._routes if self._routes else self.all_routes()
+
+    @routes.setter
+    def routes(self, routes):
+        self._routes = routes
+
+    def all_routes(self):
+        """
+        Gets all the routes within the _route_per_resource
+
+        Return
+        -------
+        All the routes within the _route_per_resource
+        """
+        routes = []
+        for logical_id in self._route_per_resource.keys():
+            routes.extend(self._get_routes(logical_id))
+        return routes
+
+    def get_api(self):
+        """
+        Creates the api using the parts from the ApiCollector. The routes are also deduped so that there is no
+        duplicate routes with the same function name, path, but different method.
+
+        The normalised_routes are the routes that have been processed. By default, this will get all the routes.
+        However, it can be changed to override the default value of normalised routes such as in SamApiProvider
+
+        Return
+        -------
+        An Api object with all the properties
+        """
+        api = Api()
+        api.routes = self.dedupe_function_routes(self.routes)
+        api.binary_media_types_set = self.binary_media_types_set
+        api.stage_name = self.stage_name
+        api.stage_variables = self.stage_variables
+        return api
+
+    @staticmethod
+    def dedupe_function_routes(routes):
+        """
+        Remove duplicate routes that have the same function_name and method
+
+        route: list(Route)
+            List of Routes
+
+       Return
+       -------
+       A list of routes without duplicate routes with the same function_name and method
+        """
+        grouped_routes = {}
+
+        for route in routes:
+            key = "{}-{}".format(route.function_name, route.path)
+            config = grouped_routes.get(key, None)
+            methods = route.methods
+            if config:
+                methods += config.methods
+            sorted_methods = sorted(methods)
+            grouped_routes[key] = Route(function_name=route.function_name, path=route.path, methods=sorted_methods)
+        return list(grouped_routes.values())
+
+    def add_binary_media_types(self, logical_id, binary_media_types):
+        """
+        Stores the binary media type configuration for the API with given logical ID
+        Parameters
+        ----------
+
+        logical_id : str
+            LogicalId of the AWS::Serverless::Api resource
+
+        api: samcli.commands.local.lib.provider.Api
+            Instance of the Api which will save all the api configurations
+
+        binary_media_types : list of str
+            List of binary media types supported by this resource
+        """
+
+        binary_media_types = binary_media_types or []
+        for value in binary_media_types:
+            normalized_value = self.normalize_binary_media_type(value)
+
+            # If the value is not supported, then just skip it.
+            if normalized_value:
+                self.binary_media_types_set.add(normalized_value)
+            else:
+                LOG.debug("Unsupported data type of binary media type value of resource '%s'", logical_id)
+
+    @staticmethod
+    def normalize_binary_media_type(value):
+        """
+        Converts binary media types values to the canonical format. Ex: image~1gif -> image/gif. If the value is not
+        a string, then this method just returns None
+        Parameters
+        ----------
+        value : str
+            Value to be normalized
+        Returns
+        -------
+        str or None
+            Normalized value. If the input was not a string, then None is returned
+        """
+
+        if not isinstance(value, string_types):
+            # It is possible that user specified a dict value for one of the binary media types. We just skip them
+            return None
+
+        return value.replace("~1", "/")

samcli/commands/local/lib/api_provider.py

@@ -0,0 +1,93 @@
+"""Class that provides the Api with a list of routes from a Template"""
+
+import logging
+
+from samcli.commands.local.lib.api_collector import ApiCollector
+from samcli.commands.local.lib.cfn_api_provider import CfnApiProvider
+from samcli.commands.local.lib.cfn_base_api_provider import CfnBaseApiProvider
+from samcli.commands.local.lib.provider import AbstractApiProvider
+from samcli.commands.local.lib.sam_api_provider import SamApiProvider
+from samcli.commands.local.lib.sam_base_provider import SamBaseProvider
+
+LOG = logging.getLogger(__name__)
+
+
+class ApiProvider(AbstractApiProvider):
+
+    def __init__(self, template_dict, parameter_overrides=None, cwd=None):
+        """
+        Initialize the class with template data. The template_dict is assumed
+        to be valid, normalized and a dictionary. template_dict should be normalized by running any and all
+        pre-processing before passing to this class.
+        This class does not perform any syntactic validation of the template.
+
+        After the class is initialized, changes to ``template_dict`` will not be reflected in here.
+        You will need to explicitly update the class with new template, if necessary.
+
+        Parameters
+        ----------
+        template_dict : dict
+            Template as a dictionary
+
+        cwd : str
+            Optional working directory with respect to which we will resolve relative path to Swagger file
+        """
+        self.template_dict = SamBaseProvider.get_template(template_dict, parameter_overrides)
+        self.resources = self.template_dict.get("Resources", {})
+
+        LOG.debug("%d resources found in the template", len(self.resources))
+
+        # Store a set of apis
+        self.cwd = cwd
+        self.api = self._extract_api(self.resources)
+        self.routes = self.api.routes
+        LOG.debug("%d APIs found in the template", len(self.routes))
+
+    def get_all(self):
+        """
+        Yields all the Apis in the current Provider
+
+        :yields api: an Api object with routes and properties
+        """
+
+        yield self.api
+
+    def _extract_api(self, resources):
+        """
+        Extracts all the routes by running through the one providers. The provider that has the first type matched
+        will be run across all the resources
+
+        Parameters
+        ----------
+        resources: dict
+            The dictionary containing the different resources within the template
+        Returns
+        ---------
+        An Api from the parsed template
+        """
+        collector = ApiCollector()
+        provider = self.find_api_provider(resources)
+        provider.extract_resources(resources, collector, cwd=self.cwd)
+        return collector.get_api()
+
+    @staticmethod
+    def find_api_provider(resources):
+        """
+        Finds the ApiProvider given the first api type of the resource
+
+        Parameters
+        -----------
+        resources: dict
+            The dictionary containing the different resources within the template
+
+        Return
+        ----------
+        Instance of the ApiProvider that will be run on the template with a default of SamApiProvider
+        """
+        for _, resource in resources.items():
+            if resource.get(CfnBaseApiProvider.RESOURCE_TYPE) in SamApiProvider.TYPES:
+                return SamApiProvider()
+            elif resource.get(CfnBaseApiProvider.RESOURCE_TYPE) in CfnApiProvider.TYPES:
+                return CfnApiProvider()
+
+        return SamApiProvider()

samcli/commands/local/lib/cfn_api_provider.py

@@ -0,0 +1,105 @@
+"""Parses SAM given a template"""
+import logging
+
+from samcli.commands.local.cli_common.user_exceptions import InvalidSamTemplateException
+from samcli.commands.local.lib.cfn_base_api_provider import CfnBaseApiProvider
+
+LOG = logging.getLogger(__name__)
+
+
+class CfnApiProvider(CfnBaseApiProvider):
+    APIGATEWAY_RESTAPI = "AWS::ApiGateway::RestApi"
+    APIGATEWAY_STAGE = "AWS::ApiGateway::Stage"
+    TYPES = [
+        APIGATEWAY_RESTAPI,
+        APIGATEWAY_STAGE
+    ]
+
+    def extract_resources(self, resources, collector, cwd=None):
+        """
+        Extract the Route Object from a given resource and adds it to the RouteCollector.
+
+        Parameters
+        ----------
+        resources: dict
+            The dictionary containing the different resources within the template
+
+        collector: samcli.commands.local.lib.route_collector.RouteCollector
+            Instance of the API collector that where we will save the API information
+
+        cwd : str
+            Optional working directory with respect to which we will resolve relative path to Swagger file
+
+        Return
+        -------
+        Returns a list of routes
+        """
+        for logical_id, resource in resources.items():
+            resource_type = resource.get(CfnBaseApiProvider.RESOURCE_TYPE)
+            if resource_type == CfnApiProvider.APIGATEWAY_RESTAPI:
+                self._extract_cloud_formation_route(logical_id, resource, collector, cwd=cwd)
+
+            if resource_type == CfnApiProvider.APIGATEWAY_STAGE:
+                self._extract_cloud_formation_stage(resources, resource, collector)
+
+    def _extract_cloud_formation_route(self, logical_id, api_resource, collector, cwd=None):
+        """
+        Extract APIs from AWS::ApiGateway::RestApi resource by reading and parsing Swagger documents. The result is
+        added to the collector.
+
+        Parameters
+        ----------
+        logical_id : str
+            Logical ID of the resource
+
+        api_resource : dict
+            Resource definition, including its properties
+
+        collector : ApiCollector
+            Instance of the API collector that where we will save the API information
+        """
+        properties = api_resource.get("Properties", {})
+        body = properties.get("Body")
+        body_s3_location = properties.get("BodyS3Location")
+        binary_media = properties.get("BinaryMediaTypes", [])
+
+        if not body and not body_s3_location:
+            # Swagger is not found anywhere.
+            LOG.debug("Skipping resource '%s'. Swagger document not found in Body and BodyS3Location",
+                      logical_id)
+            return
+        self.extract_swagger_route(logical_id, body, body_s3_location, binary_media, collector, cwd)
+
+    @staticmethod
+    def _extract_cloud_formation_stage(resources, stage_resource, collector):
+        """
+        Extract the stage from AWS::ApiGateway::Stage resource by reading and adds it to the collector.
+        Parameters
+       ----------
+        resources: dict
+            All Resource definition, including its properties
+
+        stage_resource : dict
+            Stage Resource definition, including its properties
+
+        collector : ApiCollector
+            Instance of the API collector that where we will save the API information
+        """
+        properties = stage_resource.get("Properties", {})
+        stage_name = properties.get("StageName")
+        stage_variables = properties.get("Variables")
+
+        # Currently, we aren't resolving any Refs or other intrinsic properties that come with it
+        # A separate pr will need to fully resolve intrinsics
+        logical_id = properties.get("RestApiId")
+        if not logical_id:
+            raise InvalidSamTemplateException("The AWS::ApiGateway::Stage must have a RestApiId property")
+
+        rest_api_resource_type = resources.get(logical_id, {}).get("Type")
+        if rest_api_resource_type != CfnApiProvider.APIGATEWAY_RESTAPI:
+            raise InvalidSamTemplateException(
+                "The AWS::ApiGateway::Stage must have a valid RestApiId that points to RestApi resource {}".format(
+                    logical_id))
+
+        collector.stage_name = stage_name
+        collector.stage_variables = stage_variables