canvas 0.12.0__py3-none-any.whl → 0.13.1__py3-none-any.whl

canvas_sdk/handlers/base.py

@@ -1,18 +1,17 @@
 import importlib.metadata
-from abc import ABC
+from abc import ABC, abstractmethod
 from typing import Any
 
 import deprecation
 
+from canvas_sdk.effects import Effect
 from canvas_sdk.events import Event
 
 version = importlib.metadata.version("canvas")
 
 
 class BaseHandler(ABC):
-    """
-    The class that all handlers inherit from.
-    """
+    """The class that all handlers inherit from."""
 
     secrets: dict[str, Any]
     event: Event
@@ -46,3 +45,8 @@ class BaseHandler(ABC):
     def target(self) -> str:
         """The target id of the event."""
         return self.event.target.id
+
+    @abstractmethod
+    def compute(self) -> list[Effect]:
+        """Compute the effects to be applied."""
+        pass

canvas_sdk/protocols/base.py

@@ -1,7 +1,9 @@
+from abc import ABC
+
 from canvas_sdk.handlers.base import BaseHandler
 
 
-class BaseProtocol(BaseHandler):
+class BaseProtocol(BaseHandler, ABC):
     """
     The class that protocols inherit from.
     """

plugin_runner/exceptions.py

@@ -0,0 +1,14 @@
+class PluginError(Exception):
+    """An exception raised for plugin-related errors."""
+
+
+class PluginValidationError(PluginError):
+    """An exception raised when a plugin package is not valid."""
+
+
+class InvalidPluginFormat(PluginValidationError):
+    """An exception raised when the plugin file format is not supported."""
+
+
+class PluginInstallationError(PluginError):
+    """An exception raised when a plugin fails to install."""

plugin_runner/plugin_installer.py

