Add support for experimental features

chalice/app.py

@@ -688,6 +688,10 @@ def __init__(self, app_name, debug=False, configure_logs=True, env=None):
         if env is None:
             env = os.environ
         self._initialize(env)
+        self.experimental_feature_flags = set()
+        # This is marked as internal but is intended to be used by
+        # any code within Chalice.
+        self._features_used = set()
 
     def _initialize(self, env):
         if self.configure_logs:
@@ -735,6 +739,7 @@ def _configure_log_level(self):
         self.log.setLevel(level)
 
     def register_blueprint(self, blueprint, name_prefix=None, url_prefix=None):
+        self._features_used.add('BLUEPRINTS')
         blueprint.register(self, options={'name_prefix': name_prefix,
                                           'url_prefix': url_prefix})
 

chalice/app.pyi

@@ -160,6 +160,9 @@ class Chalice(DecoratorAPI):
     builtin_auth_handlers = ... # type: List[BuiltinAuthConfig]
     event_sources = ... # type: List[BaseEventSourceConfig]
     pure_lambda_functions = ... # type: List[LambdaFunction]
+    # Used for feature flag validation
+    _features_used = ... # type: Set[str]
+    experimental_feature_flags = ... # type: Set[str]
 
     def __init__(self, app_name: str, debug: bool=False,
                  configure_logs: bool=True,

chalice/cli/__init__.py

@@ -26,6 +26,7 @@
 from chalice.logs import display_logs
 from chalice.utils import create_zip_file
 from chalice.deploy.validate import validate_routes, validate_python_version
+from chalice.deploy.validate import ExperimentalFeatureError
 from chalice.utils import getting_started_prompt, UI, serialize_to_json
 from chalice.constants import CONFIG_VERSION, TEMPLATE_APP, GITIGNORE
 from chalice.constants import DEFAULT_STAGE_NAME
@@ -466,6 +467,9 @@ def main():
                    "environment variable or set the "
                    "region value in our ~/.aws/config file.", err=True)
         return 2
+    except ExperimentalFeatureError as e:
+        click.echo(str(e))
+        return 2
     except Exception:
         click.echo(traceback.format_exc(), err=True)
         return 2

chalice/cli/factory.py

@@ -24,6 +24,7 @@
 from chalice.utils import UI  # noqa
 from chalice.utils import PipeReader  # noqa
 from chalice.deploy import deployer  # noqa
+from chalice.deploy import validate
 from chalice.invoke import LambdaInvokeHandler
 from chalice.invoke import LambdaInvoker
 from chalice.invoke import LambdaResponseFormatter
@@ -222,8 +223,11 @@ def create_lambda_invoke_handler(self, name, stage):
 
         return handler
 
-    def load_chalice_app(self, environment_variables=None):
-        # type: (Optional[MutableMapping]) -> Chalice
+    def load_chalice_app(self, environment_variables=None,
+                         validate_feature_flags=True):
+        # type: (Optional[MutableMapping], Optional[bool]) -> Chalice
+        # validate_features indicates that we should validate that
+        # any expiremental features used have the appropriate feature flags.
         if self.project_dir not in sys.path:
             sys.path.insert(0, self.project_dir)
         # The vendor directory has its contents copied up to the top level of
@@ -258,6 +262,8 @@ def load_chalice_app(self, environment_variables=None):
                 'SyntaxError: %s'
             ) % (getattr(e, 'filename'), e.lineno, e.text, e.msg)
             raise RuntimeError(message)
+        if validate_feature_flags:
+            validate.validate_feature_flags(chalice_app)
         return chalice_app
 
     def load_project_config(self):

chalice/constants.py

