extensions: new flask extension

docs/.wordlist.txt

@@ -27,6 +27,7 @@ fs
 GID
 github
 GPG
+Gunicorn
 https
 init
 interoperable

docs/how-to/index.rst

@@ -22,3 +22,4 @@ adapt the steps to fit your specific requirements.
    Convert an entrypoint to a Pebble layer <convert-to-pebble-layer.rst>
    contribute-docs
    use-chisel
+   Use the flask extension <use-flask-extension.rst>

docs/how-to/use-flask-extension.rst

@@ -0,0 +1,57 @@
+Using the flask extension
+-------------------------
+
+The Flask extension is compatible with the ``bare``, ``ubuntu:20.04``, and
+``ubuntu:22.04`` bases. To employ it, include ``extensions: [flask]`` in your
+``rockcraft.yaml`` file.
+
+Example:
+
+.. code-block:: yaml
+
+    name: example-flask
+    summary: A Flask application
+    description: A ROCK packing a Flask application via the flask extension
+    version: "0.1"
+    base: bare
+    license: Apache-2.0
+
+    extensions:
+      - flask
+
+    flask/install-app:
+      prime:
+        - -srv/flask/app/.git
+        - -srv/flask/app/.venv
+        - -srv/flask/app/.yarn
+        - -srv/flask/app/node_modules
+
+Managing project files with the flask extension
+-----------------------------------------------
+
+The prime declaration must be included in the specially-named
+``flask/install-app`` section to instruct the flask extension on which files
+to include or exclude from the project directory in the ROCK image.
+
+For example, to include only select files:
+
+.. code-block:: yaml
+
+    flask/install-app:
+      prime:
+        - srv/flask/app/static
+        - srv/flask/app/.env
+        - srv/flask/app/webapp
+        - srv/flask/app/templates
+
+To exclude certain files from the project directory in the rock image,
+add the following part to ``rockcraft.yaml``:
+
+.. code-block:: yaml
+
+    flask/install-app:
+      prime:
+        - -srv/flask/app/.git
+        - -srv/flask/app/.venv
+        - -srv/flask/app/.yarn
+        - -srv/flask/app/node_modules

docs/reference/extensions.rst

@@ -0,0 +1,16 @@
+Extensions
+**********
+
+Just as the Snapcraft extensions are designed to simplify Snap creation,
+Rockcraft extensions are crafted to expand and modify the user-provided
+rockcraft project file, aiming to minimise the boilerplate code when
+initiating a new rock.
+
+The ``flask`` extension
+-----------------------
+
+The Flask extension streamlines the process of building Flask application rocks.
+
+It facilitates the installation of Flask application dependencies, including
+Gunicorn, in the rock image. Additionally, it transfers your project files to
+``/srv/flask/app`` within the rock image.

docs/reference/index.rst

@@ -14,3 +14,4 @@ Rockcraft's components, commands and keywords.
    parts
    commands
    part_properties
+   extensions

docs/reference/rockcraft.yaml.rst

@@ -211,6 +211,18 @@ The set of parts that compose the ROCK's contents
    Rockcraft. All ROCKs have Pebble as their entrypoint, and thus you must use
    ``services`` to define your container application.
 
+``extensions``
+--------------
+
+**Type**: list[string]
+
+**Required**: No
+
+Extensions to enable when building the ROCK.
+
+Currently supported extensions:
+
+- ``flask`` (experimental)
 
 Example
 =======

rockcraft/extensions/__init__.py

@@ -17,6 +17,7 @@
 """Extension processor and related utilities."""
 
 from ._utils import apply_extensions
+from .flask import Flask
 from .registry import get_extension_class, get_extension_names, register, unregister
 
 __all__ = [
@@ -26,3 +27,5 @@
     "register",
     "unregister",
 ]
+
+register("flask", Flask)

rockcraft/extensions/flask.py