@@ -0,0 +1,208 @@
+import json
+import os
+import shutil
+import tarfile
+import tempfile
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, TypedDict
+from urllib import parse
+
+import boto3
+import psycopg
+from psycopg import Connection
+from psycopg.rows import dict_row
+
+import settings
+from plugin_runner.exceptions import InvalidPluginFormat, PluginInstallationError
+
+# Plugin "packages" include this prefix in the database record for the plugin and the S3 bucket key.
+UPLOAD_TO_PREFIX = "plugins"
+
+
+def get_database_dict_from_url() -> dict[str, Any]:
+    """Creates a psycopg ready dictionary from the home-app database URL."""
+    parsed_url = parse.urlparse(os.getenv("DATABASE_URL"))
+    db_name = parsed_url.path[1:]
+    return {
+        "dbname": db_name,
+        "user": parsed_url.username,
+        "password": parsed_url.password,
+        "host": parsed_url.hostname,
+        "port": parsed_url.port,
+    }
+
+
+def get_database_dict_from_env() -> dict[str, Any]:
+    """Creates a psycopg ready dictionary from the environment variables."""
+    APP_NAME = os.getenv("APP_NAME")
+
+    return {
+        "dbname": APP_NAME,
+        "user": os.getenv("DB_USERNAME", "app"),
+        "password": os.getenv("DB_PASSWORD", "app"),
+        "host": os.getenv("DB_HOST", f"{APP_NAME}-db"),
+        "port": os.getenv("DB_PORT", "5432"),
+    }
+
+
+def open_database_connection() -> Connection:
+    """Opens a psycopg connection to the home-app database."""
+    # When running within Aptible, use the database URL, otherwise pull from the environment variables.
+    if os.getenv("DATABASE_URL"):
+        database_dict = get_database_dict_from_url()
+    else:
+        database_dict = get_database_dict_from_env()
+    conn = psycopg.connect(**database_dict)
+    return conn
+
+
+class PluginAttributes(TypedDict):
+    """Attributes of a plugin."""
+
+    version: str
+    package: str
+    secrets: dict[str, str]
+
+
+def enabled_plugins() -> dict[str, PluginAttributes]:
+    """Returns a dictionary of enabled plugins and their attributes."""
+    conn = open_database_connection()
+
+    with conn.cursor(row_factory=dict_row) as cursor:
+        cursor.execute(
+            "select name, package, version, key, value from plugin_io_plugin p "
+            "left join plugin_io_pluginsecret s on p.id = s.plugin_id where is_enabled"
+        )
+        rows = cursor.fetchall()
+        plugins = _extract_rows_to_dict(rows)
+
+    return plugins
+
+
+def _extract_rows_to_dict(rows: list) -> dict[str, PluginAttributes]:
+    plugins = {}
+    for row in rows:
+        if row["name"] not in plugins:
+            plugins[row["name"]] = PluginAttributes(
+                version=row["version"],
+                package=row["package"],
+                secrets={row["key"]: row["value"]} if row["key"] else {},
+            )
+        else:
+            plugins[row["name"]]["secrets"][row["key"]] = row["value"]
+    return plugins
+
+
+@contextmanager
+def download_plugin(plugin_package: str) -> Generator:
+    """Download the plugin package from the S3 bucket."""
+    s3 = boto3.client("s3")
+    with tempfile.TemporaryDirectory() as temp_dir:
+        prefix_dir = Path(temp_dir) / UPLOAD_TO_PREFIX
+        prefix_dir.mkdir()  # create an intermediate directory reflecting the prefix
+        download_path = Path(temp_dir) / plugin_package
+        with open(download_path, "wb") as download_file:
+            s3.download_fileobj(
+                "canvas-client-media",
+                f"{settings.CUSTOMER_IDENTIFIER}/{plugin_package}",
+                download_file,
+            )
+        yield download_path
+
+
+def install_plugin(plugin_name: str, attributes: PluginAttributes) -> None:
+    """Install the given Plugin's package into the runtime."""
+    try:
+        print(f"Installing plugin '{plugin_name}'")
+
+        plugin_installation_path = Path(settings.PLUGIN_DIRECTORY) / plugin_name
+
+        # if plugin exists, first uninstall it
+        if plugin_installation_path.exists():
+            uninstall_plugin(plugin_name)
+
+        with download_plugin(attributes["package"]) as plugin_file_path:
+            extract_plugin(plugin_file_path, plugin_installation_path)
+
+        install_plugin_secrets(plugin_name=plugin_name, secrets=attributes["secrets"])
+    except Exception as ex:
+        print(f"Failed to install plugin '{plugin_name}', version {attributes['version']}")
+        raise PluginInstallationError() from ex
+
+
+def extract_plugin(plugin_file_path: Path, plugin_installation_path: Path) -> None:
+    """Extract plugin in `file` to the given `path`."""
+    archive: tarfile.TarFile | None = None
+
+    try:
+        if tarfile.is_tarfile(plugin_file_path):
+            try:
+                with open(plugin_file_path, "rb") as file:
+                    archive = tarfile.TarFile.open(fileobj=file)
+                    archive.extractall(plugin_installation_path, filter="data")
+            except tarfile.ReadError as ex:
+                print(f"Unreadable tar archive: '{plugin_file_path}'")
+                raise InvalidPluginFormat from ex
+        else:
+            print(f"Unsupported file format: '{plugin_file_path}'")
+            raise InvalidPluginFormat
+    finally:
+        if archive:
+            archive.close()
+
+
+def install_plugin_secrets(plugin_name: str, secrets: dict[str, str]) -> None:
+    """Write the plugin's secrets to disk in the package's directory."""
+    print(f"Writing plugin secrets for '{plugin_name}'")
+
+    secrets_path = Path(settings.PLUGIN_DIRECTORY) / plugin_name / settings.SECRETS_FILE_NAME
+
+    # Did the plugin ship a secrets.json? TOO BAD, IT'S GONE NOW.
+    if Path(secrets_path).exists():
+        os.remove(secrets_path)
+
+    with open(str(secrets_path), "w") as f:
+        json.dump(secrets, f)
+
+
+def disable_plugin(plugin_name: str) -> None:
+    """Disable the given plugin."""
+    conn = open_database_connection()
+    conn.cursor().execute(
+        "update plugin_io_plugin set is_enabled = false where name = %s", (plugin_name,)
+    )
+    conn.commit()
+    conn.close()
+
+    uninstall_plugin(plugin_name)
+
+
+def uninstall_plugin(plugin_name: str) -> None:
+    """Remove the plugin from the filesystem."""
+    plugin_path = Path(settings.PLUGIN_DIRECTORY) / plugin_name
+
+    if plugin_path.exists():
+        shutil.rmtree(plugin_path)
+
+
+def install_plugins() -> None:
+    """Install all enabled plugins."""
+    if Path(settings.PLUGIN_DIRECTORY).exists():
+        shutil.rmtree(settings.PLUGIN_DIRECTORY)
+
+    os.mkdir(settings.PLUGIN_DIRECTORY)
+
+    for plugin_name, attributes in enabled_plugins().items():
+        try:
+            print(f"Installing plugin '{plugin_name}', version {attributes['version']}")
+            install_plugin(plugin_name, attributes)
+        except PluginInstallationError:
+            disable_plugin(plugin_name)
+            print(
+                f"Installation failed for plugin '{plugin_name}', version {attributes['version']}. The plugin has been disabled"
+            )
+            continue
+
+    return None