@@ -217,6 +217,18 @@ def index():
 """
 
 
+EXPERIMENTAL_ERROR_MSG = """
+
+You are using experimental features without explicitly opting in.
+Experimental features do not guarantee backwards compatibility and may be
+removed in the future.  If you'd still like to use these experimental features,
+you can opt in by adding this to your app.py file:\n\n%s
+
+See https://chalice.readthedocs.io/en/latest/topics/experimental.html for more
+details.
+"""
+
+
 SQS_EVENT_SOURCE_POLICY = {
     "Effect": "Allow",
     "Action": [

chalice/deploy/validate.py

@@ -5,6 +5,24 @@
 
 from chalice import app  # noqa
 from chalice.config import Config  # noqa
+from chalice.constants import EXPERIMENTAL_ERROR_MSG
+
+
+class ExperimentalFeatureError(Exception):
+    def __init__(self, features_missing_opt_in):
+        # type: (Set[str]) -> None
+        self.features_missing_opt_in = features_missing_opt_in
+        msg = self._generate_msg(features_missing_opt_in)
+        super(ExperimentalFeatureError, self).__init__(msg)
+
+    def _generate_msg(self, missing_features):
+        # type: (Set[str]) -> str
+        opt_in_line = (
+            'app.experimental_feature_flags.update([\n'
+            '%s\n'
+            '])\n' % ',\n'.join(["    '%s'" % feature
+                                 for feature in missing_features]))
+        return EXPERIMENTAL_ERROR_MSG % opt_in_line
 
 
 def validate_configuration(config):
@@ -23,6 +41,18 @@ def validate_configuration(config):
     _validate_manage_iam_role(config)
     validate_python_version(config)
     validate_unique_function_names(config)
+    validate_feature_flags(config.chalice_app)
+
+
+def validate_feature_flags(chalice_app):
+    # type: (app.Chalice) -> None
+    missing_opt_in = set()
+    # pylint: disable=protected-access
+    for feature in chalice_app._features_used:
+        if feature not in chalice_app.experimental_feature_flags:
+            missing_opt_in.add(feature)
+    if missing_opt_in:
+        raise ExperimentalFeatureError(missing_opt_in)
 
 
 def validate_routes(routes):

docs/source/index.rst

@@ -65,6 +65,7 @@ Topics
    topics/purelambda
    topics/blueprints
    topics/cd
+   topics/experimental
 
 
 API Reference

docs/source/topics/blueprints.rst

@@ -2,11 +2,26 @@ Blueprints
 ==========
 
 
+.. warning::
+
+  Blueprints are considered an experimental API.  You'll need to opt-in
+  to this feature using the ``BLUEPRINTS`` feature flag:
+
+  .. code-block:: python
+
+    app = Chalice('myapp')
+    app.experimental_feature_flags.extend([
+        'BLUEPRINTS'
+    ])
+
+  See :doc:`experimental` for more information.
+
+
 Chalice blueprints are used to organize your application into logical
 components.  Using a blueprint, you define your resources and decorators in
 modules outside of your ``app.py``.  You then register a blueprint in your main
-``app.py`` file.  Any decorator supported on an application object is also
-supported in a blueprint.
+``app.py`` file.  Blueprints support any decorator available on an application
+object.
 
 
 .. note::
@@ -15,14 +30,14 @@ supported in a blueprint.
   <http://flask.pocoo.org/docs/latest/blueprints/>`__ in Flask.  Flask
   blueprints allow you to define a set of URL routes separately from the main
   ``Flask`` object.  This concept is extended to all resources in Chalice.  A
-  Chalice blueprint can have Lambda functions, event handlers, built in
+  Chalice blueprint can have Lambda functions, event handlers, built-in
   authorizers, etc. in addition to a collection of routes.
 
 
 Example
 -------
 
-In this example we'll create a blueprint with part of our routes defined in a
+In this example, we'll create a blueprint with part of our routes defined in a
 separate file.  First, let's create an application::
 
     $ chalice new-project blueprint-demo
@@ -46,10 +61,11 @@ Next, we'll oen the ``chalicelib/blueprints.py`` file:
         return {'foo': 'bar'}
 
 
-The ``__name__`` is used to denote the import path of the blueprint.  This must
-match the import name of the module so the function can be properly imported
-when running in Lambda.  We'll now import this module in our ``app.py`` and
-register this blueprint.  We'll also add a route in our ``app.py`` directly:
+The ``__name__`` is used to denote the import path of the blueprint.  This name
+must match the import name of the module so the function can be properly
+imported when running in Lambda.  We'll now import this module in our
+``app.py`` and register this blueprint.  We'll also add a route in our
+``app.py`` directly:
 
 .. code-block:: python
 
@@ -64,7 +80,7 @@ register this blueprint.  We'll also add a route in our ``app.py`` directly:
     def index():
         return {'hello': 'world'}
 
-At this point we've defined two routes.  One route, ``/``, is directly defined
+At this point, we've defined two routes.  One route, ``/``, is directly defined
 in our ``app.py`` file.  The other route, ``/foo`` is defined in
 ``chalicelib/blueprints.py``.  It was added to our Chalice app when we
 registered it via ``app.register_blueprint(extra_routes)``.
@@ -124,7 +140,7 @@ Blueprint Registration
 The ``app.register_blueprint`` function accepts two optional arguments,
 ``name_prefix`` and ``url_prefix``.  This allows you to register the resources
 in your blueprint at a certain url and name prefix.  If you specify
-``url_prefix`` any routes defined in your blueprint will have the
+``url_prefix``, any routes defined in your blueprint will have the
 ``url_prefix`` prepended to it.  If you specify the ``name_prefix``, any Lambda
 functions created will have the ``name_prefix`` prepended to the resource name.
 

docs/source/topics/experimental.rst

@@ -0,0 +1,90 @@
+Experimental APIs
+=================
+
+Chalice maintains backwards compatibility for all features that appear in this
+documentation.  Any Chalice application using version 1.x will continue to work
+for all future versions of 1.x.
+
+We also believe that Chalice has a lot of potential for new ideas and APIs,
+many of which will take several iterations to get right.  We may implement a
+new idea and need to make changes based on customer usage and feedback.  This
+may include backwards incompatible changes all the way up to the removal of
+a feature.
+
+To accommodate these new features, Chalice has support for experimental APIs,
+which are features that are added to Chalice on a provisional basis.  Because
+these features may include backwards incompatible changes, you must explicitly
+opt-in to using these features.  This makes it clear that you are using an
+experimental feature that may change.
+
+Opting-in to Experimental APIs
+------------------------------
+
+Each experimental feature in chalice has a name associated with it.  To opt-in
+to an experimental API, you must have the feature name to the
+``experimental_feature_flags`` attribute on your ``app`` object.
+This attribute's type is a set of strings.
+
+.. code-block:: python
+
+    from chalice import Chalice
+
+    app = Chalice('myapp')
+    app.experimental_feature_flags.update([
+        'MYFEATURE1',
+        'MYFEATURE2',
+    ])
+
+
+If you use an experimental API without opting-in, you will receive
+a message whenever you run a Chalice CLI command.  The error message
+tells you which feature flags you need to add::
+
+    $ chalice deploy
+    You are using experimental features without explicitly opting in.
+    Experimental features do not guarantee backwards compatibility and may be removed in the future.
+    If you still like to use these experimental features, you can opt-in by adding this to your app.py file:
+
+    app.experimental_feature_flags.update([
+        'BLUEPRINTS'
+    ])
+
+
+    See https://chalice.readthedocs.io/en/latest/topics/experimental.rst for more details.
+
+The feature flag only happens when running CLI commands.  There are no runtime
+checks for experimental features once your application is deployed.
+
+
+List of Experimental APIs
+-------------------------
+
+In the table below, the "Feature Flag Name" column is the value you
+must add to the ``app.experimental_feature_flags`` attribute.
+The status of an experimental API can be:
+
+* ``Trial`` - You must explicitly opt-in to use this feature.
+* ``Accepted`` - This feature has graduated from an experimental
+  feature to a fully supported, backwards compatible feature in Chalice.
+  Accepted features still appear in the table for auditing purposes.
+* ``Rejected`` - This feature has been removed.
+
+
+.. list-table:: Experimental APIs
+  :header-rows: 1
+
+  * - Feature
+    - Feature Flag Name
+    - Version Added
+    - Status
+    - GitHub Issue(s)
+  * - :doc:`blueprints`
+    - ``BLUEPRINTS``
+    - 1.7.0
+    - Trial
+    - `#1023 <https://github.com/aws/chalice/pull/1023>`__,
+      `#651 <https://github.com/aws/chalice/pull/651>`__
+
+
+See the `original discussion <https://github.com/aws/chalice/issues/1019>`__
+for more background information and alternative proposals.

tests/functional/cli/test_cli.py

@@ -19,6 +19,7 @@
 from chalice.invoke import LambdaInvokeHandler
 from chalice.invoke import UnhandledLambdaError
 from chalice.awsclient import ReadTimeout
+from chalice.deploy.validate import ExperimentalFeatureError
 
 
 class FakeConfig(object):
@@ -460,3 +461,24 @@ def test_invoke_does_raise_if_no_function_found(runner, mock_cli_factory):
                                   cli_factory=mock_cli_factory)
         assert result.exit_code == 2
         assert 'foo' in result.output
+
+
+def test_error_message_displayed_when_missing_feature_opt_in(runner):
+    with runner.isolated_filesystem():
+        cli.create_new_project_skeleton('testproject')
+        sys.modules.pop('app', None)
+        with open(os.path.join('testproject', 'app.py'), 'w') as f:
+            # Rather than pick an existing experimental feature, we're
+            # manually injecting a feature flag into our app.  This ensures
+            # we don't have to update this test if a feature graduates
+            # from trial to accepted.  The '_features_used' is a "package
+            # private" var for chalice code.
+            f.write(
+                'from chalice import Chalice\n'
+                'app = Chalice("myapp")\n'
+                'app._features_used.add("MYTESTFEATURE")\n'
+            )
+        os.chdir('testproject')
+        result = _run_cli_command(runner, cli.package, ['out'])
+        assert isinstance(result.exception, ExperimentalFeatureError)
+        assert 'MYTESTFEATURE' in str(result.exception)

tests/unit/deploy/test_validate.py

@@ -6,7 +6,8 @@
 from chalice import CORSConfig
 from chalice.deploy.validate import validate_configuration, validate_routes, \
     validate_python_version, validate_route_content_types, \
-    validate_unique_function_names
+    validate_unique_function_names, validate_feature_flags, \
+    ExperimentalFeatureError
 
 
 def test_trailing_slash_routes_result_in_error():
@@ -225,3 +226,19 @@ def index():
 
     assert validate_route_content_types(sample_app.routes,
                                         sample_app.api.binary_types) is None
+
+
+def test_can_validate_feature_flags(sample_app):
+    # The _features_used is marked internal because we don't want
+    # chalice users to access it, but this attribute is intended to be
+    # accessed by anything within the chalice codebase.
+    sample_app._features_used.add('SOME_NEW_FEATURE')
+    with pytest.raises(ExperimentalFeatureError):
+        validate_feature_flags(sample_app)
+    # Now if we opt in, validation is fine.
+    sample_app.experimental_feature_flags.add('SOME_NEW_FEATURE')
+    try:
+        validate_feature_flags(sample_app)
+    except ExperimentalFeatureError:
+        raise AssertionError("App was not suppose to raise an error when "
+                             "opting in to features via a feature flag.")