@@ -0,0 +1,183 @@
+# -*- Mode:Python; indent-tabs-mode:nil; tab-width:4 -*-
+#
+# Copyright 2023 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 3 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""An experimental extension for the Flask framework."""
+
+import copy
+import posixpath
+import re
+from typing import Any, Dict, Optional, Tuple
+
+from overrides import override
+
+from ..errors import ExtensionError
+from ._utils import _apply_extension_property
+from .extension import Extension
+
+
+class Flask(Extension):
+    """An extension for constructing Python applications based on the Flask framework."""
+
+    @staticmethod
+    @override
+    def get_supported_bases() -> Tuple[str, ...]:
+        """Return supported bases."""
+        return "bare", "ubuntu:20.04", "ubuntu:22.04"
+
+    @staticmethod
+    @override
+    def is_experimental(base: Optional[str]) -> bool:
+        """Check if the extension is in an experimental state."""
+        return True
+
+    @override
+    def get_root_snippet(self) -> Dict[str, Any]:
+        """Fill in some default root components for Flask.
+
+        Default values:
+          - run_user: _daemon_
+          - build-base: ubuntu:22.04 (only if user specify bare without a build-base)
+          - platform: amd64
+        """
+        snippet: Dict[str, Any] = {}
+        if "run_user" not in self.yaml_data:
+            snippet["run_user"] = "_daemon_"
+        if (
+            "build-base" not in self.yaml_data
+            and self.yaml_data.get("base", "bare") == "bare"
+        ):
+            snippet["build-base"] = "ubuntu:22.04"
+        if "platforms" not in self.yaml_data:
+            snippet["platforms"] = {"amd64": {}}
+        current_parts = copy.deepcopy(self.yaml_data.get("parts", {}))
+        current_parts.update(self._gen_new_parts())
+        snippet["parts"] = current_parts
+        snippet["services"] = self._gen_services()
+        return snippet
+
+    def _gen_services(self):
+        """Return the services snipped to be applied to the rockcraft file."""
+        services = {
+            "flask": {
+                "override": "replace",
+                "startup": "enabled",
+                "command": "/bin/python3 -m gunicorn --bind 0.0.0.0:8000 app:app",
+                "user": "_daemon_",
+                "working-dir": "/srv/flask/app",
+            }
+        }
+        existing_services = copy.deepcopy(self.yaml_data.get("services", {}))
+        for existing_service_name, existing_service in existing_services.items():
+            if existing_service_name in services:
+                services[existing_service_name].update(existing_service)
+            else:
+                services[existing_service_name] = existing_service
+        return services
+
+    @override
+    def get_part_snippet(self) -> Dict[str, Any]:
+        """Return the part snippet to apply to existing parts."""
+        return {}
+
+    def _merge_part(self, base_part: dict, new_part: dict) -> dict:
+        """Merge two part definitions by the extension part merging rule."""
+        result = {}
+        properties = set(base_part.keys()).union(set(new_part.keys()))
+        for property_name in properties:
+            if property_name in base_part and property_name not in new_part:
+                result[property_name] = base_part[property_name]
+            elif property_name not in base_part and property_name in new_part:
+                result[property_name] = new_part[property_name]
+            else:
+                result[property_name] = _apply_extension_property(
+                    base_part[property_name], new_part[property_name]
+                )
+        return result
+
+    def _merge_existing_part(self, part_name: str, part_def: dict) -> dict:
+        """Merge the new part with the existing part in the current rockcraft.yaml."""
+        existing_part = self.yaml_data.get("parts", {}).get(part_name, {})
+        return self._merge_part(existing_part, part_def)
+
+    def _gen_new_parts(self) -> Dict[str, Any]:
+        """Generate new parts for the flask extension.
+
+        Parts added:
+            - flask/dependencies: install Python dependencies
+            - flask/install-app: copy the flask project into the OCI image
+        """
+        if not (self.project_root / "requirements.txt").exists():
+            raise ExtensionError(
+                "missing requirements.txt file, "
+                "flask extension requires this file with flask specified as a dependency"
+            )
+        source_files = [f.name for f in sorted(self.project_root.iterdir())]
+        renaming_map = {f: posixpath.join("srv/flask/app", f) for f in source_files}
+        install_app_part_name = "flask/install-app"
+        dependencies_part_name = "flask/dependencies"
+
+        if install_app_part_name not in self.yaml_data.get("parts", {}):
+            raise ExtensionError(
+                "flask extension required flask/install-app not found "
+                "in parts of the rockcraft file"
+            )
+        install_prime = self.yaml_data["parts"][install_app_part_name].get("prime")
+        if not install_prime:
+            raise ExtensionError(
+                "flask extension required prime list not found or empty"
+                "in the flask/install-app part of the rockcraft file"
+            )
+        if not all(re.match("-? *srv/flask/app", p) for p in install_prime):
+            raise ExtensionError(
+                "flask extension required prime entry in the flask/install-app part"
+                "to start with srv/flask/app"
+            )
+
+        # Users are required to compile any static assets prior to executing the
+        # rockcraft pack command, so assets can be included in the final OCI image.
+        install_app_part = {
+            "plugin": "dump",
+            "source": ".",
+            "organize": renaming_map,
+            "stage": list(renaming_map.values()),
+        }
+        dependencies_part = {
+            "plugin": "python",
+            "stage-packages": ["python3-venv"],
+            "source": ".",
+            "python-packages": ["gunicorn"],
+            "python-requirements": ["requirements.txt"],
+        }
+        snippet = {
+            dependencies_part_name: self._merge_existing_part(
+                dependencies_part_name, dependencies_part
+            ),
+            install_app_part_name: self._merge_existing_part(
+                install_app_part_name, install_app_part
+            ),
+        }
+        if self.yaml_data["base"] == "bare":
+            snippet["flask/container-processing"] = {
+                "plugin": "nil",
+                "source": ".",
+                "override-build": "mkdir -m 777 ${CRAFT_PART_INSTALL}/tmp",
+            }
+        return snippet
+
+    @override
+    def get_parts_snippet(self) -> Dict[str, Any]:
+        """Return the parts to add to parts."""
+        return {}

