protocols → handlers

Author: beaugunderson

CLAUDE.md

@@ -0,0 +1,67 @@
+# canvas-plugins
+
+event-driven plugin SDK and runtime for Canvas Medical EHR. published as the `canvas` PyPI package.
+
+## project layout
+
+- `canvas_sdk/` - SDK for plugin authors (handlers, effects, commands, events, data models)
+- `plugin_runner/` - gRPC service that loads/sandboxes/executes plugins via `RestrictedPython`
+- `canvas_cli/` - typer CLI (`canvas init`, `canvas install`, `canvas emit`, etc.)
+- `canvas_generated/` - auto-generated protobuf python; **do not edit directly**
+- `protobufs/` - source `.proto` definitions
+- `pubsub/` - redis pub/sub for plugin reload signals and log streaming
+- `logger/` - structured logging with logstash + redis
+- `example-plugins/` - tens of reference plugins
+- `settings.py` - django settings (sqlite in tests, postgres in prod)
+- `conftest.py` - root pytest fixtures
+
+## companion repo
+
+`../canvas/home-app/` is the main Canvas app. cross-repo changes are common:
+- protobuf changes here must be copied to home-app's `canvas_generated/`
+- new SDK data models (`canvas_sdk/v1/data/`) mirror home-app Django models (read-only)
+- home-app's `plugin_io/database_views.py` exposes DB views for SDK models
+- run `bin/generate-protobufs` after changing `.proto` files
+
+## key architecture
+
+- plugins declare handled events in `CANVAS_MANIFEST.json`
+- `plugin_runner.plugin_runner.EVENT_HANDLER_MAP` maps event names → handler classes
+- `LOADED_PLUGINS` tracks installed plugin metadata
+- handlers extend `BaseHandler`, implement `compute()` returning effects
+- prefer "handlers" over "protocols" everywhere: use `handlers` key in `CANVAS_MANIFEST.json`, `BaseHandler` over `BaseProtocol`, `canvas_sdk.handlers` over `canvas_sdk.protocols`. the `protocols` names still work but are legacy
+- plugin code runs in a `RestrictedPython` sandbox with an allowed-imports whitelist
+- `plugin_runner/allowed-module-imports.json` is auto-generated by pre-commit
+
+## tooling
+
+- **python**: 3.11, 3.12 (requires >=3.11, <3.13)
+- **package manager**: `uv` (>=0.8.0)
+- **build**: hatchling
+- **release**: python-semantic-release, tag-based versioning
+
+## commands
+
+```sh
+uv run pytest -m "not integtest"        # unit tests
+uv run pytest path/to/test.py -k name   # specific test
+uv run mypy canvas_sdk/ plugin_runner/  # type checking (or use bin/mypy)
+uv run ruff check --fix .               # lint
+uv run ruff format .                    # format
+bin/generate-protobufs                  # regenerate protobuf python
+uv run python -m plugin_runner.generate_allowed_imports  # update import whitelist
+```
+
+## code style
+
+- prefer simple test functions over test classes
+- use `pydantic` for command validation, real types over `Any`
+
+## testing
+
+- pytest with django plugin, uses sqlite in test mode
+- `conftest.py` fixtures: `install_test_plugin`, `load_test_plugins`, `cli_runner`
+- plugin test fixtures live in `plugin_runner/tests/fixtures/plugins/`
+- CI tests against python 3.11 and 3.12 matrix
+- example plugins each tested independently in CI
+- integration tests dispatched to the canvas repo

canvas_cli/apps/plugin/plugin.py

@@ -186,10 +186,10 @@ def _get_meta_properties(protocol_path: Path, classname: str) -> dict[str, str]:
     return meta
 
 