plugin_runner/plugin_runner.py

@@ -42,8 +42,8 @@ sys.path.append(PLUGIN_DIRECTORY)
 # TODO: create typings here for the subkeys
 LOADED_PLUGINS: dict = {}
 
-# a global dictionary of events to protocol class names
-EVENT_PROTOCOL_MAP: dict[str, list] = defaultdict(list)
+# a global dictionary of events to handler class names
+EVENT_HANDLER_MAP: dict[str, list] = defaultdict(list)
 
 
 class DataAccess(TypedDict):
@@ -63,6 +63,17 @@ Protocol = TypedDict(
 )
 
 
+ApplicationConfig = TypedDict(
+    "ApplicationConfig",
+    {
+        "class": str,
+        "description": str,
+        "icon": str,
+        "scope": str,
+    },
+)
+
+
 class Components(TypedDict):
     """Components."""
 
@@ -71,6 +82,7 @@ class Components(TypedDict):
     content: list[dict]
     effects: list[dict]
     views: list[dict]
+    applications: list[ApplicationConfig]
 
 
 class PluginManifest(TypedDict):
@@ -106,7 +118,7 @@ class PluginRunner(PluginRunnerServicer):
         event = Event(request)
         event_type = event.type
         event_name = event.name
-        relevant_plugins = EVENT_PROTOCOL_MAP[event_name]
+        relevant_plugins = EVENT_HANDLER_MAP[event_name]
 
         if event_type in [EventType.PLUGIN_CREATED, EventType.PLUGIN_UPDATED]:
             plugin_name = event.target.id
@@ -117,22 +129,22 @@ class PluginRunner(PluginRunnerServicer):
 
         for plugin_name in relevant_plugins:
             plugin = LOADED_PLUGINS[plugin_name]
-            protocol_class = plugin["class"]
+            handler_class = plugin["class"]
             base_plugin_name = plugin_name.split(":")[0]
 
             secrets = plugin.get("secrets", {})
             secrets["graphql_jwt"] = token_for_plugin(plugin_name=plugin_name, audience="home")
 
             try:
-                protocol = protocol_class(event, secrets)
+                handler = handler_class(event, secrets)
                 classname = (
-                    protocol.__class__.__name__
-                    if isinstance(protocol, ClinicalQualityMeasure)
+                    handler.__class__.__name__
+                    if isinstance(handler, ClinicalQualityMeasure)
                     else None
                 )
 
                 compute_start_time = time.time()