rockcraft/providers.py

@@ -47,7 +47,12 @@ def get_command_environment() -> Dict[str, Optional[str]]:
     env["ROCKCRAFT_MANAGED_MODE"] = "1"
 
     # Pass-through host environment that target may need.
-    for env_key in ["http_proxy", "https_proxy", "no_proxy"]:
+    for env_key in [
+        "http_proxy",
+        "https_proxy",
+        "no_proxy",
+        "ROCKCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS",
+    ]:
         if env_key in os.environ:
             env[env_key] = os.environ[env_key]
 

tests/spread/general/extension-flask/README

@@ -0,0 +1 @@
+test

tests/spread/general/extension-flask/app.py

@@ -0,0 +1,8 @@
+from flask import Flask  # pyright: ignore[reportMissingImports]
+
+app = Flask(__name__)
+
+
+@app.route("/")
+def ok():
+    return "ok"

tests/spread/general/extension-flask/requirements.txt

@@ -0,0 +1 @@
+flask

tests/spread/general/extension-flask/rockcraft.yaml

@@ -0,0 +1,15 @@
+name: flask-extension
+summary: OCI image for a flask project.
+description: OCI image for a flask project.
+version: "0.1"
+base: bare
+license: Apache-2.0
+
+extensions:
+  - flask
+
+parts:
+  flask/install-app:
+    prime:
+      - -srv/flask/app/README
+      - -srv/flask/app/node_modules

tests/spread/general/extension-flask/static/js/test.js

@@ -0,0 +1 @@
+console.log("hello")

tests/spread/general/extension-flask/task.yaml

@@ -0,0 +1,36 @@
+summary: flask extension test
+
+execute: |
+  export ROCKCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS=true
+
+  run_rockcraft pack
+
+  test -f flask-extension_0.1_amd64.rock
+  test ! -d work
+
+  # Ensure docker does not have this container image
+  docker rmi --force flask-extension
+  # Install container
+  sudo /snap/rockcraft/current/bin/skopeo --insecure-policy copy oci-archive:flask-extension_0.1_amd64.rock docker-daemon:flask-extension:latest
+  # Ensure container exists
+  docker images flask-extension | MATCH "flask-extension"
+
+  # ensure container doesn't exist
+  docker rm -f flask-extension-container
+
+  # test the flask project is ready to run inside the container
+  docker run --rm --entrypoint /bin/python3 flask-extension -m gunicorn --chdir /srv/flask/app --check-config app:app
+  docker run --rm --entrypoint /bin/python3 flask-extension -c "import pathlib;assert pathlib.Path('/srv/flask/app/static/js/test.js').is_file()"
+  docker run --rm --entrypoint /bin/python3 flask-extension -c "import pathlib;assert not pathlib.Path('/srv/flask/app/node_modules').exists()"
+
+  # test the part merging
+  docker run --rm --entrypoint /bin/python3 flask-extension -c "import pathlib;assert not pathlib.Path('/srv/flask/app/README').exists()"
+
+  # test the default flask service
+  docker run --rm --name flask-extension-container -d -p 8137:8000 flask-extension
+  retry -n 5 --wait 2 curl localhost:8137
+  [ "$(curl -sSf localhost:8137)" == "ok" ]
+
+restore: |
+  rm -f flask-extension_0.1_amd64.rock
+  docker rmi -f flask-extension