-def _get_protocols_with_new_cqm_properties(
+def _get_handlers_with_new_cqm_properties(
     protocol_classes: Iterable[dict[str, Any]], plugin: Path
 ) -> Iterable[dict[str, Any]] | None:
-    """Extract the meta properties of any ClinicalQualityMeasure Protocols included in the plugin if they have changed."""
+    """Extract the meta properties of any ClinicalQualityMeasure handlers included in the plugin if they have changed."""
     has_updates = False
     protocol_props = []
     for p in protocol_classes:
@@ -229,8 +229,8 @@ def parse_secrets(secrets: builtins.list[str]) -> builtins.list[str]:
 
 def init(
     plugin_type: str = typer.Argument(
-        "protocol",
-        help="The type of plugin to create. Options are 'application' or 'protocol'.",
+        "handler",
+        help="The type of plugin to create. Options are 'application' or 'handler'.",
     ),
 ) -> None:
     """Create a new plugin."""
@@ -604,7 +604,7 @@ def validate_manifest(
     try:
         manifest_json = json.loads(manifest.read_text())
         protocols = manifest_json.get("components", {}).get("protocols", [])
-        if new_protocols := _get_protocols_with_new_cqm_properties(protocols, plugin_name):
+        if new_protocols := _get_handlers_with_new_cqm_properties(protocols, plugin_name):
             print(
                 f"Updating the CANVAS_MANIFEST.json file for {plugin_name} with CQM meta properties"
             )

canvas_sdk/protocols/base.py

@@ -4,9 +4,7 @@
 
 
 class BaseProtocol(BaseHandler, ABC):
-    """
-    The class that protocols inherit from.
-    """
+    """Deprecated alias for BaseHandler. Use canvas_sdk.handlers.base.BaseHandler instead."""
 
     pass
 

canvas_sdk/tests/caching/test_plugins.py

@@ -78,13 +78,13 @@ def test_plugin_successfully_sets_gets_key_value_in_cache(
     install_test_plugin: Path, load_test_plugins: None
 ) -> None:
     """Test that the plugin successfully sets and gets a key-value pair in the cache."""
-    plugin = LOADED_PLUGINS["test_caching_api:test_caching_api.protocols.my_protocol:Protocol"]
+    plugin = LOADED_PLUGINS["test_caching_api:test_caching_api.handlers.my_protocol:Protocol"]
     effects = plugin["class"](Event(EventRequest(type=EventType.UNKNOWN))).compute()
 
     assert effects[0].payload == "bar"
 
     plugin = LOADED_PLUGINS[
-        "test_caching_api:test_caching_api.protocols.my_secondary_protocol:Protocol"
+        "test_caching_api:test_caching_api.handlers.my_secondary_protocol:Protocol"
     ]
     effects = plugin["class"](Event(EventRequest(type=EventType.UNKNOWN))).compute()
 
@@ -97,7 +97,7 @@ def test_plugin_access_to_private_properties_cache_is_forbidden(
 ) -> None:
     """Test that plugin access to private properties of the cache api is forbidden."""
     assert (
-        "test_caching_api:test_caching_api.protocols.my_protocol:ForbiddenProtocol"
+        "test_caching_api:test_caching_api.handlers.my_protocol:ForbiddenProtocol"
         not in LOADED_PLUGINS
     )
 

canvas_sdk/tests/questionnaires/test_utils.py

@@ -15,7 +15,7 @@
 def test_from_yaml_valid_questionnaire(install_test_plugin: Path, load_test_plugins: None) -> None:
     """Test that the from_yaml function loads a valid questionnaire."""
     plugin = LOADED_PLUGINS[
-        "test_load_questionnaire:test_load_questionnaire.protocols.my_protocol:ValidQuestionnaire"
+        "test_load_questionnaire:test_load_questionnaire.handlers.my_protocol:ValidQuestionnaire"
     ]
     result: list[Effect] = plugin["class"](Event(EventRequest(type=EventType.UNKNOWN))).compute()
 
@@ -39,7 +39,7 @@ def test_from_yaml_invalid_questionnaire(
 ) -> None:
     """Test that the from_yaml function raises an error for invalid questionnaires."""
     plugin = LOADED_PLUGINS[
-        "test_load_questionnaire:test_load_questionnaire.protocols.my_protocol:InvalidQuestionnaire"
+        "test_load_questionnaire:test_load_questionnaire.handlers.my_protocol:InvalidQuestionnaire"
     ]
     with pytest.raises(FileNotFoundError):
         plugin["class"](Event(EventRequest(type=EventType.UNKNOWN))).compute()
@@ -51,7 +51,7 @@ def test_from_yaml_forbidden_questionnaire(
 ) -> None:
     """Test that the from_yaml function raises an error for a questionnaire outside plugin package."""
     plugin = LOADED_PLUGINS[
-        "test_load_questionnaire:test_load_questionnaire.protocols.my_protocol:ForbiddenQuestionnaire"
+        "test_load_questionnaire:test_load_questionnaire.handlers.my_protocol:ForbiddenQuestionnaire"
     ]
     with pytest.raises(PermissionError):
         plugin["class"](Event(EventRequest(type=EventType.UNKNOWN))).compute()

canvas_sdk/tests/templates/test_utils.py

@@ -13,7 +13,7 @@ def test_render_to_string_valid_template(
 ) -> None:
     """Test that the render_to_string function loads and renders a valid template."""
     plugin = LOADED_PLUGINS[
-        "test_render_template:test_render_template.protocols.my_protocol:ValidTemplate"
+        "test_render_template:test_render_template.handlers.my_protocol:ValidTemplate"
     ]
     result: list[Effect] = plugin["class"](Event(EventRequest(type=EventType.UNKNOWN))).compute()
     assert "This is always here" in result[0].payload
@@ -26,7 +26,7 @@ def test_render_to_string_valid_child_template(
 ) -> None:
     """Test that the render_to_string function allows template inheritance."""
     plugin = LOADED_PLUGINS[
-        "test_render_template:test_render_template.protocols.my_protocol:TemplateInheritance"
+        "test_render_template:test_render_template.handlers.my_protocol:TemplateInheritance"
     ]
     result: list[Effect] = plugin["class"](Event(EventRequest(type=EventType.UNKNOWN))).compute()
     assert "This is always here" in result[0].payload
@@ -40,7 +40,7 @@ def test_render_to_string_invalid_template(
 ) -> None:
     """Test that the render_to_string function raises an error for invalid templates."""
     plugin = LOADED_PLUGINS[
-        "test_render_template:test_render_template.protocols.my_protocol:InvalidTemplate"
+        "test_render_template:test_render_template.handlers.my_protocol:InvalidTemplate"
     ]
     with pytest.raises(FileNotFoundError):
         plugin["class"](Event(EventRequest(type=EventType.UNKNOWN))).compute()
@@ -52,7 +52,7 @@ def test_render_to_string_forbidden_template(
 ) -> None:
     """Test that the render_to_string function raises an error for a template outside plugin package."""
     plugin = LOADED_PLUGINS[
-        "test_render_template:test_render_template.protocols.my_protocol:ForbiddenTemplate"
+        "test_render_template:test_render_template.handlers.my_protocol:ForbiddenTemplate"
     ]
     with pytest.raises(PermissionError):
         plugin["class"](Event(EventRequest(type=EventType.UNKNOWN))).compute()

canvas_sdk/tests/utils/test_metrics.py

@@ -156,15 +156,15 @@ def test_track_plugins_usage_adds_plugin_tags(mock_time: MagicMock) -> None:
     with (
         patch(
             "canvas_sdk.utils.plugins.is_plugin_caller",
-            return_value=(True, "my_plugin.protocols.handler"),
+            return_value=(True, "my_plugin.handlers.handler"),
         ),
         measure("block", track_plugins_usage=True, client=client),
     ):
         pass
 
     tags = pipeline.timing.call_args.kwargs["tags"]
     assert tags["plugin"] == "my_plugin"
-    assert tags["handler"] == "my_plugin.protocols.handler"
+    assert tags["handler"] == "my_plugin.handlers.handler"
 
 
 @patch("canvas_sdk.utils.metrics.time")
@@ -218,7 +218,7 @@ def test_track_memory_usage_captures_rss_delta(
 @patch("canvas_sdk.utils.metrics.log")
 @patch(
     "canvas_sdk.utils.plugins.is_plugin_caller",
-    return_value=(True, "test_plugin.protocols.handler"),
+    return_value=(True, "test_plugin.handlers.handler"),
 )
 @patch("canvas_sdk.utils.metrics.psutil")
 @patch("canvas_sdk.utils.metrics.time")
@@ -269,7 +269,7 @@ def test_memory_below_threshold_no_warning(
 @patch("canvas_sdk.utils.metrics.log")
 @patch(
     "canvas_sdk.utils.plugins.is_plugin_caller",
-    return_value=(True, "test_plugin.protocols.handler"),
+    return_value=(True, "test_plugin.handlers.handler"),
 )
 @patch("canvas_sdk.utils.metrics.psutil")
 @patch("canvas_sdk.utils.metrics.time")

example-plugins/abnormal_lab_task_notification/abnormal_lab_task_notification/CANVAS_MANIFEST.json

@@ -4,7 +4,7 @@
     "name": "abnormal_lab_task_notification",
     "description": "A plugin that creates task notifications for abnormal lab values",
     "components": {
-        "protocols": [
+        "handlers": [
             {
                 "class": "abnormal_lab_task_notification.handlers.abnormal_lab_handler:AbnormalLabHandler",
                 "description": "Monitors lab reports and creates tasks for abnormal values",

example-plugins/ai_note_titles/ai_note_titles/CANVAS_MANIFEST.json

@@ -4,7 +4,7 @@
     "name": "ai_note_titles",
     "description": "Edit the description in CANVAS_MANIFEST.json",
     "components": {
-        "protocols": [
+        "handlers": [
             {
                 "class": "ai_note_titles.handlers.rename_note:Handler",
                 "description": "Renames Notes when locked using OpenAI and the contents of the Note"

example-plugins/api_samples/api_samples/CANVAS_MANIFEST.json

@@ -4,7 +4,7 @@
     "name": "api_samples",
     "description": "Example usages of the SimpleAPI handler",
     "components": {
-        "protocols": [
+        "handlers": [
             {
                 "class": "api_samples.routes.hello_world:HelloWorldAPI",
                 "description": "Returns a json message"