-                _effects = await asyncio.get_running_loop().run_in_executor(None, protocol.compute)
+                _effects = await asyncio.get_running_loop().run_in_executor(None, handler.compute)
                 effects = [
                     Effect(
                         type=effect.type,
@@ -165,7 +177,7 @@ class PluginRunner(PluginRunnerServicer):
 
         event_duration = get_duration_ms(event_start_time)
 
-        # Don't log anything if a protocol didn't actually run.
+        # Don't log anything if a plugin handler didn't actually run.
         if relevant_plugins:
             log.info(f"Responded to Event {event_name} ({event_duration} ms)")
             statsd_tags = tags_to_line_protocol({"event": event_name})
@@ -275,7 +287,7 @@ def sandbox_from_module(package_path: pathlib.Path, module_name: str) -> Any:
 
     full_module_name = f"{package_path.name}.{module_name}"
 
-    sandbox = Sandbox(source_code, module_name=full_module_name)
+    sandbox = Sandbox(source_code, namespace=full_module_name)
     return sandbox.execute()
 
 
@@ -306,43 +318,45 @@ def load_or_reload_plugin(path: pathlib.Path) -> None:
 
     # TODO add existing schema validation from Michela here
     try:
-        protocols = manifest_json["components"]["protocols"]
+        handlers = manifest_json["components"].get("protocols", []) + manifest_json[
+            "components"
+        ].get("applications", [])
         results = sandbox_from_package(path)
     except Exception as e:
         log.error(f'Unable to load plugin "{name}": {str(e)}')
         return
 
-    for protocol in protocols:
+    for handler in handlers:
         # TODO add class colon validation to existing schema validation
         # TODO when we encounter an exception here, disable the plugin in response
         try:
-            protocol_module, protocol_class = protocol["class"].split(":")
-            name_and_class = f"{name}:{protocol_module}:{protocol_class}"
+            handler_module, handler_class = handler["class"].split(":")
+            name_and_class = f"{name}:{handler_module}:{handler_class}"
         except ValueError:
-            log.error(f"Unable to parse class for plugin '{name}': '{protocol['class']}'")
+            log.error(f"Unable to parse class for plugin '{name}': '{handler['class']}'")
             continue
 
         try:
             if name_and_class in LOADED_PLUGINS:
                 log.info(f"Reloading plugin '{name_and_class}'")
 
-                result = results[protocol_module]
+                result = results[handler_module]
 
                 LOADED_PLUGINS[name_and_class]["active"] = True
 
-                LOADED_PLUGINS[name_and_class]["class"] = result[protocol_class]
+                LOADED_PLUGINS[name_and_class]["class"] = result[handler_class]
                 LOADED_PLUGINS[name_and_class]["sandbox"] = result
                 LOADED_PLUGINS[name_and_class]["secrets"] = secrets_json
             else:
                 log.info(f"Loading plugin '{name_and_class}'")
 
-                result = results[protocol_module]
+                result = results[handler_module]
 
                 LOADED_PLUGINS[name_and_class] = {
                     "active": True,
-                    "class": result[protocol_class],
+                    "class": result[handler_class],
                     "sandbox": result,
-                    "protocol": protocol,
+                    "handler": handler,
                     "secrets": secrets_json,
                 }
         except Exception as err:
@@ -353,17 +367,17 @@ def load_or_reload_plugin(path: pathlib.Path) -> None:
 
 def refresh_event_type_map() -> None:
     """Ensure the event subscriptions are up to date."""
-    EVENT_PROTOCOL_MAP.clear()
+    EVENT_HANDLER_MAP.clear()
 
     for name, plugin in LOADED_PLUGINS.items():
         if hasattr(plugin["class"], "RESPONDS_TO"):
             responds_to = plugin["class"].RESPONDS_TO
 
             if isinstance(responds_to, str):
-                EVENT_PROTOCOL_MAP[responds_to].append(name)
+                EVENT_HANDLER_MAP[responds_to].append(name)
             elif isinstance(responds_to, list):
                 for event in responds_to:
-                    EVENT_PROTOCOL_MAP[event].append(name)
+                    EVENT_HANDLER_MAP[event].append(name)
             else:
                 log.warning(f"Unknown RESPONDS_TO type: {type(responds_to)}")
 

plugin_runner/plugin_synchronizer.py

@@ -7,6 +7,8 @@ from subprocess import STDOUT, CalledProcessError, check_output
 
 import redis
 
+from plugin_runner.plugin_installer import install_plugins
+
 APP_NAME = os.getenv("APP_NAME")
 
 CUSTOMER_IDENTIFIER = os.getenv("CUSTOMER_IDENTIFIER")
@@ -43,6 +45,11 @@ def publish_message(message: dict) -> None:
 def main() -> None:
     """Listen for messages on the pubsub channel and restart the plugin-runner."""
     print("plugin-synchronizer: starting")
+    try:
+        print("plugin-synchronizer: installing plugins after web container start")
+        install_plugins()
+    except CalledProcessError as e:
+        print("plugin-synchronizer: `install_plugins` failed:", e)
 
     _, pubsub = get_client()
 
@@ -62,17 +69,13 @@ def main() -> None:
         if "action" not in data or "client_id" not in data:
             return
 
-        # Don't respond to our own messages
-        if data["client_id"] == CLIENT_ID:
-            return
-
         if data["action"] == "restart":
             # Run the plugin installer process
             try:
-                print("plugin-synchronizer: installing plugins")
-                check_output(["./manage.py", "install_plugins_v2"], cwd="/app", stderr=STDOUT)
+                print("plugin-synchronizer: installing plugins after receiving restart message")
+                install_plugins()
             except CalledProcessError as e:
-                print("plugin-synchronizer: `./manage.py install_plugins_v2` failed:", e)
+                print("plugin-synchronizer: `install_plugins` failed:", e)
 
             try:
                 print("plugin-synchronizer: sending SIGHUP to plugin-runner")

plugin_runner/sandbox.py

@@ -93,7 +93,6 @@ class Sandbox:
 
     source_code: str
     namespace: str
-    module_name: str | None
 
     class Transformer(RestrictingNodeTransformer):
         """A node transformer for customizing the sandbox compiler."""
@@ -200,19 +199,16 @@ class Sandbox:
                 # Impossible Case only ctx Load, Store and Del are defined in ast.
                 raise NotImplementedError(f"Unknown ctx type: {type(node.ctx)}")
 
-    def __init__(
-        self, source_code: str, namespace: str | None = None, module_name: str | None = None
-    ) -> None:
+    def __init__(self, source_code: str, namespace: str | None = None) -> None:
         if source_code is None:
             raise TypeError("source_code may not be None")
-        self.module_name = module_name
         self.namespace = namespace or "protocols"
         self.source_code = source_code
 
     @cached_property
     def package_name(self) -> str | None:
         """Return the root package name."""
-        return self.module_name.split(".")[0] if self.module_name else None
+        return self.namespace.split(".")[0] if self.namespace else None
 
     @cached_property
     def scope(self) -> dict[str, Any]:

plugin_runner/tests/test_application.py

@@ -0,0 +1,65 @@
+import pytest
+
+from canvas_sdk.effects import Effect
+from canvas_sdk.effects.launch_modal import LaunchModalEffect
+from canvas_sdk.events import Event, EventRequest, EventType
+from canvas_sdk.handlers.application import Application
+
+
+class TestApplication(Application):
+    """A concrete implementation of the Application class for testing."""
+
+    def on_open(self) -> Effect:
+        """Handle the application open event by returning a mock effect."""
+        return LaunchModalEffect(url="https://example.com").apply()
+
+
+@pytest.fixture
+def app_instance(event: Event) -> TestApplication:
+    """Provide an instance of the TestApplication with a mocked event."""
+    app = TestApplication(event)
+    return app
+
+
+def test_compute_event_not_targeted() -> None:
+    """Test that compute filters out events not targeted for the app."""
+    request = EventRequest(type=EventType.APPLICATION__ON_OPEN, target="some_identifier")
+    event = Event(request)
+    app = TestApplication(event)
+
+    result = app.compute()
+
+    assert result == [], "Expected no effects if the event target is not the app identifier"
+
+
+def test_compute_event_targeted() -> None:
+    """Test that compute processes events targeted for the app."""
+    request = EventRequest(
+        type=EventType.APPLICATION__ON_OPEN,
+        target=f"{TestApplication.__module__}:{TestApplication.__qualname__}",
+    )
+    event = Event(request)
+    app = TestApplication(event)
+    result = app.compute()
+
+    assert len(result) == 1, "Expected a single effect if the event target is the app identifier"
+    assert isinstance(result[0], Effect), "Effect should be an instance of Effect"
+
+
+def test_identifier_property() -> None:
+    """Test the identifier property of the Application class."""
+    expected_identifier = f"{TestApplication.__module__}:{TestApplication.__qualname__}"
+    request = EventRequest(
+        type=EventType.APPLICATION__ON_OPEN,
+        target=f"{TestApplication.__module__}:{TestApplication.__qualname__}",
+    )
+    event = Event(request)
+    app = TestApplication(event)
+
+    assert app.identifier == expected_identifier, "The identifier property is incorrect"
+
+
+def test_abstract_method_on_open() -> None:
+    """Test that the abstract method on_open must be implemented."""
+    with pytest.raises(TypeError):
+        Application(Event(EventRequest(type=EventType.UNKNOWN)))  # type: ignore[abstract]